PHP DateTimeImmutable 按时区转换并保持原对象

PHP 中用 DateTimeImmutable 转换时区，最小正确写法是：调用 setTimezone() 后接收返回的新对象。这个方法不会修改原对象，也不会改变底层时间点，只会让新对象按目标时区呈现同一瞬间。

setTimezone(new DateTimeZone('Asia/Shanghai'));

echo $source->format('Y-m-d H:i:s P e') . PHP_EOL;
echo $shanghai->format('Y-m-d H:i:s P e') . PHP_EOL;

原对象仍是 2026-09-28 12:00:00 +00:00 UTC，新对象显示为 2026-09-28 20:00:00 +08:00 Asia/Shanghai。墙上时间不同，但它们代表同一瞬间。

现象：调用 setTimezone 后为什么“没有变化”

最常见的问题是忽略返回值：

setTimezone(new DateTimeZone('Asia/Shanghai'));

echo $time->format('Y-m-d H:i:s P e');

DateTimeImmutable 的修改方法遵循不可变语义：不会就地改对象，而是返回一个新实例。PHP 官方手册还为这类方法标注了 NoDiscard 信息，目的就是提醒调用者不要忽略返回值。

最小可用写法：接收新对象

业务代码最好使用不同变量名，直观表达“来源”和“展示”是两个对象：

setTimezone(new DateTimeZone('Asia/Tokyo'));

echo $storedAt->format(DateTimeInterface::RFC3339) . PHP_EOL;
echo $displayAt->format(DateTimeInterface::RFC3339) . PHP_EOL;

也可以链式调用，但只适合不需要保留来源引用的短表达式。只要后续还要比较或记录来源时区，分开变量更容易排查。

先确认来源时间：构造时区和目标时区不是一回事

时区转换正确的前提，是输入时间已经被解释成正确的瞬间。构造器第二个参数描述“这个无时区字符串属于哪个来源时区”，而 setTimezone 描述“同一瞬间要按哪个目标时区显示”。

无时区字符串应显式传入来源时区：

setTimezone(new DateTimeZone('UTC'));
echo $utc->format(DateTimeInterface::RFC3339);

如果日期字符串本身已经带有 +02:00、UTC 或其他时区信息，构造器传入的 timezone 参数会被忽略；UNIX 时间戳形式也拥有自己的解释规则。不要指望第二个参数覆盖输入里已经声明的时区。

证据判断：时间戳相同才是正确转换

判断时区转换有没有改变真实时间，不要只比较格式化字符串，应比较时间戳和对象身份：

setTimezone(new DateTimeZone('America/New_York'));

// 不可变方法应返回不同对象
assert($source !== $local);

// 时区转换只改变显示规则，时间戳必须完全相同
assert($source->getTimestamp() === $local->getTimestamp());

// 原对象仍保留最初的 UTC 时区
assert($source->getTimezone()->getName() === 'UTC');

如果时间戳变了，通常不是 setTimezone 的问题，而是代码重新解析了格式化字符串，或者把目标墙上时间当成新的来源时间构造。时区转换不应通过“格式化，再 new 一次”完成。

修复动作：封装成明确的转换函数

项目中多处需要转换时，可以把目标时区校验和不可变返回值封装起来：

setTimezone($target);
}

PHP 8.3 起，无效时区会抛出 DateInvalidTimeZoneException；更早版本是普通 Exception。使用 Throwable 包装边界可以兼容不同运行环境，但不要吞掉异常后悄悄使用服务器默认时区。

夏令时边界：使用 IANA 时区标识

+08:00 是固定偏移，Asia/Shanghai 是带规则的时区标识。对不实行夏令时的地区，两者在当前日期可能看起来一样；对 America/New_York、Europe/Berlin 等地区，偏移会随日期变化。

setTimezone($newYork)->format('Y-m-d H:i:s P e') . PHP_EOL;
echo $summer->setTimezone($newYork)->format('Y-m-d H:i:s P e') . PHP_EOL;

用户资料中应优先保存 IANA 标识，而不是只保存当前偏移。固定偏移不能描述未来或历史日期的夏令时变化。

无时区输入：用 createFromFormat 固定解析规则

外部系统提供固定格式但不带时区时，可以用 createFromFormat 显式声明格式和来源时区。格式前的 ! 会把未提供字段重置到 Unix epoch 对应值，避免继承当前时间的其他字段。

 0 || $errors['error_count'] > 0)) {
    // PHP 可能对越界日期做滚动修复，业务输入应主动拒绝
    throw new InvalidArgumentException('Datetime contains warnings or errors');
}

$utc = $parsed->setTimezone(new DateTimeZone('UTC'));

反向验证：覆盖原对象、时间戳和目标时区

单元测试不要只断言一个格式化字符串。至少固定四项：

• 返回值与原对象不是同一个对象。
• 原对象的时区和格式化结果没有变化。
• 新旧对象的 getTimestamp() 相同。
• 目标对象的时区名称和预期偏移正确，包括夏令时日期。

format('Y-m-d H:i:s P e');
$target = $source->setTimezone(new DateTimeZone('Asia/Shanghai'));

// 四个断言共同证明：新对象、新显示、同一瞬间、原对象未变
assert($source !== $target);
assert($source->format('Y-m-d H:i:s P e') === $before);
assert($source->getTimestamp() === $target->getTimestamp());
assert($target->getTimezone()->getName() === 'Asia/Shanghai');

最终检查清单

• 是否接收了 setTimezone() 返回的新对象？
• 输入没有时区时，是否显式提供了来源时区？
• 输入字符串已经自带时区时，是否避免误以为构造器参数能覆盖它？
• 是否用时间戳验证“同一瞬间”，而不是只比较墙上时间？
• 用户时区是否保存为 IANA 标识，而不是固定偏移或含糊缩写？
• 非法时区和解析警告是否被明确拒绝？
• 存储层是否统一 UTC，展示层再转换为用户时区？

把规则压缩成一句话：先按来源时区正确解析，再用 setTimezone 创建目标展示对象，最后用相同时间戳证明原时间点未变。这样既保留了 DateTimeImmutable 的不可变优势，也能避免跨地区和夏令时场景中的隐性偏差。

参考资料：PHP 官方 DateTimeImmutable、DateTimeImmutable::setTimezone、DateTimeImmutable::createFromFormat 与 DateTimeZone 手册。