PHP DateTimeImmutable 月末加一个月的溢出处理方法

PHP 的 DateTimeImmutable 直接执行 modify('+1 month') 时，并不是“把日期裁剪到目标月最后一天”。例如 1 月 31 日加一个月，目标月份没有 31 日，结果会继续向后溢出到 3 月。需要月末口径时，直接写出 last day of next month，并保留返回的新对象。

月末加一个月为什么会到三月

默认的月份运算先把月份加一，再处理原来的日号。下面的代码只用于展示这个规则，不代表月末账期的最终实现：

modify('+1 month');

echo $date->format('Y-m-d'), PHP_EOL; // 原对象仍是 2015-01-31
echo $next->format('Y-m-d'), PHP_EOL; // 结果会进入 2015-03
?>

这里有两个容易混淆的点：第一，结果不是错误，而是 PHP 日期算术对月份长度差异的处理；第二，DateTimeImmutable 不会原地改写 $date，必须接住返回值。闰年时同样的起点会因为二月多一天而得到不同的溢出日期。

需要目标月末时改用 last day of

账单周期、订阅续期和月度报表通常关心“下个月最后一天”，而不是保留 31 这个日号。此时把规则写进修饰语，代码更容易复核：

modify('last day of next month');

if ($monthEnd === false) {
    // 无效修饰语在不同 PHP 版本上的表现不同，调用方要保留错误分支。
    throw new RuntimeException('无法计算目标月份的最后一天');
}
echo $monthEnd->format('Y-m-d'); // 2015-02-28
?>

把起点换成闰年 1 月 31 日，结果会是 2 月 29 日。这个写法的价值不在于“修正一个特殊日期”，而在于把业务要求从隐含的猜测变成可读的日期规则。

DateInterval 和相对修饰语怎么选

如果需求是“增加一个固定月份间隔”，可以使用 DateInterval；如果需求是“目标月的最后一天”，相对修饰语更直接。两者不是同一个语义：

不要为了让输出“看起来像月底”而在最后一步盲目减一天。先确定账期是按自然月、固定天数，还是目标月末，再选表达方式。否则测试只覆盖 1 月 31 日，换到 3 月 31 日、闰年或连续调用时仍可能暴露问题。

写进生产代码前的检查清单

建议至少覆盖四组输入：普通月份的月末、闰年 2 月前的月末、月中日期和连续计算。每组都记录起点、表达式、期望日期和原对象是否保持不变。对来自用户或配置的修饰语，不要直接拼接未受控文本；无效值应在进入日期计算前被拒绝。

PHP 8.3 起，modify() 对无效日期修饰语会抛出 DateMalformedStringException；更早版本可能表现为警告并返回失败值。文章示例把异常分支保留下来，实际项目应按运行环境统一封装。

常见问题

DateTimeImmutable 的 modify() 会改变原变量吗？

不会。它返回一个新的 DateTimeImmutable 对象；不接收返回值时，原变量仍表示原来的时间点。

为什么 2015 年 1 月 31 日加一个月不是 2 月 28 日？

因为默认的 +1 month 仍尝试保留 31 这个日号，缺少该日号的月份会发生溢出。要取目标月末，应显式使用 last day of next month。

连续执行两次 +1 month 有什么风险？

每次计算都以新的日期为起点，月末溢出可能让结果偏离按自然月计费的预期。需要固定账期时，应保存明确的锚点和月末规则。