どの言語でも日付や時刻の処理をかっちり行うには苦心するものですね。

当記事では日時処理で苦労しない PHP の便利な日付系ライブラリ Carbon をご紹介いたします。

Carbon とは

Carbon
https://carbon.nesbot.com/

A simple PHP API extension for DateTime.

Carbon とは、シンプルな PHP DateTime クラスのラッパーライブラリです。

PHP フレームワークの Laravel にも組み込まれており、人気のあるライブラリと言えます。
すでに実績があり枯れ始めているライブラリです。

使用例

昨日・今日・明日、そして今

  • 昨日
1Carbon::yesterday();
  • 今日
1Carbon::today();
  • 明日
1Carbon::yesterday();

これらは、対象日付の 「0時 0分 0秒」 を指します。

  • 現在時刻
1Carbon::now();

たとえば、今から 24 時間後は次のようにします。

1$datetime = Carbon::now();
2$datetime->addHours(24);
3
4// こちらも同義
5$datetime = Carbon::now();
6$datetime->addDay();

日付などを指定してオブジェクトを生成する

次のように、多様な表現が可能です。

1new Carbon('2017-11-17');
2
3Carbon::create(2017, 1, 1, 0, 0, 0);
4
5Carbon::parse('2017-01-10 15:00:00');

タイムスタンプ

  • オブジェクトからタイムスタンプを得る
1$timestamp = Carbon::now()->timestamp;
  • タイムスタンプからインスタンスを生成する
1Carbon::createFromTimestamp($timestamp)

日付・時間・その他

  • フォーマット指定
1Carbon::now()->format('Y-m-d H:i:s');
  • Date と Time にそれぞれアクセスする
1$datetime = Carbon::now();
2$datetime->year;
3$datetime->month;
4$datetime->dat;
5$datetime->hour;
6$datetime->minute;
7$datetime->secound;
1$datetime = Carbon::now();
2
3// その月のなかで何週目か
4$datetime->weekOfMonth;
5
6// その年の中で何週目か
7$datetime->weekOfYear;
  • 月の日数
1Carbon::now()->daysInMonth;

「1月なら 31」が得られ、たとえば末日もかんたんに調べられます。

比較

  • 過去か未来か
1$datetime = new Carbon();
2$datetime->isPast());
3$datetime->isFuture());
  • 日付の比較
 1$datetime_1 = new Carbon('2018-01-01');
 2$datetime_2 = new Carbon('2020-01-01');
 3
 4$datetime_1->eq($datetime_2); // false
 5
 6// より大きい
 7$datetime_1->gt($datetime_2); // false
 8
 9// より小さい
10$datetime_1->lt($datetime_2); // true

テストでも活躍

setTestNow() というメソッドが提供されており、日付を据え置いてテストすることが可能です。

1Carbon::setTestNow(Carbon::parse('2017-01-10'));

プロジェクトが案外長く続いちゃって、急に日付周りでテストがコケちゃった、という心配が不要です。
これって便利ですよね。

導入方法

PHP バージョン

1.x is compatible with PHP 5.3+.
2.x version requires PHP 7.1.8+.
https://carbon.nesbot.com/ より引用

1 系は PHP 5.3 以上
2 系は PHP 7.1.8 以上です。

Composer で一発インストール

Carbon は Composer でかんたんにインストールが可能です。

1$ composer require nesbot/carbon

各 PHP ファイルでは次のように呼び出すことができます。

1<?php
2require 'vendor/autoload.php';
3
4use Carbon\Carbon;
5
6printf("Now: %s", Carbon::now());
なお、公式サイトには「昔ながらのライブラリを直接配置する」方法も掲載されています。

おわりに

Carbon は直感的に操作でき、齟齬の少ない良いライブラリです。

日付時刻処理はつまづきが多いのですが、Carbon ならツマラナイ不具合を減らすことができるはずです。

ちなみに Mac を Carbon 調にしたらかっこよすぎます。