想象一下，你正在开发一个面向美国用户的日程管理系统、电商促销平台，或者任何需要考虑节假日的业务应用。计算节假日，尤其是那些每年日期不固定的节假日（比如复活节、感恩节），简直是一场噩梦！你需要考虑各种规则，例如特定月份的第N个星期X、联邦假日和银行假日的观察日调整、闰年等等。手动维护这些逻辑不仅耗时，还极易出错，一个小小的日期偏差就可能导致业务逻辑错误，影响用户体验甚至造成经济损失。

我曾经也深陷这样的困境。为了确保节假日计算的准确性，我不得不查阅大量的日历和规定，然后编写冗长且难以维护的条件判断代码。每次遇到新的节假日或者规则变更，都意味着又一轮痛苦的修改和测试。这不仅拖慢了开发进度，也让代码库变得越来越臃肿和脆弱。

Composer在线学习地址：学习地址

幸运的是，PHP生态系统拥有强大的包管理工具 Composer，它让我们可以轻松地引入成熟的解决方案。今天，我们要介绍的英雄就是 geoffreyrose/us-holidays。

geoffreyrose/us-holidays：你的节假日管理专家

geoffreyrose/us-holidays 是一个为 Carbon DateTime 库设计的美国节假日包装器。它扩展了 Carbon，并内置了对42个常用美国节假日的支持，包括：

• 固定日期节假日： 新年、圣诞节、独立日等。
• 浮动日期节假日： 复活节、感恩节、父亲节、母亲节、马丁·路德·金纪念日等。
• 特殊节假日： 银行假日、联邦假日（考虑周末顺延规则）。

这意味着你不再需要自己去计算这些节假日的日期，或者担心它们是否会因为周末而调整。这个库会为你处理所有这些复杂的逻辑。

如何通过 Composer 引入并使用？

使用 geoffreyrose/us-holidays 非常简单，只需通过 Composer 即可安装：

composer require geoffreyrose/us-holidays

安装完成后，你就可以在你的PHP代码中使用了。

基本用法

首先，引入 USHolidays 类：

use USHolidays\USHolidays;

// 创建一个指定日期的 USHolidays 实例
$holidays = USHolidays::create(2025, 1, 1); // 从2025年1月1日开始计算

获取特定年份的所有节假日

你可以轻松获取某个年份的所有节假日列表：

$holidays2025 = USHolidays::create(2025, 1, 1);
$allHolidays = $holidays2025->getHolidaysByYear('all');

echo "2025年的所有节假日：\n";
foreach ($allHolidays as $holiday) {
    echo "- " . $holiday['name'] . " (" . $holiday['date']->format('Y-m-d') . ")，是否银行假日：" . ($holiday['bank_holiday'] ? '是' : '否') . "\n";
}
/*
部分输出示例：
- New Year's Day (2025-01-01)，是否银行假日：是
- Martin Luther King Jr. Day (2025-01-16)，是否银行假日：是
...
*/

检查特定日期是否为节假日

这是最常用的功能之一，可以判断某个日期是否是普通节假日、银行假日或联邦假日：

$christmasDay = USHolidays::create(2025, 12, 25); // 2025年12月25日是星期一
if ($christmasDay->isHoliday()) {
    echo $christmasDay->getHolidayName() . " 是一个节假日！\n"; // 输出：Christmas Day 是一个节假日！
}

$newYearsDay2025 = USHolidays::create(2025, 1, 1); // 2025年1月1日是星期日
echo "2025年1月1日是否是银行假日？" . ($newYearsDay2025->isBankHoliday() ? '是' : '否') . "\n"; // 输出：否 (因为是周末)

$newYearsDayObserved2025 = USHolidays::create(2025, 1, 2); // 2025年1月2日是星期一 (新年观察日)
echo "2025年1月2日是否是联邦假日？" . ($newYearsDayObserved2025->isFederalHoliday() ? '是' : '否') . "\n"; // 输出：是

这个库能智能地处理节假日因周末而顺延的“观察日”逻辑，这对于需要精确计算工作日的业务（如银行、政府服务）至关重要。

获取未来N天/年的节假日

如果你需要提醒用户即将到来的节假日，这个功能会非常有用：

$today = USHolidays::create(2025, 10, 20); // 假设今天是2025年10月20日
$upcomingHolidays = $today->getHolidaysInDays(90, 'all'); // 获取未来90天内的所有节假日

echo "未来90天内的节假日：\n";
foreach ($upcomingHolidays as $holiday) {
    echo "- " . $holiday['name'] . " (" . $holiday['date']->format('Y-m-d') . ")\n";
}
/*
部分输出示例：
- Thanksgiving (2025-11-23)
- Black Friday (2025-11-24)
- Christmas Eve (2025-12-24)
- Christmas Day (2025-12-25)
*/

Laravel 集成

如果你在使用 Laravel 框架，这个库更是锦上添花。它支持 Laravel 的包自动发现功能，你无需手动配置 ServiceProvider 和 Facade，可以直接通过 USHolidays::getHolidaysByYear() 等方式使用，非常方便。

优势与实际应用效果

1. 简化复杂逻辑： 彻底摆脱手动编写和维护复杂的日期计算逻辑，让你的代码更简洁、更易读。
2. 提高准确性： 避免人为错误，确保节假日计算的准确性，尤其是在处理银行假日和联邦假日的观察日时。
3. 节省开发时间： 快速集成，将更多精力投入到核心业务逻辑的开发，而不是耗费在节假日计算上。
4. 易于维护： 节假日规则的更新和维护由库的开发者负责，你的应用只需定期更新库版本即可，大大减少了你的维护负担。
5. 广泛的应用场景：
   • 电商平台： 自动调整节假日期间的订单处理、物流发货时间，设置节假日促销活动。
   • 金融系统： 精确计算工作日、银行假日，用于处理支付结算、贷款到期日等。
   • 日程管理/项目管理： 在日历中自动标记节假日，避免在节假日安排会议或任务。
   • HR系统： 管理员工假期、考勤，计算节假日加班费等。

结语

geoffreyrose/us-holidays 库结合 Composer 的强大功能，为PHP开发者提供了一个优雅、高效的美国节假日管理方案。它将那些令人头疼的日期计算细节封装起来，让你能够专注于业务本身，而无需再为节假日问题而烦恼。如果你还在手动处理美国节假日，那么是时候拥抱这个强大的工具了！赶快通过 Composer 将它引入你的项目，体验一下前所未有的开发效率和准确性吧！