刨刨 Carbon API

介紹

Carbon是對PHP DateTime模塊的二次擴展；提供時間格式化，時間計算的功能；

• 官方主頁爲 http://carbon.nesbot.com/;

• Github地址爲 https://github.com/briannesbitt/Carbon;

文件結構

目錄	描述
-- src	Carbon源文件
-- src\Carbon	Carbon源文件
-- src\Carbon\CarbonInterval.php	DateInterval類的二次擴展類CarbonInterval；主要用於時差計算；
-- src\Carbon\Carbon.php	DateTime類的二次擴展類Carbon；提供時間計算，格式化輸出的功能；
-- src\Carbon\Exceptions	自定義異常文件夾
-- src\Carbon\Lang	語言本地化文件夾；Carbon類的diffForHumans方法會用到；
-- tests	Carbon測試用例文件
-- tests\AbstractTestCase.php	全部測試文件的父類；提供了執行前初始化和執行後清理的功能, 及其它公共的API；
-- tests\Carbon	針對src\\Carbon\\Carbon.php的測試用例組
-- tests\CarbonInterval	針對src\\Carbon\\CarbonInterval.php的測試用例組
-- tests\Localization	針對src\\Carbon\\Lang的測試用例組

API 細則

本篇涉及 API 爲 Carbon 1.22.1 版本；

Carbon

用途：生成Carbon實例

方法名	參數	描述
__construct	$time(null), $tz(null)	根據格式化時間字符串和指定時區, 建立Carbon實例
instance（static）	DateTime $dt	根據 DateTime實例建立Carbon實例
parse（static）	$time(null), $tz(null)	根據格式化時間字符串和指定時區, 建立Carbon實例
create（static）	$year(null), $month(null), $day(null), $hour(null), $minute(null), $second(null), $tz(null)	根據日期和時間建立Carbon實例 若是指定參數爲null，會默認使用當前時間的對應值
createSafe（static）	$year(null), $month(null), $day(null), $hour(null), $minute(null), $second(null), $tz(null)	根據日期和時間建立Carbon實例 若是指定參數爲null，會默認使用當前時間的對應值; 指定參數不符合規範，會返回異常；
createFromDate（static）	$year(null), $month(null), $day(null), $tz(null)	根據日期建立Carbon實例若是指定參數爲null，會默認使用當前時間的對應值
createFromTime（static）	$hour(null), $minute(null), $minute(null), $tz(null)	根據時間建立Carbon實例若是指定參數爲null，會默認使用當前時間的對應值
createFromFormat（static）	$format, $time, $tz（null）	根據時間字符串及其對應的format字符串建立Carbon實例
createFromTimestamp（static）	$timestamp, $tz(null)	根據時間戳和指定時區, 建立Carbon實例
createFromTimestampUTC（static）	$timestamp	根據時間戳和utc時區, 建立Carbon實例
now（static）	$tx(null)	根據當前時間建立Carbon實例
today（static）	$tx(null)	根據當前時間建立Carbon實例，時間重置爲 0時0分0秒
tomorrow（static）	$tx(null)	根據當前時間，加一天，建立Carbon實例
yesterday（static）	$tx(null)	根據當前時間， 減一天， 建立Carbon實例
minValue（static）	''	建立系統支持的最小時間，並返回Carbon實例
maxValue（static）	''	建立系統支持的最大時間，並返回Carbon實例
copy	''	複製當前Carbon實例
fromSerialized（static）	$value	解析序列化字符串，建立Carbon實例

用途：修改Carbon實例

方法名	參數	描述
setDate	$year, $month, $day	設置當前實例的年，月，日
setDateTime	$year, $month, $day, $hour, $minute, $second(0)	設置當前實例的年，月，日，時，分，秒
setTimeFromTimeString	$time	根據 H:i:s 字符串設置當前實例時間
timestamp	$value	根據時間戳設置當前實例時間
second	$value	設置當前實例時間指定秒
minute	$value	設置當前實例時間指定分鐘
hour	$value	設置當前實例時間指定小時
day	$value	設置當前實例時間指定天
month	$value	設置當前實例時間指月份
year	$value	設置當前實例時間指定年份
startOfDay	''	重置當前實例時間爲 0時0分0秒
endOfDay	''	重置當前實例時間爲 23時59分59秒
startOfWeek	''	重置當前實例時間爲 本週的第一天，同時設置 0時0分0秒
endOfWeek	''	重置當前實例時間爲 本週的最後一天，同時設置 23時59分59秒
startOfMonth	''	重置當前實例時間爲 本月第一天，同時設置 0時0分0秒
endOfMonth	''	重置當前實例時間爲 本月最後一天，同時設置 23時59分59秒
startOfQuarter	''	重置當前實例時間爲 本季度第一天，同時設置 0時0分0秒
endOfQuarter	''	重置當前實例時間爲 本季度最後一天，同時設置 23時59分59秒
startOfYear	''	重置當前實例時間爲 本年第一天，同時設置 0時0分0秒
endOfYear	''	重置當前實例時間爲 本年最後一天，同時設置 23時59分59秒
startOfDecade	''	重置當前實例時間爲 所在十年的第一天，同時設置 0時0分0秒
endOfDecade	''	重置當前實例時間爲 所在十年的最後一天，同時設置 23時59分59秒
startOfCentury	''	重置當前實例時間爲 本世紀的第一天，同時設置 0時0分0秒
endOfCentury	''	重置當前實例時間爲 本世紀的最後一天，同時設置 23時59分59秒
next	$dayOfWeek(null)	重置當前實例時間爲 下一個指定dayOfWeek，同時設置 0時0分0秒
previous	$dayOfWeek(null)	重置當前實例時間爲 上一個指定dayOfWeek，同時設置 0時0分0秒
nextWeekday	''	重置當前實例時間爲 下一個工做日，同時設置 0時0分0秒
previousWeekday	''	重置當前實例時間爲 上一個工做日，同時設置 0時0分0秒
nextWeekendDay	''	重置當前實例時間爲 下一個雙休日，同時設置 0時0分0秒
previousWeekendDay	''	重置當前實例時間爲 上一個雙休日，同時設置 0時0分0秒
firstOfMonth	$dayOfWeek(null)	重置當前實例時間爲 本月第一週的指定dayOfWeek，同時設置 0時0分0秒
nthOfMonth	$nth, $dayOfWeek	重置當前實例時間爲 本月第n周的指定dayOfWeek，同時設置 0時0分0秒
lastOfMonth	$dayOfWeek(null)	重置當前實例時間爲 本月最後一週的指定dayOfWeek，同時設置 0時0分0秒
firstOfQuarter	$dayOfWeek(null)	重置當前實例時間爲 當前季度第一週的指定dayOfWeek，同時設置 0時0分0秒
nthOfQuarter	$nth, $dayOfWeek	重置當前實例時間爲 當前季度第n周的指定dayOfWeek，同時設置 0時0分0秒
lastOfQuarter	$dayOfWeek(null)	重置當前實例時間爲 當前季度最後一週的指定dayOfWeek，同時設置 0時0分0秒
firstOfYear	$dayOfWeek(null)	重置當前實例時間爲 本年第一週的指定dayOfWeek，同時設置 0時0分0秒
nthOfYear	$nth, $dayOfWeek	重置當前實例時間爲 本年第n周的指定dayOfWeek，同時設置 0時0分0秒
lastOfYear	$dayOfWeek(null)	重置當前實例時間爲 本年最後一週的指定dayOfWeek，同時設置 0時0分0秒
average	Carbon $dt	重置當前實例時間爲 與指定Carbon對象的中間時刻
modify	$modify	按modify字符串重置當前實例時間

用途：格式化時間

方法名	參數	描述
__toString	''	按變量$toStringFormat的格式輸出
toDateString	''	日期格式化輸出
toTimeString	''	時間格式化輸出
toDateTimeString	''	日期時間格式化輸出
toDayDateTimeString	''	格式化輸出如 "Fri, Jan 3, 2013 10:50 PM"
toAtomString	''	格式化輸出如 "2012-10-20T14:12:26+00:00"
toCookieString	''	格式化輸出如 "Friday, 02-Jan-2012 14:20:39 UTC"
toIso8601String	''	同 toAtomString
toRfc822String	''	格式化輸出如 "Mon, 15 Aug 05 15:52:01 +0000"
toRfc850String	''	格式化輸出如 "Monday, 15-Aug-05 15:52:01 UTC"
toRfc1036String	''	格式化輸出如 "2005-08-15T15:52:01+0000"
toRfc1123String	''	格式化輸出如 "Mon, 15 Aug 2005 15:52:01 +0000"
toRfc2822String	''	格式化輸出如 "Mon, 15 Aug 05 15:52:01 +0000"
toRfc3339String	''	同 toAtomString
toRssString	''	格式化輸出如 "Mon, 15 Aug 2005 15:52:01 +0000"
toW3cString	''	格式化輸出如 "2005-08-15T15:52:01+00:00"
toFormattedDateString	''	格式化輸出如 "Jan 11, 1999"
formatLocalized	$format	指定格式本地化輸出

用途：時間判斷

方法名	參數	描述
eq	Carbon $dt	判斷當前Carbon實例與指定Carbon對象時間是否同樣
equalTo	Carbon $dt	同 eq 方法
ne	Carbon $dt	判斷當前Carbon實例與指定Carbon對象時間是否不相同
notEqualTo	Carbon $dt	同 ne 方法
gt	Carbon $dt	判斷當前Carbon實例是否大於指定Carbon對象時間
greaterThan	Carbon $dt	同 gt 方法
gte	Carbon $dt	判斷當前Carbon實例是否大於等於指定Carbon對象時間
greaterThanOrEqualTo	Carbon $dt	同 gte 方法
lt	Carbon $dt	判斷當前Carbon實例是否小於指定Carbon對象時間
lessThan	Carbon $dt	同 lt 方法
lte	Carbon $dt	判斷當前Carbon實例是否小於等於指定Carbon對象時間
lessThanOrEqualTo	Carbon $dt	同 lte 方法
between	Carbon $dt1, Carbon $dt2, $equal(true)	判斷當前Carbon實例是否在指定Carbon對象時間之間， 第三個參數表示是否能夠等於指定Carbon對象
min	Carbon $dt	獲取當前實例與指定Carbon對象中，最小的對象
minimum	Carbon $dt	同min
max	Carbon $dt	獲取當前實例與指定Carbon對象中，最大的對象
maximum	Carbon $dt	同max
closest	Carbon $dt1, Carbon $dt2	獲取最接近當前實例時間的Carbon對象
farthest	Carbon $dt1, Carbon $dt2	獲取最不接近當前實例時間的Carbon對象
isSameAs	$format, Carbon $dt	判斷當前實例與指定Carbon對象的format格式化結果是否相同
isSameDay	Carbon $dt	判斷當前實例與指定Carbon對象是不是同一天
isSameMonth	Carbon $dt(null), $ofSameYear(false)	判斷當前實例與指定Carbon對象月份是否相同
isBirthday	Carbon $dt	判斷當前實例與指定Carbon對象月日數是否相同
isSameYear	Carbon $dt	判斷當前實例與指定Carbon對象年份是否相同
isSunday	''	判斷當前實例是不是週日
isMonday	''	判斷當前實例是不是週一
isTuesday	''	判斷當前實例是不是週二
isWednesday	''	判斷當前實例是不是週三
isThursday	''	判斷當前實例是不是週四
isFriday	''	判斷當前實例是不是週五
isSaturday	''	判斷當前實例是不是週六
isYesterday	''	判斷當前實例是不是昨天
isToday	''	判斷當前實例是不是今天
isTomorrow	''	判斷當前實例是不是明天
isWeekday	''	判斷當前實例是否屬於工做日
isWeekend	''	判斷當前實例是否屬於週末雙休
isLastWeek	''	判斷當前實例是否屬於上週
isNextWeek	''	判斷當前實例是否屬於下一週
isLastMonth	''	判斷當前實例是否屬於上一個月
isCurrentMonth	''	判斷當前實例是否屬於當前月
isNextMonth	''	判斷當前實例是否屬於下一個月
isLastYear	''	判斷當前實例是否屬於去年
isCurrentYear	''	判斷當前實例是否屬於當前年
isNextYear	''	判斷當前實例是否屬於下一年
isLeapYear	''	判斷當前實例是否屬於閏年
isLongYear	''	判斷當前實例是否屬於終年，即一年不僅有52個星期
isPast	''	判斷當前實例是否屬於過去
isFuture	''	判斷當前實例是否屬於將來

用途：時間計算

方法名	參數	描述
addSecond	$value(1)	當前實例添加指定數量的秒數，返回當前實例
subSecond	$value(1)	當前實例減去指定數量的秒數，返回當前實例
addSeconds	$value	同addSecond
subSeconds	$value	同subSecond
addMinute	$value(1)	當前實例添加指定數量的分鐘數，返回當前實例
subMinute	$value(1)	當前實例減去指定數量的分鐘數，返回當前實例
addMinutes	$value	同addMinute
subMinutes	$value	同subMinute
addHour	$value(1)	當前實例添加指定數量的小時數，返回當前實例
subHour	$value(1)	當前實例減去指定數量的小時數，返回當前實例
addHours	$value	同addHour
subHours	$value	同subHour
addDay	$value(1)	當前實例添加指定數量的天數，返回當前實例
subDay	$value(1)	當前實例減去指定數量的天數，返回當前實例
addDays	$value	同addDay
subDays	$value	同subDay
addWeekday	$value(1)	當前實例添加指定數量的工做日數，返回當前實例
subWeekday	$value(1)	當前實例減去指定數量的工做日數，返回當前實例
addWeekdays	$value	同addWeekday
subWeekdays	$value	同subWeekday
addWeek	$value(1)	當前實例添加指定數量的星期數，返回當前實例
subWeek	$value(1)	當前實例減去指定數量的星期數，返回當前實例
addWeeks	$value	同addWeek
subWeeks	$value	同subWeek
addMonth	$value(1)	當前實例添加指定數量的月數，返回當前實例
subMonth	$value(1)	當前實例減去指定數量的月數，返回當前實例
addMonths	$value	同addMonth
subMonths	$value	同subMonth
addMonthWithOverflow(1)	$value(1)	當前實例添加指定數量的月數（可溢出），返回當前實例
subMonthWithOverflow(1)	$value(1)	當前實例添加指定數量的月數（可溢出），返回當前實例
addMonthsWithOverflow	$value	同addMonthWithOverflow
subMonthsWithOverflow	$value	同subMonthWithOverflow
addMonthNoOverflow(1)	$value(1)	當前實例添加指定數量的月數（不可溢出），返回當前實例
subMonthNoOverflow(1)	$value(1)	當前實例添加指定數量的月數（不可溢出），返回當前實例
addMonthsNoOverflow	$value	同addMonthNoOverflow
subMonthsNoOverflow	$value	同subMonthNoOverflow
addQuarter(1)	$value(1)	當前實例添加指定數量的季度數，返回當前實例
subQuarter(1)	$value(1)	當前實例減去指定數量的季度數，返回當前實例
addQuarters	$value	同addQuarter
subQuarters	$value	同subQuarter
addYear(1)	$value(1)	當前實例添加指定數量的年數，返回當前實例
subYear(1)	$value(1)	當前實例減去指定數量的年數，返回當前實例
addYears	$value	同addYear
subYears	$value	同subYear
addCentury(1)	$value(1)	當前實例添加指定數量的世紀數，返回當前實例
subCentury(1)	$value(1)	當前實例減去指定數量的世紀數，返回當前實例
addCenturies	$value	同addCentury
subCenturies	$value	同subCentury

用途：時間差值比較

方法名	參數	描述
diffInSeconds	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的秒數差，前者 - 後者； abs表示是否返回絕對值
secondsSinceMidnight	''	獲取當前實例時間的 0時0分0秒 與當前實例時間的秒差
secondsUntilEndOfDay	''	獲取當前實例時間的 23時59分59秒 與當前實例時間的秒差
diffInMinutes	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的分鐘差, 取整
diffInHours	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的小時差, 取整
diffInHoursFiltered	Closure $callback, Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的(經過回調函數較驗的)小時差, 取整
diffInDays	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的天數差, 取整
diffInDaysFiltered	Closure $callback, Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的(經過回調函數較驗的)天數差, 取整
diffInWeekdays	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的工做日數差, 取整
diffInWeekendDays	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的雙休日數差, 取整
diffInWeeks	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的星期數差, 取整
diffInMonths	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的月數差, 取整
diffInYears	Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的年數差, 取整
diffFiltered	CarbonInterval $ci， Closure $callback, Carbon $dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的(經過回調函數較驗的)$ci差, 取整
diffForHumans	Carbon $other(null), $absolute(false), $short(false)	獲取指定Carbon對象與當前實例時間的時間差，以便於人類閱讀的格式呈現

用途：Getter & Setter

方法名	參數	描述
getDays（static）	''	獲取days of the week
getWeekStartsAt（static）	''	獲取一週的第一天
setWeekStartsAt（static）	$day	設置一週的第一天
getWeekEndsAt（static）	''	獲取一週的最後一天
setWeekEndsAt（static）	$day	設置一週的最後一天
getWeekendDays（static）	''	獲取雙休日（數組）
setWeekendDays（static）	$days	設置雙休日
getTranslator（static）	''	獲取translator實例
setTranslator（static）	TranslatorInterface $translator	設置translator實例
getLocale（static）	''	獲取當前本地化語言
setLocale（static）	$locale	設置當前本地化語言
timezone	$value	設置時區
tz	$value	設置時區
setTimezone	$value	設置時區
setToStringFormat（static）	$format	設置變量$toStringFormat
resetToStringFormat（static）	''	設置變量$toStringFormat爲默認值
setTestNow（static）	$testNow(null)	設置變量$testNow，測試專用，初始化時的$now
getTestNow（static）	''	獲取變量$testNow
hasTestNow（static）	''	判斷$testNow是否爲空

用途：其它

方法名	參數	描述
setUtf8（static）	$utf8	設置是否採用 utf8 編碼方式
getLastErrors（static）	''	獲取無效時間的錯誤格式模板
serialize	''	返回當前實例的序列化字符串
hasRelativeKeywords（static）	$time	判斷字符串中是否有指定的關鍵字
shouldOverflowMonths（static）	''	獲取變量$monthsOverflow
useMonthsOverflow（static）	$monthsOverflow(true)	設置變量$monthsOverflow
resetMonthsOverflow（static）	''	重置變量$monthsOverflow爲 true
__get	$name	魔術方法
__isset	$name	魔術方法
__set	$name, $value	魔術方法

CarbonInterval

用途：生成CarbonInterval實例

方法名	參數	描述
__construct	$years(1), $months(null), $weeks(null), $days(null), $hours(null), $minutes(null), $seconds(null)	建立CarbonInterval實例
create（static）	$years(1), $months(null), $weeks(null), $days(null), $hours(null), $minutes(null), $seconds(null)	建立CarbonInterval實例
second(static)	$value	建立 CarbonInterval 實例
seconds(static)	$value	建立 CarbonInterval 實例
minute(static)	$value	建立 CarbonInterval 實例
minutes(static)	$value	建立 CarbonInterval 實例
hour(static)	$value	建立 CarbonInterval 實例
hours(static)	$value	建立 CarbonInterval 實例
day(static)	$value	建立 CarbonInterval 實例
days(static)	$value	建立 CarbonInterval 實例
dayz(static)	$value	建立 CarbonInterval 實例
week(static)	$value	建立 CarbonInterval 實例
weeks(static)	$value	建立 CarbonInterval 實例
month(static)	$value	建立 CarbonInterval 實例
months(static)	$value	建立 CarbonInterval 實例
year(static)	$value	建立 CarbonInterval 實例
years(static)	$value	建立 CarbonInterval 實例
instance(static)	$value	建立 CarbonInterval 實例

用途：本地化

方法名	參數	描述
translator（static）	''	初始化translator實例
getTranslator（static）	''	獲取translator實例
setTranslator（static）	TranslatorInterface $translator	設置translator實例
getLocale（static）	''	獲取當前本地化語言
setLocale（static）	$locale	設置當前本地化語言

用途：計算

方法名	參數	描述
add	DateInterval $interval	將指定DateInterval的時間疊加到當前實例

用途：格式化

方法名	參數	描述
spec	''	獲取規範的間隔描述字符串
forHumans	''	獲取便於人類閱讀的間隔描述字符串
__toString	''	同forHumans

用途：其它

方法名	參數	描述
__get	''	魔術方法；可操做變量有years/months/dayz/hours/minutes/seconds/weeks/daysExcludeWeeks/dayzExcludeWeeks
__set	''	魔術方法；可操做變量有years/months/dayz/hours/minutes/seconds/weeks/daysExcludeWeeks/dayzExcludeWeeks
__call	''	魔術方法；可操做方法有years/year/months/month/weeks/week/days/dayz/day/hours/hour/minutes/minute/seconds/second
weeksAndDays	$weeks, $days	爲當前實例的dayz變量賦值爲($weeks * Carbon::DAYS_PER_WEEK) + $days