Carbon インスタンスの作り方

2023年8月3日

PHP で日付や時間を扱うのに便利なライブラリである Carbon。インスタンスの作り方がいくつかありますが、忘れがちなのでまとめておくことにします。

Carbon::create($year = 0, $month = 1, $day = 1, $hour = 0, $minute = 0, $second = 0, $tz = null)

一番オーソドックスなインスタンスの作り方ではないでしょうか。パラメータにデフォルト値が指定されているので、年月日だけでもインスタンスが作れるのが便利です。それぞれのパラメータを個別に指定しなければならないので、input type="date" で飛んできたデータや DB のデータからインスタンスを作る場合、下ごしらえが必要なのがちょっと難点。

Carbon::create は $month に 13 を指定すると翌年の1月に読み替えてくれるなど、柔軟に解釈してくれますが、それが嫌な場合は Carbon::createSafe を使うとよいでしょう。無効なパラメータを指定すると Carbon\Exceptions\InvalidDateException を返します。

Carbon::parse($time = null, $tz = null)

一番楽なのが Carbon::parse ですね。日付や時刻として解釈できるものであれば何でも受け入れてくれます。$string が null や空文字の場合は、現在時刻に基づいてインスタンスを作成しますが、それだと不便なことも。飛んでくる値がある程度予測できている場合は、事前にバリデートしたほうが予想外の結果を防ぐことができます。

$string が「2023-08-03」のように、日付しか指定されていないときは、時刻部分は現在時刻になる点は注意が必要です。

Carbon::createFromFormat($format, $time, $tz = null)

あらかじめ飛んでくる値のフォーマットを指定しておくことができます。フォーマットと異なる値が飛んできたときは、Carbon\Exceptions\InvalidFormatException を返します。

こちらも $format に時刻を表すものが含まれていないときは、時刻部分は現在時刻になります。

Carbon::createFromTimestamp($timestamp, $tz = null)

UNIX タイムスタンプからインスタンスを作るときに使います。タイムスタンプが飛んでくることは少ないので、使うとしたら他のライブラリとの連携時でしょうか。

例えば、Laravel Excel や PhpSpreadsheet で日付のシリアル値が入力されているセルをインポートする際に

$dt = Carbon::createFromTimestamp(Date::excelToTimestamp($row[0]));

とする場合などが考えられます。

Carbon::instance($date)

PHP の DateTime インスタンスから Carbon インスタンスを作るときに使います。こちらも他のライブラリとの連携時に使うことが多いでしょう。

上の例と同じになってしまいますが、Laravel Excel や PhpSpreadsheet で日付のシリアル値が入力されているセルをインポートする際に

$dt = Carbon::instance(Date::excelToDateTimeObject($row[0]));

とする場合などに使えます。ちなみに、日付のシリアル値をインポートする場合は、excelToTimestamp よりも excelToDateTimeObject のほうが効率がよさそうです（excelToTimestamp は内部的に excelToDateTimeObject を呼び出しているため）。