Getting Started

Minimal Steps

Installation

composer require spatie/holidays

Add to config/app.php under providers (if not using auto-discovery):

Spatie\Holidays\HolidaysServiceProvider::class,

First Use Case Fetch holidays for a country (e.g., Belgium) in the current year:

use Spatie\Holidays\Holidays;

$holidays = Holidays::for('be')->get();
// Returns an array of Carbon instances for holidays.

Key Classes to Know
- Holidays: Main facade for fetching holidays.
- Holiday: Represents a single holiday (extends Carbon).
- HolidayCollection: Collection of holidays (extends Illuminate\Support\Collection).
Where to Look First
- README for basic usage.
- API Docs for advanced features.
- config/holidays.php for customization (if needed).

Implementation Patterns

Core Workflows

1. Fetching Holidays

Basic Usage:

$holidays = Holidays::for('us')->get(); // All US holidays for current year

Specific Year:

$holidays = Holidays::for('de', now()->year + 1)->get();

State/Region-Specific (US/Canada):

$holidays = Holidays::for('us', 'ca')->get(); // California holidays

2. Checking if a Date is a Holiday

if (Holidays::for('fr')->isHoliday($date)) {
    // Handle holiday logic
}

3. Filtering Holidays

$holidays->where('name', 'like', 'Christmas');
$holidays->where('type', 'national'); // 'national', 'regional', 'observed'

4. Integration with Laravel

Service Provider Binding (optional, for reusable logic):

$this->app->bind(HolidayChecker::class, function ($app) {
    return new HolidayChecker('be');
});

Middleware for Holiday-Specific Logic:

public function handle($request, Closure $next) {
    if (Holidays::for('be')->isHoliday(now())) {
        return redirect()->route('holiday-page');
    }
    return $next($request);
}

5. Custom Holiday Logic

Add Custom Holidays:

Holidays::for('be')->addHoliday(
    now()->copy()->setDate(2023, 12, 26),
    'Boxing Day (Custom)'
);

Override Default Holidays:

Holidays::for('be')->overrideHolidays([/* custom array */]);

6. Localization

Holidays are returned in the default Carbon format. Localize using Laravel’s trans() or Carbon’s setLocale():
```
$holiday->setLocale('fr')->translatedFormat('l, F jS');
```

Integration Tips

1. Caching Holidays

Cache holidays for performance (e.g., in a boot() method):

public function boot() {
    Cache::remember('holidays_be', now()->year, function () {
        return Holidays::for('be')->get();
    });
}

2. Dynamic Country Selection

Store user’s country in a model and fetch holidays dynamically:

$user->country; // e.g., 'jp'
$holidays = Holidays::for($user->country)->get();

3. Holiday-Based Business Logic

Disable Features on Holidays:

if (Holidays::for('us')->isHoliday(now())) {
    Feature::disable('shipping');
}

Adjust Workflows:

if ($holiday->isObserved()) {
    // Handle observed holiday logic
}

4. Testing

Use Holidays::fake() in tests to mock holidays:

Holidays::fake([
    'be' => [
        now()->copy()->setDate(2023, 1, 1),
    ],
]);

$this->assertTrue(Holidays::for('be')->isHoliday(now()));

Gotchas and Tips

Pitfalls

1. Country Codes

Use ISO 3166-1 alpha-2 codes (e.g., us, de, jp). Avoid nicknames like usa or germany.
Regions/States: Only supported for us (e.g., us-ca) and ca (e.g., ca-on). Other regions may throw exceptions.

2. Year Handling

Defaults to the current year. Explicitly pass a year for past/future dates:
```
Holidays::for('be', 2020)->get(); // Past year
```
Observed Holidays: Some holidays are "observed" on nearby days (e.g., Memorial Day in the US). Check with $holiday->isObserved().

3. Time Zones

Holidays are returned as Carbon instances in the UTC timezone by default. Convert to a local timezone if needed:
```
$holiday->setTimezone('Europe/Brussels');
```

4. Regional vs. National Holidays

Not all holidays are "national." Filter by type:
```
$holidays->where('type', 'national');
```
Some countries (e.g., us) include state-specific holidays (e.g., us-ca for California).

5. Custom Holidays Persistence

Custom holidays added via addHoliday() are not persisted across requests. Re-add them if needed (e.g., in a service provider’s boot() method).

6. Deprecated Methods

Avoid Holidays::get() (deprecated). Use Holidays::for('be')->get() instead.

Debugging

1. Invalid Country Codes

Check the supported countries list in the README.
Throw a HolidayNotFoundException if the country isn’t supported.

2. Missing Holidays

Ensure the year is correct (e.g., Holidays::for('be', 2023)->get()).
Verify the country code (e.g., be for Belgium, not belgium).

3. Time Zone Issues

Use Carbon::setTimezone() to debug:

$holiday->timezone; // Check current timezone
$holiday->setTimezone('America/New_York')->format('Y-m-d');

4. Performance

Caching is recommended for repeated calls (e.g., in a loop or API endpoint).
Avoid fetching holidays in a loop without caching.

Tips

1. Extend the Package

Create a Custom Holiday Provider:

use Spatie\Holidays\HolidayProvider;

class CustomHolidayProvider extends HolidayProvider {
    protected function configure(): void {
        $this->name('Custom Holiday');
        $this->addHoliday(now()->copy()->setDate(2023, 12, 25), 'Custom Day');
    }
}

'providers' => [
    \Spatie\Holidays\HolidayProviders\Belgium::class,
    App\Providers\CustomHolidayProvider::class,
],

2. Localization

Override holiday names in config/holidays.php:

'overrides' => [
    'be' => [
        'name' => [
            '2023-12-25' => 'Kerstmis (Custom)',
        ],
    ],
],

3. Holiday Types

Holidays have a type (e.g., national, regional, observed). Use this to filter:

$nationalHolidays = Holidays::for('jp')->get()->where('type', 'national');

4. Dynamic Country Selection

Store the

Holidays Laravel Package