さぁ、最近はLaravelの「全実例記事」をたくさん公開しているんですけど、ここいらでLaravelではないけれども切っても切れない関係にあるパッケージ「Carbon」についてもきちんと学び直しをすることにしました。

Carbonとは、PHPのDateTimeクラスを拡張したパッケージで、日付や時間をより直感的に、よりシンプルに操作することができるようになっています。また、この操作性の良さからかLaravelでも標準的に利用されているため（例えば、DBのcreated_atやupdated_atはCarbonインスタンスとして取得されます）、このパッケージをうまく使うことは生産性を高めるために有効と言っていいでしょう。

では、ひとつずつ見ていきましょう！

※実行環境はLaravel 5.6、Carbonのバージョンは1.25.0です。

【追記： 2021.01.11】
日本語の曜日を取得する方法を追記しました。（ver 2.54.0）

インスタンス

基本的なインスタンスの取得方法

$dt = new Carbon();

通常のインスタンスを作成する方法と同じですが、引数に文字列を指定することで様々なインスタンスを取得することができます。

例えば以下のような内容です。

new Carbon('today'); // 今日
new Carbon('tomorrow'); // 明日
new Carbon('yesterday'); // 昨日
new Carbon('now'); // 今
new Carbon('last month'); // 前の月
new Carbon('next year'); // 次の年

new Carbon('+1 day'); // １日後
new Carbon('-2 weeks'); // ２週間前
new Carbon('+3 minutes'); // ３分後
new Carbon('-4 seconds'); // ４秒前
new Carbon('+5 years'); // ５年後
new Carbon('-6 months'); // ６ヵ月前

new Carbon('first day of next month'); // 来月の最初の日

new Carbon('2018-01-01'); // 2018年1月1日
new Carbon('2018-01-01 01:02:03'); // 2018年1月1日 01時02分03秒

他にもより複雑な指定ができます。詳しくはPHPのstrtotimeをご覧ください。

なお、第２引数にはタイムゾーンを指定することができます。

new Carbon('today', 'Asia/Tokyo');

parse()で日付をパースする

$dt = Carbon::parse('now');

パースできる文字列の例は、基本的なインスタンスの取得方法と同じです。

now()で今の日時を取得する

$now = Carbon::now();
$now = Carbon::now('Asia/Tokyo'); // タイムゾーン付き

today()で今日が始まる日時を取得する

$today = Carbon::today();
$today = Carbon::today('Asia/Tokyo'); // タイムゾーン付き

なお、todayで取得できるのは「2018-08-03 00:00:00」といった日付、つまり「本日の日付」＋「00時00分00秒」です。

yesterday()で昨日が始まる日時を取得する

$yesterday = Carbon::yesterday();
$yesterday = Carbon::yesterday('Asia/Tokyo'); // タイムゾーン付き

today()と同様で、取得できるのは「2018-08-02 00:00:00」といった、「昨日の日付」＋「00時00分00秒」です。

tomorrow()で明日が始まる日時を取得する

$tomorrow = Carbon::tomorrow();
$tomorrow = Carbon::tomorrow('Asia/Tokyo'); // タイムゾーン付き

today()と同様で、取得できるのは「2018-08-04 00:00:00」といった、「明日の日付」＋「00時00分00秒」です。

createFromDate()で日付からインスタンスを作成する

$year = 2018;
$month = 8;
$day = 3;
$dt = Carbon::createFromDate($year, $month, $day); // 2018-08-04 09:11:23

注意が必要なのは、時間が「00時00分00秒」ではなく、現在時刻になるという点です。もし時間も指定したい場合はcreate()、もしくはcreateMidnightDate()使いましょう。

なお、第４引数ではタイムゾーンを指定できます。

Carbon::createFromDate($year, $month, $day, 'Asia/Tokyo');

createMidnightDate()で日付からインスタンスを作成する

$year = 2018;
$month = 8;
$day = 3;
Carbon::createMidnightDate($year, $month, $day); // 2018-08-03 00:00:00

createFromDate()と似ていますが、こちらは時間が「00時00分00秒」で固定されます。もし現在時刻を使いたい場合はcreateFromDate()を使いましょう。

createFromTime()で時間からインスタンスを作成する

$hour = 1;
$minute = 2;
$second = 3;
echo Carbon::createFromTime($hour, $minute, $second); // 2018-08-03 01:02:03

日付は実行したその日になります。なお、第４引数ではタイムゾーンを指定できます。

Carbon::createFromTime($hour, $minute, $second, 'Asia/Tokyo');

createFromTimeString()で時間（文字列）からインスタンスを作成する

Carbon::createFromTimeString('17:00:00'); // 2018-08-03 17:00:00

日付は実行したその日になります。なお、第２引数ではタイムゾーンを指定できます。

Carbon::createFromTimeString('17:00:00', 'Asia/Tokyo');

create()で日時からインスタンスを作成する

$year = 2018;
$month = 8;
$day = 4;
$hour = 1;
$minute = 2;
$second = 3;
echo Carbon::create(
    $year, 
    $month, 
    $day, 
    $hour, 
    $minute, 
    $second
);

なお、第７引数にタイムゾーンを指定することができます。

Carbon::create(
    $year, 
    $month, 
    $day, 
    $hour, 
    $minute, 
    $second, 
    'Asia/Tokyo'
);

createSafe()で例外を考慮しながらインスタンスを作成する

try {

    Carbon::createSafe(2000, 1, 35, 13, 0, 0); // 35日は存在しないので例外になる

} catch (\Carbon\Exceptions\InvalidDateException $e) {

    // 例外処理

}

try〜catch内使うことで存在しない日時が指定された場合に例外をキャッチするすることができます。

なお、第７引数にタイムゾーンを指定することができます。

Carbon::createSafe(2000, 1, 35, 13, 0, 0, 'Asia/Tokyo');

createFromFormat()で日時フォーマットからインスタンスを作成する

$dt = Carbon::createFromFormat(
    'Y-m-d H:i',
    '2018-01-31 17:00'
);

なお、第３引数にタイムゾーンを指定することができます。

$dt = Carbon::createFromFormat(
    'Y-m-d H:i', 
    '2018-01-31 17:00', 
    'Asia/Tokyo'
);

createFromTimestamp()でタイムスタンプからインスタンスを作成する

Carbon::createFromTimestamp(1533289356); // 2018-08-03 09:42:36

なお、第２引数にタイムゾーンを指定することができます。

Carbon::createFromTimestamp(1533289356, 'Asia/Tokyo');

createFromTimestampMs()でタイムスタンプ（ミリ秒）からインスタンスを作成する

Carbon::createFromTimestampMs(1533289629232); // 2018-08-03 09:47:09

なお、第２引数にタイムゾーンを指定することができます。

Carbon::createFromTimestampMs(1533289629232, 'Asia/Tokyo');

createFromTimestampUTC()でUTCタイムスタンプからインスタンスを作成する

Carbon::createFromTimestampUTC(1533254400); // 2018-08-03 00:00:00

なお、第２引数にタイムゾーンを指定することができます。

Carbon::createFromTimestampUTC(1533254400, 'Asia/Tokyo');

copy()で複製したインスタンスを作成する

全く同じCarbonインスタンスをコピーして複製します。

$dt = new Carbon();
$dt_2 = $dt->copy();

nowWithSameTz()で同じタイムゾーンの現在時間を取得する

例えば、ニューヨークでの待ち合わせ時間のインスタンスを作り、そこから現在の現地時間を取得する場合です。

$ny_dt = Carbon::createFromTime(19, 15, 00, 'America/New_York');
echo 'ニューヨークでの待ち合わせは、'. $ny_dt->format('H:i'). '。<br>';
echo 'なお、現在の現地時間は、'. $ny_dt->nowWithSameTz()->format('H:i'). 'です。';

これを実行すると以下のようになります。

ニューヨークでの待ち合わせは、19:15。
なお、現在の現地時間は、03:35です。

instance()でDateTimeクラスからCarbonインスタンスを作成する

$dt = new \DateTime('now');
$carbon_dt = Carbon::instance($dt);

maxValue()で最大値の日時を取得する

$dt = Carbon::maxValue(); // 9999-12-31 23:59:59

minValue()で最小値の日時を取得する

$dt = Carbon::minValue(); // 0001-01-01 00:00:00

max()で２つの日付のうち後のものを取得する

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');
echo $first->max($second); // 2018-08-11 00:00:00

なお、引数を省略すると現在時間と比較して後の方を取得することができます。

$dt = new Carbon('2018-08-01');
echo $dt->max(); // 現在時間と比較して後の日時

maximum()で２つの日付のうち後のものを取得する

max()と同じです。

min()で２つの日付のうち前のものを取得する

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');
echo $first->min($second);

なお、引数を省略すると現在時間と比較して前の方を取得することができます。

$dt = new Carbon('2019-08-01');
echo $dt->min(); // 現在時間と比較して前の日時

minimum()で２つの日付のうち前のものを取得する

min()と同じです。

closest()で２つの日付のうち近いものを取得する

例えば、「2018年8月4日」が以下のどちらに近いかを判断しその日時を取得する場合です。

• 2018年8月1日
• 2018年8月5日（こちらの日付が近いです）

$checking = new Carbon('2018-08-04');
$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');
echo $checking->closest($first, $second); // 2018-08-05 00:00:00

farthest()で２つの日付のうち遠いものを取得する

例えば、「2018年8月4日」が以下のどちらが遠いかを判断しその日時を取得する場合です。

• 2018年8月1日（もちろんこちらの日付が遠いです）
• 2018年8月5日

$checking = new Carbon('2018-08-04');
$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');
echo $checking->farthest($first, $second); // 2018-08-01 00:00:00

日時データ取得（Getter）

※$dtはCarbonインスタンスです。

yearで年を取得する

echo $dt->year; // 例：2018

monthで月を取得する

echo $dt->month; // 例：8

dayで日を取得する

echo $dt->day; // 例：14

hourで時間を取得する

echo $dt->hour; // 例：19

minuteで分を取得する

echo $dt->minute; // 例：55

secondで秒を取得する

echo $dt->second; // 例：33

microでマイクロ秒を取得する

echo $dt->micro; // 例：123789

dayOfWeekで曜日番号を取得する

echo $dt->dayOfWeek;

曜日番号は以下のようになります。

• 日　・・・　0
• 月　・・・　1
• 火　・・・　2
• 水　・・・　3
• 木　・・・　4
• 金　・・・　5
• 土　・・・　6

dayOfWeekIsoでISO形式の曜日番号を取得する

echo $dt->dayOfWeekIso;

dayOfWeekとの違いは、番号が１〜７になる（日曜日が７になる）ことです。

• 月　・・・　1
• 火　・・・　2
• 水　・・・　3
• 木　・・・　4
• 金　・・・　5
• 土　・・・　6
• 日　・・・　7

dayOfYearでその年の何日目かを取得する

echo $dt->dayOfYear; // 218（日）

この数字は、例えば以下のようになります。

• １月１日　・・・　0
• １月２日　・・・　1
• ７月２日　・・・ 182（年の折り返し）
• 12月31日　・・・　364

つまり、「もう今年も○日が終わりました。早いですね。」が分かるということですね。

weekNumberInMonthで何週目かを取得する

echo $dt->weekNumberInMonth; // 例：2

例えば、今日は2018年の8月7日だとします。

カレンダーで見るとこの日は第2週目になります。つまり取得される数字は「2」。もし、８月５日なら「１」となります。

※注意が必要なのは、月曜日〜日曜日を基準として何週目かが判断されるところです。

weekOfMonthで月の何週目かを取得する

weekNumberInMonthと似ていますが、こちらは単純に日数を基準にして何周目かを計算します。

• １〜７日　・・・　1
• ８〜14日　・・・　2
• 15〜21日　・・・　3
• 22〜28日　・・・　4
• それ以降　・・・　5

weekOfYearで年の何週目かを取得する

$dt = new Carbon('2018-12-28');
echo $dt->weekOfYear; // 52

daysInMonthで月の日数を取得する

echo $dt->daysInMonth; // 例：31

つまり、取得できる数字は28〜31となります。

timestampでタイムスタンプを取得する

echo $dt->timestamp; // 1500029733

quarterで四半期（３ヵ月ごと）の何番目かを取得する

echo $dt->quarter; // 例：3

つまり、取得できる数字は１〜４になります。

offsetでUTC時間との時差（秒）を取得する

echo $dt->offset; // 32400（Asia/Tokyoの場合）

つまり、以下のようにUTCで時間を取得した日時の場合、offsetは「０」になります。

echo Carbon::now('UTC')->offset; // 0

offsetHoursでUTC時間との時差（時間）を取得する

echo $dt->offsetHours; // 9（Asia/Tokyoの場合）

offsetでは秒を取得しましたが、こちらは何時間の時差かを取得します。

dstでサマータイム期間中かどうかをチェックする

$dt = Carbon::createFromDate(2012, 9, 1, 'America/New_York');

if($dt->dst) {

    echo 'サマータイム期間中です。';

}

※サマータイムは日本ではまだ導入されていないので、あまり利用する機会は多くないかもしれません。

localで実行環境と同じタイムゾーンかどうかをチェックする

if(Carbon::now('Asia/Tokyo')->local) {

    echo '実行環境と同じタイムゾーンです。';

}

つまり、実行環境とは別のタイムゾーンでCarbonインスタンスを作成したかどうかをチェックすることができます。

utcでUTCタイムゾーンかどうかをチェックする

if(Carbon::now('UTC')->utc) {

    echo 'UTCタイムゾーンです。';

}

timezoneでDateTimeZoneインスタンスを取得する

$timezone = $dt->timezone;

※注意が必要なのは、取得できるのはタイムゾーン名ではなく「DateTimeZone」インスタンスだということです。（シンプルにタイムゾーン名が取得したい場合はtimezoneNameを使うといいでしょう）

このインスタンスは以下のような情報を取得することができます。

getLocation()でロケーション情報を取得する

$location = $timezone->getLocation();
echo $location['country_code']; // JP
echo $location['latitude']; // 35.65444（緯度）
echo $location['longitude']; // 139.74472（経度）
echo $location['comments']; // （空白）

getName()でタイムゾーン名を取得する

echo $timezone->getName(); // Asia/Tokyo

getOffset()でGMT（≒UTC）との時差（秒）を取得する

echo $timezone->getOffset(Carbon::now()); // 32400

ちなみに、こちらのページによると、

GMTとUTCは100年間で約18秒のズレが生じる。

とのことですので、ほぼ同じものと考えていいでしょう。

getTransitions()でタイムゾーンの変遷を取得する

$transitions = $timezone->getTransitions();

listAbbreviations()でサマータイムやオフセットの情報を連想配列で取得する

$abbreviations = $timezone->listAbbreviations();
print_r($abbreviations);

listIdentifiers()で全てのタイムゾーン・識別子を取得する

$listIdentifiers = $timezone->listIdentifiers();
print_r($listIdentifiers);

例：Asia/Tokyoなど

tzでDateTimeZoneインスタンスを取得する

$timezone = $dt->tz;

timezoneと同じです。

timezoneNameでタイムゾーン名を取得する

echo $dt->timezoneName; // 例：Asia/Tokyo

tzNameでタイムゾーン名を取得する

echo $dt->tzName; // 例：Asia/Tokyo

timezoneNameと同じです。

日時データ設定（Setter）

yearで年をセットする

$dt = new Carbon('2018-08-07 19:55:33');
$dt->year = 2005;
echo $dt; // 2005-08-07 19:55:33

monthで月をセットする

$dt = new Carbon('2018-08-07 19:55:33');
$dt->month = 12;
echo $dt; //2018-12-07 19:55:33

もし「13月」をセットすると、

13月 = 1年（12月）＋１月

で自動計算してくれます。

$dt = new Carbon('2018-08-07 19:55:33');
$dt->month = 13;
echo $dt; // 2019-01-07 19:55:33

dayで日をセットする

$dt = new Carbon('2018-08-07 19:55:33', 'Asia/Tokyo');
$dt->day = 21;
echo $dt; // 2018-08-21 19:55:33

もし、「32日」をセットすると月の日数に応じて、

32日 = １月（28〜31日） + 残りの日数

で自動計算してくれます。

$dt = new Carbon('2018-02-01 19:55:33');
$dt->day = 32;
echo $dt; // 2018-03-04 19:55:33

hourで時間をセットする

$dt = new Carbon('2018-02-07 19:55:33');
$dt->hour = 22;
echo $dt; // 2018-02-07 22:55:33

もし「25」をセットすると、

25時間 = 1日（24時間）+ 1時間

で自動計算してくれます。

minuteで分をセットする

$dt = new Carbon('2018-02-07 19:55:33');
$dt->minute = 47;
echo $dt; // 2018-02-07 19:47:33

もし「65分」をセットすると、

65分 = 1時間（60分）+ 5分

で自動計算してくれます。

$dt = new Carbon('2018-02-07 19:55:33');
$dt->minute = 65;
echo $dt; // 2018-02-07 20:05:33

secondで秒をセットする

$dt = new Carbon('2018-02-07 19:55:33');
$dt->second = 5;
echo $dt; // 2018-02-07 19:55:05

もし「65分」をセットすると、

65秒 = 1分（60秒）+ 5秒

で自動計算してくれます。

$dt = new Carbon('2018-02-07 19:55:33');
$dt->second = 65;
echo $dt; // 2018-02-07 19:56:05

timestampでタイムスタンプをセットする

$dt = new Carbon('2017-07-06 17:53:03');
$dt->timestamp = 1533639333;
echo $dt; // 2018-08-07 19:55:33

日時データ設定（メソッド）

※メソッドはアロー演算子「->」でつなげて指定ができます。

$dt->year(2015)->month(8);

year(), month(), day(), hour(), minute(), second(), timestamp()で日時をセットする

それぞれ各Setterと同じです。

• year(2018)　・・・　year
• month(12)　・・・　month
• day(31)　・・・　day
• hour(24)　・・・　hour
• minute(60)　・・・　minute
• second(60)　・・・　second
• timestamp(1533639333)　・・・　timestamp

setDate()で日付をセットする

$dt = new Carbon('2018-02-25 19:55:33');
$dt->setDate(1999, 5, 21);
echo $dt; // 1999-05-21 19:55:33

setTime()で時間をセットする

$dt = new Carbon('2018-08-07 19:55:33');
$dt->setTime(17, 35, 58);
echo $dt; // 2018-08-07 17:35:58

setDateTime()で日時をセットする

$dt = new Carbon('2018-08-07 19:55:33');
$dt->setDateTime(1999, 5, 21, 17, 35, 58);
echo $dt; // 1999-05-21 17:35:58

timezone()でタイムゾーンをセットする

$dt = new Carbon();
$dt->timezone('America/New_York');
echo $dt->timezoneName; // America/New_York

tz()でタイムゾーンをセットする

$dt = new Carbon();
$dt->tz('America/New_York');
echo $dt->timezoneName;

※前項目のtimezone()と同じです。

文字列

toDateString()で日付を取得する

$dt = new Carbon('2018-08-07 19:55:33');
echo $dt->toDateString(); // 2018-08-07

toFormattedDateString()で日付（月 日, 年）を取得する

$dt = new Carbon('2018-08-07 19:55:33');
echo $dt->toFormattedDateString(); // Aug 7, 2018

toTimeString()で時間を取得する

$dt = new Carbon('2018-08-07 19:55:33');
echo $dt->toTimeString(); // 19:55:33

toDateTimeString()で日時を取得する

$dt = new Carbon('2018-08-07 19:55:33');
echo $dt->toDateTimeString(); // 2018-08-07 19:55:33

toDayDateTimeString()で日時（曜日, 月日, 年 時間 午前／午後）を取得する

$dt = new Carbon('2018-08-07 19:55:33');
echo $dt->toDayDateTimeString(); // Tue, Aug 7, 2018 7:55 PM

format()で日付形式を指定してデータを取得する

$dt = new Carbon('2018-08-07 19:55:33');
echo $dt->format('Y年m月d日 H時i分s秒'); // 2018年08月07日 19時55分33秒

hasFormat()で日付フォーマットにマッチしているかチェックする

if(Carbon::hasFormat('2018年08月07日', 'Y年m月d日')) {

    echo '日付フォーマットにマッチしています。';

}

setToStringFormat()でデフォルトの日付形式をセットする

Carbon::setToStringFormat('Y年m月d日 H時i分s秒');
echo $dt; // 2018年08月07日 19時55分33秒

Laravelでは、「app/Providers/AppServiceProvider.php」に以下のように設定しておくと一気に全ての日付フォーマットを変更できて便利です。

public function boot()
{
    \Carbon\Carbon::setToStringFormat('Y年m月d日 H時i分s秒');
}

※リセットするにはresetToStringFormat()を使ってください。

resetToStringFormat()でデフォルトの日付形式をリセットする

Carbon::resetToStringFormat();

setToStringFormat()で指定された日付フォーマットをリセットします。

日付計算

addYears()で指定年数を追加する

$dt = new Carbon('2018-08-08');
echo $dt->addYears(5); // 2023-08-08 00:00:00

addYear()で１年追加する

$dt = new Carbon('2018-08-08');
echo $dt->addYear(); // 2019-08-08 00:00:00

addMonths()で指定月数を追加する

$dt = new Carbon('2018-08-08');
echo $dt->addMonths(5); // 2019-01-08 00:00:00

addMonth()で１月追加する

$dt = new Carbon('2018-08-08');
echo $dt->addMonth(); 2018-09-08 00:00:00

addDays()で指定日数を追加する

$dt = new Carbon('2018-08-08');
echo $dt->addDays(3); // 2018-08-11 00:00:00

addDay()で１日追加する

$dt = new Carbon('2018-08-08');
echo $dt->addDay(); // 2018-08-09 00:00:00

addHours()で指定時間を追加する

$dt = new Carbon('2018-08-08 09:00:53');
echo $dt->addHours(5); // 2018-08-08 14:00:53

addHour()で１時間追加する

$dt = new Carbon('2018-08-08 09:00:53');
echo $dt->addHour(); // 2018-08-08 10:00:53

addMinutes()で指定分を追加する

$dt = new Carbon('2018-08-08 09:05:53');
echo $dt->addMinutes(7); // 2018-08-08 09:12:53

addMinute()で１分追加する

$dt = new Carbon('2018-08-08 09:05:53');
echo $dt->addMinute(); // 2018-08-08 09:06:53

addSeconds()で指定秒を追加する

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->addSeconds(5); // 2018-08-08 09:05:28

addSecond()で１秒追加する

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->addSecond(); // 2018-08-08 09:05:24

addWeekdays()で指定日数（土日以外）を追加する

$dt = new Carbon('2018-08-08 09:05:23'); // 水曜
echo $dt->addWeekdays(4); // 2018-08-14 09:05:23（火曜）

addWeekday()で１日（土日以外）追加する

$dt = new Carbon('2018-08-10 09:05:23'); // 金曜
echo $dt->addWeekday(); // 2018-08-13 09:05:23（月曜）

addWeeks()で指定週を追加する

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->addWeeks(3); // 2018-08-29 09:05:23（3週＝21日）

addWeek()で１週追加する

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->addWeek(); // 2018-08-15 09:05:23（1週＝7日）

addCenturies()で指定された世紀を追加する

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->addCenturies(5); // 2518-08-08 09:05:23（5世紀＝500年）

addCentury()で１世紀追加する

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->addCentury();// 2118-08-08 09:05:23（１世紀＝100年）

addQuarters()で指定された４半期を追加する

$dt = new Carbon('2018-03-08 09:05:23');
echo $dt->addQuarters(2); // 2018-09-08 09:05:23（4半期×2＝6ヵ月）

addQuarter()で４半期を追加する

$dt = new Carbon('2018-03-08 09:05:23');
echo $dt->addQuarter(); // 2018-06-08 09:05:23（4半期＝3ヵ月）

subYears()で指定年数を減らす

$dt = new Carbon('2018-08-08');
echo $dt->subYears(5); // 2013-08-08 00:00:00

subYear()で１年減らす

$dt = new Carbon('2018-08-08');
echo $dt->subYear(); // 2017-08-08 00:00:00

subMonths()で指定月数を減らす

$dt = new Carbon('2018-08-08');
echo $dt->subMonths(5); // 2018-03-08 00:00:00

subMonth()で１月減らす

$dt = new Carbon('2018-08-08');
echo $dt->subMonth(); 2018-07-08 00:00:00

subDays()で指定日数を減らす

$dt = new Carbon('2018-08-08');
echo $dt->subDays(3); // 2018-08-05 00:00:00

subDay()で１日減らす

$dt = new Carbon('2018-08-08');
echo $dt->subDay(); // 2018-08-07 00:00:00

subHours()で指定時間を減らす

$dt = new Carbon('2018-08-08 09:00:53');
echo $dt->subHours(5); // 2018-08-08 04:00:53

subHour()で１時間減らす

$dt = new Carbon('2018-08-08 09:00:53');
echo $dt->subHour(); // 2018-08-08 08:00:53

subMinutes()で指定分を減らす

$dt = new Carbon('2018-08-08 09:07:53');
echo $dt->subMinutes(5); // 2018-08-08 09:02:53

subMinute()で１分減らす

$dt = new Carbon('2018-08-08 09:05:53');
echo $dt->subMinute(); // 2018-08-08 09:04:53

subSeconds()で指定秒を減らす

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->subSeconds(5); // 2018-08-08 09:05:18

subSecond()で１秒減らす

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->subSecond(); // 2018-08-08 09:05:22

subWeekdays()で指定日数（土日以外）を減らす

$dt = new Carbon('2018-08-08 09:05:23'); // 水曜
echo $dt->subWeekdays(4); // 2018-08-02 09:05:23（木曜）

subWeekday()で１日（土日以外）減らす

$dt = new Carbon('2018-08-06 09:05:23'); // 月曜
echo $dt->subWeekday(); // 2018-08-03 09:05:23（金曜）

subWeeks()で指定週を減らす

$dt = new Carbon('2018-08-28 09:05:23');
echo $dt->subWeeks(3); // 2018-08-07 09:05:23（3週＝21日）

subWeek()で１週減らす

$dt = new Carbon('2018-08-15 09:05:23');
echo $dt->subWeek(); // 2018-08-08 09:05:23（1週＝7日）

subCenturies()で指定された世紀を減らす

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->subCenturies(5); // 1518-08-08 09:05:23（5世紀＝500年）

subCentury()で１世紀減らす

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->subCentury();// 1918-08-08 09:05:23（１世紀＝100年）

subQuarters()で指定された４半期を減らす

$dt = new Carbon('2018-08-08 09:05:23');
echo $dt->subQuarters(2); // 2018-02-08 09:05:23（4半期×2＝6ヵ月）

subQuarter()で４半期を減らす

$dt = new Carbon('2018-05-08 09:05:23');
echo $dt->subQuarter(); // 2018-02-08 09:05:23（4半期＝3ヵ月）

addMonthWithOverflow()で日付あふれを許可しながら１月追加する

$dt = new Carbon('2018-01-31');
echo $dt->addMonthWithOverflow(); // 2018-03-03 00:00:00

※日付あふれについて

addMonthsWithOverflow()で日付あふれを許可しながら指定月を追加する

$dt = new Carbon('2018-01-31');
echo $dt->addMonthsWithOverflow(3); // 2018-05-01 00:00:00

※日付あふれについて

addMonthNoOverflow()で日付あふれを許可せずに１月追加する

$dt = new Carbon('2018-01-31');
echo $dt->addMonthNoOverflow(); // 2018-02-28 00:00:00

※日付あふれについて

addMonthsNoOverflow()で日付あふれを許可せずに１月追加する

$dt = new Carbon('2018-01-31');
echo $dt->addMonthsNoOverflow(3); // 2018-04-30 00:00:00

※日付あふれについて

subMonthWithOverflow()で日付あふれを許可しながら１月減らす

$dt = new Carbon('2018-03-31');
echo $dt->subMonthWithOverflow(); // 2018-03-03 00:00:00

※日付あふれについて

subMonthsWithOverflow()で日付あふれを許可しながら指定月を減らす

$dt = new Carbon('2018-05-31');
echo $dt->subMonthsWithOverflow(3); // 2018-03-03 00:00:00

※日付あふれについて

subMonthNoOverflow()で日付あふれを許可せずに１月減らす

$dt = new Carbon('2018-03-31');
echo $dt->subMonthNoOverflow(); // 2018-02-28 00:00:00

※日付あふれについて

subMonthsNoOverflow()で日付あふれを許可せずに１月減らす

$dt = new Carbon('2018-05-31');
echo $dt->subMonthsNoOverflow(3); // 2018-02-28 00:00:00

※日付あふれについて

addYearWithOverflow()で日付あふれを許可しながら１年追加する

$dt = new Carbon('2020-02-29');
echo $dt->addYearWithOverflow(); // 2021-03-01 00:00:00

※日付あふれについて

addYearsWithOverflow()で日付あふれを許可しながら指定年を追加する

$dt = new Carbon('2020-02-29');
echo $dt->addYearsWithOverflow(3); // 2023-03-01 00:00:00

※日付あふれについて

addYearNoOverflow()で日付あふれを許可せずに１年追加する

$dt = new Carbon('2020-02-29');
echo $dt->addYearNoOverflow(); // 2021-02-28 00:00:00

※日付あふれについて

addYearsNoOverflow()で日付あふれを許可せずに１年追加する

$dt = new Carbon('2020-02-29');
echo $dt->addYearsNoOverflow(3); // 2023-02-28 00:00:00

※日付あふれについて

subYearWithOverflow()で日付あふれを許可しながら１年減らす

$dt = new Carbon('2020-02-29');
echo $dt->subYearWithOverflow(); // 2019-03-01 00:00:00

※日付あふれについて

subYearsWithOverflow()で日付あふれを許可しながら指定年を減らす

$dt = new Carbon('2020-02-29');
echo $dt->subYearsWithOverflow(3); // 2017-03-01 00:00:00

※日付あふれについて

subYearNoOverflow()で日付あふれを許可せずに１年減らす

$dt = new Carbon('2020-02-29');
echo $dt->subYearNoOverflow(); // 2019-02-28 00:00:00

※日付あふれについて

subYearsNoOverflow()で日付あふれを許可せずに１年減らす

$dt = new Carbon('2020-02-29');
echo $dt->subYearsNoOverflow(3); // 2017-02-28 00:00:00

※日付あふれについて

差分

diffInYears()で年の差を取得する

$first = new Carbon('2018-08-08');
$second = new Carbon('2021-08-08');
echo $first->diffInYears($second); // 3

diffInMonths()で月の差を取得する

$first = new Carbon('2018-08-08');
$second = new Carbon('2018-11-08');
echo $first->diffInMonths($second); // 3

diffInDays()で日数差を取得する

$first = new Carbon('2018-08-08');
$second = new Carbon('2018-08-15');
echo $first->diffInDays($second); // 7

diffInHours()で時間差を取得する

$first = new Carbon('2018-08-08 19:00:00');
$second = new Carbon('2018-08-08 22:00:00');
echo $first->diffInHours($second); // 3

diffInMinutes()で分の差を取得する

$first = new Carbon('2018-08-08 19:05:00');
$second = new Carbon('2018-08-08 19:15:00');
echo $first->diffInMinutes($second); // 10

diffInSeconds()で秒の差を取得する

$first = new Carbon('2018-08-08 19:05:00');
$second = new Carbon('2018-08-08 19:05:30');
echo $first->diffInSeconds($second); // 30

diffInWeeks()で週の差を取得する

$first = new Carbon('2018-08-08');
$second = new Carbon('2018-08-29');
echo $first->diffInWeeks($second); // 3

diffInWeekendDays()で週末（土日）の日数差を取得する

$first = new Carbon('2018-08-08'); // 水曜
$second = new Carbon('2018-08-15'); // 次の水曜
echo $first->diffInWeekendDays($second); // 2

diffInWeekdays()で平日（土日以外）の日数差を取得する

$first = new Carbon('2018-08-08'); // 水曜
$second = new Carbon('2018-08-15'); // 次の水曜
echo $first->diffInWeekdays($second); // 5

設定

useMonthsOverflow()で日付あふれを有効／無効にする

例えば、以下のように「2018年01月31日」にaddMonth()で１月追加する場合にある問題が発生します。

$dt = new Carbon('2018-01-31');
echo $dt->addMonth();

実行結果は、「2018-03-03 00:00:00」となります。そう、月末は月によって日数が違うため日付が溢れてしまうのです。

これを防ぐためには以下のようします。

Carbon::useMonthsOverflow(false); // デフォルトはtrue

$dt = new Carbon('2018-01-31');
echo $dt->addMonth();

これで、実行結果は「2018-02-28 00:00:00」と我々が直感で考えるような日付を取得することができます。

ただし、これにも注意が必要です。もし以下のように２月の月末にaddMonth()で１月追加しても３月の月末を取得できるわけではないからです。

$dt = new Carbon('2018-02-28');
echo $dt->addMonth(); // 2018-03-28 00:00:00

そのため、月末を取得する方法としては、以下のようなアプローチをする必要があります。

$months = 3; // 追加する月数
$dt = new Carbon('2018-01-31');
echo $dt->day(1)->addMonths($months)->endOfMonth();

実行結果は「2018-04-30 23:59:59」となります。

resetMonthsOverflow()で日付あふれを有効にする

useMonthsOverflow()をリセット（つまりデフォルトの「有効」に）する

shouldOverflowMonths()で日付があふれる設定かどうかをチェックする

if(Carbon::shouldOverflowMonths()) {

    echo '日付があふれます。';

}

useMonthsOverflow()が有効かどうかをチェックすることができます。

useYearsOverflow()で日付あふれを有効／無効にする

考え方はuseMonthsOverflowと同じです。

resetYearsOverflow()で日付あふれをリセットする

useYearsOverflow()をリセット（つまり有効に）します

定型フォーマット

toAtomString()でATOM用の日付を取得する

echo $dt->toAtomString(); // 2018-08-07T19:55:33+09:00

toCookieString()でクッキー用の日付を取得する

echo $dt->toCookieString(); // Tuesday, 07-Aug-2018 19:55:33 JST

toIso8601String()でISO8601形式の日付を取得する

echo $dt->toIso8601String(); // 2018-08-07T19:55:33+09:00

toIso8601ZuluString()でZulu（UTC）ISO8601形式の日付を取得する

echo $dt->toIso8601ZuluString(); // 2018-08-07T10:55:33Z

toRfc822String()でRFC822形式の日付を取得する

echo $dt->toRfc822String(); // Tue, 07 Aug 18 19:55:33 +0900

toRfc850String()でRFC850形式の日付を取得する

echo $dt->toRfc850String(); // Tuesday, 07-Aug-18 19:55:33 JST

toRfc1036String()でRFC1036形式の日付を取得する

echo $dt->toRfc1036String(); // Tue, 07 Aug 18 19:55:33 +0900

toRfc1123String()でRFC1123形式の日付を取得する

echo $dt->toRfc1123String(); // Tue, 07 Aug 2018 19:55:33 +0900

toRfc2822String()でRFC2822形式の日付を取得する

echo $dt->toRfc2822String(); // Tue, 07 Aug 2018 19:55:33 +0900

toRfc3339String()でRFC3339形式の日付を取得する

echo $dt->toRfc3339String(); // 2018-08-07T19:55:33+09:00

toRfc7231String()でRFC7231形式の日付を取得する

echo $dt->toRfc7231String(); // Tue, 07 Aug 2018 10:55:33 GMT

toRssString()でRSS形式の日付を取得する

echo $dt->toRssString(); // Tue, 07 Aug 2018 19:55:33 +0900

toW3cString()でW3C形式の日付を取得する

echo $dt->toW3cString(); // 2018-08-07T19:55:33+09:00

toArray()で日付データを配列で取得する

print_r($dt->toArray());

これを実行すると以下のようになります。

Array
(
    [year] => 2018
    [month] => 8
    [day] => 7
    [dayOfWeek] => 2
    [dayOfYear] => 218
    [hour] => 19
    [minute] => 55
    [second] => 33
    [micro] => 0
    [timestamp] => 1533639333
    [formatted] => 2018-08-07 19:55:33
    [timezone] => DateTimeZone Object
        (
            [timezone_type] => 3
            [timezone] => Asia/Tokyo
        )

)

比較

※比較で注意が必要なのがタイムゾーンが違っている場合です。例えば、おなじ「2018-08-07 19時00分」の日付であっても、タイムゾーンが違うと別の時間として判断されます。つまり、同じである場合タイムスタンプが同じである必要があります。

eq()で2つの日時が同じかをチェックする

$utc_dt = new Carbon('2018-08-07 10:55:33', 'UTC');
$jp_dt = new Carbon('2018-08-07 19:55:33', 'Asia/Tokyo');

if($utc_dt->eq($jp_dt)) {

    echo '同じ日時（タイムスタンプ）です。'; // 表示されます

}

※タイムゾーンに注意

なお、通常通りif()で比較もできます。可読性がいいのでこちらをおすすめします。

if($utc_dt == $jp_dt) {

    // 同じ時間です。

}

ne()で２つの日付が違っているかチェックする

$utc_dt = new Carbon('2018-08-07 10:55:33', 'UTC');
$jp_dt = new Carbon('2018-08-07 19:55:33', 'Asia/Tokyo');

if(!$utc_dt->ne($jp_dt)) {

    echo '同じ日時（タイムスタンプ）です。'; // 表示されます

}

※タイムゾーンに注意

なお、通常通りif()で比較もできます。可読性がいいのでこちらをおすすめします。

if($utc_dt != $jp_dt) {

    // 時間が違います。

}

gt()で日付が後かどうかをチェックする

$first = new Carbon('2018-08-07 21:55:33');
$second = new Carbon('2018-08-07 11:55:33');

if($first->gt($second)) {

    echo '$first が後の時間です。'; // 表示されます。

}

注意が必要なのは、同じ時間だとIFの中身はfalseとなることです。つまり、

$first > $second

の条件式が成立する必要があります。実際、以下のようにIF文での比較も可能です。可読性がいいのでこちらをおすすめします。

if($first > $second) {

    // $firstが後の時間です。

}

gte()で日付が同じかそれ以降かをチェックする

$first = new Carbon('2018-08-07 11:55:33');
$second = new Carbon('2018-08-07 11:55:33');

if($first->gte($second)) {

    echo '$first が同じか後の時間です。'; // 表示されます。

}

不等式で言うと、

$first >= $second

が成り立つかどうかをチェックすることになります。実際、以下のようにIF文での比較も可能です。可読性がいいのでこちらをおすすめします。

if($first >= $second) {

    echo '$first が同じか後の時間です。'; // 表示されます。

}

lt()で日付が前かどうかをチェックする

$first = new Carbon('2018-08-07 11:55:33');
$second = new Carbon('2018-08-07 21:55:33');

if($first->lt($second)) {

    echo '$first が前の時間です。'; // 表示されます。

}

注意が必要なのは、同じ時間だとIFの中身はfalseとなることです。つまり、

$first < $second

の条件式が成立する必要があります。実際、以下のようにIF文での比較も可能です。可読性がいいのでこちらをおすすめします。

if($first < $second) {

    // $firstが前の時間です。

}

lte()で日付が同じかそれ以降かをチェックする

$first = new Carbon('2018-08-07 11:55:33');
$second = new Carbon('2018-08-07 11:55:33');

if($first->lte($second)) {

    echo '$first が同じか前の時間です。'; // 表示されます。

}

不等式で言うと、

$first <= $second

が成り立つかどうかをチェックすることになります。実際、以下のようにIF文での比較も可能です。可読性がいいのでこちらをおすすめします。

if($first <= $second) {

    // $first が同じか前の時間です。

}

equalTo()で2つの日時が同じかをチェックする

eq()と同じです。

notEqualTo()で２つの日付が違っているかチェックする

ne()と同じです。

greaterThan()で日付が後かどうかをチェックする

gt()と同じです。

greaterThanOrEqualTo()で日付が同じかそれ以降かをチェックする

gte()と同じです。

lessThan()で日付が前かどうかをチェックする

lt()と同じです。

lessThanOrEqualTo()で日付が同じかそれ以降かをチェックする

lte()と同じです。

between()で２つの日付の間に入っているかチェックする

例えば、2018年8月3日が

• 2018年8月1日
• 2018年8月5日

の間に入っているかをチェックする場合です。

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');

if(Carbon::parse('2018-08-03')->between($first, $second)) {

    echo '間に入っています。'; // 表示されます

}

ちなみに、between()は同じ日も含めて間に入っていると判断します。以下の例を見てみましょう。

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');

if(Carbon::parse('2018-08-01')->between($first, $second)) {

    echo '間に入っています。'; // 表示されます

}

もし同じ日は含めないようにしたい場合は、第３引数にfalseを設定します。

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-05');

if(Carbon::parse('2018-08-01')->between($first, $second, false)) {

    echo '間に入っています。'; // 表示されません

}

つまり、上の例で言うと「2018年8月2日」「2018年8月3日」「2018年8月4日」の３日間のみ間に入っていると判断されるようになります。

isSameAs()で日付フォーマットを使って同じかをチェックする

例えば、以下２つの日付が同じ月かどうかをチェックする場合です。

• 2018年8月1日
• 2018年8月8日

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-08');

if($first->isSameAs('m', $second)) { // mはフォーマットの「月」

    echo '同じ月です。';

}

なお、以下のようにすると曜日が同じかチェックすることもできます。

if($first->isSameAs('w', $second)) {

    echo '同じ曜日です。';

}

isFuture()で日時が未来のものかどうかをチェックする

$dt = new Carbon('2019-08-01');

if($dt->isFuture()) {

    echo '未来の日時です。';

}

isPast()で日時が過去のものかどうかをチェックする

$dt = new Carbon('2018-08-01');

if($dt->isPast()) {

    echo '過去の日時です。';

}

isSameYear()で同じ年かをチェックする

$first = new Carbon('2018-08-01');
$second = new Carbon('2018-08-08');

if($first->isSameYear($second)) {

    echo '同じ年です。';

}

isCurrentYear()で今年かどうかをチェックする

$dt = new Carbon();

if($dt->isCurrentYear()) {

    echo '今年です。';

}

isNextYear()で来年かどうかをチェックする

$dt = new Carbon('2019-08-01');

if($dt->isNextYear()) {

    echo '来年です。';

}

isLastYear()で去年かどうかをチェックする

$dt = new Carbon('2017-08-01');

if($dt->isLastYear()) {

    echo '去年です。';

}

isLongYear()でロングイヤーかどうかをチェックする

ロングイヤー：１年に53週ある年のこと。

$dt = new Carbon('2017-08-01');

if($dt->isLongYear()) {

    echo 'ロングイヤーです。';

}

isLeapYear()でうるう年かどうかをチェックする

$dt = new Carbon('2000-08-07');

if($dt->isLeapYear()) {

    echo 'うるう年です。';

}

isSameMonth()で同じ月かどうかをチェックする

$first = new Carbon('2018-08-07');
$second = new Carbon('2019-08-27');

if($first->isSameMonth($second)) {

    echo '同じ月です。';

}

もし年も同じかどうかをチェックしたい場合は第２引数にtrueを指定します。

$first = new Carbon('2018-08-07');
$second = new Carbon('2019-08-27');

if($first->isSameMonth($second, true)) {

    echo '同じ年で、同じ月です。'; // これは表示されません。

}

isCurrentMonth()で今月かどうかをチェックする

$dt = new Carbon('2018-08-07');

if($dt->isCurrentMonth()) {

    echo '今月です。';

}

isNextMonth()で来月かどうかをチェックする

$dt = new Carbon('2018-09-07');

if($dt->isNextMonth()) {

    echo '来月です。';

}

isLastMonth()で先月かどうかをチェックする

$dt = new Carbon('2018-07-07');

if($dt->isLastMonth()) {

    echo '先月です。';

}

isWeekday()で平日（土日以外）かどうかをチェックする

$dt = new Carbon('2018-08-07');

if($dt->isWeekday()) {

    echo '平日です。';

}

isWeekend()で週末（土日）かどうかをチェックする

$dt = new Carbon('2018-08-12');

if($dt->isWeekend()) {

    echo '週末です。';

}

isMonday()で月曜日かどうかをチェックする

$dt = new Carbon('2018-08-06');

if($dt->isMonday()) {

    echo '月曜日です。';

}

isTuesday()で火曜日かどうかをチェックする

$dt = new Carbon('2018-08-07');

if($dt->isTuesday()) {

    echo '火曜日です。';

}

isWednesday()で水曜日かどうかをチェックする

$dt = new Carbon('2018-08-08');

if($dt->isWednesday()) {

    echo '水曜日です。';

}

isThursday()で木曜日かどうかをチェックする

$dt = new Carbon('2018-08-09');

if($dt->isThursday()) {

    echo '木曜日です。';

}

isFriday()で金曜日かどうかをチェックする

$dt = new Carbon('2018-08-10');

if($dt->isFriday()) {

    echo '金曜日です。';

}

isSaturday()で土曜日かどうかチェックする

$dt = new Carbon('2018-08-11');

if($dt->isSaturday()) {

    echo '土曜日です。';

}

isSunday()で日曜日かどうかチェックする

$dt = new Carbon('2018-08-12');

if($dt->isSunday()) {

    echo '日曜日です。';

}

isDayOfWeek()で指定した曜日かどうかチェックする

$dt = new Carbon('2018-08-12');

if($dt->isDayOfWeek(Carbon::SUNDAY)) {

    echo '日曜日です。';

}

isLastOfMonth()で月の最後の日かどうかチェックする

$dt = new Carbon('2018-08-31');

if($dt->isLastOfMonth()) {

    echo '月の最後の日です。';

}

isSameDay()で同じ日かチェックする

$first = new Carbon('2018-08-01 19:00:00');
$second = new Carbon('2018-08-01 20:00:00');

if($first->isSameDay($second)) {

    echo '同じ日です。';

}

注意が必要なのは、isSameDay()は

• 同じ年
• 同じ月
• 同じ日

である必要があるという部分です。単純に日にちだけの比較ではありません。

isToday()で今日かどうかチェックする

$dt = new Carbon('2018-08-08');

if($dt->isToday()) {

    echo '今日です。';

}

isYesterday()で昨日かどうかをチェックする

$dt = new Carbon('2018-08-07');

if($dt->isYesterday()) {

    echo '昨日です。';

}

isTomorrow()で明日かどうかチェックする

$dt = new Carbon('2018-08-09');

if($dt->isTomorrow()) {

    echo '明日です。';

}

isNextWeek()で来週かどうかチェックする

$dt = new Carbon('2018-08-14');

if($dt->isNextWeek()) {

    echo '来週です。';

}

isLastWeek()で先週かどうかチェックする

$dt = new Carbon('2018-08-03');

if($dt->isLastWeek()) {

    echo '先週です。';

}

isBirthday()で誕生日かどうかをチェックする

$today = Carbon::today();
$checking = new Carbon('2018-08-08');

if($today->isBirthday($checking)) {

    echo 'お誕生日おめでとう！';

}

なお、引数が省略された場合は実行された日との比較になります。

if($dt->isBirthday()) {

    echo 'お誕生日おめでとう！';

}

ローカリゼーション

setLocal()で言語を設定する

Carbon::setLocale('ja');

getLocal()で現在の言語を取得する

Carbon::getLocale(); // ja

formatLocalized()でローカル表記の日時を取得する

setlocale(LC_ALL, 'ja_JP.UTF-8');
echo Carbon::now()->formatLocalized('%Y %B %d（%a）');

これを実行すると、以下のようになります。

2018 8月 06（月）

日本語の曜日を取得する

Carbon::setLocale('ja'); // 日本語を指定する
$dt = now();

echo $dt->isoFormat('YYYY年MM月DD(ddd) HH:mm:ss'); // 2022年01月11(火) 04:51:43
echo $dt->isoFormat('YYYY年MM月DD(dddd) HH:mm:ss'); // 2022年01月11(火曜日) 04:51:28

echo $dt->dayName; // 火曜日

getTranslator()でTranslatorインスタンスを取得する

$translator = Carbon::getTranslator();

ちなみにtranslator()を使うと以下のように表示内容を変更することができます。例えば、「営業日」を使って表示したい場合です。

Carbon::setLocale('ja');
$translator = Carbon::getTranslator();
$translator->setMessages('ja', [
    'day' => ':count 営業日'
]);

$dt_1 = Carbon::createFromDate(2018, 1, 1);
$dt_2 = Carbon::createFromDate(2018, 1, 4);
echo $dt_1->diffForHumans($dt_2); // 3 営業日前

なお、英語環境では「|」を使って単数形と複数形の切り替えにも対応できます。左側が単数形の場合で、右側が複数形の場合です。

$translator->setMessages('en', array(
    'day' => ':count business day|:count business days'
));

リセットする場合はresetMessages()を使います。

$translator->resetMessages('en');

setTranslator()でTranslatorを設定する

$translator = new \Carbon\Translator('ja');
Carbon::setTranslator($translator);

\Carbon\Translatorを使っていますが、Symfony\Component\Translation\TranslatorInterfaceを使っているクラスなら何でもOKです。

setUtf8()で文字コードをUTF-8で使うかどうかを設定する

Carbon::setUtf8(true);

開発用メソッド

setTestNow()でテスト日時をセットする

例えば、「2001年5月22日の19時55分00秒に本当にこの自分のコードがうまく作動するか？？」をチェックしたい場合です。つまり、cronなどタイマー予約したコード実行などで役立つメソッドになります。

$target_dt = Carbon::create(2001, 5, 22, 19, 55, 0);
Carbon::setTestNow($target_dt);
echo Carbon::now(); // 2001-05-22 19:55:00（固定）

setTestNow()がすごいのは現在日時を返すだけでなく、基準をそのテスト日時として日時の計算をしてくれるというところです。

実際の例を見てみましょう。
例えば、先ほどと同じく「2001年5月22日の19時55分00秒」をテスト日時として設定します。

そして、以下のようにCarbon::tomorrow()で次の日の日時を取得すると、テスト日時の次の日の「2001-05-23 00:00:00」が取得されるのです。（つまり、リアルな時間は関係なくなります）

$target_dt = Carbon::create(2001, 5, 22, 19, 55, 0);
Carbon::setTestNow($target_dt);
echo Carbon::tomorrow(); // 2001-05-23 00:00:00

なお、もしテスト日時をクリアしたい場合は空白にして実行します。

Carbon::setTestNow();

getTestNow()でテスト日時を取得する

echo Carbon::getTestNow();

setTestNow()でセットしたテスト日時を取得します。

hasTestNow()でテスト日時が設定されているかチェックする

if(Carbon::hasTestNow()) {

    echo 'テスト日時が設定されています。';

}

setTestNow()でテスト日時が設定されているかどうかをチェックします。

おわりに

今回の学び直しで目からウロコだったのは、Carbonインスタンスがif()で「==」とか「>」「<=」が使えるというところです。

これまではisFuture()とかisPast()を使ってましたけど、比較条件式が使えるならより直感的に使えるので保守もしやすいんじゃないでしょうか。

ということで、皆さんのお役に立てましたら嬉しいです。

ではでは〜！