Weave Code
Holidays Laravel Package
spatie/holidays
Calculate public holidays by country (ISO alpha-2) with a simple API. Get an array of Holiday objects including localized name, CarbonImmutable date, and type (e.g., national). Supports multiple countries and is easy to extend by adding new country definitions.
Calculate which days you don't have to work!
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+, so ensure your Laravel app meets this requirement. No additional Laravel-specific setup is needed beyond installation.
- Can I use this package to check if a specific date is a holiday in Germany?
- Yes. Use `Holidays::for('de')->isHoliday('2024-12-25')` to check if December 25, 2024, is a holiday in Germany. The package supports ISO alpha-2 country codes like 'de' or country classes like `Germany::make()`.
- Does this package support regional holidays (e.g., state-specific holidays in the US)?
- Currently, the package provides national holidays only. For regional holidays (e.g., US state holidays), you’ll need to extend the package by adding custom country classes or submit a pull request to Spatie.
- How can I cache holiday results for better performance in a Laravel API?
- Cache results using Laravel’s cache system. For example, wrap the holiday fetch in `Cache::remember('holidays.{$country}.{$year}', now()->addYear(), fn() => Holidays::for($country, $year)->get())` to avoid recomputing holidays.
- Will this package work with Laravel 8.x or older versions?
- The package requires PHP 8.4+, which means it’s compatible with Laravel 10+ by default. For Laravel 8.x (PHP 8.1+), you may need to use a fork or polyfills, as Spatie does not officially support older PHP versions.
- Can I use this package to generate JSON responses for a frontend calendar?
- Yes. The `Holiday` objects are `JsonSerializable`, so you can directly return them in API responses. For example, `return response()->json(Holidays::for('jp')->get())` will return a JSON array of holidays.
- How do I add support for a country not included in the package?
- You can extend the package by creating a custom country class following Spatie’s [guide](https://github.com/spatie/holidays#adding-a-new-country). Alternatively, submit a pull request to Spatie to add the country officially.
- Does this package handle observed holidays (e.g., US holidays shifted to Mondays)?
- Yes. The package includes logic for observed holidays, such as US holidays that fall on weekends and are moved to the nearest Monday. These are automatically included when fetching holidays for supported countries.
- How can I test holiday logic in my Laravel application?
- Mock the `Holidays` facade in your tests using Laravel’s mocking tools. For example, `Holidays::shouldReceive('for')->andReturn(HolidayCollection::make([new Holiday('Test Holiday', now())]))` to simulate holiday data.
- Are there alternatives to spatie/holidays for Laravel?
- Alternatives include `league/holidays` (more countries, PHP 7.4+ support) or `mtdowling/jwt-auth` (if you need JWT-based holiday checks). However, Spatie’s package is optimized for Laravel’s Carbon integration and facade pattern, making it ideal for Laravel-specific workflows.
Weaver
How can I help you explore Laravel packages today?