Carbon（nesbot/carbon）– PHP 日期时间利器化

一、Carbon介绍

Carbon 是 PHP 中最流行的日期时间处理库，基于 PHP 原生的 DateTime 类封装，提供链式操作、易读 API、时区支持等强大功能。

特点：

链式调用，语义化强
支持日期时间加减、比较、格式化
支持中文等多语言友好显示
可与 Laravel、Hyperf 等框架无缝集成

官方文档：https://carbon.nesbot.com/docs/

安装：composer require nesbot/carbon

二、基本使用

2.1 获取当前时间

1$now = Carbon::now(); // 当前时间，默认系统时区
2echo $now; // 2023-09-28 15:30:12
3
4// 指定时区：
5$nowShanghai = Carbon::now('Asia/Shanghai');

2.2 日期创建

1$dt1 = Carbon::create(2023, 9, 28, 15, 30, 0); // 年, 月, 日, 时, 分, 秒
2$dt2 = Carbon::parse('2023-12-31 23:59:59');
3$dt3 = Carbon::today(); // 当天 0:00:00
4$dt4 = Carbon::tomorrow(); // 明天 0:00:00
5$dt5 = Carbon::yesterday(); // 昨天 0:00:00

2.3 日期格式化

1$now = Carbon::now();
2echo $now->toDateString();    // 2023-09-28
3echo $now->toTimeString();    // 15:30:12
4echo $now->toDateTimeString();// 2023-09-28 15:30:12
5echo $now->format('Y-m-d H:i'); // 自定义格式

2.4 日期加减操作

1$dt = Carbon::now();
2
3echo $dt->addDays(3);    // 当前时间 +3天
4echo $dt->subHours(5);   // 当前时间 -5小时
5echo $dt->addMonthsNoOverflow(1); // 避免月份溢出

2.5 日期比较

1$dt1 = Carbon::parse('2023-09-28');
2$dt2 = Carbon::parse('2023-10-01');
3
4if ($dt1->lt($dt2)) {
5    echo "dt1 小于 dt2";
6}
7
8echo $dt1->diffInDays($dt2); // 返回天数差
9echo $dt1->diffForHumans($dt2); // 语义化描述: "3 days before"

2.6 时区转换

1$dt = Carbon::now('UTC');
2$dtShanghai = $dt->copy()->setTimezone('Asia/Shanghai');
3echo $dtShanghai;

2.7 本地化输出

1Carbon::setLocale('zh'); // 设置中文
2
3$dt1 = Carbon::now();
4$dt2 = Carbon::parse('2025-10-01');
5
6echo $dt1->diffForHumans($dt2); // 输出: 3 天前 / 3 天后

2.8 链式操作

1$dt = Carbon::now()->addDays(5)->subHours(3)->format('Y-m-d H:i:s');
2echo $dt;

三、Carbon 高级使用技巧合集

3.1 时间区间判断

判断某个时间是否在区间内

1use Carbon\Carbon;
2
3$start = Carbon::parse('2023-09-01');
4$end = Carbon::parse('2023-09-30');
5$check = Carbon::parse('2023-09-15');
6
7if ($check->between($start, $end)) {
8    echo "时间在区间内";
9}

between($start, $end, $equal = true)

$equal = true 表示包含边界值

判断时间是否已经过期

1$expire = Carbon::parse('2023-09-30');
2if (Carbon::now()->greaterThan($expire)) {
3    echo "已过期";
4}

3.2 排班和周期任务计算

每周一、三、五触发

1$today = Carbon::now();
2if (in_array($today->dayOfWeek, [1, 3, 5])) {
3    echo "今天需要执行任务";
4}

dayOfWeek 返回 0-6（周日 = 0，周一 = 1 … 周六 = 6）

获取下一个执行日期

1$next = Carbon::now()->next(Carbon::WEDNESDAY); // 下一个周三
2echo $next;

3.3 人性化日期显示

1Carbon::setLocale('zh');
2
3$dt1 = Carbon::parse('2025-09-25');
4$dt2 = Carbon::now();
5
6echo $dt1->diffForHumans($dt2); // "3 天前"

适合前端展示时间差，如评论、日志等

3.4 日期加减与复合操作

1$dt = Carbon::now()
2    ->addDays(3)      // +3天
3    ->subHours(5)     // -5小时
4    ->addMinutes(30); // +30分钟
5
6echo $dt->format('Y-m-d H:i:s');

链式操作可显著提升代码可读性

3.5 与 MySQL 日期时间无缝转换

读取数据库 datetime

1$createdAt = Carbon::parse($user->created_at);

写入数据库 datetime

1$user->expire_at = Carbon::now()->addDays(7)->toDateTimeString();
2$user->save();

toDateTimeString() 输出 Y-m-d H:i:s 格式，直接可存入 MySQL

3.6 时间戳转换与操作

1$timestamp = 1750000000;
2
3// 时间戳转 Carbon
4$dt = Carbon::createFromTimestamp($timestamp);
5
6// Carbon 转时间戳
7echo $dt->timestamp;

3.7 本地化与时区

1// 设置默认时区
2Carbon::setLocale('zh');
3$dt = Carbon::now('Asia/Shanghai');
4
5// 转换到其他时区
6$dtUtc = $dt->copy()->setTimezone('UTC');

3.8 计算时间差

1$start = Carbon::parse('2025-09-01');
2$end = Carbon::parse('2025-09-28');
3
4echo $start->diffInDays($end);       // 相差天数
5echo $start->diffInHours($end);      // 相差小时数
6echo $start->diffInMinutes($end);    // 相差分钟数

diffForHumans() 输出语义化的时间差

3.9 生成时间区间数组（可用于报表）

1$period = Carbon::parse('2025-09-01')->daysUntil('2025-09-07');
2foreach ($period as $date) {
3    echo $date->toDateString() . PHP_EOL;
4}

四、高性能使用建议

统一时区，避免跨时区混乱
避免重复 parse，数据库时间尽量直接使用 Carbon 对象
链式操作，提升可读性
本地化，展示友好日期给用户
结合缓存，复杂报表或大量时间计算可先缓存结果

# Carbon（nesbot/carbon）-- PHP 日期时间利器化