PHPで日本の祝日、旧暦を扱えるライブラリを作った

....のは、2005年の7月のことでした。

なんか、天皇誕生日とか変わるらしいし、元号も変わるらしいので、バージョンアップを兼ねて、PHP7化とComposer,Pharに対応しました。

もともとは、PHPのMLに投稿させていただいて、
その後私の自作フレームワークの派生プロジェクトとして細々と更新を続けていたものとなります。

リポジトリも、Suzunoneの方に移しました。
https://github.com/suzunone/JapaneseDate

導入方法

1. Composerを使う方法

ComposerはPHP用のパッケージ管理ツールです。
詳しくは、先人の投稿を参照してください。

composer require japanese-date/japanese-date

で入ります。
便利！

2. Pharを使う方法

Pharはあるライブラリが依存するパッケージを1ファイルにまとめたアーカイブです。

GitHubから、Pharのパッケージ（japanese-date.phar）をダウンロードして、適当な箇所に配置してください。

どこか適当な場所で、

.php

require_once 'japanese-date.phar';

すれば、使用できるようになります。

使い方

詳しくは、

• マニュアル
• API仕様

とかにあるので、そちらも参考にしてください。

と前置きしつつ……

使い方はとっても簡単です。

Composerでインストールされていて、autoloadが効いているか、pharのrequireができている状態であれば、以下のようにすれば使用できます。

.php

use JapaneseDate\DateTime as JapaneseDateTime;

$dt = new JapaneseDateTime('2018-3-21 23:26:11'); // JapaneseDateTime::parse('2018-3-21 23:26:11');と同価です。
var_export($dt->holidayText); // '春分の日'
var_export($dt->eraNameText); // '平成'
var_export($dt->eraYear);     // 30

新しい、4.x系からCarbonを継承していますので、Carbonで使える機能は全て使えます。
（3.x以前では、Carbonは行っている処理を自前で行っていましたが、それらの関数はすべて廃止となりました）

.php

use JapaneseDate\DateTime as JapaneseDateTime;

$dt = JapaneseDateTime::parse('2018-3-21 23:26:11.123789');

//  年
var_export($dt->year); // 2018
// 月
var_export($dt->month); // 3
// 日
var_export($dt->day); // 21
// 時
var_export($dt->hour); // 23
// 分
var_export($dt->minute); // 26
// 秒
var_export($dt->second); // 11
// マイクロ秒
var_export($dt->micro); // 123789

日付のローカライズ

PHP標準のDatetime::format()は、日付のローカライズを行うことができません。
残念ながら、ローカライズを行うには、strftime()関数を使用する必要があります。

しかしながら、JapaneseDateTimeではそんな心配はありません。

v3以前も機能としては用意していましたが、Carbonと併用することで、より強力となりました。

.php

use JapaneseDate\DateTime as JapaneseDateTime;
// ロケールをjaにセットする
JapaneseDateTime::setLocale('ja');
echo JapaneseDateTime::getLocale();                          // ja
$dt = JapaneseDateTime::parse('2018-3-21 23:26:11.123789');
echo $dt->formatLocalized('%A %d %B %Y'); // 水曜日 21 3月 2018
echo $dt->formatLocalized('%#F%#E年%m月%d日(%A)');   // 平成30年03月21日(水曜日)
echo $dt->formatLocalized('%#F%#E年%-m月%-d日(%A)');   // 平成30年3月21日(水曜日)

strftime()の書式に加えて、%#から始まる文字列で、祝日などの表示を行うことができます。

新暦の日

文字	説明
%#J	%-dへのエイリアス
%#e	1～9なら先頭にスペースを付ける、1～31の日(%eのwin対応版)

新暦の月

文字	説明
%#g	1～9なら先頭にスペースを付ける、1～12の月
%#G	古い名前の月名(睦月、如月)
%#K	曜日
%#l	祝日番号
%#L	祝日
%#o	干支番号
%#O	干支

年号

文字	説明
%#f	年号ID
%#F	年号

六曜

文字	説明
%#k	六曜番号
%#6	六曜

旧暦年

文字	説明
%#E	旧暦年

旧暦日

文字	説明
%#d	旧暦の日(01,02...)
%#-d	旧暦の日(1,2,3....)
%#j	旧暦の1桁の場合は先頭にスペースをいれた日（ 1, 2, 3）

旧暦月

文字	説明
%#m	旧暦の月(01,02...)
%#-m	旧暦の月(1,2,3....)
%#n	旧暦の1桁の場合は先頭にスペースをいれた月（ 1, 2, 3）
%#b	旧暦の月(睦月,如月...)
%#h	%#bへのエイリアス
%#B	旧暦の月で閏月まで表示する 皐月(閏月)
%#u	閏月の場合 閏 と出力させる
%#U	閏月の場合 (閏) と出力させる

乗り換え

JapaneseDateTimeは、Carbonを継承しているため、
Carbonや、PHP標準のDateTimeオブジェクトで用意されている機能のすべてを使用することができます。

以下のようにすれば、エイリアスの切り替えだけで、簡単に乗り換えることができます。

CarbonからJapaneseDateTime

Carbonから、JapaneseDateにのり替えるには、PHP標準のDateTimeオブジェクト

.php

use Carbon\Carbon

こうなっているところを、

.php

use JapaneseDate\DateTime as Carbon;

こうすれば切り替えることができます。

一度上記のようにしてしまえば、IDEのリファクタリングツールなどで、エイリアスの名前を変えることもできます。

PHP標準のDateTimeオブジェクトからJapaneseDateTime

v3.x以降はPHP標準のDateTimeオブジェクトを継承しており、その機能はそのまま使用できます。（v4.xはCarbonがPHP標準のDateTimeオブジェクトを継承しています）

名前空間が使用されているなら、以下のようにすればPHP標準のDateTimeオブジェクトから簡単に切り替えることができます。

.php

namespace Hoge\Hoge;
use DateTime;

$dt = new DateTime();
$dt->format('Y-m-d');

こうなっているところを、

.php

namespace Hoge\Hoge;
use JapaneseDate\DateTime;

$dt = new DateTime();
$dt->format('Y-m-d');

こうすれば簡単に乗り換えることができます。

最後に

祝日が取れればいいだけなら、最近だとGoogleCalendarAPIとか使うと思いますが、
それはそれで、手間だと思いますので良かったら使ってみてください。