Yasumi

Yasumi (Japanese for ‘holiday’) is a lightweight, framework-agnostic PHP library that retrieves the dates and names of public, bank, observed, and seasonal holidays for a wide range of countries and states. Rather than relying on a comprehensive database, Yasumi calculates every holiday from rules, accounting for the historical dates when holidays were officially established or abolished.

With more than 60 country providers, global translations, timezone awareness, and holiday-type filters, Yasumi gives developers a simple, extensible API for any calendar-driven feature. Providers are class-based and easy to extend, so adding new countries or custom holidays is straightforward.

What You Get

• 60+ built-in country and state holiday providers covering official, bank, observed, seasonal, and other holiday types
• Rule-driven calculation that requires no bundled database and respects when holidays were historically established or abolished
• Global translations and locale support so holiday names render in the appropriate language
• Filters and an ArrayIterator implementation for easily selecting and iterating over holiday collections
• An extensible provider model for adding new countries or custom holidays with minimal code

Common Use Cases

• Determining whether a given date is a public holiday when scheduling deliveries, appointments, or business operations
• Calculating the next or previous working day while skipping weekends and holidays
• Rendering localized holiday calendars in a web or mobile application

Under The Hood

Architecture - Yasumi centers on a static factory (src/Yasumi/Yasumi.php) whose create() method resolves a country string to a provider class implementing ProviderInterface. Each provider (63 classes under src/Yasumi/Provider/) extends AbstractProvider and composes shared rule sets like CommonHolidays and ChristianHolidays via traits, populating a collection of Holiday value objects (an extension of PHP’s DateTime). The provider implements ArrayIterator, letting callers iterate, filter, and query holidays directly. Tech Stack - Pure PHP 8.2+ with no runtime dependencies beyond ext-json; ext-intl and ext-calendar are optional. Development tooling includes PHPUnit 11, PHPStan 2, php-cs-fixer, and Rector, all wired through Composer scripts. Code Quality - The codebase uses declare(strict_types=1), PSR-12 and PSR-4 compliance, and typed properties throughout. It is fully unit tested, with a dedicated test directory mirroring each country provider, and enforces static analysis and coding-standard checks in CI. API Design - The public surface is deliberately small: Yasumi::create(country, year, locale) returns an iterable provider, and helpers such as getHoliday(), isHoliday(), nextWorkingDay(), and type filters keep common tasks to a single call. Extensive documentation at yasumi.dev and an examples directory lower the barrier to adoption.