At Spatie, we organize an after-work gathering every month. To streamline the planning process, I added a Slack bot to help us.

However, it did not take public holidays into account. This led us into the development of a new mini-package named spatie/holidays.

I strived to keep the implementation simple while ensuring extensibility for different countries. My colleague, Freek, assisted in finalizing the API.

Package API

Get holidays for a country

// Using a Country object
$holidays = Holidays::for(Belgium::make())->get();
 
// Using country code
$holidays = Holidays::for('be')->get();

Get holidays for a specific year

$holidays = Holidays::for(country: 'be', year: 2024))->get();

Get holidays in a specific language

$holidays = Holidays::for(country: 'be', locale: 'fr'))->get();

Check if a date is a holiday

Holidays::for('be')->isHoliday('2024-01-01');

Get the name of a holiday

Holidays::for('be')->getName('2024-01-01');

Under the hood

Most countries have a combination of fixed holidays, such as New Year on 01/01, and variable holidays. In Western countries, the variable holidays often revolve around Easter. Fortunately, PHP provides a handy function for calculating Easter: easter_date(). If you're interested in understanding how the Belgian holidays are calculated, you can take a look here.

Support for different countries

Within the first 30h of releasing, we received more than 125 pull requests from users who added support for their respective countries. We did not expect this!

We were even trending on Github!

Feel free to send us a pull request for your country to our package or help us out in any other way!