README

English | 日本語

English

Japanese national holidays library for PHP.

Verified against the National Astronomical Observatory of Japan (NAO) official data.

Requirements

• PHP 7.1+

Installation

composer require sakai/jp-holiday

Usage

use Sakai\JpHoliday\JpHoliday;

$date = new DateTimeImmutable('2024-01-01');

JpHoliday::isHoliday($date);     // true
JpHoliday::getName($date);       // '元日'
JpHoliday::getNameEn($date);     // "New Year's Day"
JpHoliday::getDescription($date); // '年のはじめを祝う。'

Get Full Holiday Info

$info = JpHoliday::getHolidayInfo($date);
// ['name' => '元日', 'name_en' => "New Year's Day", 'description' => '...']

Get All Holidays in a Year

$holidays = JpHoliday::getHolidaysInYear(2024);
// ['2024-01-01' => [...], '2024-01-08' => [...], ...]

Get Holidays in Date Range

$holidays = JpHoliday::between(
    new DateTimeImmutable('2024-04-01'),
    new DateTimeImmutable('2024-05-31')
);

DateTime / DateTimeImmutable / Carbon

Any class implementing DateTimeInterface is supported.

API

Configuration

Limit date ranges for between() to prevent DoS:

JpHoliday::configure(['maxBetweenDays' => 365]);  // Limit to 365 days
JpHoliday::getConfig();                            // ['maxBetweenDays' => 365]
JpHoliday::resetConfig();                          // Reset to default (no limit)

Supported Holidays

• Fixed holidays (New Year's Day, National Foundation Day, etc.)
• Happy Monday holidays (Coming of Age Day, Marine Day, etc.)
• Equinox days (Vernal/Autumnal Equinox Day)
• Substitute holidays (振替休日)
• Citizen's holidays (国民の休日)
• Special: 2019 Imperial transition, 2020/2021 Olympics

Limitations

This library only supports dates from July 20, 1948 onwards, when the National Holidays Act (国民の祝日に関する法律) was enacted. Dates before this will return empty/null.

Data Sources & Maintenance

Equinox dates (Vernal Equinox Day, Autumnal Equinox Day) are hardcoded based on official announcements from the National Astronomical Observatory of Japan. The dates are published in the "Reki-yoko" (暦要項) around February 1st each year for the following year.

References:

• 国立天文台 暦要項 - Official equinox dates
• 国立天文台 FAQ - About equinox calculation
• 祝日の計算方法 - Reference for historical data

Note: This library requires annual updates to add new equinox dates. Please check for updates or contribute if you notice missing data.

License

MIT

日本語

日本の祝日を判定するPHPライブラリ

国立天文台 暦要項の公式データで検証済み。

必要環境

• PHP 7.1以上

インストール

composer require sakai/jp-holiday

使い方

use Sakai\JpHoliday\JpHoliday;

$date = new DateTimeImmutable('2024-01-01');

JpHoliday::isHoliday($date);     // true
JpHoliday::getName($date);       // '元日'
JpHoliday::getNameEn($date);     // "New Year's Day"
JpHoliday::getDescription($date); // '年のはじめを祝う。'

祝日情報をまとめて取得

$info = JpHoliday::getHolidayInfo($date);
// ['name' => '元日', 'name_en' => "New Year's Day", 'description' => '...']

1年分の祝日を取得

$holidays = JpHoliday::getHolidaysInYear(2024);
// ['2024-01-01' => [...], '2024-01-08' => [...], ...]

期間内の祝日を取得

$holidays = JpHoliday::between(
    new DateTimeImmutable('2024-04-01'),
    new DateTimeImmutable('2024-05-31')
);

DateTime / DateTimeImmutable / Carbon 対応

DateTimeInterface を実装していればどの日付クラスでも使用可能。

API

グローバル設定

between() の日数制限でDoS対策:

JpHoliday::configure(['maxBetweenDays' => 365]);  // 最大365日に制限
JpHoliday::getConfig();                            // ['maxBetweenDays' => 365]
JpHoliday::resetConfig();                          // デフォルトにリセット（無制限）

対応する祝日

• 固定祝日（元日、建国記念の日など）
• ハッピーマンデー（成人の日、海の日など）
• 春分の日・秋分の日
• 振替休日
• 国民の休日
• 特例: 2019年皇位継承、2020/2021年オリンピック

制限事項

このライブラリは国民の祝日に関する法律が施行された1948年7月20日以降の日付のみ対応しています。それ以前の日付は空/nullを返します。

データソース・メンテナンス

春分の日・秋分の日は、国立天文台の公式発表に基づきハードコードしています。日付は毎年2月1日頃に翌年分が「暦要項」で発表されます。

参照:

• 国立天文台 暦要項 - 春分・秋分の公式日付
• 国立天文台 FAQ - 春分・秋分の計算について
• 祝日の計算方法 - 過去のデータの参照元

注意: このライブラリは毎年の更新が必要です。データの不足に気づいた場合は、更新の確認またはコントリビュートをお願いします。

ライセンス

MIT

Author / 作者

Kiyoshi Sakai

Related / 関連

• jp-holiday - JavaScript/TypeScript version / JS/TS版