PHP IntlCalendar 怎样读取指定时区的月份天数

在 PHP 中按月份读取天数，不建议自己维护“4 月、6 月、9 月、11 月”的判断表。使用 IntlCalendar 时，先把日历对象的时区和年月上下文设好，再对 FIELD_DAY_OF_MONTH 调用 getActualMaximum()，就能得到当前月份实际允许的最大日期。闰年二月会返回 29，普通二月会返回 28，大小月也由日历规则处理。

官方地址：https://www.php.net/

本文只讨论按指定时区读取月份天数，不延伸到节假日、工作日或地区化日期字符串格式化。

先把日历和时区上下文固定下来

IntlCalendar 属于 PHP 的 intl 扩展，底层日历和时区语义来自 ICU。时区不是装饰信息：它会影响日历对象当前时间对应的字段值。因此，业务代码最好在创建对象时就明确传入时区。

set(IntlCalendar::FIELD_YEAR, 2024);
$calendar->set(IntlCalendar::FIELD_MONTH, 1);
$calendar->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1);

// 读取对象当前绑定的时区，便于在业务日志中确认上下文。
$timezone = $calendar->getTimeZone();
if ($timezone === false) {
    throw new RuntimeException('无法读取 IntlCalendar 时区');
}
echo $timezone->getID();
?>

这里把月份设为 1，表示公历二月，而不是人类习惯中的数字 2。这个索引差异是最容易造成月份天数错误的地方。setTimeZone() 也可以接收时区字符串，但修改时区会保留对象代表的瞬时时刻，同时改变本地字段值；如果你关心的是某个业务日期，应在设置年月后再读取结果。

用 FIELD_DAY_OF_MONTH 查询当月实际天数

查询月份天数的关键只有一行：$calendar->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)。它根据日历对象的当前时间和字段上下文返回实际最大值，返回类型是整数或失败时的 false。

getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH);

// 失败时返回 false；不要把失败值直接拼进页面或参与日期计算。
if ($daysInMonth === false) {
    throw new RuntimeException('无法读取当前月份的最大日期');
}

echo "当前月份共有 {$daysInMonth} 天";
?>

对于 2024 年二月，日历上下文会把实际最大日期确定为 29；把年份换成 2023 年，同一字段查询得到的实际最大日期就是 28。这里的结果不是固定常量，而是当前日历、年份、月份和日历体系共同决定的值。

不要把 getMaximum() 当成当月天数

getMaximum() 和 getActualMaximum() 名称相似，但回答的问题不同：

因此，生成月末日期、校验用户输入的日号或计算某月可选日期时，应围绕 getActualMaximum() 建立判断。只有在研究日历字段本身的规则边界时，才使用另外两个方法。

时区、月份索引和失败值的三个边界

时区要使用 ICU 能识别的标识

setTimeZone() 可以接收 DateTimeZone、IntlTimeZone 或字符串。字符串应是 ICU 可识别的时区标识，例如 Asia/Shanghai；也可以使用形如 GMT+08:30 的显式偏移。生产代码不要依赖服务器默认时区，否则同一日期在不同部署环境中可能落入不同的月份字段。

FIELD_MONTH 从零开始

这是 ICU 日历字段的约定。给二月设置 1，给十二月设置 11。如果业务输入是 1 到 12 的自然月份，应在写入字段前减一，并在范围外输入时直接拒绝。

把 false 当作失败处理

官方方法签名允许返回 false。不要用宽松比较把它当作数字 0，也不要把异常的返回值继续传给日期格式化器。对时区创建、字段设置和最大值读取分别保留明确的失败处理，排查时更容易定位。

常见问题

为什么不用 cal_days_in_month()？

cal_days_in_month() 适合直接按历法、年份和月份计算天数；IntlCalendar 更适合已经在使用 ICU 日历对象、时区和地区规则的代码。选择哪一个取决于调用链是否需要保留日历对象上下文。

setTimeZone() 会改变时间戳吗？

PHP 手册说明，设置新时区会保留对象代表的瞬时时刻，但本地字段值会随时区变化。读取月份天数前，要确认你要的是同一瞬时刻在目标时区下的月份，还是一个独立的业务日期。

小结

按指定时区读取 PHP IntlCalendar 的月份天数，可以记住三点：先创建明确时区的日历对象；月份字段按 ICU 规则从零开始；读取当月天数时使用 FIELD_DAY_OF_MONTH 加 getActualMaximum()，不要误用 getMaximum()。这样闰年二月、大小月和多环境部署的日期边界都交给日历规则处理。