DateTimeImmutable 怎样按时区创建不可变时间

在 PHP 里按时区创建不可变时间，关键是把“输入字符串是否已经带时区”和“DateTimeZone 参数从哪里来”先分开。没有时区的输入可以显式传入 DateTimeZone；已经带 +02:00 或 Z 的输入会优先使用自身信息。DateTimeImmutable 的 modify()、setTimezone() 等操作返回新对象，不会改掉原对象。

一、先确定创建路径与时区来源

我在处理订单时间时，最容易误判的是把“显示在哪个时区”和“这个字符串代表哪个瞬间”混成一件事。可以先按下面的规则选路径：

二、用 DateTimeImmutable 构造指定时区的本地时间

当输入只是“2026-10-25 09:30:00”这样的本地墙上时间时，把时区作为显式依赖传入。这样代码不会因为部署机器的 date.timezone 不同而改变含义。

format('Y-m-d H:i:s P e'), PHP_EOL;

// modify 返回新对象，原对象仍保持 09:30:00。
$next = $local->modify('+1 day');
echo $next->format(DateTimeInterface::ATOM), PHP_EOL;
echo $local->format(DateTimeInterface::ATOM), PHP_EOL;

如果把输入改成 2026-10-25T09:30:00+02:00，构造器中的 $zone 不会把它强行改成上海时间。此时它已经表达了一个带偏移量的时间，想换成上海展示应显式调用 setTimezone($zone)，并把返回值接住。

三、用 createFromFormat 解析外部时间并清理默认字段

日志、表单和 CSV 常常给出固定格式。解析时建议把格式写完整，并在开头放 !，让没有出现在字符串里的字段从 Unix epoch 的零值基准初始化，而不是悄悄继承当前日期。

 0 || $errors['error_count'] > 0))) {
    throw new RuntimeException('日期时间解析失败');
}

echo $parsed->format(DateTimeInterface::ATOM), PHP_EOL;

timezone 参数适用于输入没有时区的情况。如果 $text 自带 Z 或偏移量，解析结果应以输入时区为准。另一个细节是：格式中的 + 允许尾部多余数据只产生警告，生产代码仍应读取 getLastErrors()，不要把“成功返回对象”当成输入完全干净。

四、验证不可变语义与常见边界

不可变不等于不能转换，而是每次转换都产生新的对象。下面三个检查足以覆盖大多数误用：

• 检查默认时区：在没有显式时区的代码里，用 date_default_timezone_get() 记录环境差异；业务值不要把这个全局配置当作隐含契约。
• 检查返回值：setTimezone()、modify()、setTime() 都要接收返回对象，原变量不会原地变化。
• 检查输入优先级：Unix 时间戳和已经带时区的字符串会让传入的 DateTimeZone 失去决定权，先统一输入格式再做展示转换。

若只想把同一个瞬间换到另一个地区显示，用 $display = $parsed->setTimezone(new DateTimeZone('UTC'))；若想把“没有时区的墙上时间”解释成某地区，则应在首次构造或解析时传入该地区，而不是事后随意转换。

相关问题

不传 DateTimeZone 会怎样？

没有时区信息的输入会使用 PHP 当前默认时区；部署环境变化时结果也可能变化，业务代码建议显式传入。

为什么 createFromFormat 返回 false 还要检查 getLastErrors？

解析可能带警告或错误信息，返回值检查和错误数组一起判断，才能拦住溢出日期、尾部数据等输入问题。

setTimezone 会修改原来的 DateTimeImmutable 吗？

不会。它返回一个新的不可变对象；原对象的时间值和时区保持不变。