PHP IntlCalendar 的 roll 与 add 对上一级字段有什么区别

排查日期偏移时，最容易误判的是“加一天”到底要不要进入下个月。PHP 的 IntlCalendar 中，add() 会允许当前字段溢出并调整更高字段；roll() 只在当前字段的可用范围内循环，不把溢出带到月份或年份。比如从 2013-06-30 加一天，前者得到 2013-07-01，后者得到 2013-06-01。

官方地址：https://www.php.net/manual/en/class.intlcalendar.php

先从月底症状还原差异

我在处理月末提醒时遇到过这样的现象：同样是给六月最后一天加一天，有的路径进入七月，有的路径却回到六月第一天。表面看像是格式化或时区问题，真正的触发条件却是调用的方法不同。

IntlCalendar::add() 的定义是向指定字段增加一个有符号的时间量；当字段值跨过边界时，更高字段可以跟着变化。IntlCalendar::roll() 也会增加一个有符号值，但它明确不把溢出进位到更重要的字段。下面这张图只表达这个静态行为边界，不是运行截图：

用最小 PHP 示例固定输入和参数

示例把日期固定在 2013 年 6 月 30 日，并使用 FIELD_DAY_OF_MONTH。这里有两个容易忽略的细节：IntlGregorianCalendar 的月份参数从 0 开始，所以六月写成 5；roll(..., true) 表示向上滚动一次，也就是加 1。

add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);

// 重新创建相同输入，单独观察 roll 的不进位行为。
$rollCalendar = new IntlGregorianCalendar(2013, 5, 30);
$rollCalendar->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true);

// 用同一个格式化器输出日期，比较的重点是月份是否发生变化。
$formatter = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::SHORT,
    IntlDateFormatter::NONE,
    'UTC'
);

echo 'add: ' . $formatter->format($addCalendar) . PHP_EOL;
echo 'roll: ' . $formatter->format($rollCalendar) . PHP_EOL;
?>

按 PHP 手册中的行为说明，add() 这条路径会跨到 7 月 1 日；roll() 在六月的日期范围内循环，结果是 6 月 1 日。这里的输出是为了说明 API 语义，配图和代码都不是本机运行截图。

从字段层级定位根因

关键不是“哪个方法更安全”，而是调用者希望改变哪一层。日、月、年是有层级关系的字段：真实时间推进需要允许低位字段带动高位字段；周期内轮转则需要刻意截断这种进位。

因此，看到“六月 30 日加一天变成六月 1 日”时，不要先改格式字符串；先检查代码是否把“自然时间推进”误写成了 roll()。反过来，如果业务就是做一个不改变月份的循环索引，直接换成 add() 才会引入新的边界变化。

按业务边界选择，并建立回归清单

选择方法可以先问一句：结果是否应该代表时间线上的下一个瞬间？如果答案是“是”，用 add()；如果答案是“只移动当前字段，月份或年份必须保持不变”，才用 roll()。这比按“加一天/加一月”的字面描述选方法更可靠。

改动后至少保留四组回归样例：月底加一天、年末加一天、月初向负值回退，以及非边界日期的正负值变化。测试断言要同时看目标字段和上一级字段，不能只比较格式化后的日号；否则 2013-07-01 与 2013-06-01 可能被误读成同一种“第一天”。

相关问题

roll() 是否永远不会改变月份？

对日字段的典型轮转来说，它不会把溢出进位到更高字段；但最终范围仍由日历类型、字段和当前日期决定，不应把“当前字段不进位”扩展成所有字段都不变化。

add() 加一个月时，31 日一定保留吗？

不一定。PHP 手册以 1 月 31 日加一个月为例，结果会调整到目标月份可表示的日期；月长变化正是更高字段和相关字段参与调整的表现。

true 和整数 1 在 roll() 中有什么关系？

true 表示向上滚动，也就是加 1；需要更大步长或反向移动时，直接传入有符号整数更清楚。