About Yasumi

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 library was a similar attempt, however it hasn't been updated for a long time.


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
  • Straightforward API
  • Supports PHP versions 8.0 or higher
  • Framework-agnostic
  • Use of Providers to easily extend and expand new Holidays
  • Common Holiday Providers
  • 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 to easily process a provider's holidays
  • Fully documented and unit tested
  • Composer ready, PSR-12 and PSR-4 compliant

Credits and License

Yasumi is created and maintained by Sacha Telgenhof, with the support of many wonderful contributors. Yasumi is open-sourced software licensed under the MIT License (MIT). The documentation website content is licensed CC BY-NC-SA 4.0.


Last updated 01/07/2024