如何使用 Carbon 库将工作日（周一至周五）按自然周切分并生成清晰的周区间-php教程-PHP中文网

如何使用 Carbon 库将工作日（周一至周五）按自然周切分并生成清晰的周区间

本文介绍如何利用 php 的 carbon 库，将指定月份中排除周六、周日后的连续工作日，智能划分为逻辑周（如以周五起始则首周仅含周五），并生成可读性强的日期范围字符串。

本文介绍如何利用 php 的 carbon 库，将指定月份中排除周六、周日后的连续工作日，智能划分为逻辑周（如以周五起始则首周仅含周五），并生成可读性强的日期范围字符串。

在实际业务场景中（如排班系统、工时统计或薪资结算），我们常需处理“仅含工作日（周一至周五）的时间范围”，并按“逻辑周”而非日历周进行分组——例如：某月从周五开始，且跳过周末，则第一周应只包含该周五；后续每周则尽可能补足5个工作日。原生 PHP 时间函数虽可实现，但易出错且可读性差；而 Carbon 作为 Laravel 官方推荐的时间处理库，提供了链式调用、语义化方法和时区安全支持，是更优解。

以下是一个基于 Carbon 的专业实现方案（兼容 Carbon 2.x / 3.x）：

use Carbon\Carbon;

function splitWorkdaysIntoWeeks(Carbon $start, Carbon $end): array
{
    $weeks = [];
    $current = $start->copy()->startOfWeek(Carbon::FRIDAY); // 以周五为每周起点（可根据需求改为MONDAY）

    while ($current->lte($end)) {
        // 确定本周工作日范围：从当前周五向前找最近的工作日（即周一），但不早于$start
        $weekStart = $current->copy()->subDays(4)->startOfDay(); // 周一
        if ($weekStart->lt($start)) {
            $weekStart = $start->copy();
        }

        // 本周截止日：取周五或 $end 中较早者
        $weekEnd = $current->copy()->endOfDay();
        if ($weekEnd->gt($end)) {
            $weekEnd = $end->copy();
        }

        // 过滤掉周末（确保区间内仅保留周一至周五）
        $workdays = [];
        $day = $weekStart->copy();
        while ($day->lte($weekEnd)) {
            if ($day->isWeekday()) { // 自动排除周六、周日
                $workdays[] = $day->format('Y-m-d');
            }
            $day->addDay();
        }

        if (!empty($workdays)) {
            $rangeLabel = sprintf(
                '%s %d – %s %d, %d',
                $weekStart->format('M'),
                (int)$weekStart->format('j'),
                $weekEnd->format('M'),
                (int)$weekEnd->format('j'),
                (int)$weekEnd->format('Y')
            );
            $weeks[] = [
                'range' => $weekStart->format('Y-m-d') . ' to ' . $weekEnd->format('Y-m-d'),
                'label' => $rangeLabel,
                'workdays' => $workdays,
                'count' => count($workdays)
            ];
        }

        $current->addWeek(); // 移动到下一个周五
    }

    return $weeks;
}

// 使用示例：
$start = Carbon::create(2024, 10, 4); // 周五，2024-10-04
$end   = Carbon::create(2024, 10, 31); // 周四，2024-10-31

$weeklyWorkdays = splitWorkdaysIntoWeeks($start, $end);
foreach ($weeklyWorkdays as $i => $week) {
    echo "Week " . ($i + 1) . ": {$week['label']} ({$week['count']} workdays)\n";
    // 输出示例：
    // Week 1: Oct 4 – Oct 4, 2024 (1 workdays)
    // Week 2: Oct 7 – Oct 11, 2024 (5 workdays)
    // Week 3: Oct 14 – Oct 18, 2024 (5 workdays)
    // ...
}

✅ 关键特性说明：

✅ 语义清晰：使用 startOfWeek(Carbon::FRIDAY) 统一以周五为周基准，便于对齐业务逻辑；
✅ 自动过滤周末：$day->isWeekday() 内置判断，无需手动 in_array($day->dayOfWeek, [1,2,3,4,5])；
✅ 边界安全：严格限制起止范围不超出原始 $start/$end，避免跨月或越界；
✅ 结构化返回：每项含可渲染标签、原始日期范围、实际工作日数组及数量，便于前端展示或导出；
⚠️ 注意事项：若需以周一为周首，请将 Carbon::FRIDAY 替换为 Carbon::MONDAY，并同步调整 subDays(4) 为 subDays(0)（即保持周一不变）；同时建议在生产环境添加输入校验（如 $start->lte($end)）。