PHP DateTimeImmutable 怎样按 ISO 周计算范围

按 ISO 周取范围时，关键不是把日期减到周一，而是先取出 o-W-N 中的 ISO 年和周号，再用 DateTimeImmutable::setISODate() 还原周一。查询范围建议写成“包含周一 00:00:00、不包含下一周周一 00:00:00”的半开区间，这样不会因为微秒精度或 23:59:59 的取舍漏掉数据。

先分清 ISO 年和公历年

日历显示的 1 月 1 日不一定属于 ISO 年的第 1 周。例如某年的 1 月初可能仍然属于上一 ISO 年的第 53 周。PHP 的 format('o') 返回 ISO 周年，format('W') 返回两位周号，format('N') 返回 1 到 7 的周内日。要展示或传递周标识，可以使用 o-\WW-N；不要把 Y-W 当成 ISO 周键。

用 setISODate 计算周一与结束边界

下面的函数只接受已经确定时区的日期对象。它返回周一开始时间和下一周周一的排他结束时间，调用方可以把它直接用于报表条件或接口参数。

format('o');
    $isoWeek = (int) $date->format('W');

    // 第 1 天代表星期一，先还原日期，再统一到当天零点。
    $start = $date
        ->setISODate($isoYear, $isoWeek, 1)
        ->setTime(0, 0, 0);

    // 结束值取下一周周一零点，避免用 23:59:59 截断微秒数据。
    $endExclusive = $start->modify('+7 days');

    return [
        'start' => $start,
        'endExclusive' => $endExclusive,
        'isoKey' => $date->format('o-\WW'),
    ];
}

$date = new DateTimeImmutable(
    '2026-12-31 18:20:00',
    new DateTimeZone('Asia/Shanghai')
);
$range = isoWeekRange($date);

// 业务查询使用左闭右开条件，不需要把结束时刻改成 23:59:59。
printf(
    "%s ~ %s\n",
    $range['start']->format(DateTimeInterface::ATOM),
    $range['endExclusive']->format(DateTimeInterface::ATOM)
);

为什么推荐半开区间

如果把一周写成周一 00:00:00 到周日 23:59:59，字段只要存了微秒，最后一秒仍可能被漏掉；不同数据库的时间精度也会让这个边界不一致。半开区间把问题改成两个稳定的零点：start 且 created_at 。连续周之间没有空隙，也不会重叠。

跨年、时区与不可变对象的检查清单

第一，输入日期的时区要在进入函数前确定。业务按中国自然周，就显式使用 Asia/Shanghai；不要让服务器默认时区决定报表边界。第二，跨年测试要覆盖 12 月末和 1 月初，输出中同时记录 o、W、N。第三，DateTimeImmutable 的修改方法会返回新对象，必须接住返回值；只调用 $date->setISODate(...) 而继续使用旧变量，不会改变旧日期。

常见问题

ISO 周为什么不能直接使用 format('Y-W')？

Y 是公历年，跨年周可能与 ISO 周年不同。周键应使用 o-W，尤其要覆盖元旦前后的日期。

setISODate 会修改原来的 DateTimeImmutable 吗？

不会。它返回新的 DateTimeImmutable，原对象仍保持原来的日期和时间。

结束时间一定要写成周日 23:59:59 吗？

不需要。用下一周周一 00:00:00 作为排他上界，更适合带微秒的字段和连续周查询。