Carbonで日付操作(比較, 差分, format)

Carbonクラスは、phpに標準で存在するDateTimeクラスを拡張して、日付操作をより楽にしてくれます。ここでは、Carbonの基本的な使い方を解説します。

Carbonインスタンスの作り方

use Carbon\Carbon;
 
 
$carbon = new Carbon();
var_dump($carbon);
// object(Carbon\Carbon)#327 (3) { ["date"]=> string(26) "2017-01-29 11:25:17.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = new Carbon('2017-01-01 12:30:30');
var_dump($carbon);
// object(Carbon\Carbon)#328 (3) { ["date"]=> string(26) "2017-01-01 12:30:30.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = Carbon::parse('2017-01-01 12:30:30');
var_dump($carbon);
// object(Carbon\Carbon)#327 (3) { ["date"]=> string(26) "2017-01-01 12:30:30.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon= Carbon::now()->next(Carbon::MONDAY);
var_dump($carbon);
// object(Carbon\Carbon)#327 (3) { ["date"]=> string(26) "2017-01-30 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = Carbon::today();
var_dump($carbon);
// object(Carbon\Carbon)#328 (3) { ["date"]=> string(26) "2017-01-29 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = Carbon::tomorrow();
var_dump($carbon);
// object(Carbon\Carbon)#327 (3) { ["date"]=> string(26) "2017-01-30 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = Carbon::yesterday();
var_dump($carbon);
// object(Carbon\Carbon)#328 (3) { ["date"]=> string(26) "2017-01-28 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = new \DateTime();
$carbon = Carbon::instance($carbon);
var_dump($carbon);
// object(Carbon\Carbon)#328 (3) { ["date"]=> string(26) "2017-01-29 11:28:04.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = Carbon::create(2017, 1, 1, 12, 30, 15);
var_dump($carbon);
// object(Carbon\Carbon)#329 (3) { ["date"]=> string(26) "2017-01-01 12:30:15.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(10) "Asia/Tokyo" }
 
 
$carbon = new Carbon('2017-01-01 12:30:30');
echo($carbon);
// 2017-01-01 12:30:30

日時の加算減算
( add/sub )

$carbon = new Carbon('2017-01-01 12:30:30');
echo $carbon->addSeconds(2) . '<br>';  // 2017-01-01 12:30:32
echo $carbon->addMinutes(2) . '<br>';  // 2017-01-01 12:32:32
echo $carbon->addHours(2) . '<br>';    // 2017-01-01 14:32:32
 
 
$carbon = new Carbon('2017-01-01 12:30:30');
echo $carbon->addDays(2) . '<br>';     // 2017-01-03 12:30:30
 
 
$carbon = new Carbon('2017-01-01 12:30:30');
echo $carbon->addMonths(2) . '<br>';   // 2017-03-01 12:30:30
 
 
$carbon = new Carbon('2017-01-01 12:30:30');
echo $carbon->addYears(2) . '<br>';    // 2019-01-01 12:30:30
 
 
// 2営業日後(営業日=平日 祝日も営業日となる) 1/7(土) 1/8(日) 1/9(祝日:成人の日)
$carbon = new Carbon('2017-01-06 12:30:30');
echo $carbon->addWeekdays(2) . '<br>'; // 2017-01-10 00:00:00

同様に、減算はsubXxxで行えます。

addSecondsでなく、addSecondでも構いません。次のようになっているだけです。

public function addSeconds($value)
{
    return $this->modify((int) $value.' second');
}
 
public function addSecond($value = 1)
{
    return $this->addSeconds($value);
}

インスタンス自体の日時を変更したくない場合、copyメソッドを利用します。

$carbon = new Carbon('2017-01-01 12:30:30');
echo $carbon->copy()->addDays(2) . '<br>';     // 2017-01-03 12:30:30
echo $carbon;                                  // 2017-01-01 12:30:30

月の加算減算は注意

17/01/31の1ヶ月後は17/03/03となりますが、
17/03/03の1ヶ月前は17/02/03となるので注意してください。

$carbon = new Carbon('2017-01-31');
echo $carbon->addMonth() . '<br>';   // 2017-03-03 00:00:00
 
$carbon = new Carbon('2017-03-03');
echo $carbon->subMonth() . '<br>';   // 2017-02-03 00:00:00

特定の日であるか判定
( is )

$carbon = Carbon::now();
echo $carbon; // 2017-01-29 12:19:12
              // 日曜日です。
 
// 未来?
var_dump($carbon->isFuture());  // bool(false)
 
// 過去?
var_dump($carbon->isPast());  // bool(false)
 
// 今日?
var_dump($carbon->isToday());  // bool(true)
 
// 明日?
var_dump($carbon->isTomorrow());  // bool(false)
 
// 昨日?
var_dump($carbon->isYesterday());  // bool(false)
 
// 平日?
var_dump($carbon->isWeekday());  // bool(false)
 
// 週末(土日)?
var_dump($carbon->isWeekend());  // bool(true)
 
// 月曜日?
var_dump($carbon->isMonday());  // bool(false)
 
// 誕生日?
$birthday = Carbon::now();
var_dump($carbon->isBirthday($birthday));   // bool(true)
 
$birthday = Carbon::now()->tomorrow();
var_dump($carbon->isBirthday($birthday));   // bool(false)
 
// うるう年?
var_dump($carbon->isLeapYear()); // bool(false)
 
// 同じ日?
var_dump($carbon->isSameDay(Carbon::now()->tomorrow())); // bool(false)

gt ltで比較されるので、今日未来でも過去でもないようです。

他の日付との比較
( eq/ne/lt/gt/between )

$carbon1 = new Carbon('2017-01-01');
$carbon2 = new Carbon('2017-01-02');
 
// 同じ?(equal)
var_dump($carbon1->eq($carbon2)); // bool(false)
 
// 異なる?(not equal)
var_dump($carbon1->ne($carbon2)); // bool(true)
 
// 小さい?(less than)
var_dump($carbon1->lt($carbon2)); // bool(true)
 
// 大きい?(greater than)
var_dump($carbon1->gt($carbon2)); // bool(false)
 
// 以下?(less than equal)
var_dump($carbon1->lte($carbon2)); // bool(true)
 
// 以上?(greater than equal)
var_dump($carbon1->gte($carbon2)); // bool(false)
 
// 間にある?
var_dump($carbon1->between(Carbon::parse('2016-12-01'), Carbon::parse('2017-02-01'))); // bool(true)

他の日時との差分
( diff )

$carbon1 = new Carbon('2016-01-01');
$carbon2 = new Carbon('2017-01-01');
 
echo $carbon1->diffInSeconds($carbon2) . '<br>'; // 31622400
echo $carbon1->diffInMinutes($carbon2) . '<br>'; // 527040
echo $carbon1->diffInHours($carbon2) . '<br>';   // 8784
echo $carbon1->diffInDays($carbon2) . '<br>';    // 366
echo $carbon1->diffInWeeks($carbon2) . '<br>';   // 52
echo $carbon1->diffInYears($carbon2) . '<br>';   // 1

日時などのデータを取得

$carbon = new Carbon('2017-01-15 12:30:15');
 
echo $carbon->year . '<br>';    // 2017
echo $carbon->month . '<br>';   // 1
echo $carbon->day . '<br>';     // 15
echo $carbon->hour . '<br>';    // 12
echo $carbon->minute . '<br>';  // 30
echo $carbon->second . '<br>';  // 15
 
// 月の日数
echo $carbon->daysInMonth . '<br>'; // 31
 
// 日曜日が0で、金曜日が6です。
echo $carbon->format('Y年m月d日(w)') . '<br>'; // 2017年01月15日(0)
 
// 曜日が数値表示だと嫌なら。
setlocale(LC_ALL, 'ja_JP.UTF-8');
echo $carbon->formatLocalized('%Y年%m月%d日(%a)') . '<br>'; //2017年01月15日(日)
 
// 年齢
$birthday = new Carbon('2000-01-01');
echo $birthday->age . '<br>'; // 17

現在の日時を変更
( setTestNow )

テストのときに役立ちます。

$carbon = Carbon::now();
echo $carbon; // 2017-01-29 13:31:37
 
Carbon::setTestNow(Carbon::parse('2017-01-15 12:30:15'));
$carbon = Carbon::now();
echo $carbon; // 2017-01-15 12:30:15

参考

Laravelでの利用

Carbonは、Laravelなどのフレームワークにも採用されています。
Laravelでは、モデルの$datesプロパティをオーバーライドすることで指定したカラムが自動的にCarbonインスタンスに変換されます。

わくわくBank.
フリーランスのエンジニアとして活動してます。ここでは、ソフトウェア開発で必要とされる技術、用語、概念を整理しています。