深入解析 zjkal/time-helper 库中的 ChinaHoliday 类：智能节假日判断工具

在开发涉及时间管理的应用时，准确判断中国节假日和工作日是一个常见但复杂的需求。zjkal/time-helper 库中的 ChinaHoliday 类专门为此而生，提供了简单易用的中国节假日判断功能，让开发者能够轻松处理复杂的节假日逻辑。

🎯 什么是 ChinaHoliday 类？

ChinaHoliday 类是 zjkal/time-helper 项目中用于处理中国节假日逻辑的核心组件。它通过预定义的节假日和调休日数据，结合智能判断算法，能够准确识别任意日期是否为工作日或节假日。

核心功能特点

• 精准判断：基于官方发布的节假日安排数据
• 灵活输入：支持时间戳、日期字符串、默认当前时间
• 智能逻辑：自动处理调休和法定假日特殊情况
• 易于集成：静态方法调用，无需复杂配置

📊 节假日数据存储机制

ChinaHoliday 类通过两个静态数组来存储节假日和调休日数据：

private static $holiday = [
    '2025' => ['0101', '0128', '0129', '0130', '0131', '0203', '0204', '0404', '0501', '0502', '0505', '0602', '1001', '1002', '1003', '1006', '1007', '1008'],
];

private static $workday = [
    '2025' => ['0126', '0208', '0427', '0928', '1011'],
];

数据结构说明

年份	节假日（示例）	调休日（示例）
2025	0101, 0128, 0129	0126, 0208

🔍 核心判断逻辑详解

ChinaHoliday 类的工作日判断基于以下两个核心条件：

1. 平常日判断：周一至周五，且不在节假日列表中
2. 周末调休：周六或周日，但在调休日列表中

判断流程图

flowchart TD
    A[输入日期] --> B{是否为周末?}
    B -->|是| C{是否为调休日?}
    C -->|是| D[判定为工作日]
    C -->|否| E[判定为节假日]
    B -->|否| F{是否为节假日?}
    F -->|是| E
    F -->|否| D

💡 实际应用场景示例

1. 基础节假日判断

// 判断 2025 年元旦是否为节假日
$isHoliday = ChinaHoliday::isHoliday('2025-01-01');
echo $isHoliday ? '元旦是节假日🎉' : '元旦不是节假日';

// 判断调休日是否为工作日
$isWorkday = ChinaHoliday::isWorkday('2025-01-26');
echo $isWorkday ? '1月26日是调休工作日' : '1月26日不是工作日';

2. 批量日期检查

$dates = ['2025-01-01', '2025-01-26', '2025-10-01'];
foreach ($dates as $date) {
    if (ChinaHoliday::isHoliday($date)) {
        echo "{$date} 是节假日，可以安排休息\n";
    } else {
        echo "{$date} 是工作日，需要上班💼\n";
    }
}

3. 动态节假日提醒

// 计算距离下一个节假日还有多少天
$today = time();
$days = 0;

while (true) {
    $days++;
    $nextDate = strtotime("+{$days} days", $today);
    if (ChinaHoliday::isHoliday($nextDate)) {
        $holidayName = date('Y年m月d日', $nextDate);
        echo "距离下一个节假日（{$holidayName}）还有 {$days} 天⏳";
        break;
    }
}

4. 工作日计算器

// 计算跳过节假日后的任务完成日期
$startDate = '2025-10-01';
$requiredWorkDays = 7;
$currentDate = $startDate;
$completedDays = 0;

while ($completedDays < $requiredWorkDays) {
    if (ChinaHoliday::isWorkday($currentDate)) {
        $completedDays++;
    }
    $currentDate = date('Y-m-d', strtotime("+1 day", strtotime($currentDate)));
}
echo "任务将在 {$currentDate} 完成✅";

🛠️ 快速上手指南

安装方法

composer require zjkal/time-helper

基本使用

require_once 'vendor/autoload.php';
use zjkal\ChinaHoliday;

// 判断今天是否为节假日
if (ChinaHoliday::isHoliday()) {
    echo "今天可以好好休息啦😊";
} else {
    echo "今天是工作日，加油工作！💪";
}

📈 节假日统计与分析

2025年节假日分布示例

节假日	日期范围	天数
元旦	1月1日	1天
春节	1月28日-2月4日	8天
清明节	4月4日	1天
劳动节	5月1日-5月5日	5天
国庆节	10月1日-10月8日	8天

🔧 扩展与自定义

虽然 ChinaHoliday 类已经包含了多年的节假日数据，但开发者也可以根据需要扩展或更新数据：

// 添加自定义节假日
ChinaHoliday::$holiday['2025'][] = '1201'; // 12月1日

🎉 总结

zjkal/time-helper 库中的 ChinaHoliday 类为开发者提供了一个强大而实用的中国节假日判断工具。无论是简单的日期判断，还是复杂的节假日逻辑处理，它都能轻松应对。通过简单的静态方法调用，开发者可以专注于业务逻辑的实现，而无需担心复杂的节假日判断规则。

无论是开发考勤系统、任务管理工具，还是节假日提醒应用，ChinaHoliday 类都能成为你得力的时间处理助手！🚀