Yasumi

https://github.com/azuyalabs/yasumi
Admin
Yasumi is a PHP library that calculates holidays and special celebrations for various countries and...
Tokens:116,715
Snippets:810
Trust Score:7.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quick Start: Create Holiday Provider and Retrieve Holidays

Source: https://github.com/azuyalabs/yasumi/blob/develop/README.md

Basic usage example: create a holiday provider for a country and year, iterate over all holidays, get a specific holiday, and check if a date is a holiday. Requires Composer autoload.

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

--------------------------------

### Install Yasumi via Composer

Source: https://github.com/azuyalabs/yasumi/blob/develop/README.md

Use Composer to install the Yasumi library. Requires PHP 8.2 or higher.

```shell
composer require azuyalabs/yasumi
```

--------------------------------

### getProviders() usage example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Shows how to retrieve the provider map and inspect its contents. The example prints the total count (~161) and looks up a specific provider by its ID.

```php
$providers = \Yasumi\Yasumi::getProviders();
echo count($providers); // ~161
echo $providers['US-NYSE']; // USA/NYSE
```

--------------------------------

### Custom provider example (MyNYSE)

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/providers.md

Shows a custom provider class that extends USA and overrides initialize() to add Good Friday and remove Columbus Day and Veterans Day. The class is then used with Yasumi::create() to get holidays for 2026.

```php
use Yasumi\Provider\USA;

/** Provider for all observed holidays by the NYSE */
class MyNYSE extends USA
{
    public function initialize(): void
    {
        parent::initialize();

        $this->addHoliday($this->goodFriday($this->year, $this->timezone, $this->locale));
        $this->removeHoliday('columbusDay');
        $this->removeHoliday('veteransDay');
    }
}

$nyse = \Yasumi\Yasumi::create(MyNYSE::class, 2026);
```

--------------------------------

### Echo holiday and getHolidayDates example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/holiday.md

Shows how to echo a holiday (outputs the date string) and how to get an array of such date strings via getHolidayDates().

```php
echo $holiday; // 2026-07-04
$dates = $holidays->getHolidayDates(); // array of such strings
```

--------------------------------

### Full Usage Example via Factory

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Shows how to create a Yasumi provider through the factory, iterate holidays, use date predicates, run queries, and filter holidays. The example uses the Netherlands provider for 2026 with locale 'nl_NL'. Note that `next()` and `previous()` return nullable Holiday objects, and `isWeekendDay()` returns a boolean indicating whether the date is a weekend day.

```php
// Through the factory (recommended) — see yasumi.md
$holidays = \Yasumi\Yasumi::create('Netherlands', 2026, 'nl_NL');

echo $holidays->getYear();            // 2026
echo $holidays->count();              // number of unique holidays

foreach ($holidays as $holiday) {      // iterating via ArrayIterator
    echo $holiday->getName() . ': ' . $holiday . PHP_EOL;
}

// Date predicates
$date = new \DateTime('2026-12-25');
var_dump($holidays->isHoliday($date));    // bool(true)
var_dump($holidays->isWorkingDay($date)); // bool(false)
var_dump($holidays->isWeekendDay($date)); // weekend? bool

// Queries
echo $holidays->whenIs('christmasDay');    // 2026-12-25
echo $holidays->whatWeekDayIs('christmasDay'); // 5 (Friday)
echo $holidays->getHoliday('christmasDay')?->getName(); // "Eerste Kerstdag"
$next = $holidays->next('queensDay');      // ?Holiday (next year, if defined)
$prev = $holidays->previous('queensDay');  // ?Holiday

// Filtering
$dec = $holidays->between(new \DateTime('2026-12-01'), new \DateTime('2026-12-31'));
$onDay = $holidays->on(new \DateTime('2026-12-25'));
```

--------------------------------

### Using nextWorkingDay() and prevWorkingDay()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Example calls to nextWorkingDay() and prevWorkingDay(). The first finds the first non-holiday, non-weekend day after 2025-12-24 for the Netherlands. The second rewinds 3 working days from 2026-07-06 for the USA. Note: only DateTimeInterface instances are supported; a TODO exists to accept timezone and int/string start dates.

```php
$date = \Yasumi\Yasumi::nextWorkingDay('Netherlands', new \DateTime('2025-12-24'));
echo $date->format('Y-m-d'); // first non-holiday, non-weekend day after 2025-12-24

$threeDaysBack = \Yasumi\Yasumi::prevWorkingDay('USA', new \DateTime('2026-07-06'), 3);
```

--------------------------------

### createByISO3166_2() usage example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Shows how to retrieve holidays for a specific region and year with a custom locale. The example fetches Bavarian holidays for 2026 in German.

```php
$holidays = \Yasumi\Yasumi::createByISO3166_2('DE-BY', 2026, 'de_DE');
```

--------------------------------

### Project structure tree

Source: https://github.com/azuyalabs/yasumi/blob/develop/AGENTS.md

Shows the directory layout of the Yasumi project, including main entry point, providers, filters, data, tests, and examples.

```text
src/Yasumi/
  Yasumi.php              # Main entry point / factory
  Holiday.php             # Represents a single holiday
  SubstituteHoliday.php   # Substituted holiday
  ProviderInterface.php   # Contract all providers must implement
  Translations.php        # Holiday name translations
  Provider/               # One file (or directory) per country/region
    AbstractProvider.php  # Base class for all providers
    CommonHolidays.php    # Reusable holiday calculations (New Year's, etc.)
    ChristianHolidays.php # Easter and related calculations
    *.php / */            # Country and sub-region providers
  Filters/                # Holiday type filters (Official, Bank, etc.)
  data/                   # Translation data files
tests/                    # PHPUnit tests, mirroring src structure
examples/                 # Usage examples
```

--------------------------------

### Usage example with Translations

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/translations.md

Shows creating a Translations instance with available locales, loading translation files, retrieving translations, and adding a custom holiday translation.

```php
use Yasumi\Translations;

$translations = new Translations(\Yasumi\Yasumi::getAvailableLocales());
$translations->loadTranslations('/path/to/vendor/azuyalabs/yasumi/src/Yasumi/data/translations');

echo $translations->getTranslation('newYearsDay', 'nl_NL'); // "Nieuwjaar"
print_r($translations->getTranslations('christmasDay'));    // ['en' => ..., 'nl' => ..., ...]

$translations->addTranslation('myCustomHoliday', 'en_US', 'My Holiday');
```

--------------------------------

### Basic usage of Yasumi::create()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Shows how to create a provider for a country, a sub-region with a custom locale, and a custom provider class. The first example counts unique holidays for the USA in 2026; the second retrieves a holiday name in German; the third instantiates a custom provider class extending USA.

```php
// Basic usage
$holidays = \Yasumi\Yasumi::create('USA', 2026);
echo $holidays->count(); // number of unique holidays

// Sub-region provider and custom locale
$bavarian = \Yasumi\Yasumi::create('Germany/Bavaria', 2026, 'de_DE');
echo $bavarian->getHoliday('corpusChristi')?->getName(); // 'Fronleichnam'

// Custom provider class
class MyNYSE extends \Yasumi\Provider\USA { /* ... */ }
$nyse = \Yasumi\Yasumi::create(MyNYSE::class, 2026);
```

--------------------------------

### DateTimeZoneFactory usage example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/providers.md

Shows how to call DateTimeZoneFactory::getDateTimeZone with a timezone string. The second call with the same timezone returns the cached instance, demonstrating the caching behavior.

```php
$zone = \Yasumi\Provider\DateTimeZoneFactory::getDateTimeZone('Europe/Amsterdam');
$same = \Yasumi\Provider\DateTimeZoneFactory::getDateTimeZone('Europe/Amsterdam'); // cached
```

--------------------------------

### Holiday::getName() usage examples

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/holiday.md

Shows display locale translation and explicit locale preference list. The first example uses the display locale 'nl_NL' to get "Nieuwjaar". The second passes ['fr_FR', 'en'] to fall back to the parent locale 'fr' and returns "Jour de l'An".

```php
// Display locale translation
$holidays = \Yasumi\Yasumi::create('Netherlands', 2026, 'nl_NL');
echo $holidays->getHoliday('newYearsDay')->getName(); // "Nieuwjaar"

// Explicit locale preference list: 'fr_FR' misses, parent locale 'fr' matches
// (global translations for newYearsDay include 'fr' => 'Jour de l\'An')
echo $holidays->getHoliday('newYearsDay')->getName(['fr_FR', 'en']); // "Jour de l'An"
```

--------------------------------

### Run specific test suite with --testsuite

Source: https://github.com/azuyalabs/yasumi/blob/develop/CONTRIBUTING.md

Runs only the specified test suite, for example the Netherlands suite.

```shell
vendor/bin/phpunit --testsuite Netherlands
```

--------------------------------

### Create Yasumi instance for USA in 2026

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/README.md

Entry point example showing how to create a Yasumi holiday provider for the USA in 2026. Requires Composer's autoloader and PHP 8.2+.

```php
require 'vendor/autoload.php';
$holidays = \Yasumi\Yasumi::create('USA', 2026);
```

--------------------------------

### Example: get observed substitute holiday name

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/substitute-holiday.md

Creates a USA holiday provider for 2027 and retrieves the substitute holiday for New Year's Day. Outputs a localized name like "New Year's Day observed" (en_US).

```php
$holidays = \Yasumi\Yasumi::create('USA', 2027); // Jan 1, 2027 is a Friday; check year where NYD falls on Sunday
$observed = $holidays->getHoliday('substituteHoliday:newYearsDay');
echo $observed?->getName(); // e.g. "New Year's Day observed" (en_US)
```

--------------------------------

### json_encode holiday example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/holiday.md

Example of encoding a holiday with JSON_PRETTY_PRINT to see its serialized form.

```php
echo json_encode($holidays->getHoliday('independenceDay'), JSON_PRETTY_PRINT);
```

--------------------------------

### BetweenFilter Constructor

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/configuration.md

Creates a filter that selects holidays between a start and end date. The $equal parameter controls whether boundary dates are inclusive.

```APIDOC
## BetweenFilter Constructor

### Description
Creates a filter that selects holidays between a start and end date.

### Method
Constructor

### Endpoint
`BetweenFilter::__construct`

### Parameters
- **$iterator** (\Iterator) - Required - Iterator to filter.
- **$startDate** (\DateTimeInterface) - Required - Start date.
- **$endDate** (\DateTimeInterface) - Required - End date.
- **$equal** (bool) - Optional - Controls boundary inclusivity. Default `true`.
```

--------------------------------

### between()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns a BetweenFilter that filters holidays between the given start and end dates. Throws InvalidArgumentException if start date is after end date.

```APIDOC
## between()

### Description
Returns `BetweenFilter($this->getIterator(), $startDate, $endDate, $equals ?? true)`. Throws `\InvalidArgumentException` when `$startDate > $endDate`.

### Method
between

### Signature
```php
public function between(\DateTimeInterface $startDate, \DateTimeInterface $endDate, bool $equals = true): BetweenFilter
```

### Parameters
- **$startDate** (\DateTimeInterface) - Required - The start date of the range.
- **$endDate** (\DateTimeInterface) - Required - The end date of the range.
- **$equals** (bool) - Optional - Whether to include dates equal to the boundaries. Defaults to true.

### Return Value
BetweenFilter - A filter for holidays within the specified range.

### Exceptions
- **\InvalidArgumentException** - If `$startDate` is greater than `$endDate`.
```

--------------------------------

### between(\DateTimeInterface $startDate, \DateTimeInterface $endDate, ?bool $equals = null): BetweenFilter

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns a BetweenFilter that can be used to filter holidays between the given start and end dates. The $equals parameter controls whether the start and end dates are inclusive.

```APIDOC
## Method: between

### Description
Returns a BetweenFilter that can be used to filter holidays between the given start and end dates. The $equals parameter controls whether the start and end dates are inclusive.

### Signature
```php
public function between(\DateTimeInterface $startDate, \DateTimeInterface $endDate, ?bool $equals = null): BetweenFilter;
```

### Parameters
- **startDate** (\DateTimeInterface) - Required - The start date of the range.
- **endDate** (\DateTimeInterface) - Required - The end date of the range.
- **equals** (?bool) - Optional - Whether to include the start and end dates. Defaults to null (behavior not specified).

### Return Value
BetweenFilter - A filter object for further querying.
```

--------------------------------

### Yasumi::nextWorkingDay()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Returns the next working day (skipping weekends and holidays) from a given start date. The number of working days to advance can be specified.

```APIDOC
## Yasumi::nextWorkingDay()

### Description
Returns the next working day (skipping weekends and holidays) from a given start date. The number of working days to advance can be specified.

### Method
`public static function nextWorkingDay(string $class, \DateTimeInterface $startDate, int $workingDays = 1): \DateTimeInterface`

### Parameters
- **$class** (string) - Required - The holiday provider class name.
- **$startDate** (\DateTimeInterface) - Required - The starting date.
- **$workingDays** (int) - Optional - Number of working days to advance (default: 1).

### Return Value
- **\DateTimeInterface** - The next working day.
```

--------------------------------

### Holiday::getType() usage example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/holiday.md

Retrieves a holiday by key and prints its type, e.g. "official" for Christmas Day.

```php
$holiday = $holidays->getHoliday('christmasDay');
echo $holiday->getType(); // "official"
```

--------------------------------

### Yasumi::nextWorkingDay() and prevWorkingDay() method signatures

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Determines the next or previous working day relative to a start date, skipping weekends and holidays. The provider instance is re-created when crossing into a different year. Throws RuntimeException with message 'Unable to perform date interval addition/subtraction' and other exceptions from create().

```php
public static function nextWorkingDay(
    string $class,
    \DateTimeInterface $startDate,
    int $workingDays = 1,
): \DateTimeInterface

public static function prevWorkingDay(
    string $class,
    \DateTimeInterface $startDate,
    int $workingDays = 1,
): \DateTimeInterface
```

--------------------------------

### Yasumi::prevWorkingDay()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Returns the previous working day (skipping weekends and holidays) from a given start date. The number of working days to go back can be specified.

```APIDOC
## Yasumi::prevWorkingDay()

### Description
Returns the previous working day (skipping weekends and holidays) from a given start date. The number of working days to go back can be specified.

### Method
`public static function prevWorkingDay(string $class, \DateTimeInterface $startDate, int $workingDays = 1): \DateTimeInterface`

### Parameters
- **$class** (string) - Required - The holiday provider class name.
- **$startDate** (\DateTimeInterface) - Required - The starting date.
- **$workingDays** (int) - Optional - Number of working days to go back (default: 1).

### Return Value
- **\DateTimeInterface** - The previous working day.
```

--------------------------------

### Error Handling and Edge Cases

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Demonstrates exception handling for common Yasumi errors: `HolidayNotFoundException` when querying a non-existent holiday, `InvalidArgumentException` for blank holiday keys in `removeHoliday()`, and `InvalidArgumentException` when the start date is after the end date in `between()`. Each catch block prints the exception message.

```php
// Error-handling / edge cases
try {
    $holidays->whenIs('nonexistentHoliday');
} catch (\Yasumi\Exception\HolidayNotFoundException $e) {
    echo $e->getMessage(); // Holiday "nonexistentHoliday" is not defined for the year 2026.
}

try {
    $holidays->removeHoliday('');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Holiday key can not be blank.
}

try {
    $holidays->between(new \DateTime('2026-12-31'), new \DateTime('2026-01-01'));
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // Start date must be a date before the end date.
}
```

--------------------------------

### BetweenFilter class constructor

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/filters.md

Constructor for the BetweenFilter. Accepts an iterator, start and end DateTimeInterface objects, and an optional $equal flag (default true) controlling inclusive vs exclusive bounds. Dates are compared as 'Y-m-d'.

```php
class BetweenFilter extends AbstractFilter
{
    public function __construct(
        \Iterator $iterator,
        \DateTimeInterface $startDate,
        \DateTimeInterface $endDate,
        private readonly bool $equal = true,
    );
}
```

--------------------------------

### Using BetweenFilter with inclusive and exclusive bounds

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/filters.md

Creates a Yasumi provider for USA 2026, uses between() to get July holidays (inclusive), iterates to print each holiday, then creates an exclusive BetweenFilter for July 3-5 and outputs its count.

```php
$holidays = \Yasumi\Yasumi::create('USA', 2026);
$july = $holidays->between(
    new \DateTime('2026-07-01'),
    new \DateTime('2026-07-31')
);
foreach ($july as $holiday) {
    echo $holiday . ' ' . $holiday->getName() . PHP_EOL;
}

// Exclusive bounds
$exclusive = new \Yasumi\Filters\BetweenFilter(
    $holidays->getIterator(),
    new \DateTime('2026-07-03'),
    new \DateTime('2026-07-05'),
    false
);
echo $exclusive->count();
```

--------------------------------

### Custom Provider Implementation

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/providers.md

Guidelines for writing a custom provider: extend AbstractProvider, implement initialize(), define ID constant, set timezone, add/remove holidays, and provide translations and sources.

```APIDOC
## Custom Provider Implementation

### Description
To create a custom provider, extend `AbstractProvider` (or an existing provider) and implement `initialize()`. The provider must define an `ID` constant for discovery and set the timezone before adding holidays.

### Requirements
1. Extend `Yasumi\Provider\AbstractProvider` and implement `public function initialize(): void`.
2. Define `public const ID = '<ISO3166-2 code>';` to be discoverable via `getProviders()` / `createByISO3166_2()`.
3. Set `$this->timezone` inside `initialize()` before building holidays.
4. Register holidays with `$this->addHoliday($holiday)`; remove unwanted ones with `$this->removeHoliday($key)`.
5. Add translation data either inline in the `Holiday` constructor's `$translations` array or via the global `Translations` store.
6. Implement `getSources(): array` returning documentation references.

### Example
```php
use Yasumi\Provider\USA;

/** Provider for all observed holidays by the NYSE */
class MyNYSE extends USA
{
    public function initialize(): void
    {
        parent::initialize();

        $this->addHoliday($this->goodFriday($this->year, $this->timezone, $this->locale));
        $this->removeHoliday('columbusDay');
        $this->removeHoliday('veteransDay');
    }
}

$nyse = \Yasumi\Yasumi::create(MyNYSE::class, 2026);
```
```

--------------------------------

### Run tests with vendor/bin/phpunit

Source: https://github.com/azuyalabs/yasumi/blob/develop/CONTRIBUTING.md

Alternative way to run the test suite directly using PHPUnit.

```shell
vendor/bin/phpunit
```

--------------------------------

### Run full test suite with composer test

Source: https://github.com/azuyalabs/yasumi/blob/develop/CONTRIBUTING.md

Executes the complete test suite for the project.

```shell
composer test
```

--------------------------------

### Yasumi::create

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/providers.md

Creates a provider instance using a fully-qualified class name that implements ProviderInterface. The class is used directly, and the provider must implement initialize().

```APIDOC
## `Yasumi::create`

### Description
Creates a provider instance for the given class name and year. The class must implement `ProviderInterface` (typically by extending `AbstractProvider`).

### Method
`create` (static)

### Signature
```php
public static function create(string $class, int $year): ProviderInterface;
```

### Parameters
- **class** (string) - Required - Fully-qualified class name of the provider.
- **year** (int) - Required - The year for which to create the provider.

### Return Value
- `ProviderInterface` - The provider instance.

### Example
```php
$nyse = \Yasumi\Yasumi::create(MyNYSE::class, 2026);
```
```

--------------------------------

### initialize(): void

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Abstract method that must be implemented by each country/region provider to define its holidays. Called during construction to populate the provider's holiday list.

```APIDOC
## Method: initialize

### Description
Abstract method that must be implemented by each country/region provider to define its holidays. Called during construction to populate the provider's holiday list.

### Signature
```php
abstract public function initialize(): void;
```

### Parameters
None.

### Return Value
void
```

--------------------------------

### TranslationsInterface::getTranslations

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/translations.md

Interface method to get all translations for a holiday key.

```APIDOC
## `TranslationsInterface::getTranslations`

### Description
Interface method to get all translations for a holiday key.

### Method
`getTranslations`

### Signature
`public function getTranslations(string $key): array`

### Parameters
- **$key** (string) - Required - Holiday key.

### Returns
- **array** - `array<string, string>` — all translations for holiday `$key` (`['<locale>' => '<translation>', ...]`), or `[]`.

```

--------------------------------

### Run all pre-submission checks

Source: https://github.com/azuyalabs/yasumi/blob/develop/CONTRIBUTING.md

Always run these three checks before opening a pull request: coding standard, static analysis, and full test suite.

```shell
composer cs        # Check coding standard
```

```shell
composer phpstan   # Static analysis (level 9)
```

```shell
composer test      # Full test suite
```

--------------------------------

### TranslationsInterface::getTranslation

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/translations.md

Interface method to get a translation for a holiday key and locale.

```APIDOC
## `TranslationsInterface::getTranslation`

### Description
Interface method to get a translation for a holiday key and locale.

### Method
`getTranslation`

### Signature
`public function getTranslation(string $key, string $locale): ?string`

### Parameters
- **$key** (string) - Required - Holiday key.
- **$locale** (string) - Required - Locale code.

### Returns
- **?string** - The translation for holiday `$key` in `$locale`, or `null`.

```

--------------------------------

### initialize()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Abstract method that must be implemented by every country/region provider to populate the provider's holidays, typically by calling trait factories and addHoliday().

```APIDOC
## initialize()

### Description
Populates the provider's holidays — typically by calling trait factories (`$this->newYearsDay(...)`, `$this->easter(...)`) and `$this->addHoliday(...)`. Must be implemented by every country/region provider. Historically-derived holidays are often gated on the year (e.g. `if ($this->year >= 1879)`).

### Method
initialize

### Signature
```php
abstract public function initialize(): void
```

### Parameters
None

### Return Value
void
```

--------------------------------

### Abstract Method initialize()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Abstract method that must be implemented by every country/region provider to populate holidays, typically by calling trait factories and addHoliday().

```php
abstract public function initialize(): void
```

--------------------------------

### Holiday::getName() error handling example

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/holiday.md

Catches MissingTranslationException when no translation is found for the searched locales, e.g. ['xx_YY'].

```php
// Error handling: unknown translation for all searched locales
try {
    $name = $holidays->getHoliday('newYearsDay')->getName(['xx_YY']);
} catch (\Yasumi\Exception\MissingTranslationException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Composer commands for testing, code style, and static analysis

Source: https://github.com/azuyalabs/yasumi/blob/develop/AGENTS.md

Lists the key Composer commands used in the Yasumi development workflow: run tests, check coding standards, auto-fix violations, and run PHPStan at level 9.

```shell
composer test          # Run the full PHPUnit test suite
composer cs            # Check coding standard (dry-run)
composer cs-fix        # Auto-fix coding standard violations (alias: composer format)
composer phpstan       # Run static analysis (level 9)
```

--------------------------------

### whenIs

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns the date of a holiday by its key.

```APIDOC
## whenIs

### Description
Returns the date of the holiday with the given key.

### Method
`whenIs(string $key)`

### Parameters
- `$key` (string) - Required - The holiday key (e.g., 'christmasDay').

### Return Value
- `string` - The date in YYYY-MM-DD format.

### Exceptions
- `\Yasumi\Exception\HolidayNotFoundException` - If the holiday is not defined for the year.

### Example
```php
echo $holidays->whenIs('christmasDay'); // 2026-12-25
```
```

--------------------------------

### next() and previous() methods

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Delegated to private anotherTime() which creates a provider for the next or previous year and returns that year's holiday for the key, or null. Uses static::class so subclasses resolve correctly.

```php
public function next(string $key): ?Holiday     // anotherTime($this->year + 1, $key)
public function previous(string $key): ?Holiday // anotherTime($this->year - 1, $key)
```

--------------------------------

### next(string $key): ?Holiday

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns the next holiday after the current date (or after the holiday with the given key) for the given key. Returns null if no next holiday exists.

```APIDOC
## Method: next

### Description
Returns the next holiday after the current date (or after the holiday with the given key) for the given key. Returns null if no next holiday exists.

### Signature
```php
public function next(string $key): ?Holiday;
```

### Parameters
- **key** (string) - Required - The unique identifier of the holiday.

### Return Value
?Holiday - The next Holiday object or null if none exists.
```

--------------------------------

### BetweenFilter

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/filters.md

Filters holidays within a date range. It accepts an iterator of holidays, a start date, an end date, and an optional inclusive flag.

```APIDOC
## BetweenFilter

### Description
Filters holidays within a date range. It accepts an iterator of holidays, a start date, an end date, and an optional inclusive flag.

### Constructor Parameters
- **$iterator** (\Iterator) - Required - Holiday iterator.
- **$startDate** (\DateTimeInterface) - Required - Window start; compared as `'Y-m-d'`.
- **$endDate** (\DateTimeInterface) - Required - Window end.
- **$equal** (bool) - Optional - Default `true`. `true` ⇒ inclusive (`>= start && <= end`); `false` ⇒ exclusive (`> start && < end`).

### Returns
Iterating yields `Yasumi\Holiday` instances; `count()` returns the number of matching unique holidays.

### Example
```php
$holidays = \Yasumi\Yasumi::create('USA', 2026);
$july = $holidays->between(
    new \DateTime('2026-07-01'),
    new \DateTime('2026-07-31')
);
foreach ($july as $holiday) {
    echo $holiday . ' ' . $holiday->getName() . PHP_EOL;
}

// Exclusive bounds
$exclusive = new \Yasumi\Filters\BetweenFilter(
    $holidays->getIterator(),
    new \DateTime('2026-07-03'),
    new \DateTime('2026-07-05'),
    false
);
echo $exclusive->count();
```
```

--------------------------------

### getProviders() method signature

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Public static method that discovers all holiday providers shipped with the library, recursively scanning src/Yasumi/Provider/. Skips ignored provider files and classes that do not subclass AbstractProvider or lack a string ID constant. Returns a statically cached array mapping uppercase IDs to provider short names. Throws ReflectionException if a provider class cannot be reflected.

```php
public static function getProviders(): array
```

--------------------------------

### __construct(int $year, ?string $locale = null, ?TranslationsInterface $globalTranslations = null)

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Creates a new provider instance for the given year and locale. The global translations are optional and used for holiday name translations.

```APIDOC
## Constructor

### Description
Creates a new provider instance for the given year and locale. The global translations are optional and used for holiday name translations.

### Signature
```php
public function __construct(
    int $year,
    ?string $locale = null,
    private readonly ?TranslationsInterface $globalTranslations = null,
);
```

### Parameters
- **year** (int) - Required - The year for which holidays are provided.
- **locale** (?string) - Optional - The locale for holiday names. Defaults to null.
- **globalTranslations** (?TranslationsInterface) - Optional - Global translations for holiday names.
```

--------------------------------

### Using Yasumi::getAvailableLocales() to check a locale

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Example usage of getAvailableLocales() to check if a specific locale (e.g., 'ja_JP') is available. Outputs 'yes' or 'no' based on strict in_array check.

```php
$locales = \Yasumi\Yasumi::getAvailableLocales();
echo in_array('ja_JP', $locales, true) ? 'yes' : 'no';
```

--------------------------------

### SubstituteHoliday class signature

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/substitute-holiday.md

Declares the SubstituteHoliday class extending Yasumi\Holiday, with a public array for translations and methods for construction, retrieving the substituted holiday, getting the name, and merging global translations.

```php
class SubstituteHoliday extends Holiday
{
    /** @var array<string> list of translations of the "{0} observed" pattern */
    public array $substituteHolidayTranslations;

    public function __construct(
        public Holiday $substitutedHoliday,
        array $names,
        \DateTimeInterface $date,
        string $displayLocale = self::DEFAULT_LOCALE,
        string $type = self::TYPE_OFFICIAL,
    );

    public function getSubstitutedHoliday(): Holiday;
    public function getName(?array $locales = null): string;
    public function mergeGlobalTranslations(TranslationsInterface $globalTranslations): void;
}
```

--------------------------------

### getYear

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns the year of the holiday provider instance.

```APIDOC
## getYear

### Description
Returns the year for which the provider is configured.

### Method
`getYear()`

### Return Value
- `int` - The provider's year.

### Example
```php
echo $holidays->getYear(); // 2026
```
```

--------------------------------

### Yasumi::create() method signature

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Static factory method that creates a holiday provider instance. Accepts a provider name (short or fully-qualified), a year between 1000 and 9999, and a locale from the available list. Throws ProviderNotFoundException, InvalidYearException, or UnknownLocaleException on invalid input.

```php
public static function create(
    string $class,
    int $year = self::YEAR_LOWER_BOUND,
    string $locale = self::DEFAULT_LOCALE,
): ProviderInterface
```

--------------------------------

### Yasumi::prevWorkingDay()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Determines the previous working day relative to a start date, skipping weekends and holidays defined by the provider. The provider instance is re-created transparently when the scan crosses into a different year.

```APIDOC
## `Yasumi::prevWorkingDay()`

### Description
Determines the previous working day relative to a start date, skipping weekends and holidays defined by the provider. The provider instance is re-created transparently when the scan crosses into a different year.

### Method
`public static function prevWorkingDay(string $class, \DateTimeInterface $startDate, int $workingDays = 1): \DateTimeInterface`

### Parameters
- **$class** (string) - Required - Provider name/class, same resolution rules as `create()`.
- **$startDate** (\DateTimeInterface) - Required - Start date; a mutable `\DateTime` is converted to `\DateTimeImmutable` internally.
- **$workingDays** (int) - Optional (default: `1`) - Number of working days to rewind; `1` = first working day before `$startDate`.

### Returns
- **\DateTimeInterface** - A `\DateTimeImmutable` representing the previous working day.

### Throws
- **\RuntimeException** - `'Unable to perform date interval addition/subtraction'`
- **UnknownLocaleException**, **\InvalidArgumentException**, **\Exception** - Everything `create()` throws.

### Example
```php
$threeDaysBack = \Yasumi\Yasumi::prevWorkingDay('USA', new \DateTime('2026-07-06'), 3);
```
```

--------------------------------

### Yasumi::nextWorkingDay()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Determines the next working day relative to a start date, skipping weekends and holidays defined by the provider. The provider instance is re-created transparently when the scan crosses into a different year.

```APIDOC
## `Yasumi::nextWorkingDay()`

### Description
Determines the next working day relative to a start date, skipping weekends and holidays defined by the provider. The provider instance is re-created transparently when the scan crosses into a different year.

### Method
`public static function nextWorkingDay(string $class, \DateTimeInterface $startDate, int $workingDays = 1): \DateTimeInterface`

### Parameters
- **$class** (string) - Required - Provider name/class, same resolution rules as `create()`.
- **$startDate** (\DateTimeInterface) - Required - Start date; a mutable `\DateTime` is converted to `\DateTimeImmutable` internally.
- **$workingDays** (int) - Optional (default: `1`) - Number of working days to advance; `1` = first working day after `$startDate`.

### Returns
- **\DateTimeInterface** - A `\DateTimeImmutable` representing the next working day.

### Throws
- **\RuntimeException** - `'Unable to perform date interval addition/subtraction'`
- **UnknownLocaleException**, **\InvalidArgumentException**, **\Exception** - Everything `create()` throws.

### Example
```php
$date = \Yasumi\Yasumi::nextWorkingDay('Netherlands', new \DateTime('2025-12-24'));
echo $date->format('Y-m-d'); // first non-holiday, non-weekend day after 2025-12-24
```
```

--------------------------------

### Sign commit with DCO using git commit -s

Source: https://github.com/azuyalabs/yasumi/blob/develop/CONTRIBUTING.md

Each commit must include a Signed-off-by trailer to certify agreement with the Developer Certificate of Origin.

```shell
git commit -s -m "feat: your change"
```

--------------------------------

### AbstractProvider::__construct

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Constructor for the AbstractProvider class. Initializes the provider with a year, optional locale, and optional global translations, then calls the abstract initialize() method.

```APIDOC
## [CONSTRUCTOR] AbstractProvider::__construct

### Description
Constructor for the AbstractProvider class. Initializes the provider with a year, optional locale, and optional global translations, then calls the abstract initialize() method.

### Method
Constructor

### Signature
```php
public function __construct(
    int $year,
    ?string $locale = null,
    private readonly ?TranslationsInterface $globalTranslations = null,
)
```

### Parameters
- **$year** (int) - Required - Year to calculate holidays for. `0` (or falsy) falls back to the current year: `$this->year = $year ?: (int) date('Y')`.
- **$locale** (?string) - Optional - Display locale; `null` becomes `'en_US'`.
- **$globalTranslations** (?TranslationsInterface) - Optional - Global translation store merged into every added holiday.

### Description
Constructor flow: `clearHolidays()`, set `$year`/`$locale`, then call the abstract `initialize()` — i.e. subclass initialization runs during construction. (Instantiate providers via `Yasumi::create()` for validation and translation wiring.)
```

--------------------------------

### createByISO3166_2() method signature

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Public static method that creates a holiday provider by its ISO3166-2-style ID constant. Accepts a case-insensitive code like 'US', 'DE-BY', or 'AU-TAS-NW-CH', with optional year (default 1000) and locale (default 'en_US'). Returns a ProviderInterface and throws ProviderNotFoundException for unknown codes, plus InvalidYearException/UnknownLocaleException delegated to create().

```php
public static function createByISO3166_2(
    string $isoCode,
    int $year = self::YEAR_LOWER_BOUND,
    string $locale = self::DEFAULT_LOCALE,
): ProviderInterface
```

--------------------------------

### Error handling with Yasumi::create()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Demonstrates catching exceptions thrown by create() for invalid provider names and invalid years. The first try block catches ProviderNotFoundException with message 'Unable to find holiday provider "Atlantis".'; the second catches InvalidYearException with message 'Year needs to be between 1000 and 9999 (42 given).'.

```php
// Error handling
try {
    $holidays = \Yasumi\Yasumi::create('Atlantis', 2026);
} catch (\Yasumi\Exception\ProviderNotFoundException $e) {
    echo $e->getMessage(); // Unable to find holiday provider "Atlantis".
}

try {
    $holidays = \Yasumi\Yasumi::create('USA', 42);
} catch (\Yasumi\Exception\InvalidYearException $e) {
    echo $e->getMessage(); // Year needs to be between 1000 and 9999 (42 given).
}
```

--------------------------------

### Calculate Easter directly from a provider

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/traits.md

Demonstrates calling calculateEaster() on a provider instance to get a \DateTimeInterface for a given year and timezone. The result can be formatted with standard date methods, as shown by outputting the date in Y-m-d format.

```php
// Calculating Easter directly from a provider
$easterDate = $provider->calculateEaster(2026, 'Europe/Berlin'); // \DateTimeInterface
echo $easterDate->format('Y-m-d');
```

--------------------------------

### on()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns an OnFilter that filters holidays on the given date.

```APIDOC
## on()

### Description
Returns `OnFilter($this->getIterator(), $date)`.

### Method
on

### Signature
```php
public function on(\DateTimeInterface $date): OnFilter
```

### Parameters
- **$date** (\DateTimeInterface) - Required - The date to filter holidays on.

### Return Value
OnFilter - A filter for holidays on the specified date.
```

--------------------------------

### next

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns the next occurrence of a holiday after the current year.

```APIDOC
## next

### Description
Returns the next holiday object for the given key, searching in subsequent years if not found in the current year.

### Method
`next(string $key)`

### Parameters
- `$key` (string) - Required - The holiday key (e.g., 'queensDay').

### Return Value
- `?Holiday` - The next holiday object or null if not found.

### Example
```php
$next = $holidays->next('queensDay');
```
```

--------------------------------

### Yasumi::create

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Factory method to create a holiday provider instance for a given country, year, and locale.

```APIDOC
## Yasumi::create

### Description
Creates a new holiday provider instance for the specified country, year, and locale.

### Method
`Yasumi::create`

### Parameters
- `country` (string) - Required - Country name (e.g., 'Netherlands')
- `year` (int) - Required - Year for which holidays are calculated
- `locale` (string) - Optional - Locale string (e.g., 'nl_NL')

### Return Value
Returns a holiday provider instance.

### Example
```php
$holidays = \Yasumi\Yasumi::create('Netherlands', 2026, 'nl_NL');
```
```

--------------------------------

### Yasumi\Translations Constructor

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/configuration.md

Initializes a Translations instance with an allow-list of available locales for validation. The translations property is publicly accessible and holds the loaded translation map.

```APIDOC
## Translations Constructor

### Description
Initializes a Translations instance with an allow-list of available locales for validation.

### Method
Constructor

### Endpoint
`Yasumi\Translations::__construct`

### Parameters
- **$availableLocales** (array<string>) - Required - Locale allow-list for validation.

### Public Property
- **$translations** (array<string, array<string, string>>) - Loaded translation map: holiday key ⇒ locale ⇒ translation. Default `[]`.
```

--------------------------------

### Yasumi::create

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/README.md

Static factory method to create a holiday provider instance for a given country and year. This is the primary entry point for retrieving holidays.

```APIDOC
## Yasumi::create

### Description
Creates a holiday provider instance for the specified country and year.

### Method
`Yasumi::create` (static)

### Parameters
- **country** (string) - Required - Country code (e.g., 'USA')
- **year** (int) - Required - Year for which holidays are calculated

### Request Example
```php
$holidays = \Yasumi\Yasumi::create('USA', 2026);
```

### Response
Returns a provider instance (e.g., `Yasumi\Provider\USA`) that can be used to retrieve holidays.
```

--------------------------------

### Format code with composer format

Source: https://github.com/azuyalabs/yasumi/blob/develop/CONTRIBUTING.md

Run after completing work to check and correct code for PSR-12 Coding Standard using php-cs-fixer.

```shell
composer format
```

--------------------------------

### Yasumi::getProviders()

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/yasumi.md

Returns a list of all available holiday provider classes. This can be used to enumerate the supported countries and regions.

```APIDOC
## Yasumi::getProviders()

### Description
Returns a list of all available holiday provider classes. This can be used to enumerate the supported countries and regions.

### Method
`public static function getProviders(): array`

### Return Value
- **array** - List of provider class names.
```

--------------------------------

### previous(string $key): ?Holiday

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns the previous holiday before the current date (or before the holiday with the given key) for the given key. Returns null if no previous holiday exists.

```APIDOC
## Method: previous

### Description
Returns the previous holiday before the current date (or before the holiday with the given key) for the given key. Returns null if no previous holiday exists.

### Signature
```php
public function previous(string $key): ?Holiday;
```

### Parameters
- **key** (string) - Required - The unique identifier of the holiday.

### Return Value
?Holiday - The previous Holiday object or null if none exists.
```

--------------------------------

### getYear(): int

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/api-reference/abstract-provider.md

Returns the year for which this provider was instantiated.

```APIDOC
## Method: getYear

### Description
Returns the year for which this provider was instantiated.

### Signature
```php
public function getYear(): int;
```

### Parameters
None.

### Return Value
int - The year.
```

--------------------------------

### Yasumi\Translations::loadTranslations

Source: https://github.com/azuyalabs/yasumi/blob/develop/_autodocs/configuration.md

Loads translations from a directory of PHP translation files. The directory path must be provided as a string.

```APIDOC
## loadTranslations

### Description
Loads translations from a directory of PHP translation files.

### Method
loadTranslations

### Endpoint
`Yasumi\Translations::loadTranslations`

### Parameters
- **$directoryPath** (string) - Required - Directory of `*.php` translation files.
```
Tokens:
Raw