https://github.com/azuyalabs/yasumi
The easy PHP Library for calculating holidays
https://github.com/azuyalabs/yasumi
api calculate-holidays calculating-holidays calculations countries holiday holidays library php provider-holidays yasumi
Last synced: about 1 month ago
JSON representation
The easy PHP Library for calculating holidays
- Host: GitHub
- URL: https://github.com/azuyalabs/yasumi
- Owner: azuyalabs
- License: mit
- Created: 2015-03-24T12:28:50.000Z (over 11 years ago)
- Default Branch: develop
- Last Pushed: 2026-09-30T15:50:28.000Z (about 2 months ago)
- Last Synced: 2026-10-06T22:32:15.062Z (about 2 months ago)
- Topics: api, calculate-holidays, calculating-holidays, calculations, countries, holiday, holidays, library, php, provider-holidays, yasumi
- Language: PHP
- Homepage: https://www.yasumi.dev
- Size: 21.8 MB
- Stars: 1,105
- Watchers: 14
- Forks: 171
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG-ARCHIVE.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
- Dco: DCO
Awesome Lists containing this project
- awesome-php-cn - Yasumi - 一个库来帮助你计算假期的日期和名称. (目录 / 日期和时间 Date and Time)
- awesome-projects - Yasumi - An library to help you calculate the dates and names of holidays. (PHP / Date and Time)
- awesome-php - Yasumi - A library to help you calculate the dates and names of holidays. (Table of Contents / Date and Time)
- awesome-php - azuyalabs/yasumi - The easy PHP Library for calculating holidays (Utilities / Date and Time)
- fucking-awesome-php - Yasumi - A library to help you calculate the dates and names of holidays. (Table of Contents / Date and Time)
- awesome-php - Yasumi - A library to help you calculate the dates and names of holidays. (Table of Contents / Date and Time)
README
[](https://github.com/azuyalabs/yasumi/releases)
[](https://packagist.org/packages/azuyalabs/yasumi)



[](LICENSE)

## Introduction
Yasumi (Japanese for 'Holiday'「休み」) is the easy PHP library that helps you retrieve the dates and names of holidays and
other special celebrations from various countries/states. It is calculation and rule driven avoiding the need of a
comprehensive database.
Many services exist that can provide holiday information, however are either not entirely free or only offer limited
information. In addition, no exhaustive PHP library exists today covering a wide range of holidays and
countries. [PEAR's Date_Holidays](https://pear.php.net/package/Date_Holidays) library was a similar attempt, however it
hasn't been updated for a long time.
## Requirements
Yasumi requires **PHP 8.2** or higher. The library supports PHP 8.2, 8.3, 8.4, and 8.5.
For detailed information about supported PHP versions and security updates, please refer to
the [SECURITY.md](SECURITY.md) file.
## Installation
Install Yasumi using [Composer](https://getcomposer.org):
```shell
composer require azuyalabs/yasumi
```
## Quick Start
Here's a simple example to get you started:
```php
getName() . ': ' . $holiday->format('Y-m-d') . PHP_EOL;
}
// Get a specific holiday
$independenceDay = $holidays->getHoliday('independenceDay');
echo $independenceDay->getName() . ' is on ' . $independenceDay->format('F j, Y') . PHP_EOL;
// Check if a date is a holiday
$newYearsDay = $holidays->getHoliday('newYearsDay');
if ($newYearsDay !== null) {
echo 'New Year\'s Day is a holiday!' . PHP_EOL;
}
```
For more examples, check the [examples](examples/) directory in the repository.
## Highlights
The goal of Yasumi is to be powerful while remaining lightweight, by utilizing PHP native classes wherever possible.
Yasumi's calculation is provider-based (i.e. by country/state), making it easy to add new holiday providers that
calculate holidays.
- Pure PHP with a straightforward API
- Framework-agnostic
- Use of Providers to easily extend and expand new Holidays
- Common Holiday Providers (e.g. Christian Holidays)
- Accounts for the date/time when holidays have been officially established and/or abolished
- Filters enabling to easily select certain holiday types (Official, Observed, Bank, Seasonal or Other)
- Global Translations
- Time zone aware
- Implements [ArrayIterator](https://www.php.net/manual/en/class.arrayiterator.php) to easily process a provider's
holidays
- Fully [documented](https://www.yasumi.dev)
- Fully unit tested
- [Composer](https://getcomposer.org) ready, [PSR-12](https://www.php-fig.org/psr/psr-12/)
and [PSR-4](https://www.php-fig.org/psr/psr-4/) compliant
## Documentation
Yasumi’s documentation is available on [https://www.yasumi.dev](https://www.yasumi.dev). You will find all the necessary
information how to install Yasumi and also recipes how you can use Yasumi in your project.
## Release Policy
Yasumi follows a scheduled **bi-annual release cycle**, with minor releases **targeted for** **March** and
**September** (best-effort targets - actual dates may shift), plus patch releases whenever holiday legislation, calculations
or other kind of bugs that require an urgent, backwards-compatible fix.
The project adheres to [Semantic Versioning](https://semver.org). See [RELEASE.md](RELEASE.md) for the full policy.
## Contributing
Contributions are encouraged and welcome; I am always happy to get feedback or pull requests on GitHub :)
Create [GitHub Issues](https://github.com/azuyalabs/yasumi/issues) for bugs and new features and comment on the ones you
are interested in.
If you enjoy what I am making, an extra cup of coffee is very much appreciated :). Your support helps me to put more
time into Open-Source Software projects like this.
## License
This project is open-sourced software licensed under the MIT License (MIT). Please see [LICENSE](LICENSE) for more information.
