PHP DateTimeImmutable 修改月份为何会跳变：modify 与月末日期边界

订单系统把“下个月同一天”写成 $date->modify('+1 month') 后，1 月 31 日的续费时间可能直接落到 3 月。问题不在 DateTimeImmutable 修改了原对象，而在 PHP 按日历字段推进月份时，目标月份没有原来的日期，溢出天数会继续向后计算。

月度周期如果要求“不超过目标月最后一天”，不要把 +1 month 当成月末策略；先确定目标年月，再用目标月天数限制日值。

为什么 +1 month 会从一月跳到三月

先看一个最小复现。这里使用 2024 年，是为了把闰年的边界也放进验收范围：

modify('+1 month');

echo $date->format('Y-m-d'), PHP_EOL;
echo $next->format('Y-m-d'), PHP_EOL;
// 2024-01-31
// 2024-03-02

目标月份是 2 月，最多只有 29 天。解析器保留“31 号”这个日字段，再把多出的 2 天继续推入 3 月，于是结果是 3 月 2 日。PHP 手册的示例也展示了同一种规则：2000-12-31 连续两次加月后会从 1 月 31 日跳到 3 月 3 日。

图：DateTimeImmutable、2024-01-31、modify('+1 month') 与 2024-03-02 的溢出路径。

先确认业务要的是自然月还是固定天数

这一步别急着换 API。账单日、会员续期日通常需要“目标月同日，遇到月末取最后一天”；而“30 天后提醒”是固定时长，两者不是同一个问题。

DateTimeImmutable 的不可变特性很适合把每一步保存成变量：原始日期、目标月份和最终结果互不覆盖，日志里也能看出是哪一步改变了值。

用目标年月和合法日值实现月末钳制

下面的函数保留原日期的时间和时区，只把月份推进一格，并把日限制到目标月的最后一天。关键点是先把日期锚定到目标月的第一天，避免原始日值参与溢出。

modify('first day of next month');
    $daysInMonth = (int) $targetMonth->format('t');
    $day = min((int) $date->format('d'), $daysInMonth);

    return $targetMonth->setDate(
        (int) $targetMonth->format('Y'),
        (int) $targetMonth->format('m'),
        $day
    );
}

$result = sameDayOrLastDayNextMonth(new DateTimeImmutable('2024-01-31'));
echo $result->format('Y-m-d'); // 2024-02-29

这里的 targetMonth 已经是目标月第一天，daysInMonth 给出该月合法上限，min 选择原日和上限中较小的值，最后由 setDate 组成新对象。

图：targetMonth → daysInMonth → min → setDate 的稳定计算路径。

常见误区：不可变不等于不会溢出

把原对象是否变化当成日期是否正确

DateTimeImmutable 确实不会修改 $date，但它返回的新对象仍然遵循日历溢出规则。不可变解决的是状态覆盖问题，不会替业务决定“月末怎么处理”。

连续调用 modify 计算多个账期

如果第一次已经从月末跳到了下月，第二次调用是在错误的基准上继续计算。应保留原始日或直接按账期序号计算目标年月，避免误差逐期累积。

忽略时区和时间部分

月度日历规则与时区仍有关联。跨时区生成账单时间时，先明确业务时区，再格式化输出；不要用服务器默认时区碰运气。

常见问题

DateTimeImmutable::modify 会修改原变量吗？

不会。它返回一个新的 DateTimeImmutable 对象，原变量仍保持原来的日期。

为什么 2024-01-31 加一个月不是 2024-02-29？

因为 modify('+1 month') 按日历字段推进并处理溢出，31 号超过二月上限后会继续进入三月；需要月末钳制时要显式限制日期。

什么时候可以直接使用 +1 month？

当业务接受自然日历溢出，或输入日期已经避开大小月边界时可以直接使用；账单、续期、排班等月末敏感场景不建议省略规则。

把规则写进测试用例

至少覆盖 1 月 31 日、普通月 30 日、闰年 2 月和非闰年 2 月。测试断言应该写业务结果，例如“2024-01-31 的下月日期是 2024-02-29”，不要只断言对象类型或原变量未变化。