我曾经也深陷这样的困境。为了确保节假日计算的准确性，我不得不查阅大量的日历和规定，然后编写冗长且难以维护的条件判断代码。每次遇到新的节假日或者规则变更，都意味着又一轮痛苦的修改和测试。这不仅拖慢了开发进度，也让代码库变得越来越臃肿和脆弱。
Composer在线学习地址：学习地址
幸运的是，PHP生态系统拥有强大的包管理工具 Composer，它让我们可以轻松地引入成熟的解决方案。今天，我们要介绍的英雄就是 geoffreyrose/us-holidays。
geoffreyrose/us-holidays：你的节假日管理专家
geoffreyrose/us-holidays 是一个为 Carbon DateTime 库设计的美国节假日包装器。它扩展了 Carbon，并内置了对42个常用美国节假日的支持，包括：
立即学习“PHP免费学习笔记（深入）”；
- 固定日期节假日： 新年、圣诞节、独立日等。
- 浮动日期节假日： 复活节、感恩节、父亲节、母亲节、马丁·路德·金纪念日等。
- 特殊节假日： 银行假日、联邦假日（考虑周末顺延规则）。
这意味着你不再需要自己去计算这些节假日的日期，或者担心它们是否会因为周末而调整。这个库会为你处理所有这些复杂的逻辑。
如何通过 Composer 引入并使用？
使用 geoffreyrose/us-holidays 非常简单，只需通过 Composer 即可安装：
composer require geoffreyrose/us-holidays
安装完成后，你就可以在你的PHP代码中使用了。
智能代理搜索。多源检索置信度评分 - 统一API整合网络、学术和Tavily搜索。
基本用法
首先，引入 USHolidays 类：
use USHolidays\USHolidays; // 创建一个指定日期的 USHolidays 实例 $holidays = USHolidays::create(2023, 1, 1); // 从2023年1月1日开始计算
获取特定年份的所有节假日
你可以轻松获取某个年份的所有节假日列表：
$holidays2023 = USHolidays::create(2023, 1, 1);
$allHolidays = $holidays2023->getHolidaysByYear('all');
echo "2023年的所有节假日：\n";
foreach ($allHolidays as $holiday) {
echo "- " . $holiday['name'] . " (" . $holiday['date']->format('Y-m-d') . ")，是否银行假日：" . ($holiday['bank_holiday'] ? '是' : '否') . "\n";
}
/*
部分输出示例：
- New Year's Day (2023-01-01)，是否银行假日：是
- Martin Luther King Jr. Day (2023-01-16)，是否银行假日：是
...
*/检查特定日期是否为节假日
这是最常用的功能之一，可以判断某个日期是否是普通节假日、银行假日或联邦假日：
$christmasDay = USHolidays::create(2023, 12, 25); // 2023年12月25日是星期一
if ($christmasDay->isHoliday()) {
echo $christmasDay->getHolidayName() . " 是一个节假日！\n"; // 输出：Christmas Day 是一个节假日！
}
$newYearsDay2023 = USHolidays::create(2023, 1, 1); // 2023年1月1日是星期日
echo "2023年1月1日是否是银行假日？" . ($newYearsDay2023->isBankHoliday() ? '是' : '否') . "\n"; // 输出：否 (因为是周末)
$newYearsDayObserved2023 = USHolidays::create(2023, 1, 2); // 2023年1月2日是星期一 (新年观察日)
echo "2023年1月2日是否是联邦假日？" . ($newYearsDayObserved2023->isFederalHoliday() ? '是' : '否') . "\n"; // 输出：是这个库能智能地处理节假日因周末而顺延的“观察日”逻辑，这对于需要精确计算工作日的业务（如银行、政府服务）至关重要。
获取未来N天/年的节假日
如果你需要提醒用户即将到来的节假日，这个功能会非常有用：
$today = USHolidays::create(2023, 10, 20); // 假设今天是2023年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 (2023-11-23)
- Black Friday (2023-11-24)
- Christmas Eve (2023-12-24)
- Christmas Day (2023-12-25)
*/Laravel 集成
如果你在使用 Laravel 框架，这个库更是锦上添花。它支持 Laravel 的包自动发现功能，你无需手动配置 ServiceProvider 和 Facade，可以直接通过 USHolidays::getHolidaysByYear() 等方式使用，非常方便。
优势与实际应用效果
- 简化复杂逻辑： 彻底摆脱手动编写和维护复杂的日期计算逻辑，让你的代码更简洁、更易读。
- 提高准确性： 避免人为错误，确保节假日计算的准确性，尤其是在处理银行假日和联邦假日的观察日时。
- 节省开发时间： 快速集成，将更多精力投入到核心业务逻辑的开发，而不是耗费在节假日计算上。
- 易于维护： 节假日规则的更新和维护由库的开发者负责，你的应用只需定期更新库版本即可，大大减少了你的维护负担。
-
广泛的应用场景：
- 电商平台： 自动调整节假日期间的订单处理、物流发货时间，设置节假日促销活动。
- 金融系统： 精确计算工作日、银行假日，用于处理支付结算、贷款到期日等。
- 日程管理/项目管理： 在日历中自动标记节假日，避免在节假日安排会议或任务。
- HR系统： 管理员工假期、考勤，计算节假日加班费等。
结语
geoffreyrose/us-holidays 库结合 Composer 的强大功能，为PHP开发者提供了一个优雅、高效的美国节假日管理方案。它将那些令人头疼的日期计算细节封装起来，让你能够专注于业务本身，而无需再为节假日问题而烦恼。如果你还在手动处理美国节假日，那么是时候拥抱这个强大的工具了！赶快通过 Composer 将它引入你的项目，体验一下前所未有的开发效率和准确性吧！
