PHP DateTimeImmutable 修改日期后为什么原对象没有变化

如果你写过下面这种 PHP 代码，可能会遇到一个很容易误判的现象：调用 DateTimeImmutable::modify() 以后，原变量打印出来还是旧日期。原因不是修改失败，而是这个类的设计就是不可变对象：修改方法返回一个新对象，原对象不会被改写。

把 modify()、add()、sub() 或 setDate() 的返回值接住，才是真正完成了修改；如果只调用方法而不接返回值，后续代码仍然拿到旧对象。

为什么调用 modify() 后原变量没有变化

DateTimeImmutable 的核心区别是“修改产生新对象”。PHP 手册对它的描述很明确：它和 DateTime 的行为大体相同，但调用修改方法时会返回新对象。这样做的好处是，一个基准日期可以安全地被多个业务分支复用，不会因为某个分支提前加了几天而污染其他分支。

因此，下面的调用只创建了一个临时返回值，$base 仍然指向原来的日期：

modify('+7 days');

echo $base->format('Y-m-d'); // 仍然是 2026-09-01

这不是引用传递失效，也不是 format() 缓存了旧结果，而是方法调用的返回对象没有被保存。

正确写法是接住返回值，而不是继续盯着原对象

最直观的写法是新建变量。这个写法适合需要同时保留原日期和计算日期的场景，例如订单创建时间与七天后的提醒时间：

modify('+7 days');

echo $createdAt->format('Y-m-d H:i:s'); // 2026-09-01 10:30:00
echo $remindAt->format('Y-m-d H:i:s');  // 2026-09-08 10:30:00

如果业务只关心“当前变量经过多次变更后的结果”，可以重新赋回同一个变量：

modify('+7 days');
$deadline = $deadline->setTime(18, 0);

echo $deadline->format('Y-m-d H:i:s');

链式调用也可以，但不要为了“短”而牺牲调试性。日期规则复杂时，拆成几个有含义的变量更容易定位是哪一次变更出了问题。

DateTime 和 DateTimeImmutable 应该怎么选

DateTime 的修改方法会直接改变对象；DateTimeImmutable 则返回新对象。两者都能完成日期运算，真正的选择点在于：这个日期对象是否会被多个调用方共享，以及函数是否应该拥有修改输入对象的副作用。

在函数边界上，不可变对象尤其适合表达“输入是一个值，输出是另一个值”。调用者不会因为传入一个日期而担心函数偷偷把它改掉。若项目已经大量使用 DateTime，也不必一次性全量替换，可以先从跨层传递、缓存键、账期计算等容易受共享状态影响的地方开始。

月末运算和无效 modifier 需要单独处理

不可变只解决“对象是否被原地修改”，并不改变日期字符串本身的日历规则。比如从 1 月 31 日执行 +1 month，结果可能跨到 3 月，而不是简单得到 2 月 31 日，因为 2 月没有这个日期。涉及账期、订阅到期日时，应该先明确产品规则，是“加一个自然月”还是“落在目标月最后一天”，再决定使用 modify() 还是基于月份和天数自行封装。

另外，PHP 8.3 起，DateTimeImmutable::modify() 遇到无效日期时间字符串会抛出 DateMalformedStringException；更早版本的行为是警告并返回失败值。不要把用户输入直接拼进 modifier 后忽略错误，至少要在输入校验和异常处理层留下清晰边界：

modify($modifier);
} catch (DateMalformedStringException $exception) {
    throw new InvalidArgumentException('日期调整规则无效', 0, $exception);
}

常见问题

只想修改原变量，为什么还要赋值？

因为 DateTimeImmutable 的“修改”结果就是返回的新对象。重新赋值不是多余动作，而是把业务状态从旧对象切换到新对象。

可以直接把 DateTimeImmutable 当作 DateTime 用吗？

不能假设两者的副作用相同。方法名相似，但 DateTime 会修改自身，DateTimeImmutable 不会；迁移时必须检查调用方是否依赖原对象变化。

modify() 和 add() 应该选哪个？

固定的天、月、年间隔更适合用 DateInterval 配合 add() 或 sub()；需要表达“下周一”“本月最后一天”等自然语言规则时再使用 modify()，并为月末边界写测试。

参考：PHP DateTimeImmutable 手册、DateTimeImmutable::modify()、DateTime::modify()。