PHP DatePeriod 的 recurrences 为什么不等于实际日期总数

如果你把 DatePeriod::$recurrences 直接当成日期总数，报表很容易少算或多算。PHP 这里其实有三个不同的计数入口：构造函数里的重复次数、公开的 recurrences 属性，以及真正遍历出来的日期项。按结束日期构造时，前两个入口甚至都不能代表最终总数。

官方文档：https://www.php.net/manual/en/class.dateperiod.php

业务上要统计“实际产生了多少个日期”，最稳妥的依据是实际迭代结果；recurrences 更适合用来描述周期对象的计数语义或最小返回数量。

先分清三个计数入口

DatePeriod 可以按“开始日期 + 间隔 + 重复次数”构造，也可以按“开始日期 + 间隔 + 结束日期”构造。两种写法都能被 foreach 遍历，但计数属性的来源不同：

• $period->getRecurrences() 返回显式传给构造函数的重复次数；没有显式传入时返回 null。
• $period->recurrences 是迭代器返回实例数的最小值。显式传入重复次数时，默认包含开始日期，所以通常比参数多 1。
• foreach 或转换后的数组长度，才是这一次周期实际产出的日期项数量。

按重复次数构造时，属性为什么会多一项

下面把重复次数设为 2，开始日期默认参与结果。这里的“2 次重复”不是“总共返回 2 项”，而是从开始日期之后再产生 2 个间隔点，因此遍历会得到 3 项。

recurrences,
    $period->getRecurrences(),
    count($dates)
);
// property=3, explicit=2, actual=3

因此，显式次数场景可以记成：实际总数 = recurrences 参数 + 是否包含开始日期。如果业务只关心最终日期数，建议统一遍历并计数，不要把这个加一规则散落在各个调用方。

按结束日期构造时，属性只是一个下界

换成结束日期后，构造函数没有收到显式的重复次数。此时 getRecurrences() 返回 null，而公开属性只表达“至少会返回多少个实例”的下界。以每天一个日期、开始日期为 1 月 1 日、结束日期为 1 月 4 日为例，默认不把结束日期放进集合，实际会得到 1 月 1 日、2 日、3 日三项。

recurrences);       // 1：最小返回数量
var_dump($period->getRecurrences());  // NULL：没有显式重复次数
var_dump(count($dates));              // 3：本次实际日期项数量

这里的关键不是记住某个固定数字，而是区分“对象声明的下界”和“本次迭代产生的集合”。周期、间隔或边界发生变化后，属性仍可能只提供下界，业务总数仍应从迭代结果得到。

业务代码应该怎样统计

如果需要展示总天数、生成报表或判断是否为空，推荐把计数动作集中在消费周期的地方：

若还要保存日期数组，可以使用 iterator_to_array() 后读取 count()；若周期可能很长，直接循环计数更节省内存。无论采用哪种方式，都把 recurrences 当作语义信息，不把它当成已经遍历完成的结果。

常见问题

getRecurrences() 和 recurrences 是不是重复 API？

不是。前者回答“构造时是否显式设置了多少次”，后者回答“迭代器至少会返回多少项”。按结束日期构造时，一个会是 null，另一个仍可能有最小值。

为什么不直接用结束日期减开始日期计算数量？

日期间隔可能不是固定天数，时间对象还可能包含时分秒和时区。直接遍历得到的集合才是 DatePeriod 实际交付给业务的结果。

小结

记住三句话即可：显式 recurrences 是构造输入；公开属性是迭代结果的最小语义值；实际日期总数要以遍历结果为准。这样既能解释“为什么属性和总数不同”，也能避免在统计代码里依赖错误的加一规则。