PHP中时间处理类Carbon的用法详解

第PHP中时间处理类Carbon的用法详解目录1.Introduction2.Instantiation3.Localization4.TestingAids()5.Getters6.Setters7.FluentSetters8.IsSet

1.Introduction

Carbon是php的日期处理类库（AsimplePHPAPIextensionforDateTime.）。

Carbon继承了PHP的Datetime类，所以Carbon中没有涉及到的，但在Datetime中已经实现的方法都是可以使用的。

看代码

php

namespaceCarbon;

classCarbonextends\DateTime

//codehere

}

Carbon类声明在Carbon命名空间下，可以通过引入命名空间的方式来代替每次输入完整的类名。

php

useCarbon\Carbon;

Note:如果在使用Carbon时，没有专门设置时区的话，默认使用America/Toronto的时区。

要特别留意是否使用了正确的时区，比如Carbon的所有差异比较都使用UTC或者系统设定的时区。

php

$dtToronto=Carbon::createFromDate(2012,1,1,'America/Toronto');

$dtVancouver=Carbon::createFromDate(2012,1,1,'America/Vancouver');

echo$dtVancouver-diffInHours($dtToronto);//3

以上进行的时间比较是在提供的Carbon实例所在的时区下完成的。例如作者所在的时区为东京时间减13小时，因此在下午一点后。Carbon::now(Asia/Tokyo)-isToday()将会返回false，如果在调用now()时设置时区为东京时区，接下来的操作都使用东京时区是说不过去的。所以在与now()创建的实例进行比较时，默认是在当前时区下完成的。

2.Instantiation

有好几种方式可以创建Carbon的实例，但是大家应该更倾向于通过这种语义化的静态方法来实现。

php

$carbon=newCarbon();//equivalenttoCarbon::now()

$carbon=newCarbon('firstdayofJanuary2008','America/Vancouver');

echoget_class($carbon);//'Carbon\Carbon'

$carbon=Carbon::now(-5);

值得注意的是，Carbon构造器的第二个参数被增强到了不仅限于\DateTimeZone实例，还可以是String、Integer(表示相对于GMT的偏移值)。举个例子来说明下now()方法。

php

$now=Carbon::now();

$nowInLondonTz=Carbon::now(newDateTimeZone('Europe/London'));

//orjustpassthetimezoneasastring

$nowInLondonTz=Carbon::now('Europe/London');

//ortocreateadatewithatimezoneof+1toGMTduringDSTthenjustpassaninteger

echoCarbon::now(1)-tzName;//Europe/London

你将会喜欢上用parse()方法来代替原有繁琐的构造方式

php

echo(newCarbon('firstdayofDecember2008'))-addWeeks(2);//2008-12-1500:00:00

echoCarbon::parse('firstdayofDecember2008')-addWeeks(2);//2008-12-1500:00:00

类似now()这样直接返回Carbon实例的方法还有today(),tomorrow(),yesterday()，他们都接受一个timezone类型的参数，最后得到的结果时间部分都是00:00:00

php

$now=Carbon::now();

echo$now;//2016-06-2415:18:34

$today=Carbon::today();

echo$today;//2016-06-2400:00:00

$tomorrow=Carbon::tomorrow('Europe/London');

echo$tomorrow;//2016-06-2500:00:00

$yesterday=Carbon::yesterday();

echo$yesterday;//2016-06-2300:00:00

下面是一些其他的creatXXX()形式的静态方法。绝大多数静态方法的参数是可传可不传的，如果不传的话会使用方法预设的默认值，这些预设值一般都是针对当前日期、时间、时区的。如果为传递某个必要参数，会抛出一个InvalidArgumentException类型的异常，用DateTime::getLastErrors()方法可以得到异常的详细信息。

php

Carbon::createFromDate($year,$month,$day,$tz);

Carbon::createFromTime($hour,$minute,$second,$tz);

Carbon::create($year,$month,$day,$hour,$minute,$second,$tz);

createFromDate()默认返回当前时间，createFromTime()日期默认是今天。crete()所有为null的参数都将默认为当前对应的时间。同样，时区也默认是当前时区。如果只设置了小时数没有设置分秒那么分秒默认是0

php

$xmasThisYear=Carbon::createFromDate(null,12,25);//Yeardefaultstocurrentyear

$Y2K=Carbon::create(2000,1,1,0,0,0);

$alsoY2K=Carbon::create(1999,12,31,24);

$noonLondonTz=Carbon::createFromTime(12,0,0,'Europe/London');

//Atwodigitminutecouldnotbefound

try{

Carbon::create(1975,5,21,22,-2,0);

}catch(InvalidArgumentException$x){

echo$x-getMessage();

}

php

Carbon::createFromFormat($format,$time,$tz);

createFromFormat()与php的DateTime::createFromFormat。不同之处是$dt参数可以是DateTImeZone的实例或者一个时区的字符串。并且可以会返回参数异常的提示。从createXX()的源码可以看出，他们都调用了createFromFormat()方法。

php

echoCarbon::createFromFormat('Y-m-dH','1975-05-2122')-toDateTimeString();//1975-05-2122:00:00

最后提到的这两个create方法都是处理Unix时间戳的。第一个将会返回一个等于预期时间戳的Carbon实例，时区可以设置也可以选用默认值。第二个方法，createFromTimestampUTC()与第一个不同的是时区将始终是UTC(GMT).第一个方法的第二个示例，只是为了让这个函数的用法展现的更加明确。Negativetimestampsarealsoallowed.

php

echoCarbon::createFromTimestamp(-1)-toDateTimeString();//1969-12-3118:59:59

echoCarbon::createFromTimestamp(-1,'Europe/London')-toDateTimeString();//1970-01-0100:59:59

echoCarbon::createFromTimeStampUTC(-1)-toDateTimeString();//1969-12-3123:59:59

copy()方法可以copy一个已经存在的Carbon实例。对copy生成实例进行修改并不会影响被copy对象的本身。

php

$dt=Carbon::now();

echo$dt-diffInYears($dt-copy()-addYear());//1

//$dtwasunchangedandstillholdsthevalueofCarbon:now()

最后，当你正在使用的DateTime实例是通过实例化其他继承了\DateTime库而得到的，别怕！通过下边的方式仍然可以极其友好创建Carbon实例。

php

$dt=new\DateTime('firstdayofJanuary2008');//==instancefromanotherAPI

$carbon=Carbon::instance($dt);

echoget_class($carbon);//'Carbon\Carbon'

echo$carbon-toDateTimeString();//2008-01-0100:00:00

关于毫秒的一些处理。php自带的DateTime类也可以设置毫秒，但是在进行日期的数学预算时并不会考虑毫秒。从Carbon1.12.0版本起，实例化、copy也能像format()方法一样支持毫秒（PHP默认的只有Datetime::format()支持毫秒）。

php

$dt=Carbon::parse('1975-05-2122:23:00.123456');

echo$dt-micro;//123456

echo$dt-copy()-micro;//123456

获取PHP支持的有效时间取值范围：最早时间、最晚时间

php

echoCarbon::maxValue();//'2038-01-1822:14:07'

echoCarbon::minValue();//'1901-12-1315:45:52'

3.Localization

Carbon中，formatLocalized()方法通过调用strftime()方法，弥补了php底层的DateTime类不支持区域化设置的缺陷。如果你已经通过使用setlocale()方法设置过当前区域，formatLocalized($format)方法将会按照设置的区域格式进行返回。

php

setlocale(LC_TIME,'German');

echo$dt-formatLocalized('%A%d%B%Y');//Mittwoch21Mai1975

setlocale(LC_TIME,'');

echo$dt-formatLocalized('%A%d%B%Y');//Wednesday21May1975

diffForHumans()的结果也会被转化成区域语言。通过Carbon::setLocale()方法可以设置Carbon的区域语言。

php

Carbon::setLocale('de');

echoCarbon::now()-addYear()-diffForHumans();//in1Jahr

Carbon::setLocale('en');

注意:如果在linux系统中转换出现了问题，请仔细检查安装在本地或生产系统中语言环境

locale-a列举出所有可用的语言环境

sudolocale-genzh_CN.utf8安装新的语言环境

sudodpkg-reconfigurelocales配置启用新的语言环境，并重启

4.TestingAids()

通过测试方法可以得到一个模拟或真实的Carbon实例。只有在以下情况下，主动提供的Carbon实例才会被特殊处理：

调用静态方法now()，例如：Carbon::now()传给construct或parse()方法的是null(或空字符串)，例如：newCarbon(null)当传给construct或parse()的是字符串now，例如：newCarbon(now)

$knownDate=Carbon::create(2001,5,21,12);//createtestingdate

Carbon::setTestNow($knownDate);//setthemock(ofcoursethiscouldbearealmockobject)

echoCarbon::now();//2001-05-2112:00:00

echonewCarbon();//2001-05-2112:00:00

echoCarbon::parse();//2001-05-2112:00:00

echonewCarbon('now');//2001-05-2112:00:00

echoCarbon::parse('now');//2001-05-2112:00:00

var_dump(Carbon::hasTestNow());//bool(true)

Carbon::setTestNow();//clearthemock

var_dump(Carbon::hasTestNow());//bool(false)

echoCarbon::now();

有用的例子：

classSeasonalProduct

protected$price;

publicfunction__construct($price)

$this-price=$price;

publicfunctiongetPrice(){

$multiplier=1;

if(Carbon::now()-month==12){

$multiplier=2;

return$this-price*$multiplier;

$product=newSeasonalProduct(100);

Carbon::setTestNow(Carbon::parse('firstdayofMarch2000'));

echo$product-getPrice();//100

Carbon::setTestNow(Carbon::parse('firstdayofDecember2000'));

echo$product-getPrice();//200

Carbon::setTestNow(Carbon::parse('firstdayofMay2000'));

echo$product-getPrice();//100

Carbon::setTestNow();

一些相关的用法也可以得到一个模拟的now实例，返回相应的模拟数据。

$knownDate=Carbon::create(2001,5,21,12);//createtestingdate

Carbon::setTestNow($knownDate);//setthemock

echonewCarbon('tomorrow');//2001-05-2200:00:00...noticethetime!

echonewCarbon('yesterday');//2001-05-2000:00:00

echonewCarbon('nextwednesday');//2001-05-2300:00:00

echonewCarbon('lastfriday');//2001-05-1800:00:00

echonewCarbon('thisthursday');//2001-05-2400:00:00

Carbon::setTestNow();

以下是当前支持的时间转换字

thislastnexttomorrowyesterday+-firstago

值得注意的是像next(),previous()和modify()方法等相关的修改会把日期的时间部分设置成00:00:00。

5.Getters

获取器通过PHP的__get()方式实现。可以直接通过一下方式直接获取到属性的值。

$dt=Carbon::parse('2012-9-523:26:11.123789');

//Thesegettersspecificallyreturnintegers,ieintval()

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)calculatedvsnowinthesametz

var_dump($dt-quarter);//int(3)

//ReturnsanintofsecondsdifferencefromUTC(+/-signincluded)

var_dump(Carbon::createFromTimestampUTC(0)-offset);//int(0)

var_dump(Carbon::createFromTimestamp(0)-offset);//int(-18000)

//ReturnsanintofhoursdifferencefromUTC(+/-signincluded)

var_dump(Carbon::createFromTimestamp(0)-offsetHours);//int(-5)

//Indicatesifdaylightsavingstimeison

var_dump(Carbon::createFromDate(2012,1,1)-dst);//bool(false)

var_dump(Carbon::createFromDate(2012,9,1)-dst);//bool(true)

//Indicatesiftheinstanceisinthesametimezoneasthelocaltimezone

var_dump(Carbon::now()-local);//bool(true)

var_dump(Carbon::now('America/Vancouver')-local);//bool(false)

//IndicatesiftheinstanceisintheUTCtimezone

var_dump(Carbon::now()-utc);//bool(false)

var_dump(Carbon::now('Europe/London')-utc);//bool(false)

var_dump(Carbon::createFromTimestampUTC(0)-utc);//bool(true)

//GetstheDateTimeZoneinstance

echoget_class(Carbon::now()-timezone);//DateTimeZone

echoget_class(Carbon::now()-//DateTimeZone

//GetstheDateTimeZoneinstancename,shortcutfor-timezone-getName()

echoCarbon::now()-timezoneName;//America/Toronto

echoCarbon::now()-tzName;//America/Toronto

6.Setters

Setters通过PHP的__set()方法实现。值得注意的是，通过这种方式设置时间戳时，时区不会相对于时间戳而改变。如果需要改变时区的话，需要针对时区单独设置。

$dt=Carbon::now();

$dt-year=1975;

$dt-month=13;//wouldforceyear++andmonth=1

$dt-month=5;

$dt-day=21;

$dt-hour=22;

$dt-minute=3