Time and date handling

• Date and time
  • TimeImmutable specific methods
  • Time specific methods
  • Time zones
• Sleeper

The chrono library offers a set of abstractions for common time-related operations. It provides enhanced date/time classes, clock abstractions for accessing the current time, and sleeper abstractions for delaying execution, making time-based code easier to work with and test.

Date and time

Mako includes a couple of classes that extends the DateTimeImmutable, DateTime and DateTimeZone classes from the PHP core.

We'll only go over our customizations in this document. If you need documentation for all the methods defined in the base classes then you can read about them here, here and here.

You can create a new instance using the constructor. While the first parameter behaves the same as in PHP's native DateTime constructors, the optional second parameter accepts either a valid time zone string or a DateTimeZone instance.

There is also a mutable class called Time that implements the same methods with a couple of exceptions. We recommend using TimeImmutable, as immutable date and time objects help prevent accidental modifications and make it easier to reason about values as they are passed around your application.

$time = new TimeImmutable;

$time = new TimeImmutable('now', 'Europe/Paris');

$time = new TimeImmutable('now', new DateTimeZone('Europe/Paris'));

The now method allow you to create an instance where the time is set to "now". There's an optional parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::now();

$time = TimeImmutable::now('Europe/Paris');

$time = TimeImmutable::now(new DateTimeZone('Europe/Paris'));

The today method creates an instance where the time is set to todays date at 00:00:00. There's an optional parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::today();

$time = TimeImmutable::today('Europe/Paris');

$time = TimeImmutable::today(new DateTimeZone('Europe/Paris'));

The yesterday method creates an instance where the time is set to yesterdays date at 00:00:00. There's an optional parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::yesterday();

$time = TimeImmutable::yesterday('Europe/Paris');

$time = TimeImmutable::yesterday(new DateTimeZone('Europe/Paris'));

The tomorrow method creates an instance where the time is set to tomorrows date at 00:00:00. There's an optional parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::tomorrow();

$time = TimeImmutable::tomorrow('Europe/Paris');

$time = TimeImmutable::tomorrow(new DateTimeZone('Europe/Paris'));

The createFromFormat method allows you to create an instance from a time string. Unlike PHP's DateTimeImmutable implementation, Mako's time classes accepts either a valid timezone string or a DateTimeZone instance as the optional third parameter. The method returns false if date parsing fails.

$time = TimeImmutable::createFromFormat('Y-m-d', '2014-03-28');

$time = TimeImmutable::createFromFormat('Y-m-d', '2014-03-28', 'Europe/Paris');

$time = TimeImmutable::createFromFormat('Y-m-d', '2014-03-28', new DateTimeZone('Europe/Paris'));

The createFromFormatOrThrow method works like createFromFormat, but throws a ChronoException if date parsing fails.

$time = TimeImmutable::createFromFormatOrThrow('Y-m-d', '2014-03-28');

$time = TimeImmutable::createFromFormatOrThrow('Y-m-d', '2014-03-28', 'Europe/Paris');

$time = TimeImmutable::createFromFormatOrThrow('Y-m-d', '2014-03-28', new DateTimeZone('Europe/Paris'));

The createFromDate method allows you to create an instance using a date. Only the first parameter (year) is required. It'll use the current month and day if not specified. There's also an optional fourth parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::createFromDate(2014);

$time = TimeImmutable::createFromDate(2014, 4);

$time = TimeImmutable::createFromDate(2014, 4, 28);

$time = TimeImmutable::createFromDate(2014, 4, 28, 'Europe/Paris');

$time = TimeImmutable::createFromDate(2014, 4, 28, new DateTimeZone('Europe/Paris'));

The createFromTimestamp method allows you to create an instance using a UNIX timestamp. There's an optional second parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::createFromTimestamp($timestamp);

$time = TimeImmutable::createFromTimestamp($timestamp, 'Europe/Paris');

$time = TimeImmutable::createFromTimestamp($timestamp, new DateTimeZone('Europe/Paris'));

The createFromDOSTimestamp method allows you to create an instance using a DOS timestamp. There's an optional second parameter that accepts a valid time zone string or a DateTimeZone instance.

$time = TimeImmutable::createFromDOSTimestamp($timestamp);

$time = TimeImmutable::createFromDOSTimestamp($timestamp, 'Europe/Paris');

$time = TimeImmutable::createFromDOSTimestamp($timestamp, new DateTimeZone('Europe/Paris'));

The setTimezone method allows you to change the timezone after instance creation. The timezone parameter accepts either a valid time zone string or a DateTimeZone instance.

$time = $time->setTimezone('Europe/Paris');

$time = $time->setTimezone(new DateTimeZone('Europe/Paris'));

The forward method moves you forward in time by x seconds.

$time = $time->forward(60);

The rewind method moves you backward in time by x seconds.

$time = $time->rewind(60);

The getDOSTimestamp method returns the DOS timestamp of the Time instance.

$dosTimestamp = $time->getDOSTimestamp();

The isPast method returns true if the time is in the past and false if not.

$isPast = TimeImmutable::createFromFormat('Y-m-d H:i:s', '1980-01-01 00:00:00')->isPast(); // true
$isPast = TimeImmutable::createFromFormat('Y-m-d H:i:s', '2980-01-01 00:00:00')->isPast(); // false

The isFuture method returns true if the time is in the future and false if not.

$isFuture = TimeImmutable::createFromFormat('Y-m-d H:i:s', '2980-01-01 00:00:00')->isFuture(); // true
$isFuture = TimeImmutable::createFromFormat('Y-m-d H:i:s', '1980-01-01 00:00:00')->isFuture(); // false

The isBefore method returns true if the time instance is before the given time and false if not.

$time = TimeImmutable::now();

$isBefore = $time->isBefore(TimeImmutable::tomorrow()); // true
$isBefore = $time->isBefore(TimeImmutable::yesterday()); // false

The isAfter method returns true if the time instance is after the given time and false if not.

$time = TimeImmutable::now();

$isAfter = $time->isAfter(TimeImmutable::yesterday()); // true
$isAfter = $time->isAfter(TimeImmutable::tomorrow()); // false

The isBetween method returns true if the time instance is between the given times and false if not.

$time = TimeImmutable::now();

$isBetween = $time->isBetween(new TimeImmutable('-14 days'), new TimeImmutable('+7 days')); // true
$isBetween = $time->isBetween(new TimeImmutable('-14 days'), new TimeImmutable('-7 days')); // false

The isLeapYear method returns true if the year of the Time instance is a leap year and false if not.

$isLeapYear = $time->isLeapYear();

The daysInMonth method returns the number of days in the month of the Time instance. The method also takes into account whether it is a leap year or not.

$daysInMonth = $time->daysInMonth();

The daysInMonths method returns an array containing the number of days in each month of the Time instance. The method also takes into account whether it is a leap year or not.

$daysInMonths = $time->daysInMonths();

The toAtomString returns the time as an ATOM date-time string.

$atomString = $time->toAtomString();

The toIso8601String returns the time as an ISO 8601 date-time string.

$iso8601String = $time->toIso8601String();

The toExpandedIso8601String method returns the time as an expanded ISO 8601 date-time string that can represent years outside the 0000–9999 range.

$expandedIso8601String = $time->toExpandedIso8601String();

The toRfc7231String returns the time as an RFC 7231 date-time string.

$rfc7231String = $time->toRfc7231String();

TimeImmutable specific methods

The toMutable method returns a Time instance set to the same time.

$mutable = $time->toMutable();

The toNative method returns a DateTime instance set to the same time.

$mutable = $time->toNative();

Time specific methods

The toImmutable method returns a TimeImmutable instance set to the same time.

$immutable = $time->toImmutable();

The toNative method returns a DateTimeImmutable instance set to the same time.

$mutable = $time->toNative();

Time zones

The getTimezones method returns an array consisting of all available time zones where the key is a valid time zone string while the value is a presentable name.

$timeZones = TimeZone::getTimezones();

The getGroupedTimezones method returns an array consisting of grouped time zones where the key is a valid PHP time zone string while the value is a presentable name.

$timeZones = TimeZone::getGroupedTimezones();

Sleeper

The Sleeper class provides a convenient abstraction over PHP's native sleep functions. While you can call sleep, usleep, time_nanosleep, and time_sleep_until directly, using the SleeperInterface allows you to inject and mock time-based delays in your applications and tests. This makes it possible to verify that code performs the expected delays without actually pausing execution, resulting in faster and more reliable tests.

The sleep method will sleep for the given number of seconds.

$sleeper->sleep(10);

The milliSleep method will sleep for the given number of milliseconds.

$sleeper->milliSleep(500); // Equivalent to 0.5 seconds

The microSleep method will sleep for the given number of microseconds.

$sleeper->microSleep(500_000); // Equivalent to 0.5 seconds

The nanoSleep method will sleep for the given number of nanoseconds. Note that actual sleep duration depends on OS timer resolution.

$sleeper->nanoSleep(500_000_000); // Equivalent to 0.5 seconds

The sleepUntil method will sleep until the specified time.

$sleeper->sleepUntil(new TimeImmutable('+10 minutes'));