PHP 8.4: Новые методы DateTime(Immutable)::createFromTimestamp
До PHP 8.4, чтобы создать экземпляр DateTime или DateTimeImmutable из временной метки UNIX, нужно было использовать createFromFormat с форматами U/U.u, конструктора @<timestamp>, или вызвать setTimestamp на уже созданном методе.
Новые методы DateTime::createFromTimeStamp и DateTimeImmutable::createFromTimeStamp позволяют создавать экземпляры DateTime или DateTimeImmutable из временной метки UNIX.
$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
class DateTime {
// ...
public static function createFromTimestamp(int|float $timestamp): static {}
}
class DateTimeImmutable {
// ...
public static function createFromTimestamp(int|float $timestamp): static {}
}Примечательно, что метод createFromTimestamp принимает значения int или float. Это означает, что можно создавать экземпляры с микросекундной точностью. Не все существующие подходы поддерживают микросекундную точность.
Существующие подходы
Существует несколько возможных способов создания или изменения экземпляров DateTime и DateTimeImmutable с временной меткой UNIX. Не все из перечисленных ниже способов поддерживают плавающие значения, а значит, не все из них поддерживают микросекундную точность.
DateTime(Immutable)::createFromFormat с форматами U / U.u
Методы DateTime::createFromFormat и DateTimeImmutable::createFromFormat поддерживают создание методов DateTime и DateTimeImmutable из заданного значения, отформатированного в указанном формате. Сюда входят форматы U и U.u, обозначающие временную метку UNIX как целое число и временную метку UNIX как значение с плавающей точкой, содержащее микросекунды.
$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"Этот подход требует проверки типа значения временной метки и условного использования формата U или U.u. Кроме того, ожидается, что значение временной метки будет иметь тип string, что означает необходимость приведения значения к string. Используя формат U.u, можно создавать объекты с микросекундной точностью.
В этом примере используется синтаксис (string) приведения, чтобы убедиться, что приведение строк является последовательным и поддерживает числовые разделители с подчёркиванием.
Формат конструктора @<timestamp>
Конструктор классов DateTime и DateTimeImmutable принимает значение даты/времени, формат которого он пытается "угадать" из списка поддерживаемых форматов. Один из этих поддерживаемых форматов включает @<timestamp>, где <timestamp> — это временная метка UNIX в виде целого числа.
Этот метод поддерживает плавающие/десятичные значения, а значит, его можно использовать для временных меток с микросекундной точностью.
$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"Вызов setTimestamp для уже созданного метода
Для объектов DateTime и DateTimeImmutable метод setTimestamp принимает целочисленные значения временных меток UNIX. Этот подход также имеет небольшой недостаток, заключающийся в том, что при первом создании объекта заданное/текущее время переопределяется из вызова setTimestamp.
Этот подход не поддерживает микросекундную точность.
$dt = new DateTimeImmutable();
$dt->setTimestamp(1703155440);
$dt->format('Y-m-d'); // "2023-12-21"Влияние на обратную совместимость
Метод createFromTimeStamp в классах DateTime и DateTimeImmutable является новым в расширении PHP 8.4 DateTime.
Используя существующие подходы к созданию экземпляра с определённой временной меткой UNIX, полифиллы DateTime и библиотеки PHP, расширяющие классы DateTime(Immutable) (например, Carbon), могут имитировать эту функциональность с поддержкой старых версий PHP.