PHP 8.4: Date: 新增 DateTime(immutable)::createFromTimestamp 方法

PHP 8.4 中的 DateTime 和 DateTimeImmutable 类有一个名为 createFromTimeStamp 的新方法，用于从给定的 UNIX 时间戳(作为整数或浮点数)创建实例。

PHP 8.4 之前，从 UNIX 时间戳中创建 DateTime，必须使用 createFromFormat 创建，通过 U / U.u 格式、@<timestamp> 格式或者在已经实例化的方法中调用 setTimestamp。

新增的 DateTime::createFromTimeStamp 和 DateTimeImmutable::createFromTimeStamp 方法使得从 UNIX 时间戳创建 DateTime 或者 DateTimeImmutable 实例更加方便快速。

$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 值。这意味着可以创建微秒级精度的实例。并不是所有现有的方法都支持微秒级的精度。

现有方法

有几种可能的方法可以创建或修改带有 UNIX 时间戳的 DateTime 和 DateTimeImmutable 实例。并非所有以下方法都支持浮点值，这意味着并非所有方法都支持微秒精度。

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 格式。此外，时间戳的值应为字符串类型，这意味着这需要将值强制转换为字符串。使用 U.u 格式，可以创建带有微秒精度的对象。

本例中，它使用了 (string) 强制转换语法，确保字符串强制转换的一致性并支持下划线数字分隔符。

@<timestamp> 构造函数格式t {#@timestamp-replacement}

DateTime 和 DateTimeImmutable 类的构造函数接收 date/time 值，它从一系列支持的格式中“猜想”格式。它支持的格式包括 @<timestamp>，<timestamp> 是 UNIX 时间戳的整数值。

该方法支持 float/decimal 值，这意味着该方式可以使用带有微秒精度的时间戳。

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

向后兼容性影响

DateTime 和DateTimeImmutable 类的 createFromTimeStamp 方法，是 PHP 8.4  的 DateTime 扩展中新增的。

使用现有的方法来创建具有确定的 UNIX 时间戳的实例，DateTime polyfill 和扩展 DateTime(Immutable) 类（如 Carbon）的 PHP 库可以模仿此功能，同时支持旧的 PHP 版本。