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

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

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

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

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

導入方法
=================================
## 1. Composerを使う方法

ComposerはPHP用のパッケージ管理ツールです。
詳しくは、[先人の投稿](https://qiita.com/search?q=Composer)を参照してください。

````
composer require japanese-date/japanese-date
````

で入ります。
便利！

## 2. Pharを使う方法

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

[GitHub](https://github.com/suzunone/JapaneseDate/releases)から、Pharのパッケージ（japanese-date.phar）をダウンロードして、適当な箇所に配置してください。

どこか適当な場所で、

``` .php
require_once 'japanese-date.phar';
```

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

使い方
========================================

詳しくは、

 * [マニュアル](https://github.com/suzunone/JapaneseDate/blob/master/docs/Man.md)
 * [API仕様](https://github.com/suzunone/JapaneseDate/blob/master/docs/README.md)

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

と前置きしつつ……


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

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](https://carbon.nesbot.com/docs/)を継承していますので、[Carbon](https://carbon.nesbot.com/docs/)で使える機能は全て使えます。
（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()](http://php.net/manual/ja/datetime.format.php)は、日付のローカライズを行うことができません。
残念ながら、ローカライズを行うには、[strftime()](http://php.net/manual/ja/function.strftime.php)関数を使用する必要があります。

しかしながら、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()](http://php.net/manual/ja/function.strftime.php)の書式に加えて、`%#`から始まる文字列で、祝日などの表示を行うことができます。

### 新暦の日
| 文字 | 説明 |
|:-----------------:|:------------------|
| %#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](https://carbon.nesbot.com/docs/)を継承しているため、
[Carbon](https://carbon.nesbot.com/docs/)や、[PHP標準のDateTimeオブジェクト](http://php.net/manual/ja/book.datetime.php)で用意されている機能のすべてを使用することができます。

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


### [Carbon](https://carbon.nesbot.com/docs/)からJapaneseDateTime

[Carbon](https://carbon.nesbot.com/docs/)から、JapaneseDateにのり替えるには、[PHP標準のDateTimeオブジェクト](http://php.net/manual/ja/book.datetime.php)

``` .php
use Carbon\Carbon
```
こうなっているところを、

``` .php
use JapaneseDate\DateTime as Carbon;
```
こうすれば切り替えることができます。

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



### [PHP標準のDateTimeオブジェクト](http://php.net/manual/ja/book.datetime.php)からJapaneseDateTime
v3.x以降は[PHP標準のDateTimeオブジェクト](http://php.net/manual/ja/book.datetime.php)を継承しており、その機能はそのまま使用できます。（v4.xは[Carbon](https://carbon.nesbot.com/docs/)が[PHP標準のDateTimeオブジェクト](http://php.net/manual/ja/book.datetime.php)を継承しています）

名前空間が使用されているなら、以下のようにすれば[PHP標準のDateTimeオブジェクト](http://php.net/manual/ja/book.datetime.php)から簡単に切り替えることができます。


``` .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とか使うと思いますが、
それはそれで、手間だと思いますので良かったら使ってみてください。