azuyalabs/yasumi: computing holiday dates in PHP instead of loading them from a table

Calculation and rules instead of a holiday database

Yasumi, which is Japanese for holiday, is a PHP library for retrieving the dates and names of holidays and other special celebrations from various countries and states. The design decision the project puts first is that it is calculation and rule driven, which avoids the need for a comprehensive database.

That choice is the whole architecture in one sentence. Instead of shipping a table of dates for every year, every country and every holiday, and updating that table as legislation changes, the library derives dates from the rules that define them. The practical consequences are visible in the release policy: patch releases happen whenever holiday legislation, calculations or other bugs require an urgent, backwards compatible fix, which is a list that reads like a changelog for rule sets rather than for a static dataset.

The project also states the gap it is filling. Many services can provide holiday information, but they are either not entirely free or offer limited information, and no exhaustive PHP library covers a wide range of holidays and countries. It names PEAR's Date_Holidays as a similar attempt that has not been updated for a long time, which positions Yasumi as the maintained local option rather than as a different kind of tool.

One provider per country or state

Yasumi's calculation is provider based, meaning the holiday rules for a jurisdiction live in a provider class for that jurisdiction. The stated consequence is that adding new holiday providers is easy, since a provider is where the calculation rules for one country or state are written.

The repository makes that extensibility concrete. An `examples/custom_provider.php` file sits in the `examples/` directory alongside `basic.php`, `between_filter.php` and `filters.php`, so the intended extension path is not theoretical. The project also lists common holiday providers, for example Christian holidays, as a case where shared rule sets exist rather than needing to be written per country.

The framework agnostic design matters for adoption. The library uses PHP native classes wherever possible and presents a straightforward API, and it makes no assumption about the framework it runs in, so it can sit inside a Laravel application, a Symfony application or a plain PHP script with the same shape of code. The `composer.json`, `phpstan.neon.dist` and `phpunit.xml.dist` files at the top level, together with the CI badges for coding standard, static analysis and testing, indicate a library held to a normal set of quality gates.

Installing with Composer and asking for a year

Installation is a single Composer command, and the requirement is PHP 8.2 or higher, with 8.2, 8.3, 8.4 and 8.5 supported. The project points to its `SECURITY.md` file for detailed information about supported PHP versions and security updates, which is the file to check when a PHP upgrade lands:

composer require azuyalabs/yasumi

The quick start then creates a provider for a country and a year and walks the result. The provider object is iterable, since Yasumi implements `ArrayIterator` to make a provider's holidays easy to process, and individual holidays are addressable by an internal name:

<?php

require 'vendor/autoload.php';

// Create a holiday provider for a specific country and year
$holidays = Yasumi\Yasumi::create('USA', 2026);

// Get all holidays for the year
foreach ($holidays as $holiday) {
    echo $holiday->getName() . ': ' . $holiday->format('Y-m-d') . PHP_EOL;
}

The same object answers targeted questions, which is the API shape most applications will use in the end, since a payroll run or a shipping cutoff asks about one named holiday rather than all of them:

$independenceDay = $holidays->getHoliday('independenceDay');
echo $independenceDay->getName() . ' is on ' . $independenceDay->format('F j, Y') . PHP_EOL;

$newYearsDay = $holidays->getHoliday('newYearsDay');
if ($newYearsDay !== null) {
    echo 'New Year\'s Day is a holiday!' . PHP_EOL;
}

Note the null check in the second snippet. A named holiday can be absent for a given provider and year, so the code that consumes it has to handle that rather than assume it exists.

Filters that separate official, observed and bank holidays

Not every holiday in a country means the same thing to an application, so Yasumi tags its results and lets you filter on them. The filter types are Official, Observed, Bank, Seasonal and Other, and the documentation describes them as enabling you to easily select certain holiday types.

That distinction is the feature that decides whether the library is useful to you. A shop that closes on public holidays and a bank that stays open on them are working with the same list and different rules, and a library that only returns dates without types forces every consumer to hardcode its own table of exceptions. The `examples/filters.php` and `examples/between_filter.php` files show the two axes in use, filtering by type and filtering by a date range.

Global translations are also part of the design, so a holiday name can be produced in a language other than the provider's default, and the library is time zone aware, which matters for a holiday that starts at midnight local time in one jurisdiction and is consumed by a service in another.

Holidays that were created or abolished along the way

One line in the feature list is easy to skim and unusually useful: Yasumi accounts for the date and time when holidays have been officially established and abolished. In other words, the library models the lifetime of a holiday, not just its recurrence.

This is where the calculation based approach pays off. A holiday introduced by legislation in a given year should not appear in the calendar for the years before it existed, and a holiday that was abolished should stop appearing afterwards. A table based approach has to be regenerated and re-shipped whenever that changes, and a static dataset in your own code has to be patched by hand. A rule based library can express the change once, in the provider.

The limit of the same approach is worth stating. Yasumi models the holiday rules its providers encode, and it does not model everything a business calls a calendar. Working days, tax filing deadlines, bank settlement cutoffs, company shutdowns and school terms are not holidays in this model, and there is no indication in the documentation that a provider covers them. If your requirement is a business day calculation rather than a holiday list, this is the wrong library.

A March and September release rhythm with patch releases for legislation

Yasumi follows a scheduled bi-annual release cycle, with minor releases targeted for March and September, described as best effort targets whose actual dates may shift. Patch releases come out whenever holiday legislation, calculations or other bugs require an urgent, backwards compatible fix, and the project adheres to Semantic Versioning, with the full policy in `RELEASE.md`.

Recent tags fit that pattern. Version 2.10.0 was published on 2026-01-22, 2.11.0 on 2026-03-30 and 2.12.0 on 2026-09-30, with the last push to the repository on 2026-10-13. The default branch is `develop`.

For a consumer, the two things to plan around are the March and September window for catching new rules, and the possibility of a patch release landing on short notice because a country changed a holiday law. The SemVer commitment and the stated backwards compatibility of those urgent fixes are the parts that make an automatic `composer update` less frightening than it sounds, but a patch that adds a new holiday to a provider can still change what your application prints, so the changelog is worth reading when one lands.

The licence is MIT, which is permissive and carries no copyleft obligations for a commercial application that uses the library as a dependency. The `LICENSE` file in the repository is the text itself.

Where the library stops and your own data begins

Two boundaries are worth naming before you build on this. The first is coverage. Yasumi ships providers for countries and states, and the documentation does not promise a provider for every jurisdiction on earth, so a project serving several markets must check provider availability for each of them before designing around it. A missing provider is not a fallback path the library handles for you.

The second is that the rules are the library's, and your interpretation of them may differ. The internal names used with `getHoliday`, such as `independenceDay` and `newYearsDay`, are the library's vocabulary, and the observable day for a holiday that moves to a nearby weekday is a modelling decision baked into a provider. If your business treats the observed day differently from the statutory one, the filters and provider configuration are where you find that, not a configuration flag at the top level.

Compared with a hosted holiday service, the difference in approach is that Yasumi makes no network calls and requires no account or API key, at the cost of a fixed rule set compiled into the release you install. Compared with a hand maintained date table in your own codebase, the difference is that the rules are maintained upstream by someone whose job is that, and that you inherit the provider model instead of writing a calendar engine.

Editorial conclusion

Adopt Yasumi when your PHP application needs holiday dates in several jurisdictions, you would rather compute them than maintain a date table, and you can live with the rules the shipped providers encode. Do not adopt it as a general business calendar, because it models holidays and special celebrations rather than working days, tax deadlines or company specific dates, and do not expect a provider for a jurisdiction it does not ship. Verify first that a provider exists for every country and state you need, that your PHP version is 8.2 or above with 8.2 through 8.5 supported, and that the release notes for the version you are upgrading to cover the legislation change you are relying on, since patch releases exist precisely for urgent backwards compatible fixes.

Frequently asked questions

Official sources

1. azuyalabs/yasumi on GitHub
2. License: MIT
3. Project website
4. README
5. Releases