PHP DateTimeImmutable 怎样避免时区副作用

我在处理预约时间时遇到过一种很隐蔽的错误：同一个时间对象先给后台列表格式化，又被接口层切换了时区，后面的代码拿到的结果就和原先不同。问题通常不在时区换算公式，而在于把时间对象当成了可以随手改写的共享状态。

PHP 的 DateTimeImmutable 适合解决这类问题，但有一个前提：创建时明确传入 DateTimeZone，并且把 setTimezone()、modify() 等方法的返回值接住。原对象保留，派生对象单独命名，时区副作用就能被限制在当前变量里。

官方文档：https://www.php.net/manual/en/class.datetimeimmutable.php

先分清“同一时刻”与“当地显示时间”

时区问题最容易混淆的地方，是把墙上显示的时间和时间轴上的瞬时点当成一回事。例如一个 UTC 时间转换为上海时间后，小时数会变化，但它们的 Unix 时间戳应该相同。setTimezone() 的职责就是改变显示时区，不改变底层瞬时点。

因此，业务代码可以把 UTC 作为存储或交换边界，把用户所在地区作为展示边界。不要为了显示上海时间而修改原始对象，更不要把默认时区藏在全局配置里，让调用者猜测输入含义。

创建时间对象时就固定来源时区

如果输入字符串没有偏移量，构造函数不会替你猜出业务时区。显式创建 DateTimeZone 并传入，能让“这串数字属于哪个地区”在代码里留下证据：

setTimezone(new DateTimeZone('UTC'));

echo $createdAt->format('Y-m-d H:i:sP') . PHP_EOL;
echo $utc->format('Y-m-d H:i:sP') . PHP_EOL;

// 用时间戳检查两个对象是否仍指向同一瞬时时刻。
if ($createdAt->getTimestamp() !== $utc->getTimestamp()) {
    throw new RuntimeException('时区转换不应改变瞬时时刻');
}

这里的两个变量分别承担“业务来源时间”和“交换格式时间”。调用 setTimezone() 后必须保存返回值；如果只调用方法却继续使用 $createdAt，它不会自动变成 UTC。

把不可变方法当作“派生新对象”

DateTimeImmutable 和可变的 DateTime 最大的工程差别，是修改方法返回新对象。这个特性很适合把基准时间传给多个计算分支：截止时间、展示时间和审计时间互不覆盖。

modify('+30 minutes');
    $display = $base->setTimezone(new DateTimeZone('Asia/Shanghai'));

    return [
        'base' => $base->format(DateTimeInterface::ATOM),
        'deadline' => $deadline->format(DateTimeInterface::ATOM),
        'display' => $display->format(DateTimeInterface::ATOM),
    ];
}

$base = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$window = buildWindow($base);

// 反向检查调用前后的基准值，确认下游没有改写它。
if ($base->getTimezone()->getName() !== 'UTC') {
    throw new LogicException('基准对象的时区不应被下游改变');
}

这种写法的重点不是把所有时间都强制格式化成 UTC，而是让每一次转换都有新变量承接。代码评审时只要沿着变量名查看，就能知道哪一个是来源值、哪一个是展示值、哪一个是计算结果。

在输入和输出边界各做一次检查

接口收到不带偏移量的日期字符串时，建议用 createFromFormat() 指定格式和时区，并把失败情况留在输入边界处理。输出到 JSON、日志或页面时，再根据读者所在地区创建展示对象。

setTimezone(new DateTimeZone('UTC'));
echo $payloadTime->format(DateTimeInterface::ATOM);

如果字符串本身已经带有 +08:00 或 Z，就要把它视为带偏移量的输入，不要再次用一个业务时区覆盖其含义。时区名、偏移量和时间戳是三种互补的排查证据：时区名看规则来源，偏移量看当前显示，时间戳看瞬时点是否改变。

容易留下副作用的几种写法

• 只设置 date_default_timezone_set()，却不在输入边界说明字符串属于哪个时区。全局默认值可以作为应用兜底，但不应代替领域数据。
• 调用 $date->setTimezone($zone) 后忽略返回值。对不可变对象来说，这行不会原地修改变量。
• 把同一个日期变量在多个层之间反复格式化和转换。应该保留基准对象，让每个展示层创建自己的派生值。
• 只比较格式化后的字符串。两个字符串看起来不同并不代表瞬时时刻不同，排查时应同时比较 getTimestamp()。

我现在处理跨层时间时会遵守一个简单约定：进入领域层的对象必须是明确时区的 DateTimeImmutable；存储和交换优先使用可追溯的偏移或 UTC；展示层只消费派生对象。这样即使同一个请求里出现多个地区，也不会靠修改共享对象来“修正”时间。

相关问题

DateTimeImmutable 的 setTimezone 会改变时间戳吗？

不会。它返回带新时区的新对象，底层瞬时时刻保持不变；可以比较新旧对象的 getTimestamp() 进行确认。

为什么调用 modify 后原变量没有变化？

这是不可变对象的设计。modify() 返回新的 DateTimeImmutable，需要用新变量接收，或者明确链式传递返回值。

服务器默认时区还需要配置吗？

需要作为兜底配置，但不能把它当成业务输入的唯一来源。跨服务、跨用户或跨地区数据仍应显式携带时区或偏移量。