PHP 8.4 DateTimeZone::getTransitions 怎么核对夏令时：时区切换、缺口时间与排查记录

订单系统把用户填写的“本地时间”转成 UTC 时，最容易漏掉的不是格式，而是时区规则：同一个地区一年里可能发生偏移切换，切换那天还会出现不存在或重复的本地时间。PHP 的 DateTimeZone::getTransitions() 可以把这条规则变成可核对的记录，再交给 DateTimeImmutable 做输入验收。

先把地区时区和固定偏移分开

new DateTimeZone('Europe/Berlin') 保存的是地区规则，PHP 可以据此查到历史和查询区间内的偏移变化；new DateTimeZone('+01:00') 只表达一个固定偏移。后者适合已经明确是 UTC 偏移的外部数据，不适合作为用户地区的长期配置。

getName());  // Europe/Berlin
var_dump($fixed->getName()); // +01:00
var_dump($fixed->getTransitions()); // false：没有地区过渡表
?>

这个检查适合放在配置加载阶段。若数据库里存的是 +01:00，即使字段名叫“用户时区”，也不能推断它能自动处理夏令时。

用 getTransitions() 读出切换前后的证据

传入 Unix 时间戳区间后，返回数组中的每一项都有明确含义：timestamp 是切换点，time 是可读时间，offset 是切换后的秒偏移，isdst 表示是否处于夏令时，abbr 是缩写。不要只打印 time，排查时偏移和时间戳更有用。

$begin = (new DateTimeImmutable('2026-01-01T00:00:00Z'))->getTimestamp();
$end = (new DateTimeImmutable('2027-01-01T00:00:00Z'))->getTimestamp();

$transitions = $zone->getTransitions($begin, $end);
if ($transitions === false) {
    throw new RuntimeException('时区没有可用的地区过渡记录');
}

foreach ($transitions as $row) {
    printf("%s offset=%d isdst=%s abbr=%s\n",
        $row['time'], $row['offset'], $row['isdst'] ? 'yes' : 'no', $row['abbr']);
}

这里的第一行可能只是查询起点的状态，并不代表当天发生了一次切换。真正的切换应结合相邻行的 offset 变化判断。

缺口时间和重复时间如何做二次验收

夏令时开始时，钟表通常会向前跳过一段本地时间；结束时则会回拨，某段本地时间出现两次。解析器可能会对不明确输入作出修正，所以“对象不为 false”不能单独当作业务验收标准。

function parseLocal(string $input, DateTimeZone $zone): DateTimeImmutable
{
    $value = DateTimeImmutable::createFromFormat('!Y-m-d H:i', $input, $zone);
    $errors = DateTimeImmutable::getLastErrors();

    if ($value === false || ($errors !== false && ($errors['warning_count'] || $errors['error_count']))) {
        throw new InvalidArgumentException('本地时间格式或时区规则不接受');
    }

    if ($value->format('Y-m-d H:i') !== $input) {
        throw new InvalidArgumentException('本地时间被时区规则修正，需人工确认');
    }
    return $value;
}

这段比较能拦住一部分“输入被悄悄调整”的情况。对于回拨造成的重复时间，业务还要要求客户端携带偏移、UTC 时间或一次性选择项，否则单凭 Y-m-d H:i 仍无法唯一定位。

上线前的最小排查清单

• 配置值是否是 IANA 地区标识，而不是把地区名转换成固定偏移后保存。
• 是否记录输入字符串、时区名、解析后的 offset、Unix timestamp 和最终 UTC 值。
• 切换区间是否覆盖业务关心的日期，而不是只查当前小时。
• 测试是否包含正常日期、向前跳跃的缺口时间、回拨后的重复时间。
• PHP 版本和时区数据库更新后，是否重新跑一遍边界样例。

出现异常时先保留原始输入。不要只把结果改成服务器默认时区再重试，那会让问题看似消失，却丢掉用户选择的地区上下文。

常见问题

getTransitions() 为什么返回 false？

常见原因是对象使用了固定 UTC 偏移或缩写，而不是带地区规则的时区。先检查 $zone->getName()，确认传入的是 IANA 标识。

第一条 transition 是不是一次真实切换？

不一定。给定起始时间后，返回结果通常会先给出起点时刻的状态，之后的行才是区间内发生的变化；应比较相邻行的 offset 和 isdst。

为什么 parse 成功还要比较格式化结果？

日期解析会对部分不合法或不存在的本地时间作修正。回格式后与原字符串比较，可以发现这种静默变化，再交给业务决定是否接受。

数据库里该保存时区名还是偏移？

用户地区和日程规则建议保存 IANA 时区名；事件发生瞬间还应保存 UTC 时间。固定偏移只能作为外部输入或已经明确的协议字段。

总结

排查夏令时不靠猜某个日期的偏移，而是先确认时区对象的类型，再用 getTransitions() 输出区间证据，最后对本地输入做格式回检和重复时间处理。这样日志里既有用户看到的时间，也有能复算的 offset 与 UTC 结果。