PHPで日付時刻の処理を書くなら Carbon がおすすめ

どうも、筋トレにハマっているたきゃはしです。
本日はPHPにおける日付時刻のライブラリについて書いていきたいと思います。

突然ですが、日付や時刻が絡む処理って意外とやっかいだと思いませんか？おそらく皆さんもいくつか思い当たるフシがあるかと思いますが、そんなやっかい事も Carbon（カーボン）を使えば解消できるかもしれません！

Carbon - A simple PHP API extension for DateTime.

Carbon とはPHPのDateTimeクラスを継承して拡張された日時操作ライブラリです。

「Carbonってどうなの？流行ってるの？」という方向けに予め補足致します。
Carbonはすでに人気のフレームワークに統合されていたり、GitHubで☆3000に迫る評価もありますのでDateTimeライブラリとしてデファクトになるんじゃないかと予想できます。

ではインストールからはじめます。


composer require nesbot/carbon

Composerでインストールすれば


<?php
require 'vendor/autoload.php';
use Carbon\Carbon;
echo Carbon::now(); // 2015-05-13 10:14:28（現在の日時）
Carbon::setTestNow(Carbon::create(2015, 5, 9, 15, 0, 0));
echo Carbon::now(); // 2015-05-09 15:00:00
echo Carbon::today()->toDateString(); // 2015-05-09
Carbon::setTestNow();
$carbon = Carbon::create(1980, 4, 15, 10, 20, 30);
echo $carbon->year;        // 1980
echo $carbon->age;         // 35
echo Carbon::today()->subYears(13)->addMonths(2)->subDays(10)->toDateString(); // 2002-07-02

Carbonはすぐに使えます。

基本的にCarbonのメソッドはインスタンスを返します。なのでメソッドチェーンによる直感的な表現が可能です。またインスタンスを文字列型へとキャストするとデフォルトフォーマットに変換してくれます。

もちろんフォーマットを指定することも可能です。


<?php
require 'vendor/autoload.php';
use Carbon\Carbon;
$carbon = Carbon::create(1980, 4, 15, 10, 20, 30);
echo $carbon; // 1980-04-15 10:20:30
echo $carbon->format('Y年m月d日'); // 1980年04月15日
$carbon->setToStringFormat('Y/m/d H:i:s'); // デフォルトフォーマットを変更
echo $carbon; // 1980/04/15 10:20:30
$carbon->resetToStringFormat();
echo $carbon; // 1980-04-15 10:20:30

フォーマットの書式は date() と同じです。
- http://php.net/manual/ja/function.date.php

またCarbonではインスタンスを生成するための方法がいくつか準備されています。


<?php
use Carbon\Carbon;
class CarbonTest extends PHPUnit_Framework_TestCase
{
    /**
     * @test
     */
    public function instance()
    {
        $dt = new \DateTime();
        $carbon = Carbon::instance($dt);
        $carbon2 = Carbon::instance($dt);
        $this->assertTrue($carbon2 instanceof Carbon);
        $this->assertTrue($carbon !== $carbon2);
    }
    /**
     * @test
     */
    public function copy()
    {
        $carbon = new Carbon();
        $copiedCarbon = $carbon->copy();
        $this->assertTrue($copiedCarbon instanceof Carbon);
        $this->assertTrue($copiedCarbon !== $carbon);
    }
    /**
     * @test
     */
    public function parse()
    {
        $carbon = Carbon::parse('2002-07-02');
        $this->assertSame(2002, $carbon->year);
        $this->assertSame(7, $carbon->month);
        $this->assertSame(2, $carbon->day);
    }
    /**
     * @test
     */
    public function create()
    {
        $carbon = Carbon::create(2002, 7, 2);
        $this->assertSame(2002, $carbon->year);
        $this->assertSame(7, $carbon->month);
        $this->assertSame(2, $carbon->day);
    }
}

基本的にcreate()もしくはparse()を使って生成することになりそうです。
parse()なんかはDBのDATE型やDATETIME型の値をそのまま引数に使えるので便利そうです。

次は Carbon::setTestNow() についてです。
setTestNow() はCarbonが基準とする現在の日時をモックで設定できる機能です。つまりロジック内でCarbonを適切に扱うことで時間に関するテストをユニットテストでも書けるようになります。

ユニットテストの例を用意しました。
賞味期限(BestBefore)が過ぎていないか確認するだけのシンプルな機能です。


<?php
namespace Services;
use DateTime;
class BestBefore
{
    protected $dt;
    public function __construct(DateTime $dt)
    {
        $this->dt = $dt;
    }
    public function isSafe(DateTime $dt)
    {
        return $this->dt < $dt;
    }
}

次に BestBefore::isSafe() のテストを書いてみます。


<?php
use Carbon\Carbon;
use Services\BestBefore;
class BestBeforeTest extends PHPUnit_Framework_TestCase
{
    /**
     * @test
     */
    public function 賞味期限が切れていないかどうか()
    {
        Carbon::setTestNow(Carbon::createFromDate(2015, 5, 1));
        $expire = new BestBefore(new Carbon());
        $this->assertFalse($expire->isSafe(Carbon::createFromDate(2015, 4, 30)));
        $this->assertFalse($expire->isSafe(Carbon::createFromDate(2015, 5, 1)));
        $this->assertTrue($expire->isSafe(Carbon::createFromDate(2015, 5, 2)));
        Carbon::setTestNow(Carbon::createFromDate(2015, 4, 30));
        $expire2 = new BestBefore(new Carbon());
        $this->assertFalse($expire2->isSafe(Carbon::createFromDate(2015, 4, 30)));
        $this->assertTrue($expire2->isSafe(Carbon::createFromDate(2015, 5, 1)));
        $this->assertTrue($expire2->isSafe(Carbon::createFromDate(2015, 5, 2)));
    }
}

ご覧の通り Carbon::setTestNow() を設定することで冪等なテストを書くことができました。もしBestBeforeクラスのロジックでPHP標準の date() や time() を使っていたならこのようなテストは書けないですよね。個人的にすごく魅力的な仕組みだと感じました。

また例のBestBeforeクラスではタイプヒンティングにDateTimeを指定していますので、Carbonを拡張したMyCarbonを使いたいといった場合でもBestBeforeクラスに手を加えることなく利用することができます。

Carbonは単に「DateTime扱いやすいぞーやったー」というだけでなく、日時処理まわりのメンテナンス性およびコード品質の向上に一役買うライブラリであるということをお伝えできたかと思います。

ということで概ね私が伝えたかったのはここまでです。
ここからは覚えておくと便利なことや調べた機能をメモとして記載します。

アクセサ


<?php
require 'vendor/autoload.php';
use Carbon\Carbon;
$dt = Carbon::parse('2012-9-5 23:26:11.123789');
var_dump($dt->year);                                         // int(2012)
var_dump($dt->month);                                        // int(9)
var_dump($dt->day);                                          // int(5)
var_dump($dt->hour);                                         // int(23)
var_dump($dt->minute);                                       // int(26)
var_dump($dt->second);                                       // int(11)
var_dump($dt->micro);                                        // int(123789)
var_dump($dt->dayOfWeek);                                    // int(3)          曜日。数値。0 (日曜)から 6 (土曜)
var_dump($dt->dayOfYear);                                    // int(248)        年間の通算日。数字。(ゼロから開始)
var_dump($dt->weekOfMonth);                                  // int(1)          月間の週番号。
var_dump($dt->weekOfYear);                                   // int(36)         ISO-8601に基づく月曜日に始まる年単位の週番号。
var_dump($dt->daysInMonth);                                  // int(30)         指定した月の日数。28 から 31。
var_dump($dt->timestamp);                                    // int(1346901971)
var_dump(Carbon::createFromDate(1975, 5, 21)->age);          // int(39)
var_dump($dt->quarter);                                      // int(3)          四半期。

小ネタですが、上記プロパティはメンバとして定義されておらず __get() で動的に処理されています。age等は計算が必要だからですね。またIDEでプロパティが補完されたのですがどうやらDocで宣言すれば出来るようです。なるほど〜

- https://github.com/briannesbitt/Carbon/blob/master/src/Carbon/Carbon.php#L42

比較


<?php
require 'vendor/autoload.php';
use Carbon\Carbon;
$first = Carbon::create(2012, 9, 5, 23, 26, 11);
$second = Carbon::create(2012, 9, 5, 7, 26, 11, 'America/Vancouver');
echo $first->toDateTimeString();                   // 2012-09-05 23:26:11
echo $first->tzName;                               // Asia/Tokyo
echo $second->toDateTimeString();                  // 2012-09-05 07:26:11
echo $second->tzName;                              // America/Vancouver
var_dump($first->eq($second));                     // bool(true)
var_dump($first->ne($second));                     // bool(false)
var_dump($first->gt($second));                     // bool(false)
var_dump($first->gte($second));                    // bool(true)
var_dump($first->lt($second));                     // bool(false)
var_dump($first->lte($second));                    // bool(true)
$first->setDateTime(2012, 1, 1, 0, 0, 0);
$second->setDateTime(2012, 1, 1, 0, 0, 0);         // Remember tz is 'America/Vancouver'
var_dump($first->eq($second));                     // bool(false)
var_dump($first->ne($second));                     // bool(true)
var_dump($first->gt($second));                     // bool(false)
var_dump($first->gte($second));                    // bool(false)
var_dump($first->lt($second));                     // bool(true)
var_dump($first->lte($second));                    // bool(true)

範囲比較


<?php
require 'vendor/autoload.php';
use Carbon\Carbon;
$first = Carbon::create(2012, 9, 5, 1);
$second = Carbon::create(2012, 9, 5, 5);
var_dump(Carbon::create(2012, 9, 5, 3)->between($first, $second));          // bool(true)
var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second));          // bool(true)
var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second, false));   // bool(false)