[PHP5.3+] PHPで曜日文字列を含む日付・時刻の書式を扱うAPI

PHP で日本語の曜日を扱うためのソリューションとして, 既に

* [PHPで和暦・日本語曜日を使う](http://qiita.com/chiyoyo/items/da32649b0e04957856c1)
* [PHPで和暦・日本語曜日を使う DateTime拡張版](http://qiita.com/chiyoyo/items/3d12e5b1ef63e7f332ba)

などの事例がありますが, 後発ながら自分も API を作ってみました.
Java の [SimpleDateFormat](http://docs.oracle.com/javase/jp/8/docs/api/java/text/SimpleDateFormat.html) と同じような使い勝手で扱うことが出来ます.
この API は汎用クラスライブラリ [PEACH](https://github.com/trashtoy/PEACH2) のバージョン 2.0.1 (2015-04-28 リリース) で導入されました.
PHP 5.3.0 以上の環境で動作します.

※追記: PHP5.2 以下の環境を対象としたバージョン 1.0.2 (2015-08-09 リリース) でも実装済みです.

## インストール

1. PEACH の最新版ソースコード https://github.com/trashtoy/PEACH2/releases/download/2.0.1/peach-2.0.1.zip (2015-04-28 現在) をダウンロードします. 
2. ダウンロードした ZIP ファイルを展開し, 適当なディレクトリに配置します.
3. PHP ファイルで以下のように autoload.php を読み込むだけで OK です.

```php
<?php
require_once("/path/to/peach/autoload.php");

// Your code here...
```

## 文字列を時間オブジェクトに変換する

まずはサンプルコードをお見せします. `"2015/02/13 (金)"` のような形式の文字列を, 該当する時間オブジェクト [^1] に変換します.

[^1]: [Peach\DT\Date](http://trashtoy.github.io/PEACH2/class-Peach.DT.Date.html), [Peach\DT\Datetime](http://trashtoy.github.io/PEACH2/class-Peach.DT.Datetime.html), [Peach\DT\Timestamp](http://trashtoy.github.io/PEACH2/class-Peach.DT.Timestamp.html) など, 特定の日付 (および時刻) を表現するクラスのオブジェクトのことを「時間オブジェクト」と呼びます.

```php
<?php
use Peach\DT\Date;
use Peach\DT\SimpleFormat;

require_once("/path/to/peach/autoload.php");

$f = new SimpleFormat("Y/m/d (E)", ["日", "月", "火", "水", "木", "金", "土"]);
$d = Date::parse("2015/02/13 (金)", $f);
var_dump($d->get("year"));
var_dump($d->get("month"));
var_dump($d->get("date"));
```

このコードは以下の結果を出力します.

```
int(2015)
int(2)
int(13)
```

「文字列 ⇒ 時間オブジェクト」の変換手順は以下の通りです.

1. [Peach\DT\SimpleFormat](http://trashtoy.github.io/PEACH2/class-Peach.DT.SimpleFormat.html) インスタンスを生成します.  
コンストラクタの第 1 引数に書式パターン, 第 2 引数に曜日文字列を配列で指定します.
2. [Date](http://trashtoy.github.io/PEACH2/class-Peach.DT.Date.html), [Datetime](http://trashtoy.github.io/PEACH2/class-Peach.DT.Datetime.html), [Timestamp](http://trashtoy.github.io/PEACH2/class-Peach.DT.Timestamp.html) の parse メソッドを実行します.  
第 1 引数に変換対象の文字列, 第 2 引数に `SimpleFormat` インスタンスを指定します.

## 時間オブジェクトを文字列に変換する

逆に時間オブジェクトを文字列に変換することもできます. 以下にサンプルコードをお見せします.

```php
<?php
use Peach\DT\Datetime;
use Peach\DT\SimpleFormat;

require_once("/path/to/peach/autoload.php");

$f = new SimpleFormat("Y/m/d (E) H:i", ["日", "月", "火", "水", "木", "金", "土"]);
$d = Datetime::now();
var_dump($d->format($f));
```

このコードは以下のような結果を出力します.

```
string(22) "2015/05/19 (火) 19:02"
```

「時間オブジェクト ⇒ 文字列」の変換手順は以下の通りです.

1. [SimpleFormat](http://trashtoy.github.io/PEACH2/class-Peach.DT.SimpleFormat.html) インスタンスを生成します.
2. 変換対象の時間オブジェクトを用意します.
3. 引数に `SimpleFormat` インスタンスを指定して時間オブジェクトの [format](http://trashtoy.github.io/PEACH2/class-Peach.DT.Time.html#_format) メソッドを実行します. (そのオブジェクトの文字列表現が返り値となります)

## PEACH を採用する理由

巷には, 冒頭に挙げた実装も含めて曜日文字列を扱うための様々な方法がありますが, PEACH を採用するとこんな利点があるよ！ というポイントをまとめてみました.

### 1. 日本語以外への対応

「日」「月」「火」……などの文字列がハードコーディングされているのではなく, 外部から配列で与える形になっているので, 日本語以外にも応用可能です.
例えば以下のコードはドイツ語の曜日付き書式の出力を行います.

```php
<?php
use Peach\DT\Timestamp;
use Peach\DT\SimpleFormat;

require_once("/path/to/peach/autoload.php");

$f = new SimpleFormat("E, \\d\\e\\n d.m.Y H:i:s", ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"]);
$d = Timestamp::now();
var_dump($d->format($f));
```

このコードは以下のような結果を出力します.

```
string(33) "Dienstag, den 19.05.2015 18:59:10"
```

### 2. がっつりオブジェクト指向

`SimpleFormat` クラスはその名の通り [Peach\DT\Format](http://trashtoy.github.io/PEACH2/class-Peach.DT.Format.html) インタフェースを継承しているのですが,
PEACH にはこれ以外にも様々な種類の Format クラスが用意されています.
プログラム内で動的に Format オブジェクトを切り替えたり, 複数の Format オブジェクトを連携させたりすることが出来ます.

時間オブジェクトと Format インタフェースの関係はこんな感じ.
![Peach_DT.png](https://qiita-image-store.s3.amazonaws.com/0/24430/016c23b6-a042-ae91-e492-0ffe35cad790.png)


以下, HTTP-date (RFC 1123) 形式の文字列 `"Tue, 19 May 2015 09:30:25 GMT"` を日本語の書式 `"2015/05/19 (火) 18:30:25"` に変換するサンプルです.

```php
<?php
// php.ini で date.timezone = "Asia/Tokyo" が設定されている前提です
use Peach\DT\Timestamp;
use Peach\DT\HttpDateFormat;
use Peach\DT\SimpleFormat;

require_once("/path/to/peach/autoload.php");

$f1 = new HttpDateFormat();
$f2 = new SimpleFormat("Y/m/d (E) H:i:s", array("日", "月", "火", "水", "木", "金", "土"));
$ts = Timestamp::parse("Tue, 19 May 2015 09:30:25 GMT", $f1);
var_dump($ts->format($f2));
```

このコードは以下の結果を出力します.

```
string(25) "2015/05/19 (火) 18:30:25"
```

このコードで何をやっているかというと

1. [HttpDateFormat](http://trashtoy.github.io/PEACH2/class-Peach.DT.HttpDateFormat.html) クラスを使って「文字列 ⇒ 時間オブジェクト」の変換を行います.
2. SimpleFormat クラスを使って「時間オブジェクト ⇒ 文字列」の変換を行います.
3. 変換した文字列を var_dump で標準出力に表示します.

もちろん逆の操作 (日本語の書式から HTTP-date) もできます.

```php
<?php
// php.ini で date.timezone = "Asia/Tokyo" が設定されている前提です
use Peach\DT\Timestamp;
use Peach\DT\HttpDateFormat;
use Peach\DT\SimpleFormat;

require_once("/path/to/peach/autoload.php");

$f1 = new HttpDateFormat();
$f2 = new SimpleFormat("Y/m/d (E) H:i:s", array("日", "月", "火", "水", "木", "金", "土"));
$ts = Timestamp::parse("2015/05/19 (火) 18:45:01", $f2);
var_dump($ts->format($f1));
```

このコードは以下の結果を出力します.

```
string(29) "Tue, 19 May 2015 09:45:01 GMT"
```

## 詳細について

* 日付・時刻の加算・減算やフィールドの参照方法など, 基本的な使い方は [[PHP5.3+] PHPで日付・時間操作をカンタンに出来るAPIの紹介](http://qiita.com/trashtoy/items/dcee2c039be3f5542624) をご覧ください.
* API に関する詳細なドキュメントは http://trashtoy.github.io/PEACH2/ にあります.