https://github.com/spatie/holidays
Calculate which days you don't have to work!
https://github.com/spatie/holidays
date holidays php
Last synced: 6 months ago
JSON representation
Calculate which days you don't have to work!
- Host: GitHub
- URL: https://github.com/spatie/holidays
- Owner: spatie
- License: mit
- Created: 2024-01-12T09:14:27.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-12T15:35:28.000Z (6 months ago)
- Last Synced: 2025-05-12T16:48:25.738Z (6 months ago)
- Topics: date, holidays, php
- Language: PHP
- Homepage: https://spatie.be/open-source
- Size: 806 KB
- Stars: 363
- Watchers: 4
- Forks: 198
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Calculate public holidays for a country
[](https://packagist.org/packages/spatie/holidays)
[](https://github.com/spatie/holidays/actions/workflows/run-tests.yml)
[](https://packagist.org/packages/spatie/holidays)
This package can calculate public holidays for a country.
```php
use Spatie\Holidays\Holidays;
// returns an array of Belgian holidays
// for the current year
$holidays = Holidays::for('be')->get();
```
## Support us
[
](https://spatie.be/github-ad-click/holidays)
We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
## Installation
You can install the package via composer:
```bash
composer require spatie/holidays
```
## Supported countries
We support the countries listed in [this directory](https://github.com/spatie/holidays/tree/main/src/Countries). If you want to add a country, please create a pull request.
## Usage
You can get all holidays for a country by using the `get` method.
```php
use Spatie\Holidays\Holidays;
use Spatie\Holidays\Countries\Belgium;
// returns an array of Belgian holidays
// for the current year
$holidays = Holidays::for(Belgium::make())->get();
```
Alternatively, you could also pass an [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) code to the `for` method.
In case of region based holidays, these will not be included. Use a country class instead.
```php
use Spatie\Holidays\Holidays;
// returns an array of Belgian holidays
// for the current year
$holidays = Holidays::for('be')->get();
```
### Getting holidays for a specific year
You can also pass a specific year.
```php
use Spatie\Holidays\Holidays;
$holidays = Holidays::for(country: 'be', year: 2024)->get();
```
### Getting holidays between two dates
You can also get all holidays between two dates (inclusive).
```php
use Spatie\Holidays\Holidays;
$holidays = Holidays::for('be')->getInRange('2023-06-01', '2024-05-31');
```
### Getting holidays in a specific language
```php
$holidays = Holidays::for(country: 'be', locale: 'fr')->get();
```
If the locale is not supported for a country, an exception will be thrown.
### Determining if a date is a holiday
If you need to see if a date is a holiday, you can use the `isHoliday` method.
```php
use Spatie\Holidays\Holidays;
Holidays::for('be')->isHoliday('2024-01-01'); // true
```
### Getting the name of a holiday
If you need the name of the holiday, you can use the `getName` method.
```php
use Spatie\Holidays\Holidays;
Holidays::for('be')->getName('2024-01-01'); // Nieuwjaar
```
### Determining whether a country is supported
To verify whether a country is supported, you can use the `has` method.
```php
use Spatie\Holidays\Holidays;
Holidays::has('be'); // true
Holidays::has('unknown'); // false
```
## Contributing
This is a community driven package. If you find any errors, please create a pull request with the fix, or at least open an issue.
## Adding a new country
1. Create a new class in the `Countries` directory. It should extend the `Country` class.
2. Add a test for the new country in the `tests` directory.
3. Run the tests so a snapshot gets created.
4. Verify the result in the newly created snapshot is correct.
5. If the country has multiple languages, add a file in the `lang/` directory.
In case your country has specific rules for calculating holidays,
for example region specific holidays, you can pass this to the constructor of your country class.
```php
$holidays = Holidays::for(Germany::make('DE-BW'))->get();
```
The value, `DE-BW`, will be passed to the region parameter of the constructor of a country.
```php
class Germany extends Country
{
protected function __construct(
protected ?string $region = null,
) {
}
protected function allHolidays(int $year): array
{
// Here you can use $this->region (or other variables) to calculate holidays
}
```
Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for more details.
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Niels Vanpachtenbeke](https://github.com/Nielsvanpach)
- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.