PHP 8.4: Новые методы DateTime(Immutable)::get/setMicroseconds

Хотя можно создавать/обновлять объекты DateTime и DateTimeImmutable с меткой времени, новые методы позволяют задавать доли микросекунд, не зная и не изменяя часы, минуты, секунды или остальные параметры даты и времени.

Метод setTime в классах DateTime и DateTimeImmutable позволяет задать значение микросекунды в качестве последнего параметра (int $microsecond). Микросекундную долю временной метки можно получить, отформатировав временную метку в формате u и принудительно преобразовав строковое значение в целое число.

Новые методы getMicroseconds и setMicroseconds

Новые методы getMicroseconds и setMicroseconds доступны в классах DateTime и DateTimeImmutable:

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

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

Для существующих объектов DateTime и DateTimeImmutable метод getMicroseconds возвращает микросекундную часть временной метки в виде целого числа:

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

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

Аналогично, метод setTimestamp принимает целочисленное значение для установки микросекундной части временной метки:

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

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

setMicroseconds принимаемые значения

Методы DateTime::setMicroseconds и DateTimeImmutable::setMicroseconds принимают целочисленное значение в диапазоне >= 0 и <= 999999. Это гарантирует, что установка доли микросекунд не приведёт к изменению секундной части временной метки.

Передача значения, выходящего за пределы этого диапазона, приводит к исключению DateRangeError.

$date = new DateTimeImmutable();
$date->setMicroseconds(1000000);

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

Существующие подходы для установки/получения микросекунд

Новые методы setMicroseconds и getMicroseconds — не единственный способ установить и получить значение микросекунд из объектов DateTime и DateTimeImmutable.

Самый простой подход — метод setTime, принимающий количество микросекунд:

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

Недостатком этого подхода является то, что значения часа, минуты и секунды должны быть известны. В следующем фрагменте показана установка количества микросекунд при повторном использовании существующих значений даты, часа, минуты и секунды:

$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"

Новые методы setMicroseconds и getMicroseconds делают процесс интуитивно понятным, когда требуется только установить/получить значение микросекунды.

Влияние на обратную совместимость

Если пользовательский PHP-класс не расширяет классы DateTime или DateTimeImmutable и не объявляет те же методы с несовместимой сигнатурой, это изменение не должно вызвать проблем совместимости с существующим кодом.

Связанные изменения

• Новые методы DateTime(Immutable)::createFromTimestamps

• Реализация