PHP 8.4: Date: New DateTime(Immutable)::get/setMicroseconds methods

TypeNew Feature

The DateTime and DateTimeImmutable classes in PHP 8.4 and later support getMicroseconds and setMicroseconds methods to get and set the microseconds amount of the DateTime/DateTimeImmutable objects.

While it is possible to create/update DateTime and DateTimeImmutable objects with a timestamp, the new methods allow setting microsecond fractions without knowing or modifying the hour, minute, second, or the rest of the date and time.

The setTime method on DateTime and DateTimeImmutable classes allows setting the microsecond value as the last parameter (int $microsecond). The microsecond fraction of the timestamp can be obtained by formatting the timestamp in u format, and coercing that string value to an integer.

New getMicroseconds and setMicroseconds methods

The new getMicroseconds and setMicroseconds methods are available on both DateTime and DateTimeImmutable classes:

class DateTime {
    // ...
    public function getMicroseconds(): int {}

    public function setMicroseconds(int $microseconds): static {}
    // ...

On existing DateTime and DateTimeImmutable objects, the getMicroseconds method returns the microsecond part of the timestamp as an integer:

// 2024-02-06 08:40:46.899561 UTC (+00:00)
$date = new DateTimeImmutable(); 

$date->getMicroseconds(); // (int) 899561

Similarly, the setTimestamp method accepts an integer value to set the microsecond part of the timestamp:

// 2024-02-06 08:40:46.899561 UTC (+00:00)
$date = new DateTime(); 

$date->getMicroseconds(); // (int) 426286

setMicroseconds accepted values

The DateTime::setMicroseconds and DateTimeImmutable::setMicroseconds methods accept an integer value in the range >= 0 and <= 999999. This ensures that setting the microsecond fraction does not modify the seconds part of the timestamp.

Passing a value out of this range results in a DateRangeError exception.

$date = new DateTimeImmutable();
DateRangeError: DateTimeImmutable::setMicroseconds(): Argument #1 ($microseconds) must be between 0 and 999999, 1000000 given.

Existing approaches to set/get microseconds

The new setMicroseconds and getMicroseconds methods are not the only way to set and get the microsecond amounts from DateTime and DateTimeImmutable objects.

The easiest approach is the setTime method, which accepts the microseconds amount:

$date = new DateTimeImmutable();
$date = $date->setTime(hour: 10, minute: 44, second: 0, microsecond: 628115);
$date->format('u'); // string(6) "628115"

The downside of this approach is that the hour, minute, and second values must be known. The following snippet shows setting the microsecond amount while reusing the existing date, hour, minute, and second values from the existing values:

$date = new DateTimeImmutable();
$date = $date->setTime(
    hour: (int) $date->format('G'),
    minute: (int) $date->format('i'),
    second: (int) $date->format('s'),
    microsecond: 628115

(int) $date->format('u'); // int "628115"

The new setMicroseconds and getMicroseconds methods make it intuitive when all it needs is setting/getting the microsecond value.

Related Changes

Backward Compatibility Impact

Unless a user-land PHP class extends DateTime or DateTimeImmutable classes, and declares the same methods with an incompatible signature, this change should not cause any compatibility issues with existing code.