PHP 8.4: Date: New DateTime(Immutable)::createFromTimestamp methods

Version8.4
TypeNew Feature

The DateTime and DateTimeImmutable classes in PHP 8.4 have a new method named createFromTimeStamp creates an instance from a given UNIX timestamp as an integer or a float value.

Prior to PHP 8.4, to create a DateTime or DateTimeImmutable instance from a UNIX timestamp, it had to be created using [the createFromFormat with U / U.u formats, @<timestamp> constructor format, or calling setTimestamp on an already instantiated method.

The new DateTime::createFromTimeStamp and DateTimeImmutable::createFromTimeStamp methods make it convenient and fast to create DateTime or DateTimeImmutable instances from a UNIX timestamp.

$dt = DateTimeImmutable::createFromTimeStamp(1703155440);
$dt->format('Y-m-d'); // "2023-12-21"
$dt = DateTimeImmutable::createFromTimeStamp(1703155440.628);
$dt->format('Y-m-d h:i:s.u'); // "2023-12-21 10:44:00.628000"

createFromTimeStamp Method Synopses 

class DateTime {
    // ...
    public static function createFromTimestamp(int|float $timestamp): static {}
}

class DateTimeImmutable {
    // ...
    public static function createFromTimestamp(int|float $timestamp): static {}
}

Notably, the createFromTimestamp method accepts int or float values. This means it is possible to create instances with microsecond precision. Not every existing approach supports microsecond precision.

Existing Approaches

There are few possible ways to create or modify DateTime and DateTimeImmutable instances with a UNIX timestamp. Not all of the following approaches support float values, which means not all of them support microsecond precision.

DateTime(Immutable)::createFromFormat with with U / U.u formats

DateTime::createFromFormat and DateTimeImmutable::createFromFormat methods support creating DateTime and DateTimeImmutable methods from a given value that is formatted as the specified format. This includes the U and U.u formats, which respectively refer to the UNIX timestamp as an integer, and UNIX timestamp as a float value containing the microseconds.

$dt = DateTimeImmutable::createFromFormat('U', (string) 1703155440);
$dt->format('Y-m-d'); // "2023-12-21"

$dt = DateTimeImmutable::createFromFormat('U.u', (string) 1703155440.628);
$dt->format('Y-m-d h:i:s.u'); // "2023-12-21 10:44:00.628000"

This approach requires inspecting the timestamp value type, and conditionally using the U or U.u format. Additionally, the timestamp value is expected to be of type string, which means this requires casting the value to a string. Using the U.u format, it is possible to create objects with microsecond precision.

In this example, it uses the (string) cast syntax to make sure the string cast is consistent and supports underscore numeric separators.

@<timestamp> constructor format

The constructor of DateTime and DateTimeImmutable classes accepts a date/time value that it tries to "guess" the format from a list of supported formats. One of these supported formats includes @<timestamp>, where the <timestamp> is the UNIX timestamp as an integer.

This method supports float/decimal values, which means this approach can be used for timestamps with microsecond precision.

$dt = new DateTimeImmutable('@' . (string) 1703155440);
$dt->format('Y-m-d'); // "2023-12-21"

$dt = new DateTimeImmutable('@' . (string) 1703155440.628);
$dt->format('Y-m-d h:i:s.u'); // "2023-12-21 10:44:00.628000"

Calling setTimestamp on an already instantiated method

On DateTime and DateTimeImmutable objects, the setTimestamp method accepts integer UNIX timestamp values. This approach also has the slight disadvantage of the first instantiation with the given/current time that get overridden from the setTimestamp call.

This approach does not support microsecond precision.

$dt = new DateTimeImmutable();
$dt->setTimestamp(1703155440);
$dt->format('Y-m-d'); // "2023-12-21"

Related Changes

Backward Compatibility Impact

The createFromTimeStamp method in DateTime and DateTimeImmutable classes are new in the PHP 8.4 DateTime extension.

Using the existing approaches to create an instance with a determined UNIX timestamp, DateTime polyfills and PHP libraries that extend DateTime(Immutable) classes (such as Carbon) can mimic this functionality with support for older PHP versions as well.

Implementation