2024年5月24日

Carbonを使った日時操作例

日時を扱うのに便利なライブラリ、Carbonを使った日時操作例。
独断と偏見でよく使いそうなものをピックアップしているだけですが、それでも機能が多くて忘れそうなので辞書例用に。

使用環境

・ PHP 8.2.9
・ nesbot/carbon 3.3.1

事前準備

composerでCarbonをインストール。

composer require nesbot/carbon

インスタンス生成と文字列化例

<?php

require '../vendor/autoload.php';

use Carbon\Carbon;


// 現在日時
$dt = Carbon::now();
echo $dt->toDateTimeString(), PHP_EOL;    // 2024-05-24 01:48:17

// 今日の日付（00:00:00）
$dt = Carbon::today();
echo $dt->toDateString(), PHP_EOL;    // 2024-05-24

// 昨日の日付（00:00:00）
$dt = Carbon::yesterday();
echo $dt->toDateString(), PHP_EOL;    // 2024-05-23

// 明日の日付（00:00:00）
$dt = Carbon::tomorrow();
echo $dt->toDateString(), PHP_EOL;    // 2024-05-25

// 指定した日付（00:00:00）
$dt = Carbon::parse( '2024-05-23' );
echo $dt->toDateString(), PHP_EOL;    // 2024-05-23

// 指定した日時
$dt = Carbon::parse( '2024-05-23 11:12:13' );
echo $dt->format( 'Y-m-d H:i:s' ), PHP_EOL;    // 2024-05-23 11:12:13

PHP

分解して各値を取得

// 日時の分解取得
$dt = Carbon::parse( '2024-05-24 12:13:14' );
echo $dt->year, PHP_EOL;    // 2024（年）
echo $dt->month, PHP_EOL;    // 5（月）
echo $dt->day, PHP_EOL;    // 23（日）
echo $dt->hour, PHP_EOL;    // 12（時）
echo $dt->minute, PHP_EOL;    // 13（分）
echo $dt->second, PHP_EOL;    // 14（秒）
echo $dt->dayOfWeek, PHP_EOL;    // 5（曜日　5=金曜日）
echo $dt->quarter, PHP_EOL;    // 2（四半期　2=第2四半期）
echo $dt->dayOfYear, PHP_EOL;    // 31（年の内の何日目）
echo $dt->weekOfMonth, PHP_EOL;    // 5（月の内の何週目）
echo $dt->weekOfYear, PHP_EOL;    // 5（年の内の何週目）
echo $dt->offsetHours, PHP_EOL;    // 9（標準時からの時差）

// 日本語の曜日
Carbon::setLocale('ja');
$dt = Carbon::now();
echo $dt->isoFormat( 'ddd' ), PHP_EOL;    // 金
echo $dt->isoFormat( 'dddd' ), PHP_EOL;    // 金曜日

// 誕生日から年齢取得
echo Carbon::parse( '2004-01-01' )->age, PHP_EOL;    // 20

PHP

増減

メソッドを実行すると、インスタンスが保持している日時が変わるので注意。
元の日時を残しておきたい場合はcopy()を使ってインスタンスを2つにしておく。

// 複製取得（元の日時を残しておく場合に使用）
$dt = Carbon::parse( '2024-01-31' );
$dtCopy = $dt->copy();


// 1日後
$dt = Carbon::parse( '2024-01-31' )->addDay();
echo $dt->toDateString(), PHP_EOL;    // 2024-02-01

// 2日後
$dt = Carbon::parse( '2024-01-31' )->addDay(2);
echo $dt->toDateString(), PHP_EOL;    // 2024-02-02

// 1週間後
$dt = Carbon::parse( '2024-01-31' )->addWeek();
echo $dt->toDateString(), PHP_EOL;    // 2024-02-07

// 2週間後
$dt = Carbon::parse( '2024-01-31' )->addWeek(2);
echo $dt->toDateString(), PHP_EOL;    // 2024-02-14


// 1ヶ月後（月末日ズレに注意）
$dt = Carbon::parse( '2024-01-31' )->addMonth();
echo $dt->toDateString(), PHP_EOL;    // 2024-03-02

// 2ヶ月後（月末日ズレに注意）
$dt = Carbon::parse( '2023-12-31' )->addMonth(2);
echo $dt->toDateString(), PHP_EOL;    // 2024-03-02

// 1年後（月末日ズレに注意）
$dt = Carbon::parse( '2024-02-29' )->addYear();
echo $dt->toDateString(), PHP_EOL;    // 2025-03-01

// 2年後（月末日ズレに注意）
$dt = Carbon::parse( '2024-02-29' )->addYear(2);
echo $dt->toDateString(), PHP_EOL;    // 2026-03-01


// 1ヶ月後（月末日合わせ）
$dt = Carbon::parse( '2024-01-31' )->addMonthNoOverflow();
echo $dt->toDateString(), PHP_EOL;    // 2024-02-29

// 2ヶ月後（月末日合わせ）
$dt = Carbon::parse( '2023-12-31' )->addMonthNoOverflow(2);
echo $dt->toDateString(), PHP_EOL;    // 2024-02-29

// 1年後（月末日合わせ）
$dt = Carbon::parse( '2024-02-29' )->addYearNoOverflow();
echo $dt->toDateString(), PHP_EOL;    // 2025-02-28

// 2年後（月末日合わせ）
$dt = Carbon::parse( '2024-02-29' )->addYearNoOverflow(2);
echo $dt->toDateString(), PHP_EOL;    // 2026-02-28


// 1ヶ月前（月末日ズレに注意）
$dt = Carbon::parse( '2024-03-31' )->subMonth();
echo $dt->toDateString(), PHP_EOL;    // 2024-03-02

// 2ヶ月前（月末日ズレに注意）
$dt = Carbon::parse( '2024-04-30' )->subMonth(2);
echo $dt->toDateString(), PHP_EOL;    // 2024-03-01

// 1年前（月末日ズレに注意）
$dt = Carbon::parse( '2024-02-29' )->subYear();
echo $dt->toDateString(), PHP_EOL;    // 2023-03-01

// 2年前（月末日ズレに注意）
$dt = Carbon::parse( '2024-02-29' )->subYear(2);
echo $dt->toDateString(), PHP_EOL;    // 2022-03-01


// 1ヶ月前（月末日合わせ）
$dt = Carbon::parse( '2024-03-31' )->subMonthNoOverflow();
echo $dt->toDateString(), PHP_EOL;    // 2024-02-29

// 2ヶ月前（月末日合わせ）
$dt = Carbon::parse( '2024-04-30' )->subMonthNoOverflow(2);
echo $dt->toDateString(), PHP_EOL;    // 2024-02-29

// 1年前（月末日合わせ）
$dt = Carbon::parse( '2024-02-29' )->subYearNoOverflow();
echo $dt->toDateString(), PHP_EOL;    // 2023-02-28

// 2年前（月末日合わせ）
$dt = Carbon::parse( '2024-02-29' )->subYearNoOverflow(2);
echo $dt->toDateString(), PHP_EOL;    // 2022-02-28


// 月初
$dt = Carbon::now()->startOfMonth();
echo $dt->toDateString(), PHP_EOL;    // 2024-05-01

// 月末
$dt = Carbon::now()->endOfMonth();
echo $dt->toDateString(), PHP_EOL;    // 2024-05-31

PHP

差分

// 日差分　※時間が異なると小数が入るので注意
$dt1 = Carbon::parse( '2024-02-29' );
$dt2 = Carbon::parse( '2024-03-01' );
echo $dt1->diffInDays( $dt2 ), PHP_EOL;    // 1


// 月差分（整数）
// diffInMonths()だと月の日数ズレの影響で意図した挙動ではない懸念があるので計算
// 月内の同じ日に達したら1としてカウント（月末で日が存在しない場合は翌月1日でカウント）
$dt1 = Carbon::parse( '2024-02-29' );
$dt2 = Carbon::parse( '2025-03-01' );
echo floor( abs( ( $dt2->year - $dt1->year ) * 12 + ( $dt2->month - $dt1->month ) + ( $dt2->day - $dt1->day ) / 100 ) ), PHP_EOL;

PHP

比較

$dt1 = Carbon::parse( '2024-02-29' );
$dt2 = Carbon::parse( '2024-03-29' );
$dt3 = Carbon::parse( '2024-04-29' );
echo $dt1->eq( $dt2 ) ? 'true' : 'false', PHP_EOL;    // dt1 = dt2 かどうか
echo $dt1->gt( $dt2 ) ? 'true' : 'false', PHP_EOL;    // dt1 > dt2 かどうか
echo $dt1->gte( $dt2 ) ? 'true' : 'false', PHP_EOL;    // dt1 >= dt2 かどうか
echo $dt1->lt( $dt2 ) ? 'true' : 'false', PHP_EOL;    // dt1 < dt2 かどうか
echo $dt1->lte( $dt2 ) ? 'true' : 'false', PHP_EOL;    // dt1 <= dt2 かどうか
echo $dt1->between( $dt2, $dt3 ) ? 'true' : 'false', PHP_EOL;    // $dt2 <= dt1 <= dt3 かどうか

PHP

書式チェック

echo Carbon::hasFormat( '2024-01-01', 'Y-m-d' ) ? 'true' : 'false', PHP_EOL;

PHP