背景

テストコードを書く時にさっと日付を戻したり進めたりする時にすごい便利だったので使い方をメモします。

Carbon型とは

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

導入方法

Composerでインストールすればすぐに使えます。

composer require nesbot/carbon

使い方

<?php
  use Carbon\Carbon;
  echo Carbon::now(); // 現在の日時を取得(2022-01-01 00:00:00)
  echo Carbon::today()->toDateString(); // 日付のみ取得(2022-01-01)
  $carbon = Carbon::create(2022, 1, 1, 10, 20, 30); // 引数で時刻を設定
  echo $carbon->year; // 2022
  echo $carbon->format('Y年m月d日'); // フォーマットを指定できます(2022年01月01日)

CarbonImutable型

Carbon型の他にCarbonImutable型というのがあります。
CarbonImutable型は一度オブジェクトが作成された後にメソッドを呼んでも内部状態が変わらない性質があります。

具体的な違いを以下の例で説明します。

// 現在時刻を操作
\Carbon\Carbon::setTestNow('2020-01-01T00:00:00');
// 現在時刻を取得
$now = \Carbon\Carbon::now();
// 翌日の時刻を取得
$tomorrow = $now->addDay();

上記のように実装した場合、それぞれの出力結果は以下のようになります。

now: '2020-01-02T00:00:00'
tomorrow: '2020-01-02T00:00:00'

$nowの値も変わってしまいます。
これは$nowと$tomorrowが同一のオブジェクトであることが原因です。
$nowの中身を変えないようにするにはcopy()を使用します。

// 現在時刻を取得
$now = \Carbon\Carbon::now();
// 翌日の時刻を取得
$tomorrow = $now->copy()->addDay();

// 出力結果
now: '2020-01-01T00:00:00'
tomorrow: '2020-01-02T00:00:00'

CarbonImutable型を使えばcopy()を使わなくても大丈夫です。

\Carbon\CarbonImmutable::setTestNow('2022-01-01T00:00:00');
$now = \Carbon\CarbonImmutable::now();
$tomorrow = $nowImm->addDay();

// 出力結果
now: '2020-01-01T00:00:00'
tomorrow: '2020-01-02T00:00:00'

状況に応じて使い分ける必要はありますが、時刻操作をする際はかなり便利なので覚えておくと良さそうです。