laravel中Carbon包的使用詳解

介紹

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	tz(null)	根據格式化時間字符串和指定時區, 創建Carbon實例
instance（static）	DateTime $dt	根據 DateTime實例創建Carbon實例
parse（static）	tz(null)	根據格式化時間字符串和指定時區, 創建Carbon實例
create（static）	month(null), hour(null), second(null), $tz(null)	根據日期和時間創建Carbon實例 如果指定參數為null，會默認使用當前時間的對應值
createSafe（static）	month(null), hour(null), second(null), $tz(null)	根據日期和時間創建Carbon實例 如果指定參數為null，會默認使用當前時間的對應值; 指定參數不符合規范，會返回異常；
createFromDate（static）	month(null), tz(null)	根據日期創建Carbon實例如果指定參數為null，會默認使用當前時間的對應值
createFromTime（static）	minute(null), tz(null)	根據時間創建Carbon實例如果指定參數為null，會默認使用當前時間的對應值
createFromFormat（static）	time, $tz（null）	根據時間字符串及其對應的format字符串創建Carbon實例
createFromTimestamp（static）	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	dayOfWeek	重置當前實例時間為 本月第n周的指定dayOfWeek，同時設置 0時0分0秒
lastOfMonth	$dayOfWeek(null)	重置當前實例時間為 本月最后一周的指定dayOfWeek，同時設置 0時0分0秒
firstOfQuarter	$dayOfWeek(null)	重置當前實例時間為 當前季度第一周的指定dayOfWeek，同時設置 0時0分0秒
nthOfQuarter	dayOfWeek	重置當前實例時間為 當前季度第n周的指定dayOfWeek，同時設置 0時0分0秒
lastOfQuarter	$dayOfWeek(null)	重置當前實例時間為 當前季度最后一周的指定dayOfWeek，同時設置 0時0分0秒
firstOfYear	$dayOfWeek(null)	重置當前實例時間為 本年第一周的指定dayOfWeek，同時設置 0時0分0秒
nthOfYear	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 dt2, $equal(true)	判斷當前Carbon實例是否在指定Carbon對象時間之間， 第三個參數表示是否可以等於指定Carbon對象
min	Carbon $dt	獲取當前實例與指定Carbon對象中，最小的對象
minimum	Carbon $dt	同min
max	Carbon $dt	獲取當前實例與指定Carbon對象中，最大的對象
maximum	Carbon $dt	同max
closest	Carbon dt2	獲取最接近當前實例時間的Carbon對象
farthest	Carbon dt2	獲取最不接近當前實例時間的Carbon對象
isSameAs	dt	判斷當前實例與指定Carbon對象的format格式化結果是否相同
isSameDay	Carbon $dt	判斷當前實例與指定Carbon對象是否是同一天
isSameMonth	Carbon 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 abs(true)	獲取指定Carbon對象與當前實例時間的秒數差，前者 - 后者； abs表示是否返回絕對值
secondsSinceMidnight	''	獲取當前實例時間的 0時0分0秒 與當前實例時間的秒差
secondsUntilEndOfDay	''	獲取當前實例時間的 23時59分59秒 與當前實例時間的秒差
diffInMinutes	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的分鍾差, 取整
diffInHours	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的小時差, 取整
diffInHoursFiltered	Closure dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的(通過回調函數較驗的)小時差, 取整
diffInDays	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的天數差, 取整
diffInDaysFiltered	Closure dt(null), $abs(true)	獲取指定Carbon對象與當前實例時間的(通過回調函數較驗的)天數差, 取整
diffInWeekdays	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的工作日數差, 取整
diffInWeekendDays	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的雙休日數差, 取整
diffInWeeks	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的星期數差, 取整
diffInMonths	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的月數差, 取整
diffInYears	Carbon abs(true)	獲取指定Carbon對象與當前實例時間的年數差, 取整
diffFiltered	CarbonInterval callback, Carbon abs(true)	獲取指定Carbon對象與當前實例時間的(通過回調函數較驗的)$ci差, 取整
diffForHumans	Carbon 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	value	魔術方法

CarbonInterval

用途：生成CarbonInterval實例

方法名	參數	描述
__construct	months(null), days(null), minutes(null), $seconds(null)	創建CarbonInterval實例
create（static）	months(null), days(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	days	為當前實例的dayz變量賦值為($weeks * Carbon::DAYS_PER_WEEK) + $days