azuyalabs/yasumi

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 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 file.

Installation

Install Yasumi using Composer:

composer require azuyalabs/yasumi

Quick Start

Here's a simple example to get you started:

<?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;
}

// 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 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 to easily process a provider's holidays
• Fully documented
• Fully unit tested
• Composer ready, PSR-12 and PSR-4 compliant

Documentation

Yasumi’s documentation is available on 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. See 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 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 for more information.