PHP DateTimeImmutable 修改月份后为什么日期会跳到下个月

如果日期是 2025-01-31，直接调用 $date->modify('+1 month')，结果可能是 2025-03-03，而不是很多人期待的 2025-02-28。这不是 DateTimeImmutable 失效，也不是不可变对象被改写，而是 PHP 按“保留日号、再做日历归一化”的相对日期规则处理了一个并不存在的 2 月 31 日。

为什么 +1 month 会跨过目标月份

月份并不是固定天数。PHP 的相对日期解析会先把月份加一，同时保留原来的日号。于是 1 月 31 日加一个月，内部会先得到“2 月 31 日”这个中间状态，再把超出 2 月的天数继续归一化到 3 月。平年 2 月只有 28 天，所以 31 日会多出 3 天，结果就是 3 月 3 日；闰年则会落在 3 月 2 日。

官方示例也专门提醒了这一点：从 2000-12-31 连续加月，会先得到 2001-01-31，再得到 2001-03-03。这里的关键不是“加月失败”，而是“加月”没有承诺把日期夹到目标月末。

modify('+1 month');

echo $source->format('Y-m-d'), PHP_EOL; // 2025-01-31
echo $next->format('Y-m-d'), PHP_EOL;   // 2025-03-03
?>

因此排查时要同时记录输入日期、modifier 字符串和每一次返回值。只看最后一个日期，很容易把“不可变对象没有生效”和“月份溢出”混为一谈。

先确定你要的是自然日还是月底日

迁移旧的 DateTime 代码时，先不要机械地把类型替换成 DateTimeImmutable。真正要确认的是业务规则：会员续费可能要求“同一日号，遇到短月再按约定处理”；月末结算往往要求“下个月最后一天”；固定扣款日则可能要求保留 15 日或 20 日。三者都叫“下个月”，但实现完全不同。

用显式规则固定月底语义

如果产品定义的是“本月最后一天对应下月最后一天”，直接把规则写进 modifier 更清楚。它表达的是目标月末，而不是先构造一个无效的目标日期再等待归一化。

modify('last day of next month');

echo $nextBillingDate->format('Y-m-d'), PHP_EOL; // 2025-02-28
?>

如果业务要求“尽量保留原日号，短月时降到月末”，可以把年份和月份先移动，再用当月天数做上限。这样规则可测试，也不会把溢出继续带进下一个月：

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

    // 原日号存在就保留，不存在就降到目标月末。
    return $targetMonth->setDate(
        (int) $targetMonth->format('Y'),
        (int) $targetMonth->format('m'),
        min($day, $lastDay)
    );
}

echo addMonthClamped(new DateTimeImmutable('2025-01-31'))
    ->format('Y-m-d'); // 2025-02-28
?>

迁移时要补的回归检查

至少把 1 月 31 日、平年 2 月 28 日、闰年 2 月 29 日、跨年 12 月 31 日放进测试表。还要测试连续两次加月，因为第一次返回的新对象会成为第二次调用的基准；如果产品要保持“月末身份”，连续调用应始终落在各自目标月的最后一天。

另外，PHP 8.3 起，传入无法解析的 modifier 会抛出 DateMalformedStringException；旧代码若依赖 warning 或返回值判断，也应在迁移清单中单独检查。这个变化与月底溢出是两件事，不要用异常处理去掩盖日期规则没有定义的问题。

相关问题

DateTimeImmutable::modify 会改变原对象吗？

不会。它返回新的 DateTimeImmutable，原对象保持不变；要使用新日期，必须接住返回值。

为什么 2024 年 1 月 31 日加月不是 2 月 29 日？

因为相对加月先保留 31 日，再处理无效的 2 月 31 日，闰年会把溢出归一化到 3 月 2 日。若目标是月末，应使用显式月末规则。

固定扣款日应该选哪种实现？

先写清短月策略：降到月末、顺延到下一个有效日，还是直接报错。文章中的 addMonthClamped 只代表“降到月末”，不能替代所有扣款规则。