Chainable date/time helper for convenient work with integer timestamps
This date/time helper tries to make date/time management in PHP less prickly, by
providing a chainable helper that can be accessed via a global function
I wanted a convenient way to work with timestamps, which would provide the same
convenience (and IDE support) as e.g.
DateTime, but without the problems.
datetime() function takes an integer timestamp as argument, or a
valid date/time string compatible with
strtotime(), applies it to the helper,
and returns it.
$time = datetime('1975-07-07')->time; // parse date/time string to timestamp $str = datetime(time())->datetime; // timestamp to 'YYYY-MM-DD HH:MM:SS' format
The helper has a configuration object that defines global date/time formats and
a default timezone, which is UTC by default, regardless of any environment
settings - since timestamps (unlike
DateTime) do not carry around timezone
information, the default timezone can be changed, but you can also switch to
different timezones for easy string output.
$a = datetime()->utc()->long; // system date/time in long format $b = datetime()->timezone('EST')->short; // short date/time in EST timezone
The helper implements
__toString() and will format itself using the
format, which is also configurable. You can define as many formats as you want,
or specify the format directly, and you can render these using
the end of a chain. Default formats like
'date' are also supported directly as (dynamic) properties.
datetime()->config->formats['weekday'] = 'l'; echo datetime()->timezone('PST')->format('weekday'); // current weekday in PST
Basic computations can also be performed using plain english:
$today = datetime()->date()->time; // date() resets the time to 00:00:00 $this_month = datetime()->month()->time; // month() resets to start of the month $next_week = datetime()->add('1 week')->time; $whenever = datetime()->add('1 month')->sub('3 days 2 hours 1 minute')->time;
One word of caution: unless you
echo the result (invoking
call-chains should always end with a property rather than a method
() call - the
properties of the helper-class never return the helper object, always a value.
$bad = datetime(); // reference to DateTimeHelper ! $wrong = datetime()->timezone('EST')->add('1 week'); // oh noes!
There's a bunch of other features, go ahead and check out the unit-test for examples of every possible operation, or play around using auto-complete in your IDE.
Nobody doesn't love objects, but
DateTime is trouble - watch:
$today = new DateTime(); $yesterday = $today->modify('-1 day'); echo "today: " . $today->format('Y-m-d') . "\n"; echo "yesterday: " . $yesterday->format('Y-m-d');
If you understand how
DateTime works, you might be prepared for this nonsense:
today: 2013-03-21 yesterday: 2013-03-21
sub() modify the
DateTime object, rather
than returning a new
And sure, you got
DateTimeImmutable in more recent versions of PHP (and before
it, dozens of third-party immutable date/time object implementations in userland)
but you're still working with objects.
A timestamp is a value - when dealing with timestamps, I therefore want a value type, not an object, which is more complicated to handle when dealing with e.g. serialization, object/relational-mapping, etc.
When dealing with timezones, I don't want the timezone attached to the timestamp, because the timestamp and timezone do not actually have a meaningful relationship: timestamps are absolute, and that doesn't change when you attach it to a timezone; the only time that isn't true, is when you want the date/time as a string, but it's often more confusing to carry around the timezone information with the value for later use, since, when it finally gets turned into a string, it may not be obvious what timezone is being used - this can make programs rather confusing and difficult to read.