PHP 时间处理器: Carbon 文档 #72
Description
Carbon 文档
本文翻译自 Carbon 类文档，并进行适当演义，以供学习
Carbon 类库继承自 DateTime 类
<?php
namespace Carbon;
class Carbon extends \DateTime
{
// code here
}Carbon 类继承所有 DateTime 类方法。如果你在 Carbon 类中发现有些方法缺失，那么一定在 DateTime类中。
通过上面的代码你会发现 Carbon 类定义在 Carbon 命名空间下，你可以通过使用
use Carbon\Carbon;使用 Carbon 类，而不需要每次实例化都需要使用全限定命名空间。
注意：加入我居住在 Ottawa, Ontario, Canada 但没有该地的时区(timezone)，那么会默认为
America/Toronto，一般 Ottawa 是 -0500 时区，但它的日照时区为 -0400。
在使用 Carbon 时，一定要注意正确使用时区。当然 Carbon 类时区的实现，也是基于 DateTime 类的。比如关于时间比较时，都是基于 DateTime 类的 UTC 或时区(timezone)
<?php
$dtToronto = Carbon::createFromDate(2012, 1, 1, "America/Toronto");
$dtVanouver = Carbon::createFromDate(2012, 1, 1, "America/Vancouver");
echo $dtVanouver->diffInHours($dtToronto);// 3Carbon 也提供了 is 比较。比如我居住地比 Tokyo 差 -13 小时，所以
<?php
Carbon::now("Asia/Tokyo")->isToday()将会返回 false，因为我当前时间是下午 1 点。这个比较是没有意义的
实例化
构造函数实例化
有很多不同方式可以创建 Carbon 实例。
- 通过构造函数，Carbon 构造函数 重写了 DateTime 构造函数。你需要掌握构造函数第一个参数相关说明，可以阅读 PHP 文档中关于 date/time 格式文档
<?php
$carbon = new Carbon(); // equivalent to Carbon::now()
$carbon = new Carbon("first day of January 2008", "America/Vancouver");
echo get_class($carbon);// Carbon/Carbon
$carbon = Carbon::now(-5);你会发现上面实例的时区参数(第二个参数)的实参是一个字符串而不是一个 \DateTimeZone 实例。Carbon 对时区参数进行了重写，我们可以传入
DateTimeZone 实例，时区字符串，或者 GMT 时间的相对时间。
下面的实例将演示 now() 方法的使用
<?php
$now = Carbon::now();
$nowInLondonTz = Carbon::now(new DateTimeZone("Europe/London"));
//也可以这样
$nowInLondonTz = Carbon::now("Europe/London");
// or to create a date with a timezone of +1 to GMT during DST then just pass an integer
echo Carbon::now(1)->tzName; // Europe/London你也可以使用链式操作
<?php
echo (new Carbon("first day of Dencember 2008"))->addWeeks(2);
echo Carbon::parse("first day of Dencember 2008")->addWeeks(2);today, tomorrow, yesterday 静态方法实例化
除了 now() 静态方法，还有很多实用的静态方法。这里需要注意 today() , yesterday() 和 tomorrow() 这三个静态方法，这三个静态方法将时分秒设置为 00:00:00
<?php
$now = Carbon::now();// 2016-06-24 15:18:34
$today = Carbon::today();// 2016-06-24 00:00:00
$tomorrow = Carbon::tomorrow();// 2016-06-25 00:00:00
$yesterday = Carbon::yesterday();// 2016-06-23 00:00:00createXXX 静态方法实例化
多数的的 create 静态方法支持接收多个参数，并且所有参数都有默认值，默认值为当前日期，时间或时区。参数无效或参数值过大将抛出 InvalidArgumentException 异常，错误内容可以通过 Carbon::getLastErrors() 获取。
createFromDate, createFromTime, create
<?php
Carbon::createFromDate($year, $month, $day, $tz);
Carbon::createFromTime($hour, $minute, $second, $tz);
Carbon::create($year, $month, $day, $hour, $minute, $second, $tz);- create 创建当前时间
- createFromDate 创建当前日期
- createFromTime 创建当前时间
$xmasThisYear = Carbon::createFromDate(null, 12, 25); // Year defaults to current year
$Y2K = Carbon::create(2000, 1, 1, 0, 0, 0);
$alsoY2K = Carbon::create(1999, 12, 31, 24);
$noonLondonTz = Carbon::createFromTime(12, 0, 0, 'Europe/London');
// A two digit minute could not be found
try { Carbon::create(1975, 5, 21, 22, -2, 0); } catch(InvalidArgumentException $x) { echo $x->getMessage(); }createFromFormat
Carbon::createFromFormat($form, $time, $tz);createFromFormat 实现了对 DateTime::createFromFormat 方法重写，如果出错同样抛出 InvalidArgumentException 异常。并且所有的 createXXX 方法内都调用了 createFromFormat() 方法
echo Carbon::createFromFormat("Y-m-d H", '2017-09-10 19')->toDateTimeString();// 2017-09-10 19:00:00Unix timestamps 时间静态方法
- createFromTimestampUTC
- Carbon::createFromFormat('@'.$timestamp)
echo Carbon::createFromTimestamp(-1)->toDateTimeString(); // 1969-12-31 18:59:59
echo Carbon::createFromTimestamp(-1, 'Europe/London')->toDateTimeString(); // 1970-01-01 00:59:59
echo Carbon::createFromTimeStampUTC(-1)->toDateTimeString(); // 1969-12-31 23:59:59copy 通过 Carbon 克隆
copy 方法将完美克隆日期，时间和时区
$dt = Carbon::now();
$dt->diffInYears($dt->copy()->addYear());// 1通过 DateTime 实例创建 Carbon 实例
$dt = new DateTime("first day of January 2008");
$carbon = Carbon::instance($dt);
echo get_class($carbon); // 'Carbon\Carbon'
echo $carbon->toDateTimeString();// 2008-01-01 00:00:00微秒 microsecond
$dt = Carbon::parse('1975-05-21 22:23:00.123456');
echo $dt->micro; // 123456
echo $dt->copy()->micro; // 123456支持的最大和做小时间
echo Carbon::maxValue(); // '2038-01-18 22:14:07'
echo Carbon::minValue(); // '1901-12-13 15:45:52'本地化
PHP DateTime 类默认不支持本地化。Carbon 类通过方法 formatLocalized($format) 实现对本地化的支持，该方法原理是以当前时间戳作为参数调用 strftime 函数。如果使用 setlocale() 函数设置地区，那么本地化的时间为设置地区的时间。
setlocale(LC_TIME, 'German');
echo $dt->formatLocalized('%A %d %B %Y'); // Mittwoch 21 Mai 1975
setlocale(LC_TIME, '');
echo $dt->formatLocalized('%A %d %B %Y'); // Wednesday 21 May 1975[diffForHumans()] 方法同样实现了本地化支持，可以通过 Carbon 了的 setLocale() 静态方法实现本地支持。
Carbon::setLocale("zh");
echo Carbon::now()->addYear()->diffForHumans();Linux 本地化支持
如果在 Linux 使用 Carbon 本地化有任何问题，请检测是否安装了 local 程序
local -a 获取所有可用本地化支持列表
sudo local-gen fr_FR.UTF-8 安装新的语言支持
sudo dpkg-reconfigure locales 将所有语言支持重新发布
然后重启 Linux
测试实例
测试方法将返回一个 now() 方法实例。当满足下列情况是，将返回这个测试实例
- 方法内调用了 now() 方法的，如 Carbon::now()
- 当构造器或 parse() 方法传 null 或空字符时，如 parse(),new Carbon(null)
- 当构造器或 parse() 方法传 'now' 字符时，如 parse("now"),new Carbon()
$knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
Carbon::setTestNow($knownDate); // set the mock (of course this could be a real mock object)
echo Carbon::now(); // 2001-05-21 12:00:00
echo new Carbon(); // 2001-05-21 12:00:00
echo Carbon::parse(); // 2001-05-21 12:00:00
echo new Carbon('now'); // 2001-05-21 12:00:00
echo Carbon::parse('now'); // 2001-05-21 12:00:00
var_dump(Carbon::hasTestNow()); // bool(true)
Carbon::setTestNow(); // clear the mock
var_dump(Carbon::hasTestNow()); // bool(false)
echo Carbon::now(); // 2016-06-24 15:18:34一个比较有意义的实例
class SeasonalProduct
{
protected $price;
public function __construct($price)
{
$this->price = $price;
}
public function getPrice() {
$multiplier = 1;
if (Carbon::now()->month == 12) {
$multiplier = 2;
}
return $this->price * $multiplier;
}
}
$product = new SeasonalProduct(100);
Carbon::setTestNow(Carbon::parse('first day of March 2000'));
echo $product->getPrice(); // 100
Carbon::setTestNow(Carbon::parse('first day of December 2000'));
echo $product->getPrice(); // 200
Carbon::setTestNow(Carbon::parse('first day of May 2000'));
echo $product->getPrice(); // 100
Carbon::setTestNow();测试实例的相对时间支持
$knownDate = Carbon::create(2001, 5, 21, 12); // create testing date
Carbon::setTestNow($knownDate); // set the mock
echo new Carbon('tomorrow'); // 2001-05-22 00:00:00 ... notice the time !
echo new Carbon('yesterday'); // 2001-05-20 00:00:00
echo new Carbon('next wednesday'); // 2001-05-23 00:00:00
echo new Carbon('last friday'); // 2001-05-18 00:00:00
echo new Carbon('this thursday'); // 2001-05-24 00:00:00
Carbon::setTestNow(); // always clear it !相对修饰符列表：
- this
- next
- last
- tomorrow
- yesterday
-
-
- first
- last
- ago
重点需要关注 nexe(), previous(), modify() 方法，这些方法会将时间设置为 00:00:00
Getters 访问器
Carbon 访问器实现了 __set() 方法，你可以直接访问 Carbon 内的属性。
$dt = Carbon::parse('2012-9-5 23:26:11.123789');
// These getters specifically return integers, ie intval()
var_dump($dt->year); // int(2012)
var_dump($dt->month); // int(9)
var_dump($dt->day); // int(5)
var_dump($dt->hour); // int(23)
var_dump($dt->minute); // int(26)
var_dump($dt->second); // int(11)
var_dump($dt->micro); // int(123789)
var_dump($dt->dayOfWeek); // int(3)
var_dump($dt->dayOfYear); // int(248)
var_dump($dt->weekOfMonth); // int(1)
var_dump($dt->weekOfYear); // int(36)
var_dump($dt->daysInMonth); // int(30)
var_dump($dt->timestamp); // int(1346901971)
var_dump(Carbon::createFromDate(1975, 5, 21)->age); // int(41) calculated vs now in the same tz
var_dump($dt->quarter); // int(3)
// Returns an int of seconds difference from UTC (+/- sign included)
var_dump(Carbon::createFromTimestampUTC(0)->offset); // int(0)
var_dump(Carbon::createFromTimestamp(0)->offset); // int(-18000)
// Returns an int of hours difference from UTC (+/- sign included)
var_dump(Carbon::createFromTimestamp(0)->offsetHours); // int(-5)
// Indicates if day light savings time is on
var_dump(Carbon::createFromDate(2012, 1, 1)->dst); // bool(false)
var_dump(Carbon::createFromDate(2012, 9, 1)->dst); // bool(true)
// Indicates if the instance is in the same timezone as the local timezone
var_dump(Carbon::now()->local); // bool(true)
var_dump(Carbon::now('America/Vancouver')->local); // bool(false)
// Indicates if the instance is in the UTC timezone
var_dump(Carbon::now()->utc); // bool(false)
var_dump(Carbon::now('Europe/London')->utc); // bool(false)
var_dump(Carbon::createFromTimestampUTC(0)->utc); // bool(true)
// Gets the DateTimeZone instance
echo get_class(Carbon::now()->timezone); // DateTimeZone
echo get_class(Carbon::now()->tz); // DateTimeZone
// Gets the DateTimeZone instance name, shortcut for ->timezone->getName()
echo Carbon::now()->timezoneName; // America/Toronto
echo Carbon::now()->tzName; // America/TorontoSetters
Carbon 的 setter 实现了 PHP 的 __set() 方法。
$dt = Carbon::now();
$dt->year = 1975;
$dt->month = 13; // would force year++ and month = 1
$dt->month = 5;
$dt->day = 21;
$dt->hour = 22;
$dt->minute = 32;
$dt->second = 5;
$dt->timestamp = 169957925; // This will not change the timezone
// Set the timezone via DateTimeZone instance or string
$dt->timezone = new DateTimeZone('Europe/London');
$dt->timezone = 'Europe/London';
$dt->tz = 'Europe/London';Fluent Setters 链式操作
No arguments are optional for the setters, but there are enough variety in the function definitions that you shouldn't need them anyway. Its good to take note here that none of the setters, with the obvious exception of explicitly setting the timezone, will change the timezone of the instance. Specifically, setting the timestamp will not set the corresponding timezone to UTC.
$dt = Carbon::now();
$dt->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->toDateTimeString();
$dt->setDate(1975, 5, 21)->setTime(22, 32, 5)->toDateTimeString();
$dt->setDateTime(1975, 5, 21, 22, 32, 5)->toDateTimeString();
$dt->timestamp(169957925)->timezone('Europe/London');
$dt->tz('America/Toronto')->setTimezone('America/Vancouver');isSet
Carbon 实现了 __isset() 方法。在当调用 isset() 或 empty() 方法校验属性是否存在是会调用 __isset() 方法。了解 PHP : __isset(),isset(),empty()
var_dump(isset(Carbon::now()->iDoNotExist)); // bool(false)
var_dump(isset(Carbon::now()->hour)); // bool(true)
var_dump(empty(Carbon::now()->iDoNotExist)); // bool(true)
var_dump(empty(Carbon::now()->year)); // bool(false)日期格式化(String Formatting)
Carbon 内置的 toXXXString() 方法族，基于 DateTime::format() 方法。如果你阅读 Carbon 源码会发现 Carbon::__toString() 方法会将 Carbon 实例以指定日期格式格式化输出。
$dt = Carbon::create(1975, 12, 25, 14, 15, 16);
var_dump($dt->toDateTimeString() == $dt); //bool(true) => use __toString()
echo $dt->toDateString(); // 1975-12-25
echo $dt->toFormattedDateString();// Dec 25, 1975
echo $dt->toTimeString();// 14:15:16
echo $dt->toDateTimeString();// 1975-12-25 14:15:16
echo $dt->toDayDateTimeString();// Thu, Dec 25, 1975 2:15 PM
//format() 方法同样可以使用
echo $dt->format('l jS \\of F Y h:i:s A');// Thursday 25th of December 1975 02:15:16 PM此外，你也可以设置 __toString() 方法内使用的格式化类型(默认格式化类型是: Y-m-d H:i:s)，这是通过类型转换的判别实现的
$dt->setToStringFormat("'jS \o\f F, Y g:i:s a'");
echo $dt;// 25th of December, 1975 2:15:16 pm
//重置日期格式
$dt->resetToStringFromat();
echo $dt;// 1975-12-25 14:15:16本地化支持，请查看本地化章节
常用日期格式化(Common Formats)
下面的格式化方法，是对 DateTime 类的封装
$dt = Carbon::now();
//$dt->toAtomString 等同于 $dt->format(DateTime::ATOM)
echo $dt->toAtomString(); // 1975-12-25T14:15:16-05:00
echo $dt->toCookieString(); // Thursday, 25-Dec-1975 14:15:16 EST
echo $dt->toIso8601String(); // 1975-12-25T14:15:16-0500
echo $dt->toRfc822String(); // Thu, 25 Dec 75 14:15:16 -0500
echo $dt->toRfc850String(); // Thursday, 25-Dec-75 14:15:16 EST
echo $dt->toRfc1036String(); // Thu, 25 Dec 75 14:15:16 -0500
echo $dt->toRfc1123String(); // Thu, 25 Dec 1975 14:15:16 -0500
echo $dt->toRfc2822String(); // Thu, 25 Dec 1975 14:15:16 -0500
echo $dt->toRfc3339String(); // 1975-12-25T14:15:16-05:00
echo $dt->toRssString(); // Thu, 25 Dec 1975 14:15:16 -0500
echo $dt->toW3cString(); // 1975-12-25T14:15:16-05:00日期比较
Carbon 提供了基本的日期比较方法，请牢记日期比较基于 UTC 时区。
<?php
require "../src/Carbon/Carbon.php";
use Carbon\Carbon;
function d($d)
{
echo PHP_EOL;
var_dump($d);
echo PHP_EOL;
}
// $dt = Carbon::now("Asia/Shanghai");
// echo $dt->tzName;
$first = Carbon::create(2017, 9, 18, 10, 45, 01, 'Asia/Shanghai');
$second = Carbon::create(2017, 9, 15, 10, 45, 01, 'America/Vancouver');
d($first->toDateTimeString());
d($first->tzName);
d($second->toDateTimeString());
d($second->tzName);
d($first->eq($second));
d($first->ne($second));
d($first->gt($second));
d($first->gte($second));
d($first->lt($second));
d($first->lte($second));
$first->setDateTime(2012, 1, 1, 0, 0, 0);
$second->setDateTime(2012, 1, 1, 0, 0, 0); // Remember tz is 'America/Vancouver'
d("--------------------");
d($first->eq($second));
d($first->ne($second));
d($first->gt($second));
d($first->gte($second));
d($first->lt($second));
d($first->lte($second));如果需要判断一个日期实例的时间是否在另外两个日期实例之间，可以使用 between() 方法。第三个参数用于闭区间比较，默认是闭区间比较。
$first = Carbon::create(2012, 9, 5, 1);
$second = Carbon::create(2012, 9, 5, 5)
var_dump(Carbon::create(2012, 9, 5, 3)->between($first, $second)); // bool(true)
var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second)); // bool(true)
var_dump(Carbon::create(2012, 9, 5, 5)->between($first, $second, false)); // bool(false)不要忘记 min() 和 max() 方法,如果不传入参数，将默认设置为当前时间
$dt1 = Carbon::create(2012, 1, 1, 0, 0, 0);
$dt2 = Carbon::create(2012, 1, 30, 0, 0, 0);
echo $dt1->min($dt2); // 2012-01-01 00:00:00
$dt1 = Carbon::create(2012, 1, 1, 0, 0, 0);
$dt2 = Carbon::create(2014, 1, 30, 0, 0, 0);
echo $dt1->min($dt2); // 2014-01-30 00:00:00
// now is the default param
$dt1 = Carbon::create(2000, 1, 1, 0, 0, 0);
echo $dt1->max(); // 2016-06-24 15:18:34此外，还提供了一些常用的日期处理方法，你可以通过方法名见文知义。并且，这些方法都是同 now() 实例进行比较运算的
<?php
require "../src/Carbon/Carbon.php";
use Carbon\Carbon;
function d($d)
{
echo PHP_EOL;
var_dump($d);
echo PHP_EOL;
}
$dt = Carbon::now("Asia/Shanghai");
d($dt->isWeekday());
d($dt->isWeekend());
d($dt->isYesterday());
d($dt->isToday());
d($dt->isTomorrow());
d($dt->isFuture());
d($dt->isPast());
d($dt->isLeapYear());
d($dt->isSameDay(Carbon::now()));
$born = Carbon::createFromDate(1987, 4, 23);
$noCake = Carbon::createFromDate(2014, 9, 26);
$yesCake = Carbon::createFromDate(2014, 4, 23);
$overTheHill = Carbon::now()->subYears(50);
d($born->isBirthday($noCake)); // bool(false)
d($born->isBirthday($yesCake)); // bool(true)
d($overTheHill->isBirthday()); // bool(true) -> default compare it to today!日期运算(Addition and Subtraction)
DateTime 类提供了两种不同的方式对日期进行运算，即modify()，add() 和 sub()。modify() 方法通过待魔术关键词的日期字符串如 last day of next month，该方法原理是调用了使用了 DateInterval 实例 new \DateInterval('P6YT5M') 的 add() 或 sub() 方法。通过链式操作可以实现日期运算，不过有更好的方法
$dt = Carbon::now();
echo $dt->toDateTimeString();// 2012-01-31 00:00:00
echo $dt->addYears(5);
echo $dt->addYear();
echo $dt->subYears(5);
echo $dt->subYear();
echo $dt->addMonths(60);
echo $dt->addMonth();
echo $dt->subMonths(60);
echo $dt->subMonth();
echo $dt->addDays(20);
echo $dt->addDay();
echo $dt->subDays(20);
echo $dt->subDay();
echo $dt->addWeekdays(4);
echo $dt->addWeekday();
echo $dt->subWeekdays(4);
echo $dt->subWeekday();
echo $dt->addWeeks(3);
echo $dt->addWeek();
echo $dt->subWeeks(3);
echo $dt->subWeek();
echo $dt->addHours(24);
echo $dt->addHour();
echo $dt->subHours(24);
echo $dt->subHour();
echo $dt->addMinutes(61);
echo $dt->addMinute();
echo $dt->subMinutes(61);
echo $dt->subMinute();
echo $dt->addSeconds(61);
echo $dt->addSecond();
echo $dt->subSeconds(61);
echo $dt->subSecond();For fun you can also pass negative values to addXXX(), in fact that's how subXXX() is implemented.
差值(Difference)
差值运算，将计算两个 Carbon 实例的时间差。不同于基类的 diff() 方法，基类两时间相差 61 秒，差值返回为 1 分钟和 1 秒。diffInMinutes() 仅返回 1，返回值是直接舍去，而不是四舍五入返回。
所有的 diffXXX() 方法默认的第一个参数为 null，null 值将默认与 now() 求差值；或者传入一个 Carbon 实例。第二个参数为可选参数，表示是求取差值绝对值或相对值；求相对值时如果传入的 Carbon 实例小于当前实例，则返回负值。参数默认为 true，时间比较基于 UTC。
// echo Carbon::diffInYears(Carbon $dt = null, $abs = true)
echo Carbon::now("America/Vancouver")->diffInSeconds(Carbon::now("Europe/London"));
$dtOttawa = Carbon::createFromDate(2000, 1, 1, "America/Toronto");
$dtVancouver = Carbon::createFromDate(2000, 1, 1, "America/Vancouver");
echo $dtOttawa->diffInHours($dtVancouver);
echo $dtOttawa->diffInHours($dtVancouver, false);// 3
echo $dtVancouver->diffInHours($dtOttawa, false);// -3
$dt = Carbon::create(2012, 1, 31, 0);
echo $dt->diffInDays($dt->copy()->addMonth());// 31
echo $dt->diffInDays)$dt->copy()->subMonth(), false);// -31
$dt = Carbon::create(2012, 4, 30, 0);
echo $dt->diffInDays($dt->copy()->addMonth()); // 30
echo $dt->diffInDays($dt->copy()->addWeek()); // 7
$dt = Carbon::create(2012, 1, 1, 0);
echo $dt->diffInMinutes($dt->copy()->addSeconds(59)); // 0
echo $dt->diffInMinutes($dt->copy()->addSeconds(60)); // 1
echo $dt->diffInMinutes($dt->copy()->addSeconds(119)); // 1
echo $dt->diffInMinutes($dt->copy()->addSeconds(120)); // 2
echo $dt->addSeconds(120)->secondsSinceMidnight(); // 120此外还有提供一些过滤器(filter)方法，像 diffInDaysFiltered(), diffInHoursFiltered() 和 diffFiltered()，to help you filter the difference by days, hours or a custom interval. For example to count the weekend days between two instances
$dt = Carbon::create(2014, 1, 1);
$dt2 = Carbon::create(2014, 12, 31);
$daysForExtraCoding = $dt->diffInDaysFiltered(function(Carbon $date) {
return $date->isWeekend();
}, $dt2);
echo $daysForExtraCoding; // 104
$dt = Carbon::create(2014, 1, 1)->startOfDay();
$dt2 = $dt->copy()->endOfDay();
$littleHandRotations = $dt->diffFiltered(CarbonInterval::minute(), function(Carbon $date) {
return $date->minute === 0;
}, $dt2);
echo $littleHandRotations; // 24
// others that are defined
// diffInYears(), diffInMonths(), diffInWeeks()
// diffInDays(), diffInWeekdays(), diffInWeekendDays()
// diffInHours(), diffInMinutes(), diffInSeconds()
// secondsSinceMidnight(), secondsUntilEndOfDay()友好的日期差值(Difference for Humans)
显而易见 1 month ago 要比 30 days ago 更容易让人理解。这类的友好的时间显示在很多时间组件库都得以实现。diffForHumans() 方法的第一个参数为另一个 Carbon 实例，不传默认为 now()。
方法返回值将会在差值后加入一个时间描述。有四种类型的描述：
- 当比较的时间相比与 now() 发生在过去:
- 1 hour ago
- 5 months ago
- 当比较的时间相比与 now() 发生在未来：
- 1 hour from now
- 5 months from now
- 当比较时间比另一个时间要早:
- 1 hour before
- 5 months before
- 当比较的时间比另一个时间晚:
- 1 hour after
- 5 months after
第二个参数为是否移除 ago, from now, after 等之类的短语标识
// The most typical usage is for comments
// The instance is the date the comment was created and its being compared to default now()
echo Carbon::now()->subDays(5)->diffForHumans(); // 5 days ago
echo Carbon::now()->diffForHumans(Carbon::now()->subYear()); // 1 year after
$dt = Carbon::createFromDate(2011, 8, 1);
echo $dt->diffForHumans($dt->copy()->addMonth()); // 1 month before
echo $dt->diffForHumans($dt->copy()->subMonth()); // 1 month after
echo Carbon::now()->addSeconds(5)->diffForHumans(); // 5 seconds from now
echo Carbon::now()->subDays(24)->diffForHumans(); // 3 weeks ago
echo Carbon::now()->subDays(24)->diffForHumans(null, true); // 3 weeks该方法同样支持本地化，在调用 diffForHumans() 方法前设置 Carbon::setLocale("fr") 即可，更多查看本地化章节
修改器(Modifiers)
修改器大多数都是见文知义的，它们是 startOfXXX(), endOfXXX(), next(), previous(),其中 endOfXXX() 将时间设置到 23:59:59, 其它的则将时间设置到 00:00:00。
只有一个例外 average() 方法。It moves your instance to the middle date between itself and the provided Carbon argument.
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfDay(); // 2012-01-31 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfDay(); // 2012-01-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfMonth(); // 2012-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfMonth(); // 2012-01-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfYear(); // 2012-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfYear(); // 2012-12-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfDecade(); // 2010-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfDecade(); // 2019-12-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfCentury(); // 2000-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfCentury(); // 2099-12-31 23:59:59
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfWeek(); // 2012-01-30 00:00:00
var_dump($dt->dayOfWeek == Carbon::MONDAY); // bool(true) : ISO8601 week starts on Monday
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfWeek(); // 2012-02-05 23:59:59
var_dump($dt->dayOfWeek == Carbon::SUNDAY); // bool(true) : ISO8601 week ends on Sunday
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->next(Carbon::WEDNESDAY); // 2012-02-01 00:00:00
var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
$dt = Carbon::create(2012, 1, 1, 12, 0, 0);
echo $dt->next(); // 2012-01-08 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->previous(Carbon::WEDNESDAY); // 2012-01-25 00:00:00
var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
$dt = Carbon::create(2012, 1, 1, 12, 0, 0);
echo $dt->previous(); // 2011-12-25 00:00:00
$start = Carbon::create(2014, 1, 1, 0, 0, 0);
$end = Carbon::create(2014, 1, 30, 0, 0, 0);
echo $start->average($end); // 2014-01-15 12:00:00
// others that are defined that are similar
// firstOfMonth(), lastOfMonth(), nthOfMonth()
// firstOfQuarter(), lastOfQuarter(), nthOfQuarter()
// firstOfYear(), lastOfYear(), nthOfYear()常量(Constants)
The following constants are defined in the Carbon class.
// These getters specifically return integers, ie intval()
var_dump(Carbon::SUNDAY); // int(0)
var_dump(Carbon::MONDAY); // int(1)
var_dump(Carbon::TUESDAY); // int(2)
var_dump(Carbon::WEDNESDAY); // int(3)
var_dump(Carbon::THURSDAY); // int(4)
var_dump(Carbon::FRIDAY); // int(5)
var_dump(Carbon::SATURDAY); // int(6)
var_dump(Carbon::YEARS_PER_CENTURY); // int(100)
var_dump(Carbon::YEARS_PER_DECADE); // int(10)
var_dump(Carbon::MONTHS_PER_YEAR); // int(12)
var_dump(Carbon::WEEKS_PER_YEAR); // int(52)
var_dump(Carbon::DAYS_PER_WEEK); // int(7)
var_dump(Carbon::HOURS_PER_DAY); // int(24)
var_dump(Carbon::MINUTES_PER_HOUR); // int(60)
var_dump(Carbon::SECONDS_PER_MINUTE); // int(60)$dt = Carbon::createFromDate(2012, 10, 6);
if ($dt->dayOfWeek === Carbon::SATURDAY) {
echo 'Place bets on Ottawa Senators Winning!';
}CarbonInterval 类
The Carbon class is inherited from the PHP DateInterval class.
<?php
class CarbonInterval extends \DateInterval
{
// code here
}可以通过下列方法创建类实例
echo CarbonInterval::year(); // 1 year
echo CarbonInterval::months(3); // 3 months
echo CarbonInterval::days(3)->seconds(32); // 3 days 32 seconds
echo CarbonInterval::weeks(3); // 3 weeks
echo CarbonInterval::days(23); // 3 weeks 2 days
echo CarbonInterval::create(2, 0, 5, 1, 1, 2, 7); // 2 years 5 weeks 1 day 1 hour 2 minutes 7 secondsIf you find yourself inheriting a \DateInterval instance from another library, fear not! You can create a CarbonInterval instance via a friendly instance() function.
$di = new \DateInterval('P1Y2M'); // <== instance from another API
$ci = CarbonInterval::instance($di);
echo get_class($ci); // 'Carbon\CarbonInterval'
echo $ci; // 1 year 2 monthsOther helpers, but beware the implemenation provides helpers to handle weeks but only days are saved. Weeks are calculated based on the total days of the current instance.
echo CarbonInterval::year()->years; // 1
echo CarbonInterval::year()->dayz; // 0
echo CarbonInterval::days(24)->dayz; // 24
echo CarbonInterval::days(24)->daysExcludeWeeks; // 3
echo CarbonInterval::weeks(3)->days(14)->weeks; // 2 <-- days setter overwrites the current value
echo CarbonInterval::weeks(3)->weeks; // 3
echo CarbonInterval::minutes(3)->weeksAndDays(2, 5); // 2 weeks 5 days 3 minutesIt also has a handy forHumans(), which is mapped as the __toString() implementation, that prints the interval for humans.
CarbonInterval::setLocale('fr');
echo CarbonInterval::create(2, 1)->forHumans(); // 2 ans 1 mois
echo CarbonInterval::hour()->seconds(3); // 1 heure 3 secondes
CarbonInterval::setLocale('en');As you can see, you can change the locale of the string using CarbonInterval::setLocale('fr').