nesbot/carbon 常用功能总结

Carbon 是 PHP DateTime 类的增强版，极大简化了日期时间的操作，提升了开发效率。以下为常用操作和功能整理，方便日常参考。

---

1. 安装（Composer）

composer require nesbot/carbon

---

2. 实例化方式

use Carbon\Carbon;

// 当前时间（默认服务器时区）
$now = Carbon::now();
// 当前日期（时间部分为 00:00:00）
$today = Carbon::today();
// 当前时间戳对应的 Carbon 对象
$timestamp = Carbon::createFromTimestamp(time());
// 自定义日期时间
$customDate = Carbon::create(2026, 1, 27, 10, 30, 0);
// 从字符串解析（支持多种格式）
$fromString = Carbon::parse('2026-01-27 10:30:00');

---

3. 日期时间格式化

Carbon 兼容 DateTime 的格式化规则，同时提供了更便捷的方法：

// 标准格式化
echo Carbon::now()->format('Y-m-d H:i:s'); // 2026-01-27 15:30:00

// 快捷格式化方法
echo Carbon::now()->toDateString();      // 2026-01-27
echo Carbon::now()->toTimeString();      // 15:30:00
echo Carbon::now()->toDateTimeString();  // 2026-01-27 15:30:00
echo Carbon::now()->toISOString();       // 2026-01-27T15:30:00+08:00

// 人性化格式（多语言支持）
echo Carbon::now()->subDays(2)->diffForHumans();   // 2 天前
echo Carbon::now()->addHours(3)->diffForHumans();  // 3 小时后

---

4. 日期时间计算（增减 / 修改）

$date = Carbon::now();

// 增减时间（支持年/月/日/时/分/秒/周）
$date->addDay();       // 加1天
$date->subDays(3);     // 减3天
$date->addMonth();     // 加1月
$date->subMonths(2);   // 减2月
$date->addYear();      // 加1年
$date->addHours(5);    // 加5小时

// 直接修改字段
$date->year = 2025;
$date->month = 12;
$date->day = 31;

// 取整/边界时间
echo Carbon::now()->startOfDay();    // 今天 00:00:00
echo Carbon::now()->endOfDay();      // 今天 23:59:59
echo Carbon::now()->startOfMonth();  // 当月1号 00:00:00
echo Carbon::now()->endOfMonth();    // 当月最后一天 23:59:59
echo Carbon::now()->startOfWeek();   // 本周一 00:00:00（默认周日为一周开始，可配置）

---

5. 日期时间比较

$date1 = Carbon::create(2026, 1, 27);
$date2 = Carbon::create(2026, 2, 1);

// 基础比较
var_dump($date1->isBefore($date2));      // true
var_dump($date1->isAfter($date2));       // false
var_dump($date1->isSameDay($date2));     // false
var_dump(Carbon::now()->isToday());      // 是否今天
var_dump(Carbon::now()->isYesterday());  // 是否昨天
var_dump(Carbon::now()->isTomorrow());   // 是否明天

// 范围判断
$start = Carbon::create(2026, 1, 1);
$end = Carbon::create(2026, 12, 31);
var_dump($date1->isBetween($start, $end)); // true

// 差值计算
$diffDays = $date2->diffInDays($date1);   // 5（date2 比 date1 多5天）
$diffHours = $date2->diffInHours($date1); // 120
$diffYears = $date2->diffInYears($date1); // 0

---

6. 时区处理

// 实例化时指定时区
$date = Carbon::now('Asia/Shanghai');
// 修改时区（不改变时间值）
$date->setTimezone('UTC');
// 获取时区信息
echo $date->getTimezone()->getName(); // UTC

// 转换时区并同步时间
$date = Carbon::parse('2026-01-27 10:00:00', 'Asia/Shanghai');
$date->tz('UTC'); // 转换为 UTC 时间 2026-01-27 02:00:00

---

7. 本地化（多语言）

use Carbon\Carbon;
use Carbon\Translator;
use Symfony\Component\Translation\Loader\MoFileLoader;

// 配置中文翻译
$translator = new Translator('zh_CN');
$translator->addLoader('mo', new MoFileLoader());
// 加载 Carbon 自带的中文语言包（需确保语言包路径正确）
$translator->addResource('mo', __DIR__ . '/vendor/nesbot/carbon/src/Carbon/Lang/zh_CN.mo', 'zh_CN');
Carbon::setTranslator($translator);
Carbon::setLocale('zh_CN');

// 人性化显示变为中文
echo Carbon::now()->subDays(2)->diffForHumans();   // 2天前
echo Carbon::now()->addHours(3)->diffForHumans();  // 3小时后

---

8. 其他实用功能

8.1 节假日 / 工作日判断（需扩展）

// 需安装扩展：composer require kylekatarnls/business-day
use Carbon\Carbon;
use Carbon\BusinessDay;

Carbon::mixin(new BusinessDay());
// 判断是否为工作日（默认周六日为非工作日）
var_dump(Carbon::now()->isBusinessDay());
// 下一个工作日
echo Carbon::now()->nextBusinessDay();

8.2 日期验证

// 检查日期是否有效
var_dump(Carbon::createFromFormat('Y-m-d', '2026-02-30')->isValid()); // false

8.3 生成时间范围

// 生成指定区间的日期数组（按天）
$dates = Carbon::parse('2026-01-01')->toPeriod('2026-01-05')->days();
foreach ($dates as $date) {
    echo $date->toDateString() . PHP_EOL;
}

---

总结

• 核心定位：Carbon 是 PHP DateTime 类的增强版，简化了日期时间的初始化、格式化、计算、比较等操作。
• 高频功能：日期增减（add/sub）、人性化显示（diffForHumans）、时区转换、边界时间（startOf/endOf）是日常开发中最常用的功能。
• 扩展能力：支持本地化、节假日判断、时间范围生成等扩展场景，满足复杂业务需求。
  通过以上整理，你可以快速掌握 Carbon 的核心用法，覆盖日常开发中 90% 以上的日期时间处理场景。

---