laravelcarbon时间处理组件开发文档中文版zh7314

useCarbon\Carbon;

本文档中的示例将假定您以这种方式导入了Carbon名称空间的类。

现在，让我们看看这个文档有多酷。点击下面的代码：

$dtToronto=Carbon::create(2012,1,1,0,0,0,'America/Toronto');$dtVancouver=Carbon::create(2012,1,1,0,0,0,'America/Vancouver');//Trytoreplacethe4thnumber(hours)orthelastargument(timezone)with//Europe/Parisforexampleandseetheactualresultontherighthand.//It'salive!echo$dtVancouver->diffInHours($dtToronto);//3//Now,trytodouble-clickon"diffInHours"or"create"toopen//theReferencespanel.//Oncethereferencespanelisopen,youcanusethesearchfieldto//filterthelistorclickthe(<)buttontocloseit.

一些示例是静态代码段，其他一些示例是可编辑的（当有右上角的展开按钮时）。您也可以单击此按钮在新标签页中打开代码段。您可以在静态和动态示例中双击方法名称。

$carbon=newCarbon();//equivalenttoCarbon::now()$carbon=newCarbon('firstdayofJanuary2008','America/Vancouver');echoget_class($carbon);//'Carbon\Carbon'$carbon=newCarbon(newDateTime('firstdayofJanuary2008'),newDateTimeZone('America/Vancouver'));//equivalenttopreviousinstance

您会在上面注意到timezone（2nd）参数是作为字符串而不是\DateTimeZone实例传递的。所有DateTimeZone参数都得到了增强，因此您可以将DateTimeZone实例，字符串或整数偏移量传递给GMT，并将为您创建时区。在下一个示例中再次显示了该示例，该示例还介绍了该now()功能。

$now=Carbon::now();//willusetimezoneassetwithdate_default_timezone_set//PS:werecommendyoutoworkwithUTCasdefaulttimezoneandonlyuse//othertimezones(suchastheusertimezone)ondisplay$nowInLondonTz=Carbon::now(newDateTimeZone('Europe/London'));//orjustpassthetimezoneasastring$nowInLondonTz=Carbon::now('Europe/London');echo$nowInLondonTz->tzName;//Europe/Londonecho"\n";//ortocreateadatewithacustomfixedtimezoneoffset$date=Carbon::now('+13:30');echo$date->tzName;//+13:30echo"\n";//Get/setminutesoffsetfromUTCecho$date->utcOffset();//810echo"\n";$date->utcOffset(180);echo$date->tzName;//+03:00echo"\n";echo$date->utcOffset();//180

如果您真的喜欢您的可变方法调用，并在使用构造函数时对多余的行或丑陋的括号感到沮丧，那么您会喜欢这种parse方法。

echo(newCarbon('firstdayofDecember2008'))->addWeeks(2);//2008-12-1500:00:00echo"\n";echoCarbon::parse('firstdayofDecember2008')->addWeeks(2);//2008-12-1500:00:00

$string='firstdayofnextmonth';if(strtotime($string)===false){echo"'$string'isnotavaliddate/timestring.";}elseif(Carbon::hasRelativeKeywords($string)){echo"'$string'isarelativevaliddate/timestring,itwillreturnsdifferentdatesdependingonthecurrentdate.";}else{echo"'$string'isanabsolutedate/timestring,itwillalwaysreturnsthesamedate.";}

$now=Carbon::now();echo$now;//2020-02-1416:05:16echo"\n";$today=Carbon::today();echo$today;//2020-02-1400:00:00echo"\n";$tomorrow=Carbon::tomorrow('Europe/London');echo$tomorrow;//2020-02-1500:00:00echo"\n";$yesterday=Carbon::yesterday();echo$yesterday;//2020-02-1300:00:00

$year=2000;$month=4;$day=19;$hour=20;$minute=30;$second=15;$tz='Europe/Madrid';echoCarbon::createFromDate($year,$month,$day,$tz)."\n";echoCarbon::createMidnightDate($year,$month,$day,$tz)."\n";echoCarbon::createFromTime($hour,$minute,$second,$tz)."\n";echoCarbon::createFromTimeString("$hour:$minute:$second",$tz)."\n";echoCarbon::create($year,$month,$day,$hour,$minute,$second,$tz)."\n";

$xmasThisYear=Carbon::createFromDate(null,12,25);//Yeardefaultstocurrentyear$Y2K=Carbon::create(2000,1,1,0,0,0);//equivalenttoCarbon::createMidnightDate(2000,1,1)$alsoY2K=Carbon::create(1999,12,31,24);$noonLondonTz=Carbon::createFromTime(12,0,0,'Europe/London');$teaTime=Carbon::createFromTimeString('17:00:00','Europe/London');try{Carbon::create(1975,5,21,22,-2,0);}catch(InvalidArgumentException$x){echo$x->getMessage();}//minutemustbebetween0and99,-2given//Becareful,asCarbon::createFromDate()defaultvaluestocurrentdate,itcantriggeroverflow://Forexample,ifwearethe15thofJune2020,thefollowingwillsetthedateon15:Carbon::createFromDate(2019,4);//2019-04-15//Ifwearethe31thofOctober,as31thAprildoesnotexist,itoverflowstoMay:Carbon::createFromDate(2019,4);//2019-05-01//That'swhyyousimplyshouldnotuseCarbon::createFromDate()withonly2parameters(1or3aresafe,butno2)

创建异常会在此类负值上发生，但不会在溢出时发生，要在溢出时获取异常，请使用createSafe()

echoCarbon::create(2000,1,35,13,0,0);//2000-02-0413:00:00echo"\n";try{Carbon::createSafe(2000,1,35,13,0,0);}catch(\Carbon\Exceptions\InvalidDateException$exp){echo$exp->getMessage();}//day:35isnotavalidvalue.

注1：2018-02-29也会产生例外，而2020-02-29不会例外，因为2020年是a年。

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

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

echoCarbon::createFromTimestamp(-1)->toDateTimeString();//1969-12-3123:59:59echoCarbon::createFromTimestamp(-1,'Europe/London')->toDateTimeString();//1970-01-0100:59:59echoCarbon::createFromTimestampUTC(-1)->toDateTimeString();//1969-12-3123:59:59echoCarbon::createFromTimestampMs(1)->format('Y-m-d\TH:i:s.uPT');//1970-01-01T00:00:00.001000+00:00UTCechoCarbon::createFromTimestampMs(1,'Europe/London')->format('Y-m-d\TH:i:s.uPT');//1970-01-01T01:00:00.001000+01:00BST

$dt=Carbon::now();echo$dt->diffInYears($dt->copy()->addYear());//1//$dtwasunchangedandstillholdsthevalueofCarbon:now()

您可以使用nowWithSameTz()现有的Carbon实例在同一时区现在获取一个新实例。

$meeting=Carbon::createFromTime(19,15,00,'Africa/Johannesburg');//19:15inJohannesburgecho'Meetingstartsat'.$meeting->format('H:i').'inJohannesburg.';//Meetingstartsat19:15inJohannesburg.//nowinJohannesburgecho"It's".$meeting->nowWithSameTz()->format('H:i').'rightnowinJohannesburg.';//It's18:05rightnowinJohannesburg.

最后，如果您发现自己\DateTime从另一个库继承实例，请不要担心！您可以Carbon通过友好的instance()方法创建实例。或者使用更加灵活的方法make()，该方法可以从DateTime，Carbon或字符串返回新的Carbon实例，否则它仅返回null。

$dt=new\DateTime('firstdayofJanuary2008');//<==instancefromanotherAPI$carbon=Carbon::instance($dt);echoget_class($carbon);//'Carbon\Carbon'echo$carbon->toDateTimeString();//2008-01-0100:00:00

是否曾经需要遍历某些日期来查找最早或最新的日期？不知道将初始最大值/最小值设置为什么？现在有两个帮助程序使您的决定变得简单：

echoCarbon::maxValue();//'9999-12-3123:59:59'echoCarbon::minValue();//'0001-01-0100:00:00'

最小值和最大值主要取决于系统（32或64位）。

对于64位OS系统和64位版本的PHP，最小值为01-01-0100:00:00，最大值为9999-12-3123:59:59。甚至可以使用负数年份，最大为-9999，但是请注意，由于PHP中存在年份0，但在公历中不存在年份，因此某些操作可能无法获得准确的结果。

从2.9.0版开始，您可以轻松自定义翻译：

//werecommendtousecustomlanguagename/variant//ratherthanoverridinganexistinglanguage//toavoidconflictsuchas"en_Boring"intheexamplebelow:$boringLanguage='en_Boring';$translator=\Carbon\Translator::get($boringLanguage);$translator->setTranslations(['day'=>':countboringday|:countboringdays',]);//asthislanguagestartswith"en_"itwillinheritfromthelocale"en"$date1=Carbon::create(2018,1,1,0,0,0);$date2=Carbon::create(2018,1,4,4,0,0);echo$date1->locale($boringLanguage)->diffForHumans($date2);//3boringdaysbefore$translator->setTranslations(['before'=>function($time){return'['.strtoupper($time).']';},]);echo$date1->locale($boringLanguage)->diffForHumans($date2);//[3BORINGDAYS]

您可以通过以下方式使用后备语言环境locale()：

\Carbon\Translator::get('xx')->setTranslations(['day'=>':countXday',]);\Carbon\Translator::get('xy')->setTranslations(['day'=>':countYday','hour'=>':countYhour',]);$date=Carbon::now()->locale('xx','xy','es')->sub('3days6hours40minutes');echo$date->ago(['parts'=>3]);//hace3Xday6Yhour40minutos

在上面的示例中，它将尝试先在“xx”中查找翻译，然后在“xy”中查找缺失的翻译，然后在“es”中查找，因此在这里，您会从“xx”获得“Xday”，从“xy”，“es”中的“hace”和“minutos”。

因此，对于一个区域的支撑formatLocalized，吸气如localeMonth，localeDayOfWeek短的变体是由安装在操作系统语言环境驱动。对于其他翻译，Carbon社区在内部为它提供了支持。您可以检查以下方法支持什么：

echoimplode(',',array_slice(Carbon::getAvailableLocales(),0,3)).'...';//aa,aa_DJ,aa_ER...//Supportdiffsyntax(before,after,fromnow,ago)var_dump(Carbon::localeHasDiffSyntax('en'));//bool(true)var_dump(Carbon::localeHasDiffSyntax('zh_TW'));//bool(true)//Support1-daydiffwords(justnow,yesterday,tomorrow)var_dump(Carbon::localeHasDiffOneDayWords('en'));//bool(true)var_dump(Carbon::localeHasDiffOneDayWords('zh_TW'));//bool(true)//Support2-daysdiffwords(beforeyesterday,aftertomorrow)var_dump(Carbon::localeHasDiffTwoDayWords('en'));//bool(true)var_dump(Carbon::localeHasDiffTwoDayWords('zh_TW'));//bool(false)//Supportshortunits(1y=1year,1mo=1month,etc.)var_dump(Carbon::localeHasShortUnits('en'));//bool(true)var_dump(Carbon::localeHasShortUnits('zh_TW'));//bool(false)//Supportperiodsyntax(Xtimes,everyX,fromX,toX)var_dump(Carbon::localeHasPeriodSyntax('en'));//bool(true)var_dump(Carbon::localeHasPeriodSyntax('zh_TW'));//bool(false)

因此，这是处理Carbon国际化的新推荐方法。

$date=Carbon::now()->locale('fr_FR');echo$date->locale();//fr_FRecho"\n";echo$date->diffForHumans();//ilya1secondeecho"\n";echo$date->monthName;//févrierecho"\n";echo$date->isoFormat('LLLL');//vendredi14février202016:05

该->locale()方法仅更改当前实例的语言，并且优先于全局设置。我们建议您使用这种方法，以免与其他可能使用Carbon的地方或第三方库发生冲突。但是，为了避免->locale()每次都调用，可以使用工厂。

//LetsayMartinfromParisandJohnfromChicagoplaychess$martinDateFactory=newFactory(['locale'=>'fr_FR','timezone'=>'Europe/Paris',]);$johnDateFactory=newFactory(['locale'=>'en_US','timezone'=>'America/Chicago',]);//Eachonewillseedateinhisownlanguageandtimezone//WhenMartinmoves,wedisplaythingsinFrench,butwenotifyJohninEnglish:$gameStart=Carbon::parse('2018-06-1512:34:00','UTC');$move=Carbon::now('UTC');$toDisplay=$martinDateFactory->make($gameStart)->isoFormat('lll')."\n".$martinDateFactory->make($move)->calendar()."\n";$notificationForJohn=$johnDateFactory->make($gameStart)->isoFormat('lll')."\n".$johnDateFactory->make($move)->calendar()."\n";echo$toDisplay;/*15juin201812:34Aujourd’huià16:05*/echo$notificationForJohn;/*Jun15,201812:34PMTodayat4:05PM*/

您可以在工厂上调用任何静态Carbon方法（进行制造，现在，昨天，明天，解析，创建等）。工厂（以及生成CarbonImmutable实例的FactoryImmutable）是使事物保持组织和隔离的最佳方法。我们建议您尽可能多地使用UTC日期，然后在向用户显示日期之前在本地（或在工厂使用）时区和语言。

$factory=newFactory(['locale'=>'fr_FR','timezone'=>'Europe/Paris',]);$factory->now();//Youcanrecall$factoryasneededtogeneratenewinstanceswithsamesettings//isequivalentto:Carbon::now()->settings(['locale'=>'fr_FR','timezone'=>'Europe/Paris',]);//Importantnote:timezonesettingcalls->shiftTimezone()andnot->setTimezone(),//Itmeansitdoesnotjustsetthetimezone,butshiftthetimetoo:echoCarbon::today()->setTimezone('Asia/Tokyo')->format('d/mG\he');//14/029hAsia/Tokyoecho"\n";echoCarbon::today()->shiftTimezone('Asia/Tokyo')->format('d/mG\he');//14/020hAsia/Tokyo

settings()还允许传递本地宏：

$date=Carbon::parse('Today12:34:56')->settings(['macros'=>['lastSecondDigit'=>function(){returnself::this()->second%10;},],]);echo$date->lastSecondDigit();//6var_dump($date->hasLocalMacro('lastSecondDigit'));//bool(true)//Youcanalsoretrievethemacroclosureusing->getLocalMacro('lastSecondDigit')

之后可以使用更改工厂设置，也可以将其setSettings(array$settings)与现有设置合并，mergeSettings(array$settings)然后可以将要生成的类初始化为构造的第二个参数，然后使用进行更改setClassName(string$className)。

$factory=newFactory(['locale'=>'ja'],CarbonImmutable::class);var_dump($factory->now()->locale);//string(2)"ja"var_dump(get_class($factory->now()));//string(22)"Carbon\CarbonImmutable"classMyCustomCarbonSubClassextendsCarbon{/*...*/}$factory->setSettings(['locale'=>'zh_CN'])->setClassName(MyCustomCarbonSubClass::class);var_dump($factory->now()->locale);//string(5)"zh_CN"var_dump(get_class($factory->now()));//string(22)"MyCustomCarbonSubClass"

以前是Carbon::setLocale在全球范围内设置的。但是对于其他静态设置器，我们强烈建议您不要使用它。它违反了隔离原则，因为该配置将适用于所有使用Carbon的类。

您可能也知道formatLocalized()Carbon1中的方法。此方法在Carbon2中仍然相同，但最好isoFormat()改用。

$date=Carbon::parse('2018-06-1517:34:15.984512','UTC');echo$date->isoFormat('MMMMDoYYYY,h:mm:ssa');//June15th2018,5:34:15pmecho"\n";echo$date->isoFormat('dddd');//Fridayecho"\n";echo$date->isoFormat('MMMDoYY');//Jun15th18echo"\n";echo$date->isoFormat('YYYY[escaped]YYYY');//2018escaped2018

您还可以根据ISO格式的字符串创建日期：

$date=Carbon::createFromIsoFormat('!YYYY-MMMM-Dh:mm:ssa','2019-January-36:33:24pm','UTC');echo$date->isoFormat('M/D/YYHH:mm');//1/3/1918:33

->isoFormat对日期名称和月份名称使用上下文化的方法，因为它们在某些语言中可以具有多种形式，请参见以下示例：

这是可用替代品的完整列表（示例带有$date=Carbon::parse('2017-01-0517:04:05.084512');）：

也可以使用一些宏格式。以下是每种语言的示例：

与宏格式一起使用时createFromIsoFormat，可以指定区域设置以选择应以哪种语言搜索宏格式。

$date=Carbon::createFromIsoFormat('LLLL','Monday11March201916:28',null,'fr');echo$date->isoFormat('M/D/YYHH:mm');//3/11/1916:28

另一种有用的翻译方法是calendar($referenceTime=null,array$formats=[]):string：

$date=CarbonImmutable::now();echo$date->calendar();//Todayat4:05PMecho"\n";echo$date->sub('1day3hours')->calendar();//Yesterdayat1:05PMecho"\n";echo$date->sub('3days10hours23minutes')->calendar();//LastTuesdayat5:42AMecho"\n";echo$date->sub('8days')->calendar();//02/06/2020echo"\n";echo$date->add('1day3hours')->calendar();//Tomorrowat7:05PMecho"\n";echo$date->add('3days10hours23minutes')->calendar();//Tuesdayat2:28AMecho"\n";echo$date->add('8days')->calendar();//02/22/2020echo"\n";echo$date->locale('fr')->calendar();//Aujourd’huià16:05

如果您知道momentjs，那么它的工作方式相同。您可以将参考日期作为第二个参数传递，否则现在使用。您可以使用第二个参数来自定义一种或多种格式（作为数组键传递的格式为：sameDay，nextDay，nextWeek，lastDay，lastWeek和sameElse）：

$date1=CarbonImmutable::parse('2018-01-0112:00:00');$date2=CarbonImmutable::parse('2018-01-028:00:00');echo$date1->calendar($date2,['lastDay'=>'[Previousdayat]LT',]);//Previousdayat12:00PM

请注意，如果您使用Laravel5.5+，将根据当前的上次App:setLocale执行自动设置语言环境。因此diffForHumans，isoFormat，translatedFormat和本地化如属性->dayName或->monthName将被透明地本地化。

默认情况下，每个Carbon，CarbonImmutable，CarbonInterval或CarbonPeriod实例都Carbon\Translator根据其区域设置链接到一个实例。您可以使用getLocalTranslator()/获取和/或更改它setLocalTranslator(Translator$translator)。

$date=Carbon::parse('2018-03-1615:45')->locale('uk');echo$date->translatedFormat('g:ialjSFY');//3:45дняп’ятниця16-гоберезня2018

请注意，W不支持某些字母之类的字母，因为它们不能安全翻译，并且translatedFormat语法比短，但可能性比少isoFormat()。

您可以自定义format()方法的行为，以使用任何其他方法或自定义方法来代替PHPDateTime类中的本机方法：

$date=Carbon::parse('2018-03-1615:45')->locale('ja');echo$date->format('g:ialjSFY');//3:45pmFriday16thMarch2018echo"\n";$date->settings(['formatFunction'=>'translatedFormat']);echo$date->format('g:ialjSFY');//3:45午後金曜日16日3月2018echo"\n";$date->settings(['formatFunction'=>'isoFormat']);echo$date->format('LL');//2018年3月16日echo"\n";//Whenyousetacustomformat()methodyoustillcanaccessthenativemethodusingrawFormat()echo$date->rawFormat('D');//Fri

您可以使用Carbon中可用的日期翻译将字符串从一种语言翻译为另一种：

echoCarbon::translateTimeString('mercredi8juillet','fr','nl');//woensdag8juliecho"\n";//Youcanselecttranslationstouseamongavailableconstants://-CarbonInterface::TRANSLATE_MONTHS//-CarbonInterface::TRANSLATE_DAYS//-CarbonInterface::TRANSLATE_UNITS//-CarbonInterface::TRANSLATE_MERIDIEM//-CarbonInterface::TRANSLATE_ALL(allabove)//Youcancombinethemwithpipes:likebelow(translateunitsanddaysbutnotmonthsandmeridiem):echoCarbon::translateTimeString('mercredi8juillet+3jours','fr','nl',CarbonInterface::TRANSLATE_DAYS|CarbonInterface::TRANSLATE_UNITS);//woensdag8juillet+3dagen

如果未指定输入语言环境，Carbon::getLocale()则改为使用。如果未指定输出语言环境，"en"则改为使用。您还可以使用实例的语言环境进行翻译：

echoCarbon::now()->locale('fr')->translateTimeStringTo('mercredi8juillet+3jours','nl');//woensdag8juli+3dagen

您可以使用任何语言的字符串直接使用创建日期对象parseFromLocale：

$date=Carbon::parseFromLocale('mercredi6mars2019+3jours','fr','UTC');//timezoneisoptionalecho$date->isoFormat('LLLL');//Saturday,March9,201912:00AM

$date=Carbon::createFromLocaleFormat('!d/F/y','fr','25/Aot/19','Europe/Paris');//timezoneisoptionalecho$date->isoFormat('LLLL');//Sunday,August25,201912:00AM

使用ISO格式的等效方法是createFromLocaleIsoFormat：

$date=Carbon::createFromLocaleIsoFormat('!DD/MMMM/YY','fr','25/Aot/19','Europe/Paris');//timezoneisoptionalecho$date->isoFormat('LLLL');//Sunday,August25,201912:00AM

要获取有关语言的一些有趣信息（例如完整的ISO名称或本机名称，地区（例如，显示在语言选择器中）），可以使用getAvailableLocalesInfo。

请让我感谢一些项目，这些项目对我们支持更多区域设置和国际化功能很有帮助：

$knownDate=Carbon::create(2001,5,21,12);//createtestingdateCarbon::setTestNow($knownDate);//setthemock(ofcoursethiscouldbearealmockobject)echoCarbon::getTestNow();//2001-05-2112:00:00echoCarbon::now();//2001-05-2112:00:00echonewCarbon();//2001-05-2112:00:00echoCarbon::parse();//2001-05-2112:00:00echonewCarbon('now');//2001-05-2112:00:00echoCarbon::parse('now');//2001-05-2112:00:00echoCarbon::create(2001,4,21,12)->diffForHumans();//1monthagovar_dump(Carbon::hasTestNow());//bool(true)Carbon::setTestNow();//clearthemockvar_dump(Carbon::hasTestNow());//bool(false)echoCarbon::now();//2020-02-1416:05:24

一个更有意义的完整示例：

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();//100Carbon::setTestNow(Carbon::parse('firstdayofDecember2000'));echo$product->getPrice();//200Carbon::setTestNow(Carbon::parse('firstdayofMay2000'));echo$product->getPrice();//100Carbon::setTestNow();

相对短语也会根据给定的“now”实例进行模拟。

$knownDate=Carbon::create(2001,5,21,12);//createtestingdateCarbon::setTestNow($knownDate);//setthemockechonewCarbon('tomorrow');//2001-05-2200:00:00...noticethetime!echonewCarbon('yesterday');//2001-05-2000:00:00echonewCarbon('nextwednesday');//2001-05-2300:00:00echonewCarbon('lastfriday');//2001-05-1800:00:00echonewCarbon('thisthursday');//2001-05-2400:00:00Carbon::setTestNow();//alwaysclearit!

被视为相对修饰语的单词列表为：

Carbon::parse($time,$tz)并且newCarbon($time,$tz)既可以采取时区作为第二个参数。

echoCarbon::parse('2012-9-523:26:11.223','Europe/Paris')->timezone->getName();//Europe/Paris

useCarbon\Carbonite;在文件顶部添加导入。

$holidays=CarbonPeriod::create('2019-12-23','2020-01-06',CarbonPeriod::EXCLUDE_END_DATE);Carbonite::freeze('2019-12-22');//Freezethetimetoagivendatevar_dump($holidays->isStarted());//bool(false)//Thengotoanytime:Carbonite::elapse('1day');var_dump($holidays->isInProgress());//bool(true)Carbonite::jumpTo('2020-01-0522:00');var_dump($holidays->isEnded());//bool(false)Carbonite::elapse('2hours');var_dump($holidays->isEnded());//bool(true)Carbonite::rewind('1microsecond');var_dump($holidays->isEnded());//bool(false)Carbonite::release();//Releasetimeaftereachtest

吸气剂是通过PHP的__get()方法实现的。这样一来，您就可以像对待属性而不是调用函数一样访问该值。

如果您熟悉momentjs，那么您会发现所有Week方法都工作相同。它们大多数具有iso{Method}变体。Week方法遵循当前语言环境的规则（例如，使用en_US，默认语言环境，一周的第一天为Sunday，一年的第一周为包含1月1日的一周）。ISO方法遵循ISO8601规范，这意味着星期从星期一开始，一年的第一周是包含1月4日的星期。

您可以将任何基本单元称为设置器或某些分组的设置器：

$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->setDate(1975,5,21)->setTimeFromTimeString('22:32:05')->toDateTimeString();$dt->setDateTime(1975,5,21,22,32,5)->toDateTimeString();//Allallowmicrosecondasoptionalargument$dt->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->microsecond(123456)->toDateTimeString();$dt->setDate(1975,5,21)->setTime(22,32,5,123456)->toDateTimeString();$dt->setDate(1975,5,21)->setTimeFromTimeString('22:32:05.123456')->toDateTimeString();$dt->setDateTime(1975,5,21,22,32,5,123456)->toDateTimeString();$dt->timestamp(169957925);//Note:timestampsareUTCbutdonotchangethedatetimezone$dt->timezone('Europe/London')->tz('America/Toronto')->setTimezone('America/Vancouver');

$source1=newCarbon('2010-05-1622:40:10.1');$dt=newCarbon('2001-01-0101:01:01.2');$dt->setTimeFrom($source1);echo$dt;//2001-01-0122:40:10$source2=newDateTime('2013-09-0109:22:56.2');$dt->setDateFrom($source2);echo$dt;//2013-09-0122:40:10$dt->setDateTimeFrom($source2);//setdateandtimeincludingmicroseconds//botnotsettingsaslocale,timezone,options.

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)

$dt=Carbon::create(1975,12,25,14,15,16);var_dump($dt->toDateTimeString()==$dt);//bool(true)=>uses__toString()echo$dt->toDateString();//1975-12-25echo$dt->toFormattedDateString();//Dec25,1975echo$dt->toTimeString();//14:15:16echo$dt->toDateTimeString();//1975-12-2514:15:16echo$dt->toDayDateTimeString();//Thu,Dec25,19752:15PM//...ofcourseformat()isstillavailableecho$dt->format('ljS\\ofFYh:i:sA');//Thursday25thofDecember197502:15:16PM//ThereversehasFormatmethodallowsyoutotestifastringlookslikeagivenformatvar_dump($dt->hasFormat('Thursday25thDecember197502:15:16PM','ljSFYh:i:sA'));//bool(true)

echo$dt;//1975-12-2514:15:16echo"\n";$dt->settings(['toStringFormat'=>'jS\o\fF,Yg:i:sa',]);echo$dt;//25thofDecember,19752:15:16pm//Asanysetting,youcangetthecurrentvalueforagivendateusing:var_dump($dt->getSettings());/*array(3){["toStringFormat"]=>string(20)"jS\o\fF,Yg:i:sa"["locale"]=>string(2)"en"["timezone"]=>string(3)"UTC"}*/

作为设置的一部分，'toStringFormat'也可以在工厂中使用。它也可能是一个闭包，因此您可以在字符串强制转换上运行任何代码。

如果您使用Carbon1或要将其作为默认格式全局应用，则可以使用：

$dt=Carbon::create(1975,12,25,14,15,16);Carbon::setToStringFormat('jS\o\fF,Yg:i:sa');echo$dt;//25thofDecember,19752:15:16pmecho"\n";Carbon::resetToStringFormat();echo$dt;//1975-12-2514:15:16

您可以使用该方法根据给定的源实例（根据需要用作参考）carbonize将许多事物转换为Carbon实例。它返回一个新实例。

$dt=Carbon::createFromFormat('Y-m-dH:i:s.u','2019-02-0103:45:27.612584','Europe/Paris');//Cantakeadatestringandwillapplythetimezonefromreferenceobjectvar_dump($dt->carbonize('2019-03-21'));/*object(Carbon\Carbon)#3444(3){["date"]=>string(26)"2019-03-2100:00:00.000000"["timezone_type"]=>int(3)["timezone"]=>string(12)"Europe/Paris"}*///IfyoupassaDatePeriodorCarbonPeriod,itwillcopytheperiodstartvar_dump($dt->carbonize(CarbonPeriod::create('2019-12-10','2020-01-05')));/*object(Carbon\Carbon)#3439(3){["date"]=>string(26)"2019-12-1000:00:00.000000"["timezone_type"]=>int(3)["timezone"]=>string(3)"UTC"}*///IfyoupassaDateIntervalorCarbonInterval,itwilladdtheintervalto//thereferenceobjectvar_dump($dt->carbonize(CarbonInterval::days(3)));/*object(Carbon\Carbon)#3444(3){["date"]=>string(26)"2019-02-0403:45:27.612584"["timezone_type"]=>int(3)["timezone"]=>string(12)"Europe/Paris"}*/

通过以下功能可以进行简单比较。请记住，比较是在UTC时区进行的，因此情况并非总是如此。

这些方法使用PHP提供的自然比较，$date1==$date2因此所有这些方法都将在PHP7.1之前忽略毫秒/微秒，然后从7.1开始考虑它们。

要确定当前实例是否在其他两个实例之间，可以使用适当命名的between()方法（或isBetween()别名）。第三个参数指示是否应该进行等于比较。默认值是true，它确定其介于边界之间还是等于边界。

$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)var_dump(Carbon::create(2012,9,5,5)->isBetween($first,$second,false));//bool(false)//Ratherthanpassingfalseasathirdargument,youcanusebetweenExcludedvar_dump(Carbon::create(2012,9,5,5)->betweenExcluded($first,$second));//bool(false)//AllthosemethodsarealsoavailableonCarbonInterval

哇！您忘记了min（）和max（）吗？不。适当命名的min()和max()方法或minimum()和maximum()别名也涵盖了这一点。与往常一样，如果指定了null，则默认参数现在为。

为了处理最常用的情况，有一些简单的辅助函数，希望它们的名称是显而易见的。对于now()以某种方式与（例如isToday（））进行比较的方法，now()会在与实例相同的时区中创建。

为了好玩，您还可以将负值传递给addXXX()，实际上subXXX()就是这样实现的。

PS不要担心，如果您忘记和使用，addDay(5)或者subYear(3)，我有您的支持;）

默认情况下，Carbon依赖于基础父类PHPDateTime行为。结果，增加或减少月份可能会溢出，例如：

$dt=CarbonImmutable::create(2017,1,31,0);echo$dt->addMonth();//2017-03-0300:00:00echo"\n";echo$dt->subMonths(2);//2016-12-0100:00:00

从Carbon2开始，您可以为每个实例设置本地溢出行为：

$dt=CarbonImmutable::create(2017,1,31,0);$dt->settings(['monthOverflow'=>false,]);echo$dt->addMonth();//2017-02-2800:00:00echo"\n";echo$dt->subMonths(2);//2016-11-3000:00:00

这将应用于方法addMonth(s)，subMonth(s)，add($x,'month')，sub($x,'month')和等效季度方法。但是它不适用于间隔对象或字符串，例如add(CarbonInterval::month())或add('1month')。

你也可以使用->addMonthsNoOverflow，->subMonthsNoOverflow，->addMonthsWithOverflow和->subMonthsWithOverflow（或奇异的方法，没有s到“月”），明确添加/带或不带溢出子月，无论现在的模式与同为任何更大的单元（季，年，十年，百年，千年）。

多年以来一直可用。

使用未知输入时，您还可以控制任何单元的溢出：

任何可修改的单位都可以作为这些方法的参数传递：

$units=[];foreach(['millennium','century','decade','year','quarter','month','week','weekday','day','hour','minute','second','millisecond','microsecond']as$unit){$units[$unit]=Carbon::isModifiableUnit($unit);}echojson_encode($units,JSON_PRETTY_PRINT);/*{"millennium":true,"century":true,"decade":true,"year":true,"quarter":true,"month":true,"week":true,"weekday":true,"day":true,"hour":true,"minute":true,"second":true,"millisecond":true,"microsecond":true}*/

随着Carbon扩展，DateTime它继承了其方法，例如以diff()第二个date对象作为参数并返回一个DateInterval实例。

这些方法的结果被截断。这意味着diffInMinutes对于包含1和排除2之间的任何差值，将返回1。但是相同的方法可用于浮点结果：

关于夏令时（DST）的重要说明，默认情况下，PHPDateTime不考虑DST，这意味着例如，像2014年3月30日在伦敦这样仅23小时的一天将被计为24小时。

$date=newDateTime('2014-03-3000:00:00',newDateTimeZone('Europe/London'));//DSToffecho$date->modify('+25hours')->format('H:i');//01:00(DSTon,24hoursonlyhavebeenactuallyadded)

用同样的方法，你可以使用addRealX()和subRealX()任何设备上。

还具有特殊的过滤功能diffInDaysFiltered()，diffInHoursFiltered()和diffFiltered()，以帮助您按天，小时或自定义间隔过滤差异。例如，计算两个实例之间的周末天数：

所有diffIn*Filtered方法都将1个可调用过滤器作为必需参数，将date对象作为可选的第二个参数（如果缺少），现在使用。您也可以将true作为第三个参数传递以获得绝对值。

要了解周/周末的高级信息，请使用以下工具：

1monthago与30天前相比，人类更容易阅读。这是大多数日期库中常见的功能，因此我想也将其添加到此处。该函数的唯一参数是要比较的另一个Carbon实例，当然，now()如果未指定，则默认为默认值。

此方法将在相对于实例和传入实例的差值之后添加一个短语。有4种可能性：

您也可以通过CarbonInterface::DIFF_ABSOLUTE作为第二个参数，以去除改性剂前，从现在开始，等：diffForHumans($other,CarbonInterface::DIFF_ABSOLUTE)，CarbonInterface::DIFF_RELATIVE_TO_NOW得到改性前或从现在开始，CarbonInterface::DIFF_RELATIVE_TO_OTHER得到改性剂之前或之后，或者CarbonInterface::DIFF_RELATIVE_AUTO（默认模式），以获得修饰或者前/从现在开始，如果2第二个参数是空值或前/后如果没有。

true如果使用的语言环境可用，则可以作为第三个参数传递以使用简短语法diffForHumans($other,CarbonInterface::DIFF_RELATIVE_AUTO,true)。

可在1和6之间传递的数作为第四参数来获取在多个部分中的差异（更精确的差异）：diffForHumans($other,CarbonInterface::DIFF_RELATIVE_AUTO,false,4)。

该$other实例可以是DateTime，Carbon实例或实现DateTimeInterface的任何对象，如果传递了字符串，则将对其进行解析以获取Carbon实例；如果null传递了字符串，Carbon::now()则将使用它。

为避免过多的参数并混合使用顺序，可以使用详细方法：

PS：$other和$parts参数可以根据需要交换。

//Themosttypicalusageisforcomments//Theinstanceisthedatethecommentwascreatedanditsbeingcomparedtodefaultnow()echoCarbon::now()->subDays(5)->diffForHumans();//5daysagoechoCarbon::now()->diffForHumans(Carbon::now()->subYear());//11monthsafter$dt=Carbon::createFromDate(2011,8,1);echo$dt->diffForHumans($dt->copy()->addMonth());//1monthbeforeecho$dt->diffForHumans($dt->copy()->subMonth());//1monthafterechoCarbon::now()->addSeconds(5)->diffForHumans();//4secondsfromnowechoCarbon::now()->subDays(24)->diffForHumans();//3weeksagoechoCarbon::now()->subDays(24)->longAbsoluteDiffForHumans();//3weeksechoCarbon::parse('2019-08-03')->diffForHumans('2019-08-13');//1weekbeforeechoCarbon::parse('2000-01-0100:50:32')->diffForHumans('@946684800');//50minutesafterechoCarbon::create(2018,2,26,4,29,43)->longRelativeDiffForHumans(Carbon::create(2016,6,21,0,0,0),6);//1year8months5days4hours29minutes43secondsafter

由于2.9.0diffForHumans（）参数可以作为数组传递：

如果参数被省略或设置为null，则仅Carbon::NO_ZERO_DIFF启用。可用的选项有：

使用管道运算符一次启用/禁用多个选项，例如：Carbon::ONE_DAY_WORDS|Carbon::TWO_DAY_WORDS

你也可以使用Carbon::enableHumanDiffOption($option)，Carbon::disableHumanDiffOption($option)，Carbon::setHumanDiffOptions($options)更改默认选项，并Carbon::getHumanDiffOptions()获得默认选项，但你应该避免使用它为静态的，可能与其他的部分代码/第三方库调用冲突。

出于语义目的提供了别名和反向方法：

唯一略有不同的是average()功能。它将您的实例移动到其自身与所提供的Carbon参数之间的中间日期。

四舍五入也适用于任何单位：

在Carbon类中定义了以下常量。

//Thesegettersspecificallyreturnintegers,ieintval()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'PlacebetsonOttawaSenatorsWinning!';}

Carbon实例可以序列化（包括CarbonImmutable，CarbonInterval和CarbonPeriod）。

$dt=Carbon::create(2012,12,25,20,30,00,'Europe/Moscow');echoserialize($dt);//O:13:"Carbon\Carbon":3:{s:4:"date";s:26:"2012-12-2520:30:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:13:"Europe/Moscow";}//sameas:echo$dt->serialize();//O:13:"Carbon\Carbon":3:{s:4:"date";s:26:"2012-12-2520:30:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:13:"Europe/Moscow";}$dt='O:13:"Carbon\Carbon":3:{s:4:"date";s:26:"2012-12-2520:30:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:13:"Europe/Moscow";}';echounserialize($dt)->format('Y-m-d\TH:i:s.uPT');//2012-12-25T20:30:00.000000+04:00MSK//sameas:echoCarbon::fromSerialized($dt)->format('Y-m-d\TH:i:s.uPT');//2012-12-25T20:30:00.000000+04:00MSK

$dt=Carbon::create(2012,12,25,20,30,00,'Europe/Moscow');echojson_encode($dt);//"2012-12-25T16:30:00.000000Z"$json='{"date":"2012-12-2520:30:00.000000","timezone_type":3,"timezone":"Europe\/Moscow"}';$dt=Carbon::__set_state(json_decode($json,true));echo$dt->format('Y-m-d\TH:i:s.uPT');//2012-12-25T20:30:00.000000+04:00MSK

您可以用settings(['toJsonFormat'=>$format])来自定义序列化。

$dt=Carbon::create(2012,12,25,20,30,00,'Europe/Moscow')->settings(['toJsonFormat'=>function($date){return$date->getTimestamp();},]);echojson_encode($dt);//1356453000

如果要在全球范围内使用此功能，请首先考虑使用factory，否则，或者如果我使用Carbon1，则可以使用：

$dt=Carbon::create(2012,12,25,20,30,00,'Europe/Moscow');Carbon::serializeUsing(function($date){return$date->valueOf();});echojson_encode($dt);//1356453000000//CallserializeUsingwithnulltoresettheserializer:Carbon::serializeUsing(null);

如果未指定自定义序列化，则该jsonSerialize()方法允许您调用给定的函数Carbon::serializeUsing()或结果toJson()。

Carbon::macro()以宏名作为第一个参数，以闭包作为第二个参数来调用该方法。这将使关闭操作可用于所有Carbon实例。

Carbon::macro('diffFromYear',staticfunction($year,$absolute=false,$short=false,$parts=1){returnself::this()->diffForHumans(Carbon::create($year,1,1,0,0,0),$absolute,$short,$parts);});//CanbecalledonCarboninstances:self::this()=currentinstance($this)echoCarbon::parse('2020-01-1212:00:00')->diffFromYear(2019);//1yearafterecho"\n";echoCarbon::parse('2020-01-1212:00:00')->diffFromYear(2019,true);//1yearecho"\n";echoCarbon::parse('2020-01-1212:00:00')->diffFromYear(2019,true,true);//1yrecho"\n";echoCarbon::parse('2020-01-1212:00:00')->diffFromYear(2019,true,true,5);//1yr1w4d12h//Canalsobecalledstatically,inthiscaseself::this()=Carbon::now()echo"\n";echoCarbon::diffFromYear(2017);//3yearsafter

请注意，闭包之前static和使用self::this()（自版本2.25.0起可用）代替$this。这是创建碳宏的标准方法，这也适用于其他类的宏（CarbonImmutable，CarbonInterval和CarbonInterval）。

通过遵循这种模式，可以确保您团队（以及您将来）的其他开发人员可以安全地依赖断言：Carbon::anyMacro()等效于Carbon::now()->anyMacro()。这使宏的用法一致且可预测，并确保可以安全地静态或动态调用比任何宏都大的开发人员。

宏是使用某些设置或用户首选项输出日期的理想工具。

//Letassumeyougetusersettingsfromthebrowserorpreferencesstoredinadatabase$userTimezone='Europe/Paris';$userLanguage='fr_FR';Carbon::macro('formatForUser',staticfunction()use($userTimezone,$userLanguage){$date=self::this()->copy()->tz($userTimezone)->locale($userLanguage);return$date->calendar();//or->isoFormat($customFormat),->diffForHumans(),etc.});//Thenletassumeyoustoreallyourdates/timesinUTC(becauseyoudefinitelyshould)$dateString='2010-01-2310:00:00';//Getthisfromyourdatabaseoranyinput//Thennowyoucaneasilydisplayanydateinapage/e-mailusingthoseusersettingsandthechosenformatechoCarbon::parse($dateString,'UTC')->formatForUser();//23/01/2010echo"\n";echoCarbon::tomorrow()->formatForUser();//Demainà01:00echo"\n";echoCarbon::now()->subDays(3)->formatForUser();//mardidernierà17:05

宏也可以分组在类中，并与mixin()

classBeerDayCarbonMixin{publicfunctionnextBeerDay(){returnstaticfunction(){returnself::this()->modify('nextwednesday');};}publicfunctionpreviousBeerDay(){returnstaticfunction(){returnself::this()->modify('previouswednesday');};}}Carbon::mixin(newBeerDayCarbonMixin());$date=Carbon::parse('FirstsaturdayofDecember2018');echo$date->previousBeerDay();//2018-11-2800:00:00echo"\n";echo$date->nextBeerDay();//2018-12-0500:00:00

从Carbon2.23.0开始，还可以使用特征来缩短mixin语法：

traitBeerDayCarbonTrait{publicfunctionnextBeerDay(){return$this->modify('nextwednesday');}publicfunctionpreviousBeerDay(){return$this->modify('previouswednesday');}}Carbon::mixin(BeerDayCarbonTrait::class);$date=Carbon::parse('FirstsaturdayofDecember2018');echo$date->previousBeerDay();//2018-11-2800:00:00echo"\n";echo$date->nextBeerDay();//2018-12-0500:00:00

您可以检查宏（包括混合）是否可用，hasMacro()并使用来检索宏闭包getMacro()

var_dump(Carbon::hasMacro('previousBeerDay'));//bool(true)var_dump(Carbon::hasMacro('diffFromYear'));//bool(true)echo"\n";var_dump(Carbon::hasMacro('dontKnowWhat'));//bool(false)

宏起始与get后跟大写字母将自动提供动态吸气而一个宏开始set和后跟一个大写字母将提供一个动态调节器：

//Let'ssayaschoolyearstarts5monthsbeforethestartoftheyear,sotheschoolyearof2018actuallybeginsinAugust2017andendsinJuly2018,//Thenyoucancreateget/setmethodthisway:Carbon::macro('setSchoolYear',staticfunction($schoolYear){$date=self::this();$date->year=$schoolYear;if($date->month>7){$date->year--;}});Carbon::macro('getSchoolYear',staticfunction(){$date=self::this();$schoolYear=$date->year;if($date->month>7){$schoolYear++;}return$schoolYear;});//ThiswillmakegetSchoolYear/setSchoolYearasusual,butget/setprefixwillalsoenable//thegetterandsettermethodsforthe->schoolYearproperty.$date=Carbon::parse('2016-06-01');var_dump($date->schoolYear);//int(2016)$date->addMonths(3);var_dump($date->schoolYear);//int(2017)$date->schoolYear++;var_dump($date->format('Y-m-d'));//string(10)"2017-09-01"$date->schoolYear=2020;var_dump($date->format('Y-m-d'));//string(10)"2019-09-01"

您还可以使用通用宏拦截其他任何调用：

CarbonInterval::macro('twice',staticfunction(){returnself::this()->times(2);});echoCarbonInterval::day()->twice()->forHumans();//2days$interval=CarbonInterval::hours(2)->minutes(15)->twice();echo$interval->forHumans(['short'=>true]);//4h30m

CarbonPeriod::macro('countWeekdays',staticfunction(){returnself::this()->filter('isWeekday')->count();});echoCarbonPeriod::create('2017-11-01','2017-11-30')->countWeekdays();//22echoCarbonPeriod::create('2017-12-01','2017-12-31')->countWeekdays();//21

Carbon::macro('toAtomStringWithNoTimezone',staticfunction(){returnself::this()->format('Y-m-d\TH:i:s');});echoCarbon::parse('2021-06-1620:08:34')->toAtomStringWithNoTimezone();//2021-06-16T20:08:34

Carbon::macro('easterDate',staticfunction($year){returnCarbon::createMidnightDate($year,3,21)->addDays(easter_days($year));});echoCarbon::easterDate(2015)->format('d/m');//05/04echoCarbon::easterDate(2016)->format('d/m');//27/03echoCarbon::easterDate(2017)->format('d/m');//16/04echoCarbon::easterDate(2018)->format('d/m');//01/04echoCarbon::easterDate(2019)->format('d/m');//21/04

Carbon::macro('datePeriod',staticfunction($startDate,$endDate){returnnewDatePeriod($startDate,newDateInterval('P1D'),$endDate);});foreach(Carbon::datePeriod(Carbon::createMidnightDate(2019,3,28),Carbon::createMidnightDate(2019,4,3))as$date){echo"$date\n";}/*2019-03-2800:00:002019-03-2900:00:002019-03-3000:00:002019-03-3100:00:002019-04-0100:00:002019-04-0200:00:00*/

虽然推荐使用宏向Carbon添加新方法或行为，但是您可以进一步扩展类本身，从而允许使用一些替代方法来覆盖主要方法。解析，格式化和createFromFormat。

classMyDateClassextendsCarbon{protectedstatic$formatFunction='translatedFormat';protectedstatic$createFromFormatFunction='createFromLocaleFormat';protectedstatic$parseFunction='myCustomParse';publicstaticfunctionmyCustomParse($string){returnstatic::rawCreateFromFormat('dmY',$string);}}$date=MyDateClass::parse('20122001')->locale('de');echo$date->format('jSFy');//20.Dezember01echo"\n";$date=MyDateClass::createFromFormat('jFY','pt','20fevereiro2001')->locale('pt');echo$date->format('d/m/Y');//20/02/2001echo"\n";//NotethanyoucanstillaccessnativemethodsusingrawParse,rawFormatandrawCreateFromFormat:$date=MyDateClass::rawCreateFromFormat('jFY','20February2001','UTC')->locale('pt');echo$date->rawFormat('jSFy');//20thFebruary01echo"\n";$date=MyDateClass::rawParse('2001-02-01','UTC')->locale('pt');echo$date->format('jSFy');//1ofevereiro01echo"\n";

以下宏允许您仅使用城市名称（省略大洲）来选择时区。使您的单元测试更加流畅的完美之选：

Carbon::macro('goTo',function(string$city){static$cities=null;if($cities===null){foreach(DateTimeZone::listIdentifiers()as$identifier){$chunks=explode('/',$identifier);if(isset($chunks[1])){$id=strtolower(end($chunks));$cities[$id]=$identifier;}}}$city=str_replace('','_',strtolower($city));if(!isset($cities[$city])){thrownewInvalidArgumentException("$citynotfound.");}return$this->tz($cities[$city]);});echoCarbon::now()->goTo('Chicago')->tzName;//America/Chicagoecho"\n";echoCarbon::now()->goTo('BuenosAires')->tzName;//America/Argentina/Buenos_Aires

您可以通过以下方式创建实例：

echoCarbonInterval::createFromFormat('H:i:s','10:20:00');//10hours20minutesecho"\n";echoCarbonInterval::year();//1yearecho"\n";echoCarbonInterval::months(3);//3monthsecho"\n";echoCarbonInterval::days(3)->seconds(32);//3days32secondsecho"\n";echoCarbonInterval::weeks(3);//3weeksecho"\n";echoCarbonInterval::days(23);//3weeks2daysecho"\n";//years,months,weeks,days,hours,minutes,seconds,microsecondsechoCarbonInterval::create(2,0,5,1,1,2,7,123);//2years5weeks1day1hour2minutes7secondsecho"\n";echoCarbonInterval::createFromDateString('3months');//3months

如果您发现自己\DateInterval从另一个库继承实例，请不要担心！您可以CarbonInterval通过友好instance()函数创建实例。

$di=new\DateInterval('P1Y2M');//<==instancefromanotherAPI$ci=CarbonInterval::instance($di);echoget_class($ci);//'Carbon\CarbonInterval'echo$ci;//1year2months

相反，您可以DateInterval从CarbonInterval任何扩展的类中提取原始数据，甚至将其转换为DateInterval

$ci=CarbonInterval::days(2);$di=$ci->toDateInterval();echoget_class($di);//'DateInterval'echo$di->d;//2//YourcustomclasscanalsoextendsCarbonIntervalclassCustomDateIntervalextends\DateInterval{}$di=$ci->cast(\CustomDateInterval::class);echoget_class($di);//'CustomDateInterval'echo$di->d;//2

其他帮助程序，但请注意，该实现使帮助程序可以处理数周，但仅节省了几天。周数是根据当前实例的总天数计算得出的。

echoCarbonInterval::year()->years;//1echoCarbonInterval::year()->dayz;//0echoCarbonInterval::days(24)->dayz;//24echoCarbonInterval::days(24)->daysExcludeWeeks;//3echoCarbonInterval::weeks(3)->days(14)->weeks;//2<--dayssetteroverwritesthecurrentvalueechoCarbonInterval::weeks(3)->weeks;//3echoCarbonInterval::minutes(3)->weeksAndDays(2,5);//2weeks5days3minutes

$ci=CarbonInterval::create('P1Y2M3D');var_dump($ci->isEmpty());//bool(false)$ci=newCarbonInterval('PT0S');var_dump($ci->isEmpty());//bool(true)

借助方法，可以从人性化的弦创建碳间隔fromString()。

CarbonInterval::fromString('2minutes15seconds');CarbonInterval::fromString('2m15s');//orabbreviated

请注意，月份缩写为“mo”以区别分钟，并且整个语法不区分大小写。

CarbonInterval::setLocale('fr');echoCarbonInterval::create(2,1)->forHumans();//2ans1moisechoCarbonInterval::hour()->seconds(3);//1heure3secondesCarbonInterval::setLocale('en');

如您所见，您可以使用更改字符串的语言环境CarbonInterval::setLocale('fr')。

至于Carbon，您可以使用make方法从其他间隔或字符串中返回CarbonInterval的新实例：

$interval=CarbonInterval::make('7h55m');$interval->add(CarbonInterval::make('17h35m'));$interval->subtract(10,'minutes');//add(),sub()andsubtract()cantakeDateInterval,CarbonInterval,intervalasstringor2argumentsfactorandunit$interval->times(3);echo$interval->forHumans();//72hours240minutesecho"\n";$interval->shares(7);echo$interval->forHumans();//10hours34minutesecho"\n";//Asyoucanseeadd(),times()andshares()operatenaivelyaroundedcalculationoneachunit//Youalsocanusemultiply()ofdivide()tocascadeunitsandgetprecisecalculation:echoCarbonInterval::make('19h55m')->multiply(3)->forHumans();//2days11hours45minutesecho"\n";echoCarbonInterval::make('19h55m')->divide(3)->forHumans();//6hours38minutes20seconds

您可以从输入单位中获得纯计算。要将分钟分为几小时，将几小时变为几天等，请使用级联方法：

echo$interval->forHumans();//10hours34minutesecho$interval->cascade()->forHumans();//10hours34minutes

默认因素是：

是否可以将间隔转换为给定的单位（使用提供的级联系数）。

echoCarbonInterval::days(3)->hours(5)->total('hours');//77echoCarbonInterval::days(3)->hours(5)->totalHours;//77echoCarbonInterval::months(6)->totalWeeks;//24echoCarbonInterval::year()->totalDays;//336

->total方法和属性需要级联间隔，如果间隔可能溢出，请在调用以下功能之前将它们级联：

echoCarbonInterval::minutes(1200)->cascade()->total('hours');//20echoCarbonInterval::minutes(1200)->cascade()->totalHours;//20

您还可以通过以下方式获得该inverval的ISO8601规范spec()

echoCarbonInterval::days(3)->hours(5)->spec();//P3DT5H

也可以从DateInterval对象中获取它，直到静态帮助器为止：

echoCarbonInterval::getDateIntervalSpec(newDateInterval('P3DT6M10S'));//P3DT6M10S

可以通过compare()和compareDateIntervals()方法对日期间隔列表进行排序：

$halfDay=CarbonInterval::hours(12);$oneDay=CarbonInterval::day();$twoDay=CarbonInterval::days(2);echoCarbonInterval::compareDateIntervals($oneDay,$oneDay);//0echo$oneDay->compare($oneDay);//0echoCarbonInterval::compareDateIntervals($oneDay,$halfDay);//1echo$oneDay->compare($halfDay);//1echoCarbonInterval::compareDateIntervals($oneDay,$twoDay);//-1echo$oneDay->compare($twoDay);//-1$list=[$twoDay,$halfDay,$oneDay];usort($list,['Carbon\CarbonInterval','compareDateIntervals']);echoimplode(',',$list);//12hours,1day,2days

将间隔值转储为具有以下内容的数组：

$interval=CarbonInterval::months(2)->hours(12)->seconds(50);//Allthevalues:print_r($interval->toArray());/*Array([years]=>0[months]=>2[weeks]=>0[days]=>0[hours]=>12[minutes]=>0[seconds]=>50[microseconds]=>0)*///Valuessequencefromthebiggesttothesmallestnon-zeroones:print_r($interval->getValuesSequence());/*Array([months]=>2[weeks]=>0[days]=>0[hours]=>12[minutes]=>0[seconds]=>50)*///Non-zerovalues:print_r($interval->getNonZeroValues());/*Array([months]=>2[hours]=>12[seconds]=>50)*/

最后，可以通过toPeriod()使用互补参数调用将CarbonInterval实例转换为CarbonPeriod实例。

我听到你问什么是CarbonPeriod实例。哦!完美过渡到下一章。

CarbonPeriod可以通过多种方式构造：

日期可以作为DateTime/Carbon实例，绝对字符串（例如“2007-10-1515:00”）或相对字符串（例如“下周一”）给出。间隔可以指定为DateInterval/CarbonInterval实例，ISO8601间隔规范（例如“P4D”）或人类可读的字符串（例如“4days”）。

默认构造函数和create()方法在参数类型和顺序方面是非常宽容的，因此，如果您想更精确地建议使用流利的语法。另一方面，您可以传递值的动态数组，createFromArray()该数组将使用给定数组作为参数列表来构造新实例。

$period=CarbonPeriod::create('2018-04-21','3days','2018-04-27');foreach($periodas$key=>$date){if($key){echo',';}echo$date->format('m-d');}//04-21,04-24,04-27echo"\n";//Hereiswhathappensunderthehood:$period->rewind();//restarttheiterationwhile($period->valid()){//checkifcurrentitemisvalidif($period->key()){//echocommaifcurrentkeyisgreaterthan0echo',';}echo$period->current()->format('m-d');//echocurrentdate$period->next();//movetothenextitem}//04-21,04-24,04-27

可以在迭代期间修改参数：

$period=CarbonPeriod::create('2018-04-29',7);$dates=[];foreach($periodas$key=>$date){if($key===3){$period->invert()->start($date);//invert()isanaliasforinvertDateInterval()}$dates[]=$date->format('m-d');}echoimplode(',',$dates);//04-29,04-30,05-01,05-02,05-01,04-30,04-29

请注意，本机DatePeriod将重复次数视为重复间隔的次数。因此，如果不包括开始日期，结果将少一。在CarbonPeriod中引入了自定义过滤器后，更加难以知道结果的数量。因此，我们对实现进行了一些更改，并且将重复作为返回日期总数的整体限制。

//Possibleoptionsare:CarbonPeriod::EXCLUDE_START_DATE|CarbonPeriod::EXCLUDE_END_DATE//Defaultvalueis0whichwillhavethesameeffectaswhennooptionsaregiven.$period=CarbonPeriod::createFromIso('R4/2012-07-01T00:00:00Z/P7D',CarbonPeriod::EXCLUDE_START_DATE);$dates=[];foreach($periodas$date){$dates[]=$date->format('m-d');}echoimplode(',',$dates);//07-08,07-15,07-22,07-29

您可以使用多种吸气剂从该期间检索数据：

其他获取器使您可以将结果作为数组访问：

$period=CarbonPeriod::create('2010-05-11','2010-05-13');echo$period->count();//3,equivalenttocount($period)echo"\n";echoimplode(',',$period->toArray());//2010-05-1100:00:00,2010-05-1200:00:00,2010-05-1300:00:00echo"\n";echo$period->first();//2010-05-1100:00:00echo"\n";echo$period->last();//2010-05-1300:00:00

请注意，如果您打算使用上述功能，则最好将toArray()调用结果存储到变量中并改用它，因为每个调用都在内部执行完整的迭代。

要更改参数，可以使用setter方法：

$period=CarbonPeriod::create('2010-05-01','2010-05-14',CarbonPeriod::EXCLUDE_END_DATE);$period->setStartDate('2010-05-11');echoimplode(',',$period->toArray());//2010-05-1100:00:00,2010-05-1200:00:00,2010-05-1300:00:00echo"\n";//Secondargumentcanbeoptionallyusedtoexcludethedatefromtheresults.$period->setStartDate('2010-05-11',false);$period->setEndDate('2010-05-14',true);echoimplode(',',$period->toArray());//2010-05-1200:00:00,2010-05-1300:00:00,2010-05-1400:00:00echo"\n";$period->setRecurrences(2);echoimplode(',',$period->toArray());//2010-05-1200:00:00,2010-05-1300:00:00echo"\n";$period->setDateInterval('PT12H');echoimplode(',',$period->toArray());//2010-05-1112:00:00,2010-05-1200:00:00

您可以使用setOptions()替换所有选项来更改选项，但也可以单独更改它们：

$period=CarbonPeriod::create('2010-05-06','2010-05-25');var_dump($period->isStartExcluded());//bool(false)var_dump($period->isEndExcluded());//bool(false)$period->toggleOptions(CarbonPeriod::EXCLUDE_START_DATE,true);//true,falseornothingtoinverttheoptionvar_dump($period->isStartExcluded());//bool(true)var_dump($period->isEndExcluded());//bool(false)(unchanged)$period->excludeEndDate();//specifyfalsetoinclude,trueoromittoexcludevar_dump($period->isStartExcluded());//bool(true)(unchanged)var_dump($period->isEndExcluded());//bool(true)$period->excludeStartDate(false);//specifyfalsetoinclude,trueoromittoexcludevar_dump($period->isStartExcluded());//bool(false)var_dump($period->isEndExcluded());//bool(true)

您可以检查两个周期是否重叠：

$period=CarbonPeriod::create('2010-05-06','2010-05-25');var_dump($period->overlaps('2010-05-22','2010-06-03'));//bool(true)$period2=CarbonPeriod::create('2010-05-22','2010-05-24');var_dump($period->overlaps($period2));//bool(true)$period=CarbonPeriod::create('2010-05-0612:00','2010-05-25');$start=Carbon::create('2010-05-0605:00');$end=Carbon::create('2010-05-0611:59');var_dump($period->overlaps($start,$end));//bool(false)

如前所述，根据ISO8601规范，重复是间隔应重复的次数。因此，本机DatePeriod将根据排除的开始日期来改变返回日期的数量。同时，CarbonPeriod在输入方面更为宽容，并允许自定义过滤器，将重复性视为返回日期数的整体限制：

$period=CarbonPeriod::createFromIso('R4/2012-07-01T00:00:00Z/P7D');$days=[];foreach($periodas$date){$days[]=$date->format('d');}echo$period->getRecurrences();//4echoimplode(',',$days);//01,08,15,22$days=[];$period->setRecurrences(3)->excludeStartDate();foreach($periodas$date){$days[]=$date->format('d');}echo$period->getRecurrences();//3echoimplode(',',$days);//08,15,22$days=[];$period=CarbonPeriod::recurrences(3)->sinceNow();foreach($periodas$date){$days[]=$date->format('Y-m-d');}echoimplode(',',$days);//2020-02-14,2020-02-15,2020-02-16

DatePeriod返回的日期可以轻松过滤。过滤器可用于例如跳过某些日期或仅在工作日或周末进行迭代。过滤器功能应返回true接受日期，false跳过日期但继续搜索或CarbonPeriod::END_ITERATION结束迭代。

$period=CarbonPeriod::between('2000-01-01','2000-01-15');$weekendFilter=function($date){return$date->isWeekend();};$period->filter($weekendFilter);$days=[];foreach($periodas$date){$days[]=$date->format('m-d');}echoimplode(',',$days);//01-01,01-02,01-08,01-09,01-15

您也可以在循环内跳过一个或多个值。

$period=CarbonPeriod::between('2000-01-01','2000-01-10');$days=[];foreach($periodas$date){$day=$date->format('m-d');$days[]=$day;if($day==='01-04'){$period->skip(3);}}echoimplode(',',$days);//01-01,01-02,01-03,01-04,01-08,01-09,01-10

$period=CarbonPeriod::end('2000-01-01')->recurrences(3);var_export($period->getFilters());/*array(0=>array(0=>'Carbon\\CarbonPeriod::filterEndDate',1=>NULL,),1=>array(0=>'Carbon\\CarbonPeriod::filterRecurrences',1=>NULL,),)*/

筛选器存储在堆栈中，可以使用一组特殊的方法进行管理：

$period=CarbonPeriod::between('2000-01-01','2000-01-15');$weekendFilter=function($date){return$date->isWeekend();};var_dump($period->hasFilter($weekendFilter));//bool(false)$period->addFilter($weekendFilter);var_dump($period->hasFilter($weekendFilter));//bool(true)$period->removeFilter($weekendFilter);var_dump($period->hasFilter($weekendFilter));//bool(false)//Toavoidstoringfiltersasvariablesyoucannameyourfilters:$period->prependFilter(function($date){return$date->isWeekend();},'weekend');var_dump($period->hasFilter('weekend'));//bool(true)$period->removeFilter('weekend');var_dump($period->hasFilter('weekend'));//bool(false)

添加过滤器的顺序可能会影响性能和结果，因此可以用来addFilter()在堆栈末尾添加过滤器。您可以prependFilter()在开始时添加一个。您甚至可以setFilters()用来更换所有过滤器。请注意，您必须保持正确的堆栈格式，并记住有关重复发生限制和结束日期的内部过滤器。或者，您可以使用resetFilters()方法，然后一个接一个地添加新的过滤器。

例如，当您添加一个限制尝试日期数量的自定义过滤器时，如果在工作日过滤器之前或之后添加结果，结果将有所不同。

//NotethatyoucanpassanameofanyCarbonmethodstartingwith"is",includingmacros$period=CarbonPeriod::between('2018-05-03','2018-05-25')->filter('isWeekday');$attempts=0;$attemptsFilter=function()use(&$attempts){return++$attempts<=5true:CarbonPeriod::END_ITERATION;};$period->prependFilter($attemptsFilter,'attempts');$days=[];foreach($periodas$date){$days[]=$date->format('m-d');}echoimplode(',',$days);//05-03,05-04,05-07$attempts=0;$period->removeFilter($attemptsFilter)->addFilter($attemptsFilter,'attempts');$days=[];foreach($periodas$date){$days[]=$date->format('m-d');}echoimplode(',',$days);//05-03,05-04,05-07,05-08,05-09

请注意，内置的重复发生过滤器无法通过这种方式工作。相反，它基于当前密钥，每个密钥仅递增一次，无论找到有效日期之前必须检查多少个日期。如果将其放在堆栈的开头或结尾，此技巧将使其工作相同。

添加了一些别名以简化CarbonPeriod的构建：

CarbonPeriod可以轻松转换为人类可读的字符串并符合ISO8601规范：

$period=CarbonPeriod::create('2000-01-0112:00','3days12hours','2000-01-1512:00');echo$period->toString();//Every3daysand12hoursfrom2000-01-0112:00:00to2000-01-1512:00:00echo"\n";echo$period->toIso8601String();//2000-01-01T12:00:00+00:00/P3DT12H/2000-01-15T12:00:00+00:00

定期使用并默认返回Carbon实例，但是您可以轻松地设置/获取要使用的日期类，例如以获取不可变的日期或任何实现CarbonInterface的类。

$period=newCarbonPeriod;$period->setDateClass(CarbonImmutable::class);$period->every('3days12hours')->since('2000-01-0112:00')->until('2000-01-1512:00');echo$period->getDateClass();//Carbon\CarbonImmutableecho"\n";echo$period->getStartDate();//2000-01-0112:00:00echo"\n";echoget_class($period->getStartDate());//Carbon\CarbonImmutable

CarbonPeriod具有forEach()和map()辅助方法：

$period=CarbonPeriod::create('2018-04-21','3days','2018-04-27');$dates=$period->map(function(Carbon$date){return$date->format('m-d');});//OrwithPHP7.4://$dates=$period->map(fn(Carbon$date)=>$date->format('m-d'));$array=iterator_to_array($dates);//$datesisaiterable\Generatorvar_dump($array);echoimplode(',',$array);/*array(3){[0]=>string(5)"04-21"[1]=>string(5)"04-24"[2]=>string(5)"04-27"}04-21,04-24,04-27*/echo"\n";//Hereiswhathappensunderthehood:$period->forEach(function(Carbon$date){echo$date->format('m-d')."\n";});/*04-2104-2404-27*/

与所有其他Carbon类一样，CarbonPeriod有一种cast()方法可以将其转换：

$period=CarbonPeriod::create('2000-01-0112:00','3days12hours','2000-01-1512:00');//ItwouldalsoworksifyourclassextendsDatePeriodclassMyPeriodextendsCarbonPeriod{}echoget_class($period->cast(MyPeriod::class));//MyPeriod//ShortcuttoexportasrawDatePeriod:echoget_class($period->toDatePeriod());//DatePeriod

您可以检查期间是否跟随自己。期间甲如下周期乙如果的第一次迭代日期乙等于的最后一次迭代日期甲+的间隔甲。例如，[2019-02-01=>2019-02-16]下面的示例[2019-01-15=>2019-01-31]（假设通过该时段的开始和结束均未排除，并以（1天）为间隔）。

$a=CarbonPeriod::create('2019-01-15','2019-01-31');$b=CarbonPeriod::create('2019-02-01','2019-02-16');var_dump($b->follows($a));//bool(true)var_dump($a->isFollowedBy($b));//bool(true)//->isConsecutiveWith($period)istrueifiteither->follows($period)or->isFollowedBy($period)var_dump($b->isConsecutiveWith($a));//bool(true)var_dump($a->isConsecutiveWith($b));//bool(true)

$period=CarbonPeriod::create('2019-01-15','2019-01-31');var_dump($period->contains('2019-01-22'));//bool(true)

比较包括开始和结束，除非您在选项中排除它们，并且就此而言contains()，排除只排除确切的日期，因此：

$period=CarbonPeriod::create('2019-01-15','2019-01-31',CarbonPeriod::EXCLUDE_END_DATE);var_dump($period->contains('2019-01-3100:00:00'));//bool(false)var_dump($period->contains('2019-01-3023:59:59'));//bool(true)

您可以使用开始/结束比较方法（忽略排除项）进行更精确的比较：

虽然区域时区（“大陆/城市”）可以具有DST，因此一年中的偏移量可变，但偏移量时区具有固定的固定偏移量：

$tz=CarbonTimeZone::create('+03:00');//fullstring$tz=CarbonTimeZone::create(3);//orhourintegershortwayecho$tz->getName();//+03:00echo"\n";echo$tz;//+03:00echo"\n";//toRegionNamewilltrytoguesswhatregionitcouldbe:echo$tz->toRegionName();//Europe/Helsinkiecho"\n";//toguesswithDSToff:echo$tz->toRegionName(null,0);//Europe/Moscowecho"\n";//toOffsetNamewillgivetheinitialoffsetnomatterthedate:echo$tz->toOffsetName();//+03:00echo"\n";echo$tz->toOffsetName($winter);//+03:00echo"\n";echo$tz->toOffsetName($summer);//+03:00

您还可以将区域时区相互转换为偏移时区。

$tz=newCarbonTimeZone(7);echo$tz;//+07:00echo"\n";$tz=$tz->toRegionTimeZone();echo$tz;//Asia/Novosibirskecho"\n";$tz=$tz->toOffsetTimeZone();echo$tz;//+07:00

您可以CarbonTimeZone使用instance()方法根据混合值创建一个。

$tz=CarbonTimeZone::instance(newDateTimeZone('Europe/Paris'));echo$tz;//Europe/Parisecho"\n";//BadtimezonewillreturnfalsewithoutstrictmodeCarbon::useStrictMode(false);$tz=CarbonTimeZone::instance('Europe/Chicago');var_dump($tz);//bool(false)echo"\n";//orthrowanexceptionusingstrictmodeCarbon::useStrictMode(true);try{CarbonTimeZone::instance('Europe/Chicago');}catch(InvalidArgumentException$exception){$error=$exception->getMessage();}echo$error;//Unknownorbadtimezone(Europe/Chicago)//assomevaluecannotbedumpasstringinanerrormessageor//haveuncleardump,youmaypassasecondargumenttodisplay//insteadintheerrorsCarbon::useStrictMode(true);try{$mixedValue=['dummy','array'];CarbonTimeZone::instance($mixedValue,json_encode($mixedValue));}catch(InvalidArgumentException$exception){$error=$exception->getMessage();}echo$error;//Unknownorbadtimezone(["dummy","array"])

如果您打算从Carbon1迁移到Carbon2，请注意以下重要更改，您应该注意。