Weave Code
Holidays Laravel Package
spatie/holidays
Calculate public holidays for supported countries using ISO codes or country classes. Get an array of Holiday objects with name, CarbonImmutable date, and type (e.g., national). PHP 8.4+ package by Spatie, with extensible country definitions.
Calculate public holidays
Frequently asked questions about Holidays
- How do I install spatie/holidays in a Laravel project?
- Run `composer require spatie/holidays` in your project directory. The package requires PHP 8.4+ and no additional Laravel setup. It works as a standalone utility with no migrations or config files needed.
- Can I get holidays for a specific year range (e.g., 2024–2025) instead of just one year?
- Yes, use the `getInRange()` method with start and end years: `Holidays::for('us')->getInRange(2024, 2025)`. This returns an array of `Holiday` objects for all holidays in that period.
- Does this package support regional holidays (e.g., US states or German Bundesländer)?
- Currently, the package supports country-level holidays only (ISO 3166-1 alpha-2 codes). For regional holidays, you’d need to extend the package or combine it with a regional database like `spatie/regional`.
- How do I cache holidays to avoid recalculating them every request?
- Cache the results using Laravel’s cache system. For example, cache holidays for Belgium in 2024 with a 1-year TTL: `Cache::remember('holidays:be:2024', now()->addYear(), fn() => Holidays::for('be')->get());`
- Will this package work with Laravel’s Carbon or only CarbonImmutable?
- The package uses `CarbonImmutable` internally, but it’s compatible with Laravel’s Carbon. You can convert dates easily: `$holiday->date->toCarbon()` or `$holiday->date->toDateTimeString()`.
- How do I handle unsupported countries or invalid ISO codes (e.g., 'zz')?
- The package throws an exception for invalid ISO codes. Catch it with a try-catch block or validate the country code first using `Holidays::has('be')` before calling methods.
- Can I use this package in a Laravel API to return holiday data as JSON?
- Yes, `Holiday` objects are `JsonSerializable`, so you can return them directly from API routes. Example: `return response()->json(Holidays::for('jp')->get());`
- Does spatie/holidays support dynamic holidays like Islamic or Chinese lunar calendars?
- Yes, the package includes support for dynamic calendars like Islamic and Chinese holidays. Use the country class (e.g., `SaudiArabia`) or ISO code (`sa`) to fetch these holidays automatically.
- How do I test holiday calculations in Laravel with Pest/PHPUnit?
- Use Laravel’s Carbon testing helpers to mock dates: `Carbon::setTestNow(now()->year(2024)->month(12)->day(25));`. Verify holidays with assertions like `assertTrue(Holidays::for('us')->isHoliday());`
- What’s the best alternative if I need more granular control over holiday rules?
- For highly customized holiday logic, consider building a custom solution using `spatie/calendar` or `spatie/laravel-calendar`. However, `spatie/holidays` is ideal for 90% of use cases with its extensible country definitions.
Weaver
How can I help you explore Laravel packages today?