PHP DateTimeZone transitions 怎样查看夏令时切换

遇到“某个地区什么时候切到夏令时”这类问题时，最稳妥的做法不是手工猜日期，而是让 DateTimeZone 按 IANA 时区规则返回指定时间范围内的过渡记录。核心方法是 getTransitions()：结果里的 ts、time、offset、isdst 和 abbr 可以共同说明切换发生在哪里、偏移变成多少，以及是否正在使用夏令时。

官方资料：https://www.php.net/manual/en/datetimezone.gettransitions.php

先用 IANA 标识（例如 Europe/London）创建时区，再传入明确的起止 Unix 时间戳。返回数组的第一项可能是时间窗口起点的当前状态，不能把它无条件当成一次夏令时切换。

问题现场：为什么只格式化日期看不出切换

如果代码只保存“2026-03-29 01:00”这样的本地字符串，就很难判断它对应的是切换前还是切换后的偏移。夏令时变化本质上是时区规则在时间轴上的过渡，应该先读取规则记录，再决定如何展示。

DateTimeZone 支持三类时区对象：IANA 标识、固定 UTC 偏移和缩写。只有 IANA 标识携带完整的历史规则，固定偏移或缩写对象没有可供 getTransitions() 查询的过渡表；调用时可能得到 false。因此，业务输入应优先保存类似 Europe/London、America/New_York 的标识，而不是只保存 +01:00。

先确认查询对象，再限定时间范围

先把用户输入转换为 DateTimeZone，然后用 UTC 时间点计算查询窗口。时间戳是绝对时间，窗口不会因为服务器默认时区不同而改变；查询结果中的 time 则是可读的时间字符串。

下面的示例只查询一个年度窗口，并把每条记录整理成业务更容易消费的数组。时间范围可以按报表周期、预约周期或日志保留周期调整。

getTransitions($begin->getTimestamp(), $end->getTimestamp());
if ($transitions === false) {
    throw new RuntimeException('当前时区不包含可查询的过渡表');
}

foreach ($transitions as $transition) {
    // ts 是时间轴上的 Unix 时间戳，offset 是相对 UTC 的秒数。
    $offsetHours = $transition['offset'] / 3600;
    $state = $transition['isdst'] ? '夏令时' : '标准时';
    printf(
        "%s | %s | UTC%+.1f | %s | %s\n",
        $transition['time'],
        $transition['abbr'],
        $offsetHours,
        $state,
        $transition['ts']
    );
}

这里故意检查了 false，因为返回值并不总是数组。若改成固定偏移对象，不能继续假设结果里存在过渡记录。另一个容易忽略的点是：给出 timestampBegin 后，返回数组的第一项可能是窗口起点对应的当前状态，后续项才是窗口内真正发生的变化。

动手验证：怎样从字段判断夏令时切换

每个过渡数组至少要从四个字段一起看：

• ts：绝对时间点，适合排序、比较和关联日志。
• time：便于阅读的时间字符串，PHP 8.2 及更新版本的格式与旧版本略有差异。
• offset：相对 UTC 的秒数，比较前后两项即可看到偏移变化。
• isdst 与 abbr：前者表示是否启用夏令时，后者提供该规则下的缩写。

判断“发生了切换”时，不要只判断 isdst 是否为 true。从夏令时回到标准时的记录会把它改回 false；某些地区的偏移变化也不应仅靠缩写推断。更稳的做法是按 ts 排序，比较相邻记录的 offset 和 isdst，再把业务标签建立在规则变化上。

定位原因：过渡记录的时间与页面显示不是两条时间轴

getTransitions() 给出的 ts 是时间轴上的点，而用户页面通常需要显示某个地区的本地时间。可以先用 UTC 保存和比较，再用 setTimezone() 生成面向读者的显示对象。

DateTimeImmutable::setTimezone() 返回一个新对象，不会修改原对象，也不会改变底层时间点。它改变的是时区和格式化结果。把这个区别保留下来，才能避免把“显示成凌晨两点”误判为“时间被加了一个小时”。

getTransitions(
    (new DateTimeImmutable('2026-01-01', new DateTimeZone('UTC')))->getTimestamp(),
    (new DateTimeImmutable('2027-01-01', new DateTimeZone('UTC')))->getTimestamp()
);

if ($transitions === false) {
    throw new RuntimeException('无法读取该对象的时区过渡');
}

foreach ($transitions as $transition) {
    // 先按 Unix 时间戳定位同一个瞬间，再生成本地显示文本。
    $instant = (new DateTimeImmutable('@' . $transition['ts']))->setTimezone($zone);
    $label = $transition['isdst'] ? '夏令时' : '标准时';

    printf(
        "%s | %s | %s | offset=%d | %s\n",
        $instant->format('Y-m-d H:i:s P'),
        $label,
        $transition['abbr'],
        $transition['offset'],
        $transition['time']
    );
}

示例中 @ 形式先把时间戳解释为 UTC 时间点，再调用 setTimezone() 转换显示时区。这样日志关联仍可使用 ts，页面展示则使用格式化后的 Y-m-d H:i:s P。

修复方案：把非法时区、无过渡表和空窗口分开处理

稳定的接口至少需要区分三种情况：时区名称完全非法；时区对象合法但类型不含过渡表；时区和窗口都合法，但窗口内没有后续变化。它们对应的处理方式不同，不能统一返回“没有夏令时”。

 $end) {
        throw new InvalidArgumentException('查询起点不能晚于终点');
    }

    // 只有带规则的时区对象才适合读取过渡表。
    $transitions = $zone->getTransitions($begin, $end);
    if ($transitions === false) {
        return [];
    }

    // 调用方可根据 count 判断窗口内是否只返回了起始状态。
    return $transitions;
}

PHP 8.3 及更新版本对非法时区使用更具体的 DateInvalidTimeZoneException；如果项目要兼容更早版本，应按实际运行版本设计异常捕获。无过渡表返回空数组只是接口层的选择，调用方仍应在响应中说明“该对象没有可查询的时区过渡”，不要让读者误以为该地区永远没有夏令时。

复查结果：用一份小清单避免误读

1. 输入保存的是 IANA 时区标识，而不是只有偏移值的字符串。
2. 查询窗口使用绝对 Unix 时间戳，并明确了起点和终点。
3. 第一条记录按“窗口起始状态”理解，后续记录再作为窗口内过渡。
4. 判断切换同时参考 offset、isdst 和 abbr，不依赖单一字段。
5. 保存与比较使用时间戳，展示时才调用 setTimezone()。
6. 非法时区、无过渡表和窗口内无变化分别给出不同提示。

常见追问是：为什么返回的第一项看起来不像切换？因为传入起始时间后，PHP 文档允许第一项表示该时刻已经生效的状态；为什么固定 +08:00 查不到夏令时？因为固定偏移没有历史规则；为什么换了时区后原对象没变？因为 DateTimeImmutable 的 setTimezone() 返回新对象。把这三点分开，基本就能避免大多数时区过渡误读。