最後更新日期: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 官方網站

Last modified: 2022-08-17

Author

Comments

Sunny.cat 

感謝大大分享!
另外提醒文章第一段亂的台北時區拚錯了

// 明天的 0 時 0 分,並設定時區為台北
$tomorrowTaipei = Carbon::tomorrow(“Asis/Taipei”);

應該是”Asia/Taipei”

Write a Reply or Comment

Your email address will not be published.