介绍
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 |