Weave Code
Holidays Laravel Package
spatie/holidays
Spatie's PHP package calculates public holidays for a country. Call Holidays::for('be')->get() to receive Holiday objects with localized names, CarbonImmutable dates, and types. Supports many countries via ISO 3166-1 alpha-2 codes or country instances. Requires PHP 8.4+.
spatie/holidays is a PHP package that calculates public holidays for a country. Retrieve holidays for any supported country using an ISO 3166-1 alpha-2 code or a country class, and receive an array of Holiday objects with a name, a CarbonImmutable date, and a holiday type.
- Simple API —
Holidays::for('be')->get() - Structured results — name, date, and
HolidayType - Carbon-powered immutable dates
- Extensible — add a new country via pull request
- Requires PHP 8.4+
Frequently asked questions about Holidays
- How do I install spatie/holidays in a Laravel application?
- Install it with composer require spatie/holidays. There is no service provider, config file, migration or published asset, so nothing else is required after the Composer install. You can start calling Holidays::for('be')->get() immediately, or wrap it in your own application service.
- Does spatie/holidays support Laravel 11 and Laravel 12, and which PHP version does it need?
- The package is framework-agnostic PHP with no Laravel coupling, so it runs fine inside Laravel 11 or 12 as long as the PHP requirement is met. That requirement is PHP 8.4 or higher, which is stricter than the 8.1 to 8.3 floor typical of most Laravel packages. Check your deployment images and any pinned dependencies before adding it to an older application.
- Which countries does spatie/holidays support?
- Supported countries live in the src/Countries directory of the repository, and each one is exposed through an ISO 3166-1 alpha-2 code such as 'be' or a country class like Belgium::make(). Coverage is community-driven, so verify your operating countries before committing to the package. Adding a missing country is a documented pull request process.
- How do I get all public holidays for a country in a specific year or date range?
- Call Holidays::for('be')->get() to receive an array of Holiday objects with name, CarbonImmutable date and HolidayType, or scope the call to a year. For planning features, helpers such as getInRange(), getUpcoming() and getLongWeekends() cover date ranges, upcoming holidays and long weekend detection. Each Holiday is JsonSerializable, so returning the list from an API endpoint works without extra mapping.
- How do I check if a given date is a public holiday?
- Use the isHoliday() method on the Holidays instance for the country you need. Because the package only computes calendar dates, remember that the answer is a plain calendar-date comparison rather than a timezone-aware instant check. If your SLA timers or notification suppression depend on a specific timezone, apply that logic in your own adapter.
- Does spatie/holidays support regional or state-level holidays?
- Regional support is uneven: only eight countries currently implement the HasRegions interface, namely Australia, Bosnia and Herzegovina, Brazil, France, Germany, Malaysia, Spain and Switzerland. For those countries you can request holidays for a specific region so regional and observed days are included. Elsewhere you get the national set, and any sub-region differences must be handled yourself.
- Can I get holiday names translated into my own language?
- Holiday names come from translation files and fall back silently to the native holiday names when a locale file is missing. Translation coverage is community-contributed, so a country may return Dutch, German or French names even when you request another locale. Test the locales you actually ship with rather than assuming full coverage.
- How do I add a custom or one-off holiday that is not in the package yet?
- The package deliberately stops at computation, so there is no built-in override mechanism for one-off government decrees. The recommended approach is a thin application service that fetches the package results and merges in your own Holiday objects for locally declared days. That adapter also gives you a swap point if upstream coverage or accuracy ever degrades.
- How accurate is the holiday data for Islamic, Chinese or other non-Gregorian calendars?
- Calendar systems such as Islamic, Chinese, Indian and Nepali rely on precomputed lookup tables with a declared supportedYearRange(), typically 2024 to 2037 for those countries. Inside that range the data is snapshot-tested; outside it, behaviour should be treated as undefined rather than guaranteed. Payroll and multi-year forecasting must detect out-of-range years and handle them explicitly, for example by falling back to your own override data.
- Should I cache holiday results in production?
- The package performs no caching itself, it is a pure compute primitive, so caching is your responsibility. Cache per country, region, locale and year or range key in the Laravel cache, and invalidate when you upgrade the package since holiday rules change annually. Long TTLs are usually safe because results only change through Composer updates or your own overrides.
Weaver
How can I help you explore Laravel packages today?