README

A PHP library for calculating public holidays around the world. It makes rules and holiday data equivalent to JavaScript's date-holidays / date-holidays-parser available from PHP.

Features

Get holiday lists by country, state, and region code
Check whether a given date is a holiday
Support holiday names in multiple languages
Support configurable timezones
Support substitute holidays, movable holidays, and calendar-based holiday calculations
Build YAML holiday data into a PHP array cache

Requirements

PHP 8.2 or later
PHP extensions
- calendar
- json
Composer

Installation

composer require suzunone/date-holidays

For development, clone this repository and install its dependencies.

composer install

Basic Usage

<?php

require __DIR__ . '/vendor/autoload.php';

use Suzunone\DateHolidays\Holidays;

$holidays = new Holidays('JP', null, null, [
    'languages' => 'ja',
    'timezone' => 'Asia/Tokyo',
]);

foreach ($holidays->getHolidays(2024) as $holiday) {
    echo $holiday['date'] . ' ' . $holiday['name'] . PHP_EOL;
}

getHolidays() returns the holidays for the specified year in date order.

$holidays = new Holidays('US', 'ca');

$items = $holidays->getHolidays(2024);

// Example:
// [
//     'date' => '2024-01-01 00:00:00',
//     'start' => DateTimeImmutable,
//     'end' => DateTimeImmutable,
//     'name' => 'New Year\'s Day',
//     'type' => 'public',
//     'rule' => '01-01 and if sunday then next monday if saturday then previous friday',
// ]

Check a Date

$holidays = new Holidays('JP', null, null, ['languages' => 'en']);

$result = $holidays->isHoliday('2024-01-01');

if ($result !== false) {
    echo $result[0]['name']; // New Year's Day
}

isHoliday() returns an array of holiday information when the date is a holiday, and false otherwise.

Country, State, and Region Codes

Country, state, and region codes can be retrieved with query() or the dedicated methods.

$holidays = new Holidays();

$countries = $holidays->getCountries('ja');
$states = $holidays->getStates('US', 'en');
$regions = $holidays->getRegions('GB', 'eng', 'en');

// Returns countries / states / regions depending on the arguments.
$countries = $holidays->query(null, null, 'ja');
$states = $holidays->query('US', null, 'en');

When initializing, pass the country code, state code, and region code in that order.

$jp = new Holidays('JP');
$california = new Holidays('US', 'ca');
$region = new Holidays('GB', 'eng', 'wls');

Languages and Timezones

Languages are specified with ISO 639-1 codes.

$holidays = new Holidays('JP', null, null, [
    'languages' => ['ja', 'en'],
    'timezone' => 'Asia/Tokyo',
]);

$languages = $holidays->getLanguages();
$timezones = $holidays->getTimezones();
$dayOff = $holidays->getDayOff();

The second argument of getHolidays() can be used to set the preferred language for that call only.

$holidays = new Holidays('JP');

$items = $holidays->getHolidays(2024, 'ja');

Custom Rules

You can add custom holidays in addition to the existing holiday rules.

$holidays = new Holidays('JP', null, null, ['languages' => 'en']);

$holidays->setHoliday('07-20', [
    'name' => ['en' => 'Company Anniversary'],
    'type' => 'observance',
]);

$items = $holidays->getHolidays(2024);

You can also set holidays using the rule object format.

$holidays->setRule([
    'rule' => '12-31',
    'name' => ['en' => 'Year-End Closure'],
    'type' => 'bank',
]);

Existing rules can be disabled with unsetRule().

$holidays->unsetRule('01-01');

Data

Holiday data is stored in data/yaml.

data/yaml/names.yaml: Name data such as country and region names
data/yaml/countries/*.yaml: Holiday definitions for each country and region
data/php/holidays.php: PHP array cache generated from YAML

At runtime, data/php/holidays.php is loaded first when it exists. If the cache is unavailable, or if the dataDir option is specified, data is loaded from YAML.

$holidays = new Holidays('JP', null, null, [
    'dataDir' => __DIR__ . '/data/yaml',
]);

Run the following command to regenerate the data cache.

composer build-data

Alternatively, run the builder directly with explicit input and output paths.

php bin/build-data.php --source=data/yaml --output=data/php/holidays.php

Development

Common Composer scripts are listed below.

composer test
composer test:serial
composer cs-fix
composer rector
composer doc
composer doc-html
composer build

composer test: Run PHPUnit in parallel with ParaTest
composer test:serial: Run PHPUnit in a single process
composer cs-fix: Format code with PHP-CS-Fixer
composer rector: Run Rector
composer doc: Generate Markdown API documentation
composer doc-html: Generate HTML API documentation
composer build: Run data generation, code formatting, and documentation generation together

API Documentation

Generated Markdown API documentation is available in docs/api.

docs/api/index.md
docs/api/Suzunone/DateHolidays/Holidays.md

License

This project follows the license terms of the original date-holidays project.

Holiday data: CC BY-SA 3.0
Other code: ISC License

See LICENSE for the full license text and attribution.

suzunone / date-holidays

Maintainers

Package info

Statistics

Security