Yasumi PHP Library

If you are creating a custom holiday provider by extending the AbstractProvider class, note the following:

• Method Visibility: Many methods in the provider hierarchy are protected. Do not rely on them being public if you are extending the class.
• Namespace Resolution: When using ReflectionClass via the anotherTime() method in AbstractProvider, the library uses getName() instead of getShortName(). This ensures that custom holiday providers with full namespaces do not trigger a ProviderNotFoundException.

To use Yasumi, ensure your environment meets the following requirements:

• PHP Version: As of version 2.7.0, PHP 7.4 support has been removed. Ensure you are using PHP 8.0 or higher (PHP 8.3 is supported).
• Required Extension: The ext-intl PHP extension is a required dependency as of version 2.6.0.

Install Yasumi using Composer to include it in your PHP project. Ensure your environment meets the minimum requirement of PHP 8.2.

composer require azuyalabs/yasumi

To use Yasumi, use the Yasumi\Yasumi::create() method to instantiate a holiday provider for a specific country (or state) and year. The resulting object implements ArrayIterator, allowing you to loop through all holidays for that period. Each holiday object provides methods like getName() and format() to retrieve details.

<?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 Yasumi\Holiday class represents a specific holiday instance. It extends PHP's native \DateTime, meaning you can use it anywhere a DateTime object is expected (e.g., for date arithmetic or formatting). It carries additional metadata such as the holiday's unique key, its type (official, observance, etc.), and localized names via a translation system.

use Yasumi\Holiday;

// A Holiday instance behaves like a DateTime object
$holiday = new Holiday('newYearsDay', [], new \DateTime('2026-01-01'));
echo $holiday->format('Y-m-d'); // 2026-01-01

You can retrieve a specific holiday from a provider using the getHoliday() method by passing its identifier (e.g., 'independenceDay'). If the holiday exists, it returns the holiday object; otherwise, it returns null. This allows you to easily check if a specific date is recognized as a holiday.

<?php

require 'vendor/autoload.php';

$holidays = Yasumi\Yasumi::create('USA', 2026);

// Get a specific holiday
$independenceDay = $holidays->getHoliday('independenceDay');
if ($independenceDay !== null) {
    echo $independenceDay->getName() . ' is on ' . $independenceDay->format('F j, Y') . PHP_EOL;
}

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