Warp

Business days and holidays in Laravel: due dates done right

7 min read

"Ships in 3 business days." "Payment due within 5 business days." "We need 2 business days to pack." Almost every business app has a sentence like this somewhere, and almost every first implementation gets it wrong in December.

This post shows how to do it properly in plain Laravel, with a small class you can copy, and the edge cases that tend to show up only after the app is live. At the end there is a short section on how Warp DatePicker does the same inside a Filament panel, if you'd rather not maintain it yourself.

Why addWeekdays() is not enough

Carbon has addWeekdays(), and it is the first thing most of us reach for:

CarbonImmutable::parse('2026-12-24')->addWeekdays(3); // 2026-12-29

It skips Saturday and Sunday, and nothing else. Friday 25 December 2026 is Christmas, so the right answer is Wednesday 30 December, not Tuesday 29. Carbon has no idea which days your business is closed, and it shouldn't: that depends on the country, sometimes the state, and on your company.

A business day is a day that is:

  1. a working weekday for you (not always Monday to Friday),
  2. not a public holiday where you are, and
  3. not one of your own days off (a year-end shutdown, a stocktake, a founding day).

Getting the public holidays

Don't type holidays into a config file. Some move every year (Thanksgiving is the fourth Thursday of November), some are replaced by another day when they fall on a weekend, and new ones get added (Juneteenth became a US federal holiday in 2021).

Yasumi is a well-maintained PHP library that works them out for many countries and regions, for any year, with no API calls:

composer require azuyalabs/yasumi
use Yasumi\Yasumi;

foreach (Yasumi::create('USA', 2026) as $holiday) {
    echo $holiday->format('Y-m-d').' '.$holiday->getName().PHP_EOL;
}

// 2026-07-03 Independence Day observed
// 2026-07-04 Independence Day
// 2026-11-26 Thanksgiving Day
// 2026-12-25 Christmas
// ...

Notice 2026-07-03. Independence Day falls on a Saturday in 2026, so federal offices close on Friday the 3rd. If your list only has 4 July, your "next business day" lands on a day the bank is closed. Whatever source you use, check that it includes observed days. (Other options are spatie/holidays, and cmixin/business-day if you want the rules as Carbon macros.)

Yasumi also lists some days that are not days off, such as observances in some countries. Keep only the official ones, as in the class below.

A small business calendar class

This is enough for most apps. It caches the holidays per year, so counting through a long list doesn't build the same calendar again and again.

namespace App\Support;

use Carbon\CarbonImmutable;
use LogicException;
use Yasumi\Holiday;
use Yasumi\Yasumi;

final class BusinessCalendar
{
    /** @var array<int, array<string, string>> holiday names by date, per year */
    private array $holidays = [];

    /**
     * @param  list<int>  $workingDays  ISO weekdays, 1 = Monday
     * @param  list<string>  $closedDays  company days off, Y-m-d
     */
    public function __construct(
        private string $country = 'USA',
        private array $workingDays = [1, 2, 3, 4, 5],
        private array $closedDays = [],
    ) {}

    public function isBusinessDay(CarbonImmutable $date): bool
    {
        return in_array($date->dayOfWeekIso, $this->workingDays, true)
            && ! in_array($date->toDateString(), $this->closedDays, true)
            && ! isset($this->holidaysOf($date->year)[$date->toDateString()]);
    }

    public function addBusinessDays(CarbonImmutable $date, int $days): CarbonImmutable
    {
        $date = $date->startOfDay();

        for ($checked = 0; $days > 0; $checked++) {
            if ($checked > 3660) {
                throw new LogicException('No business day in ten years. Check the working days.');
            }

            $date = $date->addDay();

            if ($this->isBusinessDay($date)) {
                $days--;
            }
        }

        return $date;
    }

    /** @return list<string> the days off between two dates, Y-m-d */
    public function daysOffBetween(CarbonImmutable $from, CarbonImmutable $to): array
    {
        $days = [];

        for ($date = $from->startOfDay(); $date <= $to; $date = $date->addDay()) {
            if (! $this->isBusinessDay($date)) {
                $days[] = $date->toDateString();
            }
        }

        return $days;
    }

    /** @return array<string, string> */
    private function holidaysOf(int $year): array
    {
        if (! isset($this->holidays[$year])) {
            $this->holidays[$year] = [];

            foreach (Yasumi::create($this->country, $year) as $holiday) {
                if ($holiday->getType() === Holiday::TYPE_OFFICIAL) {
                    $this->holidays[$year][$holiday->format('Y-m-d')] = $holiday->getName();
                }
            }
        }

        return $this->holidays[$year];
    }
}

Register it once, with your company's days off:

// AppServiceProvider::register()
$this->app->singleton(BusinessCalendar::class, fn () => new BusinessCalendar(
    country: 'USA',
    closedDays: ['2026-12-28', '2026-12-29', '2026-12-30', '2026-12-31'],
));

And now:

$calendar = app(BusinessCalendar::class);

$calendar->addBusinessDays(CarbonImmutable::parse('2026-12-24'), 3);
// Without the shutdown: 2026-12-30
// With the year-end shutdown above: 2027-01-06
// (past Christmas, the weekend, the shutdown, New Year's Day and another weekend)

The guard in the loop matters more than it looks. If someone saves a calendar with no working days, an unguarded while loop will spin until the request times out, on every page that shows a due date.

The edge cases that bite later

Which "today"? If your app runs in UTC and your warehouse is in New York, it is already "tomorrow" on the server from 7 or 8 PM local time. Count from the business's own clock:

$today = CarbonImmutable::now('America/New_York')->startOfDay();

Cut-off times. "Orders before 3 PM ship today" means an order at 3:30 PM counts from the next business day. Put that rule in one place, next to the calendar, not in each controller.

Does today count? Decide once and write it down. A common rule: "3 business days from today" doesn't count today, and the day you land on must itself be a business day. Show the result to the user ("Ships Wed, Dec 30") so nobody has to do the counting in their head.

Regional holidays. Germany, Spain, Canada, Australia and the US all have holidays that only some states or regions take. Yasumi has providers for many of them (for example Germany/Bavaria). If you have warehouses in two regions, you need two calendars.

Weekends aren't universal. Some businesses work Saturdays, and in some countries the weekend isn't Saturday and Sunday. Keep working days as a setting, as the $workingDays argument above does.

Dates are dates. A due date has no time of day. Store it in a date column, cast it with 'date' or 'immutable_date', and compare with toDateString(). Mixing datetime values and time zones into this is how a date silently moves by one day.

Using it in a Filament form

Filament's DatePicker can grey out days and set a minimum date. One thing to know: in Filament 5, minDate() is also checked on the server (it adds an after_or_equal rule), but disabledDates() only greys out days in the picker. A typed or crafted request can still save a holiday. Add a rule for that:

use App\Support\BusinessCalendar;
use Carbon\CarbonImmutable;
use Closure;
use Filament\Forms\Components\DatePicker;

DatePicker::make('ships_on')
    ->required()
    ->minDate(fn () => app(BusinessCalendar::class)->addBusinessDays(CarbonImmutable::today(), 2))
    ->disabledDates(fn () => app(BusinessCalendar::class)->daysOffBetween(
        CarbonImmutable::today(),
        CarbonImmutable::today()->addYear(),
    ))
    ->rules([
        fn (): Closure => function (string $attribute, mixed $value, Closure $fail): void {
            if (! app(BusinessCalendar::class)->isBusinessDay(CarbonImmutable::parse($value))) {
                $fail('Please pick a business day.');
            }
        },
    ]);

This works. What it doesn't do is tell the user why a day is greyed out. Was it Christmas, the shutdown, or a weekend? Users then email you to ask why they can't pick the 25th.

Testing it

Business-day code is easy to test because it is just dates in and dates out. Freeze the clock, and test the days that are hard to get right:

public function test_three_business_days_after_christmas_eve(): void
{
    $calendar = new BusinessCalendar(country: 'USA');

    $this->assertSame('2026-12-30', $calendar->addBusinessDays(CarbonImmutable::parse('2026-12-24'), 3)->toDateString());
}

public function test_the_observed_independence_day_is_a_day_off(): void
{
    $this->assertFalse((new BusinessCalendar(country: 'USA'))->isBusinessDay(CarbonImmutable::parse('2026-07-03')));
}

A good checklist of dates: a Friday before a long weekend, a holiday that falls on a Saturday or Sunday, the turn of the year, a company day off next to a public holiday, and a date late in the evening in the business's time zone.

The same thing with Warp DatePicker

If you build in Filament and don't want to own this code, Warp DatePicker is a drop-in replacement for Filament's DatePicker that does all of the above and shows it to the user. Holidays for 49 countries and their states come from Yasumi on your own server (no API key), and your company days off can be set in code or on a calendar page in the panel.

// The panel provider: which country's holidays
FilamentWarpDatePickerPlugin::make()->country('US');

// The form
WarpDatePicker::make('ships_on')
    ->required()
    ->onDayOff(DayOff::Suggest)       // picks Christmas? "Use Mon, Dec 28 instead"
    ->minBusinessDaysFromToday(2)     // also checked on the server
    ->showBusinessDaysFromToday();    // "4 business days from today" under the field

Holidays are red with their name on hover, company days off are amber, and DayOff::Disallow refuses days off on the server with its own validation rule. The same calendar is available in PHP and as Carbon macros:

now()->addBusinessDays(3);
today()->businessDaysUntil($order->due_on);
WarpDate::calendar()->dueDate($invoice->issued_on, PaymentTerms::net(30));

It also covers the next steps most apps run into: payment terms that move off holidays (Net 30, end of next month), a "3 business days left" table column, business hours with a cut-off time, and a separate calendar for each warehouse or shop. The README has the details, and the live demo lets you pick Christmas and see what happens.

More from the blog

Import a messy customer CSV into Filament, and fix it before anything is saved

Moving off an old system? Its export has the wrong column names, a broken email, a missing name and the same customer twice. Match the columns, see every problem, fix the cells, then import.

Stop duplicate customers in a Filament form before they are saved

The same customer added twice, once with capitals in the email and once with brackets in the phone number. Warn the person typing, show the existing customer, and keep your list clean.

Dispatch field technicians from a Filament schedule board

Morning at a repair company. Drag each waiting job from a Filament table onto a technician's row, let the board refuse double bookings, and stretch a job when it runs long.

Filament + AI coding tips, by email

How to fit Warp plugins into your own app and pair them with Claude Code or Cursor: prompts that work, mistakes AI makes, real examples. Once or twice a month. Unsubscribe anytime.

Ask us anything about Warp

No email address or sign-up needed.

We read every question and answer here on the site, usually within a day. Others see your question after we have checked it.

What's stopping you from using Warp's plugins?

One question. We read every answer, and it decides what we build next. It is not shown on the site.

What's stopping you from using Warp's plugins?