Carbon中文文檔
Introduction
Carbon 是php的日期處理類庫（A simple PHP API extension for DateTime.）。
Carbon 繼承了PHP的 Datetime 類，因此 Carbon 中沒有涉及到的，但在 Datetime 中已經實現的方法都是可使用的。
<?php
namespace Carbon;
class Carbon extends \DateTime
{
// code here
}
Carbon 類聲明在 Carbon 命名空間下，能夠經過引入命名空間的方式來代替每次輸入完整的類名。php
<?php use Carbon\Carbon;
Note:若是在使用 Carbon 時，沒有專門設置時區的話，默認使用 America/Toronto 的時區。
要特別留意是否使用了正確的時區，好比 Carbon 的全部差別比較都使用 UTC 或者系統設定的時區。linux
<?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() 建立的實例進行比較時，默認是在當前時區下完成的。git
Instantiation
有好幾種方式能夠建立 Carbon 的實例，可是你們應該更傾向於經過這種語義化的靜態方法來實現。函數
<?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);
值得注意的是，Carbon 構造器的第二個參數被加強到了不只限因而 DateTimeZone 實例，還能夠是 String、Integer (表示相對於GMT的偏移值)。舉個栗子來講明下 now() 方法。測試
<?php
$now = Carbon::now();
$nowInLondonTz = Carbon::now(new DateTimeZone('Europe/London'));
// or just pass the timezone as a string
$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
你將會喜歡上用 parse() 方法來代替原有繁瑣的構造方式ui
<?php
echo (new Carbon('first day of December 2008'))->addWeeks(2); // 2008-12-15 00:00:00
echo Carbon::parse('first day of December 2008')->addWeeks(2); // 2008-12-15 00:00:00
相似 now() 這樣直接返回 Carbon 實例的方法還有 today(), tomorrow(),yesterday()，他們都接受一個 timezone 類型的參數，最後獲得的結果時間部分都是 00:00:00this
<?php
$now = Carbon::now();
echo $now; // 2016-06-24 15:18:34
$today = Carbon::today();
echo $today; // 2016-06-24 00:00:00
$tomorrow = Carbon::tomorrow('Europe/London');
echo $tomorrow; // 2016-06-25 00:00:00
$yesterday = Carbon::yesterday();
echo $yesterday; // 2016-06-23 00:00:00
下面是一些其餘的 creatXXX() 形式的靜態方法。絕大多數靜態方法的參數是可傳可不傳的，若是不傳的話會使用方法預設的默認值，這些預設值通常都是針對當前日期、時間、時區的。若是爲傳遞某個必要參數，會拋出一個 InvalidArgumentException 類型的異常，用 DateTime::getLastErrors() 方法能夠獲得異常的詳細信息。spa
<?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 的參數都將默認爲當前對應的時間。一樣，時區也默認是當前時區。若是隻設置了小時數沒有設置分秒那麼分秒默認是 0code
<?php
$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();
}
<?php Carbon::createFromFormat($format, $time, $tz);
createFromFormat() 與php的DateTime::createFromFormat。不一樣之處是 $dt 參數能夠是 DateTImeZone 的實例或者一個時區的字符串。而且能夠會返回參數異常的提示。從createXX()的源碼能夠看出，他們都調用了createFromFormat()方法。orm
<?php
echo Carbon::createFromFormat('Y-m-d H', '1975-05-21 22')->toDateTimeString(); // 1975-05-21 22:00:00
最後提到的這兩個create方法都是處理Unix時間戳的。第一個將會返回一個等於預期時間戳的 Carbon 實例，時區能夠設置也能夠選用默認值。第二個方法，createFromTimestampUTC() 與第一個不一樣的是時區將始終是 UTC(GMT) .第一個方法的第二個示例，只是爲了讓這個函數的用法展示的更加明確。Negative timestamps are also allowed.
<?php 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:59
copy() 方法能夠copy一個已經存在的 Carbon 實例。對copy生成實例進行修改並不會影響被copy對象的自己。
<?php $dt = Carbon::now(); echo $dt->diffInYears($dt->copy()->addYear()); // 1 // $dt was unchanged and still holds the value of Carbon:now()
最後，當你正在使用的 DateTime 實例是經過實例化其餘繼承了 DateTime 庫而獲得的，別怕！經過下邊的方式仍然能夠極其友好建立 Carbon 實例。
<?php
$dt = new \DateTime('first day of January 2008'); // <== instance from another API
$carbon = Carbon::instance($dt);
echo get_class($carbon); // 'Carbon\Carbon'
echo $carbon->toDateTimeString(); // 2008-01-01 00:00:00
關於毫秒的一些處理。php自帶的 DateTime 類也能夠設置毫秒，可是在進行日期的數學預算時並不會考慮毫秒。從 Carbon 1.12.0版本起，實例化、copy也能像 format() 方法同樣支持毫秒（PHP默認的只有 Datetime::format() 支持毫秒）。
<?php
$dt = Carbon::parse('1975-05-21 22:23:00.123456');
echo $dt->micro; // 123456
echo $dt->copy()->micro; // 123456
獲取PHP支持的有效時間取值範圍：最先時間、最晚時間
<?php echo Carbon::maxValue(); // '2038-01-18 22:14:07' echo Carbon::minValue(); // '1901-12-13 15:45:52'
Localization
Carbon中，formatLocalized() 方法經過調用 strftime() 方法，彌補了php底層的 DateTime 類不支持區域化設置的缺陷。若是你已經經過使用 setlocale() 方法設置過當前區域，formatLocalized($format) 方法將會按照設置的區域格式進行返回。
<?php
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 的區域語言。
<?php
Carbon::setLocale('de');
echo Carbon::now()->addYear()->diffForHumans(); // in 1 Jahr
Carbon::setLocale('en');
注意:若是在linux系統中轉換出現了問題，請仔細檢查安裝在本地或生產系統中語言環境。
locale -a 列舉出全部可用的語言環境 sudo locale-gen zh_CN.utf8 安裝新的語言環境 sudo dpkg-reconfigure locales 配置啓用新的語言環境，並重啓
Testing Aids()
經過測試方法能夠獲得一個模擬或真實的 Carbon 實例。只有在一下狀況下，主動提供的 Carbon 實例纔會被特殊處理：
- 調用靜態方法 now()，例如： Varbon::now()
- 傳給 construct 或 parse() 方法的是 null (或空字符串)，例如：new Carbon(null)
- 當傳給 construct 或 parse()的是字符串 now，例如：new Carbon(‘now’)
$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();
有用的例子：
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();
一些相關的用法也能夠獲得一個模擬的 now 實例，返回相應的模擬數據。
$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();
如下是當前支持的時間轉換字
- this
- net
- last
- this
- next
- last
- tomorrow
- yesterday
- +
- -
- first
- last
- ago
值得注意的是像 next() , previous() 和 modify() 方法等相關的修改會把日期的時間部分設置成 00:00:00 。
Getters
獲取器經過PHP的 __get() 方式實現。能夠直接經過一下方式直接獲取到屬性的值。
$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/Toronto
Setters
Setters 經過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
此處 Setters 方法的參數是必選參數，Carbon 提供了更多種設置方式可供使用。值得注意的是，全部對於時區的修改都會影響整個到 Carbon 實例。對時間戳進行修改時不會自動轉換到時間戳對應的時區。
$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 實例的屬性時，會首先檢查該屬性是否存在，存在返回 true，不存在返回 false。
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
全部相似 toXXXString() 這樣的方法都依賴於DateTime::format()。__toString() 方法容許 Carbon 實例被打印時以一種可讀性更好的方式被打印出來。
$dt = Carbon::create(1975, 12, 25, 14, 15, 16);
var_dump($dt->toDateTimeString() == $dt); // bool(true) => uses __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
// ... of course format() is still available
echo $dt->format('l jS \\of F Y h:i:s A'); // Thursday 25th of December 1975 02:15:16 PM
另外能夠默認設置 __toString() 方法所要顯示的時間日期格式。
Carbon::setToStringFormat('jS \o\f F, Y g:i:s a');
echo $dt; // 25th of December, 1975 2:15:16 pm
Carbon::resetToStringFormat();
echo $dt; // 1975-12-25 14:15:16
若是須要設定特定的語言顯示，請參考 Localization 部分。
Common Formats
下面是對 DateTime 類提供的通用格式的一些封裝。
$dt = Carbon::now(); // $dt->toAtomString() is the same as $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
Comparison
經過如下方式能夠對兩個 Carbon 實例進行簡單的比較。牢記這些比較都是在UTC時區下完成的。
echo Carbon::now()->tzName; // America/Toronto $first = Carbon::create(2012, 9, 5, 23, 26, 11); $second = Carbon::create(2012, 9, 5, 20, 26, 11, 'America/Vancouver'); echo $first->toDateTimeString(); // 2012-09-05 23:26:11 echo $first->tzName; // America/Toronto echo $second->toDateTimeString(); // 2012-09-05 20:26:11 echo $second->tzName; // America/Vancouver var_dump($first->eq($second)); // bool(true) var_dump($first->ne($second)); // bool(false) var_dump($first->gt($second)); // bool(false) var_dump($first->gte($second)); // bool(true) var_dump($first->lt($second)); // bool(false) var_dump($first->lte($second)); // bool(true) $first->setDateTime(2012, 1, 1, 0, 0, 0); $second->setDateTime(2012, 1, 1, 0, 0, 0); // Remember tz is 'America/Vancouver' var_dump($first->eq($second)); // bool(false) var_dump($first->ne($second)); // bool(true) var_dump($first->gt($second)); // bool(false) var_dump($first->gte($second)); // bool(false) var_dump($first->lt($second)); // bool(true) var_dump($first->lte($second)); // bool(true)
若是要判斷當前實例對應的時間，是否在其餘兩個實例對應的時間之間，能夠用 between() 方法。若是提供了第三個參數，而且爲 true，將會進行 >= 和 <= 的操做。若是爲 false，會進行 > 和 < 的操做。該參數默認是 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)
還記得以前提到的 min() 和 max() 嗎？min() 將會返回兩個實例中時間較早的實例，max() 返回時間較晚的那個。若是沒有提供給 min() 或 max() 任何參數，將會拿當前時間和調用該方法的實例進行比較。
$dt1 = Carbon::create(2012, 1, 1, 0, 0, 0); $dt2 = Carbon::create(2014, 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->max($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
Carbon 提供了一些見名知意的輔助方法去處理大部分用到的場景。須要執行比較操做的方法都會與當前時區的當前時間進行比較。
$dt = Carbon::now(); $dt->isWeekday(); $dt->isWeekend(); $dt->isYesterday(); $dt->isToday(); $dt->isTomorrow(); $dt->isFuture(); $dt->isPast(); $dt->isLeapYear(); $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); var_dump($born->isBirthday($noCake)); // bool(false) var_dump($born->isBirthday($yesCake)); // bool(true) var_dump($overTheHill->isBirthday()); // bool(true) -> default compare it to today!
Addition and Subtraction
默認的DateTime類提供了一對方便增長和減小時間的方法。有 modify()，add() 和 sub() 。modify() 方法接受一個標準的 data/time 字符串，該方法會對字符串進行解析，當牽扯到 add() 和 sub() 時會隱式調用DateInterval類進行處理。用鏈式調用的方式進行操做，代碼將會更加的清晰和易讀。固然，因爲繼承關係這並不會影響你使用底層的方法進行操做。
$dt = Carbon::create(2012, 1, 31, 0); echo $dt->toDateTimeString(); // 2012-01-31 00:00:00 echo $dt->addYears(5); // 2017-01-31 00:00:00 echo $dt->addYear(); // 2018-01-31 00:00:00 echo $dt->subYear(); // 2017-01-31 00:00:00 echo $dt->subYears(5); // 2012-01-31 00:00:00 echo $dt->addMonths(60); // 2017-01-31 00:00:00 echo $dt->addMonth(); // 2017-03-03 00:00:00 equivalent of $dt->month($dt->month + 1); so it wraps echo $dt->subMonth(); // 2017-02-03 00:00:00 echo $dt->subMonths(60); // 2012-02-03 00:00:00 echo $dt->addDays(29); // 2012-03-03 00:00:00 echo $dt->addDay(); // 2012-03-04 00:00:00 echo $dt->subDay(); // 2012-03-03 00:00:00 echo $dt->subDays(29); // 2012-02-03 00:00:00 echo $dt->addWeekdays(4); // 2012-02-09 00:00:00 echo $dt->addWeekday(); // 2012-02-10 00:00:00 echo $dt->subWeekday(); // 2012-02-09 00:00:00 echo $dt->subWeekdays(4); // 2012-02-03 00:00:00 echo $dt->addWeeks(3); // 2012-02-24 00:00:00 echo $dt->addWeek(); // 2012-03-02 00:00:00 echo $dt->subWeek(); // 2012-02-24 00:00:00 echo $dt->subWeeks(3); // 2012-02-03 00:00:00 echo $dt->addHours(24); // 2012-02-04 00:00:00 echo $dt->addHour(); // 2012-02-04 01:00:00 echo $dt->subHour(); // 2012-02-04 00:00:00 echo $dt->subHours(24); // 2012-02-03 00:00:00 echo $dt->addMinutes(61); // 2012-02-03 01:01:00 echo $dt->addMinute(); // 2012-02-03 01:02:00 echo $dt->subMinute(); // 2012-02-03 01:01:00 echo $dt->subMinutes(61); // 2012-02-03 00:00:00 echo $dt->addSeconds(61); // 2012-02-03 00:01:01 echo $dt->addSecond(); // 2012-02-03 00:01:02 echo $dt->subSecond(); // 2012-02-03 00:01:01 echo $dt->subSeconds(61); // 2012-02-03 00:00:00
固然你也能夠傳遞負值到addXXX()方法，實際這正是subXXX()方法所實現的功能。
Difference
如下方法老是返回兩個實例之間的時間差。與基類中的 diff() 方法不一樣的是，diff() 方法會經過DateInterval實例將61秒轉化成1分1秒來返回。下邊的這些方法第一個參數是將會用來比較的 Carbon 實例，默認爲 now() 方法建立的當前時間實例。第二個參數也是可選的,指明瞭你是否須要返回一個比較結果的絕對值，默認爲 true，當第二個參數爲 false，而且用於比較的實例時間早於被比較的實例時，返回負數。全部的比較操做都在UTC時區下完成。
// Carbon::diffInYears(Carbon $dt = null, $abs = true)
echo Carbon::now('America/Vancouver')->diffInSeconds(Carbon::now('Europe/London')); // 0
$dtOttawa = Carbon::createFromDate(2000, 1, 1, 'America/Toronto');
$dtVancouver = Carbon::createFromDate(2000, 1, 1, 'America/Vancouver');
echo $dtOttawa->diffInHours($dtVancouver); // 3
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
一些特殊的過濾方法，像 diffInDaysFiltered() 、diffInHoursFiltered() 和 diffFiltered() ,能夠幫助你過濾時間差中的 days 、hour 或者一個自定義的時間間隔。下邊是統計兩個實例之間的週末天數。
$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
對於人們來講,一月前比30天前更加易與理解。這是一個常見的方法在許多日期處理類庫中，因此他想也應該把這個加進來。這裏把一個月看作四周，這些方法須要一個可選的 Carbon 實例做爲參數來進行比較，默認爲當前時間的實例。
這些方法會在兩個時間差值後增長一寫描述，可能相似下邊這四種：
-
When comparing a value in the past to default now:
- 1 hour ago
- 5 months ago
-
When comparing a value in the future to default now:
- 1 hour from now
- 5 months from now
-
When comparing a value in the past to another value:
- 1 hour before
- 5 months before
-
When comparing a value in the future to another value:
- 1 hour after
- 5 months after
你也能夠傳遞第二個參數去掉相似 ago，from now 這種修飾符，相似這樣的用法 diffForHumans(Carbon $other, true) 等。
// 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’) 來改變語言設置。詳細請參考 localization 部分。
Modifiers
Carbon argument.這些方法組對修改當前實例頗有幫助。你會注意到 startOfXXX()，next()，和 previous() 方法將會設置時間爲 00:00:00，另外 endOfXXX() 方法將會設置時間爲 23:59:59 。
$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
Carbon 中定義瞭如下常量。
// 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
Carbon 類繼承了PHP 的DateInterval類。
<?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 seconds
若是你繼承的 DateInterval 實例來自其餘類庫，別怕，經過 instance() 這種友好的方式你手動能夠建立一個 CarbonInterval 實例。
$di = new \DateInterval('P1Y2M'); // <== instance from another API
$ci = CarbonInterval::instance($di);
echo get_class($ci); // 'Carbon\CarbonInterval'
echo $ci; // 1 year 2 months
其餘的一些輔助方法，但要注意這些輔助方法處理周時，只有天會被保存下來。而且是在當前實例的總天數基礎上計算周。
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 minutes
也有一個方便的 forHumans()，在調用 __toString() 方法時，自動執行，並打印出可讀性更好的時間格式。
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');
固然，你能夠經過 CarbonInterval::setLocale(‘fr’) 來改變語言顯示。
相關文章
- 1. Carbon中文使用手冊
- 2. Carbon Data 文件結構
- 3. golang文檔、中文、學習文檔
- 4. rollup文檔翻譯 中文文檔
- 5. Imagine中文文檔
- 6. axios 中文文檔
- 7. pyqtgraph中文文檔
- 8. JointJS中文文檔
- 9. Express中文文檔
- 10. Spring中文文檔
- 更多相關文章...
- • WSDL 文檔 - WSDL 教程
- • XSL-FO 文檔 - XSL-FO 教程
- • Scala 中文亂碼解決
- • SpringBoot中properties文件不能自動提示解決方法
相關標籤/搜索
每日一句
-
每一个你不满意的现在，都有一个你没有努力的曾经。
歡迎關注本站公眾號,獲取更多信息
相關文章
- 1. Carbon中文使用手冊
- 2. Carbon Data 文件結構
- 3. golang文檔、中文、學習文檔
- 4. rollup文檔翻譯 中文文檔
- 5. Imagine中文文檔
- 6. axios 中文文檔
- 7. pyqtgraph中文文檔
- 8. JointJS中文文檔
- 9. Express中文文檔
- 10. Spring中文文檔