Carbon インスタンスの作り方
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
を呼び出しているため)。
ディスカッション
コメント一覧
まだ、コメントがありません