最後更新日期：2022 年 08 月 17 日

「日期」跟「時間」是我們在寫程式時常遇到的資料類型，看起來容易，但是有些地方要特別注意，例如：格式、地區、不同天數的月份、閏年…等等；Carbon 把我們會用到的功能以物件導向的方式做有系統的整理，讓我們能更直覺的解決問題。

如何開始

使用 composer 來安裝

composer require nesbot/carbon

然後我們就可以在程式中使用了

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

use Carbon\Carbon;

echo Carbon::now();

基本用法

這個元件中的靈魂，是 Carbon 這個類別。

Carbon 類別提供了非常多的靜態方法，來生成 Carbon 實體物件。

Carbon 實體物件是 PHP 標準類別 DateTime 的延伸，我們可以透過他來操作時間的加減，顯示不同格式的時間…等等方便的功能。

生成 Carbon 物件

從日常語意

$now = Carbon::now();
// 這跟上面相同意思
$now = new Carbon();

// 今天的 0 時 0 分
// 不指定時區的話，會採用系統時區
$today = Carbon::today();

// 明天的 0 時 0 分，並設定時區為台北
$tomorrowTaipei = Carbon::tomorrow("Asia/Taipei");

// 昨天的 0 時 0 分，並設定時區為倫敦
$yesterdayLondon = Carbon::yesterday("Europe/London");

// 這個月的第一天
$firstDayofMonth = Carbon::now()->startOfMonth();

// 這個月的最後
$lastDayofMonth = Carbon::now()->endOfMonth();

從字串

$dt = new Carbon("first day of March 2020");

// 也可以用 parse 靜態方法
$dt = Carbon::parse("first day of March 2020");

// 指定時區為台北
$dtTaipei = new Carbon("first day of March 2020", "Asia/Taipei");

echo $dtTaipei->toDateTimeString(); // 2020-03-01 00:00:00⏎

從時間戳記 (timestamp)

$dtTaipei = Carbon::createFromTimestamp(1611237657, "Asia/Taipei");

echo $dtTaipei->toDateTimeString(); // 2021-01-21 22:00:57⏎

從時間日期資料

// 年 月 日 時 分 秒
$dt = Carbon::create(2021, 1, 1, 0, 0, 0);

// 設定時區為台北
$dtTaipei = Carbon::create(2021, 1, 1, 0, 0, 0, "Asia/Taipei");

echo $dtTaipei->toDateTimeString(); // 2021-01-01 00:00:00⏎

讓時間物件格式化輸出

$dt = Carbon::create(2021, 1, 21, 22, 35, 15);

echo $dt->toDateString();  // 2021-01-21
echo $dt->toTimeString();  // 22:35:15
echo $dt->toDateTimeString();  // 2021-01-21 22:35:15

echo $dt->format("Y-m-d H:i:s");  // 2021-01-21 22:35:15

// 轉成 timestamp 時間戳記
echo $dt->timestamp;  // 1611239715⏎

時間的前進及退後

可用的單位：Day, Month, Year, Week, Hour, Minute, Second …

$dt = Carbon::create(2021, 1, 21, 0);

// 注意！！ 時間的前進及退後，會對 Carbon 物件變數本身產生變化
// 以「天」為例，可以改為 年(Year)、月(Month) …等
echo $dt->addDays(8); // 2021-01-29 00:00:00
echo $dt->addDay(); // 2021-01-30 00:00:00
echo $dt->subDay(); // 2021-01-29 00:00:00
echo $dt->subDays(8); // 2021-01-21 00:00:00

// 如果不想時間 Carbon 物件變數本身產生變化，必須將其從預設的 mutable 改為 immutable
$dtImmutable = $dt->toImmutable();

// 此時 Carbon 物件變數已不再隨操作而產生變化
echo $dtImmutable->addDay();  // 2021-01-22 00:00:00
echo $dtImmutable; // 2021-01-21 00:00:00

異常 (Exception) 處理

try { 
    Carbon::create(2021, 1, 21, 22, -2, 0);
} catch(InvalidArgumentException $ex) { 
    echo $ex->getMessage();
}

參考資料

Carbon 官方網站