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

Version8.4

TypeNew Feature

The DateTime and DateTimeImmutable classes in PHP 8.4 and later support getMicrosecond and setMicrosecond methods to get and set the microsecond 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 `getMicrosecond` and `setMicrosecond` methods

The new getMicrosecond and setMicrosecond methods are available on both DateTime and DateTimeImmutable classes:

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

    public function setMicrosecond(int $microsecond): static {}
    // ...
}

On existing DateTime and DateTimeImmutable objects, the getMicrosecond 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->getMicrosecond(); // (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->setMicrosecond(426286);
$date->getMicrosecond(); // (int) 426286

`setMicrosecond` accepted values

The DateTime::setMicrosecond and DateTimeImmutable::setMicrosecond 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();
$date->setMicrosecond(1000000);

DateRangeError: DateTimeImmutable::setMicrosecond(): Argument #1 ($microsecond) must be between 0 and 999999, 1000000 given.

Existing approaches to set/get microsecond

The new setMicrosecond and getMicrosecond 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 microsecond 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 setMicrosecond and getMicrosecond 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.

Implementation

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

New getMicrosecond and setMicrosecond methods

setMicrosecond accepted values