README

FyreDateTime 是一个用于 PHP 的免费、开源、不可变的日期操作库。

它是一个现代库，支持 ICU 格式、时区和地区。

安装

使用 Composer

composer require fyre/datetime

在 PHP 中

use Fyre\DateTime\DateTime;

日期创建

$dateString 是表示日期的字符串，默认为当前时间戳。
$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$dateTime = new DateTime($dateString, $timeZone, $locale);

从数组

$dateArray 是包含年、月、日、小时、分钟、秒和毫秒的数组。
$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$dateTime = DateTime::fromArray($dateArray, $timeZone, $locale);

如果未设置，$dateArray 中的月份和日期将默认为 1。小时、分钟、秒和毫秒将默认为 0。

从 DateTime

$dateTime 是实现了 DateTimeInterface 类的实例。
$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$newDateTime = DateTime::fromDateTime($dateTime, $timeZone, $locale);

从格式

$formatString 是包含您希望用于解析的格式的字符串。
$dateString 是您正在解析的日期的字符串。
$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$formatString 支持在 ICU 规范中描述的令牌。

$dateTime = DateTime::fromFormat($formatString, $dateString, $timeZone, $locale);

从 ISO 字符串

$dateString 是您正在解析的日期的字符串。
$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$dateTime = DateTime::fromISOString($dateString, $timeZone, $locale);

从时间戳

$timestamp 是自 UNIX 纪元以来的秒数。
$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$dateTime = DateTime::fromTimestamp($timestamp, $timeZone, $locale);

现在

$timeZone 是表示日期时区的字符串，默认为系统时区。
$locale 是表示日期地区的字符串，默认为系统地区。

$dateTime = DateTime::now($timeZone, $locale);

日期格式化

格式

一旦创建了 DateTime 对象，您就可以使用 format 方法以特定格式获取字符串表示。

$formatString 是包含您希望使用的输出格式的字符串。

$formatString 支持在 ICU 规范中描述的令牌。

$dateString = $dateTime->format($formatString);

转换为字符串

使用 "eee MMM dd yyyy HH:mm:ss xx (VV)" 格式化当前日期。

$string = $dateTime->toString();

转换为日期字符串

使用 "eee MMM dd yyyy" 格式化当前日期。

$dateString = $dateTime->toDateString();

转换为 ISO 字符串

使用 "yyyy-MM-dd'T'HH:mm:ss.SSSxxx" (以英文和 UTC 时区) 格式化当前日期。

$isoString = $dateTime->toISOString();

转换为时间字符串

使用 "HH:mm:ss xx (VV)" 格式化当前日期。

$timeString = $dateTime->toTimeString();

转换为 UTC 字符串

使用 "eee MMM dd yyyy HH:mm:ss xx (VV)" (在 UTC 时区) 格式化当前日期。

$utcString = $dateTime->toUTCString();

日期属性

获取日期

获取当前时区的日期。

$date = $dateTime->getDate();

获取星期

获取当前时区的星期。

返回的 $day 将在 0 (星期日) 和 6 (星期六) 之间。

$day = $dateTime->getDay();

获取年中的天数

获取当前时区的年中的天数。

返回的 $dayOfYear 将在 0 和 365 之间。

$dayOfYear = $dateTime->getDayOfYear();

获取月份

获取当前时区的月份。

返回的 $month 将在 1 (一月) 和 12 (十二月) 之间。

$month = $dateTime->getMonth();

获取季度

获取当前时区的年份中的季度。

返回的 $quarter 将在 1 和 4 之间。

$quarter = $dateTime->getQuarter();

获取年份

获取当前时区的年份。

$year = $dateTime->getYear();

设置日期

设置当前时区的日期。

$date 是表示日期的数字。

$newDate = $dateTime->setDate($date);

设置日期

在当前时区中设置星期。

$day 是一个表示星期的数字（介于 0 和 6 之间）。

$newDateTime = $dateTime->setDay($day);

设置年度日期

在当前时区中设置年度日期。

$dayOfYear 是一个表示年度日期的数字（介于 0 和 365 之间）。

$newDateTime = $dateTime->setDayOfYear($dayOfYear);

设置月份

在当前时区中设置月份。

$month 是一个表示月份的数字（介于 1 和 12 之间）。
$date 是一个表示日期的数字，默认为当前值。

如果省略 $date 参数，并且新月份的天数少于当前日期，则日期将设置为新月份的最后一天。

要禁用日期限制，请使用方法 DateTime::setDateClamping() 并使用 false 作为参数。

$newDateTime = $dateTime->setMonth($month, $date);

设置季度

在当前时区中设置年度季度。

$quarter 是一个表示季度的数字（介于 1 和 4 之间）。

$newDateTime = $dateTime->setQuarter($quarter);

设置年份

在当前时区中设置年份。

$year 是一个表示年份的数字。
$month 是一个表示月份的数字（介于 1 和 12 之间），默认为当前值。
$date 是一个表示日期的数字，默认为当前值。

如果省略 $date 参数，并且新月份的天数少于当前日期，则日期将设置为新月份的最后一天。

要禁用日期限制，请使用方法 DateTime::setDateClamping() 并使用 false 作为参数。

$newDateTime = $dateTime->setYear($year, $month, $date);

周属性

获取周

获取当前时区中的年度周。

返回的 $week 将介于 1 和 53 之间（周从星期一开始）。

$week = $dateTime->getWeek();

获取星期几

获取当前时区中的本地星期几。

返回的 $weekDay 将介于 1 和 7 之间。

$weekDay = $dateTime->getWeekDay();

获取月份中的星期几

获取当前时区中的月份中的星期几。

返回的 $weekDayInMonth 将介于 1 和 5 之间。

$weekDayInMonth = $dateTime->getWeekDayInMonth();

获取月份中的周

获取当前时区中的月份中的周。

返回的 $weekOfMonth 将介于 1 和 5 之间。

$weekOfMonth = $dateTime->getWeekOfMonth();

获取周年度

获取当前时区中的周年度。

此方法与 getYear() 相同，除非在星期属于上一年或下一年时，则使用该值。

$weekYear = $dateTime->getWeekYear();

设置周

在当前时区中设置周。

$week 是一个表示周的数字。
$weekDay 是一个表示天的数字（介于 1 和 7 之间），默认为当前值。

$newDateTime = $dateTime->setWeek($week, $weekDay);

设置星期几

在当前时区中设置本地星期几。

$weekDay 是一个表示星期几的数字（介于 1 和 7 之间）。

$newDateTime = $dateTime->setWeekDay($weekDay);

设置月份中的星期几

在当前时区中设置月份中的星期几。

$weekDayInMonth 是一个表示月份中星期几的数字（介于 1 和 5 之间）。

$newDateTime = $dateTime->setWeekDayInMonth($weekDayInMonth);

设置月份中的周

在当前时区中设置月份中的周。

$weekOfMonth 是一个表示月份中周的数字（介于 1 和 5 之间）。

$newDateTime = $dateTime->setWeekOfMonth($weekOfMonth);

设置周年度

在当前时区中设置周年度。

$weekYear 是一个表示年份的数字。
$week 是一个表示周的数字，默认为当前值。
$weekDay 是一个表示天的数字（介于 1 和 7 之间），默认为当前值。

$newDateTime = $dateTime->setWeekYear($weekYear, $week, $weekDay);

时间属性

获取小时

获取当前时区中的每日小时数。

返回的 $hours 将介于 0 和 23 之间。

$hours = $dateTime->getHours();

获取毫秒

获取当前时区中的每秒毫秒数。

返回的 $milliseconds 将介于 0 和 999 之间。

$milliseconds = $dateTime->getMilliseconds();

获取分钟

获取当前时区中的每小时分钟数。

返回的 $minutes 将介于 0 和 59 之间。

$minutes = $dateTime->getMinutes();

获取秒

获取当前时区的分钟秒数。

返回的 $seconds 将介于 0 和 59 之间。

$seconds = $dateTime->getSeconds();

设置小时

设置当前时区中一天的小时。

$hours 是表示一天中的小时数（介于 0 和 23）的数字。
$minutes 是表示一小时中的分钟数（介于 0 和 59）的数字，默认为当前值。
$seconds 是表示一分钟中的秒数（介于 0 和 59）的数字，默认为当前值。
$milliseconds 是表示一秒中的毫秒数（介于 0 和 999）的数字，默认为当前值。

$newDateTime = $dateTime->setHours($hours, $minutes, $seconds, $milliseconds);

设置毫秒

设置当前时区中的秒毫秒数。

$milliseconds 是表示一秒中的毫秒数（介于 0 和 999）的数字。

$newDateTime = $dateTime->setMilliseconds($milliseconds);

设置分钟

设置当前时区中一小时中的分钟。

$minutes 是表示一小时中的分钟数（介于 0 和 59）的数字。
$seconds 是表示一分钟中的秒数（介于 0 和 59）的数字，默认为当前值。
$milliseconds 是表示一秒中的毫秒数（介于 0 和 999）的数字，默认为当前值。

$newDateTime = $dateTime->setMinutes($minutes, $seconds, $milliseconds);

设置秒

设置当前时区中的分钟秒数。

$seconds 是表示一分钟中的秒数（介于 0 和 59）的数字。
$milliseconds 是表示一秒中的毫秒数（介于 0 和 999）的数字，默认为当前值。

$newDateTime = $dateTime->setSeconds($seconds, $milliseconds);

时间戳

获取毫秒

获取自 UNIX 纪元以来的毫秒数。

$time = $dateTime->getTime();

获取秒

获取自 UNIX 纪元以来的秒数。

$timestamp = $dateTime->getTimestamp();

设置毫秒

设置自 UNIX 纪元以来的毫秒数。

$newDateTime = $dateTime->setTime($time);

设置秒

设置自 UNIX 纪元以来的秒数。

$newDateTime = $dateTime->setTimestamp($timestamp);

时区

获取时区

获取当前时区的名称。

$timeZone = $dateTime->getTimeZone();

获取时区偏移

获取当前时区的 UTC 偏移（以分钟为单位）。

$offset = $dateTime->getTimeZoneOffset();

设置时区

设置当前时区。

$timeZone 是新时区的名称，可以是 "UTC"，来自 IANA timeZone 数据库的支持值或偏移字符串。

$newDateTime = $dateTime->setTimeZone($timeZone);

设置时区偏移

设置 UTC 偏移（以分钟为单位）。

$offset 是 UTC 偏移（以分钟为单位）。

$newDateTime = $dateTime->setTimeZoneOffset($offset);

地区

获取区域设置

获取当前区域设置的名称。

$locale = $dateTime->getLocale();

设置区域设置

设置当前区域设置。

$locale 是新区域设置的名称。

$newDateTime = $dateTime->setLocale($locale);

操作

添加天数

向当前日期添加一天。

$newDateTime = $dateTime->addDay();

添加天数

向当前日期添加天数。

$amount 是表示要添加的天数的数字。

$newDateTime = $dateTime->addDay($amount);

添加小时

向当前日期添加一小时。

$newDateTime = $dateTime->addHour();

添加小时

向当前日期添加小时。

$amount 是表示要添加的小时数的数字。

$newDateTime = $dateTime->addHours($amount);

添加分钟

向当前日期添加一分钟。

$newDateTime = $dateTime->addMinute();

添加分钟

向当前日期添加分钟。

$amount 是表示要添加的分钟数的数字。

$newDateTime = $dateTime->addMinutes($amount);

添加月份

向当前日期添加一个月。

$newDateTime = $dateTime->addMonth();

添加月份

向当前日期添加月份。

$amount 是表示要添加的月份数字的。

$newDateTime = $dateTime->addMonths($amount);

添加秒

向当前日期添加一秒。

$newDateTime = $dateTime->addSecond();

添加秒

向当前日期添加秒。

$amount 是表示要添加的秒数的数字。

$newDateTime = $dateTime->addSeconds($amount);

添加周

向当前日期添加一周。

$newDateTime = $dateTime->addWeek();

添加周

向当前日期添加周。

$amount 是表示要添加的周数的数字。

$newDateTime = $dateTime->addWeeks($amount);

添加年

向当前日期添加一年。

$newDateTime = $dateTime->addYear();

添加年

向当前日期添加年。

$amount 是表示要添加的年数的数字。

$newDateTime = $dateTime->addYears($amount);

一天结束

将日期设置为当前时区中一天结束的时间。

$newDateTime = $dateTime->endOfDay();

一小时结束

将日期设置为当前时区中一小时结束的时间。

$newDateTime = $dateTime->endOfHour();

一分钟结束

将日期设置为当前时区中一分钟结束的时间。

$newDateTime = $dateTime->endOfMinute();

月末

将日期设置为当前时区的月末。

$newDateTime = $dateTime->endOfMonth();

季度末

将日期设置为当前时区的季度末。

$newDateTime = $dateTime->endOfQuarter();

秒末

将日期设置为当前时区的秒末。

$newDateTime = $dateTime->endOfSecond();

周末

将日期设置为当前时区的周末。

$newDateTime = $dateTime->endOfWeek();

年未

将日期设置为当前时区的年未。

$newDateTime = $dateTime->endOfYear();

日始

将日期设置为当前时区的日始。

$newDateTime = $dateTime->startOfDay();

时始

将日期设置为当前时区的时始。

$newDateTime = $dateTime->startOfHour();

分始

将日期设置为当前时区的分始。

$newDateTime = $dateTime->startOfMinute();

月始

将日期设置为当前时区的月始。

$newDateTime = $dateTime->startOfMonth();

季度始

将日期设置为当前时区的季度始。

$newDateTime = $dateTime->startOfQuarter();

秒始

将日期设置为当前时区的秒始。

$newDateTime = $dateTime->startOfSecond();

周始

将日期设置为当前时区的周始。

$newDateTime = $dateTime->startOfWeek();

年始

将日期设置为当前时区的年始。

$newDateTime = $dateTime->startOfYear();

减日

从当前日期减去一天。

$newDateTime = $dateTime->subtractDay();

减去天数

从当前日期减去指定天数。

$amount 表示要减去的天数。

$newDateTime = $dateTime->subtractDay($amount);

减小时

从当前日期减去一个小时。

$newDateTime = $dateTime->subtractHour();

减去小时数

从当前日期减去指定小时数。

$amount 表示要减去的小时数。

$newDateTime = $dateTime->subtractHours($amount);

减分钟

从当前日期减去一分钟。

$newDateTime = $dateTime->subtractMinute();

减去分钟数

从当前日期减去指定分钟数。

$amount 表示要减去的分钟数。

$newDateTime = $dateTime->subtractMinutes($amount);

减月

从当前日期减去一个月。

$newDateTime = $dateTime->subtractMonth();

减去月数

从当前日期减去指定月数。

$amount 表示要减去的月数。

$newDateTime = $dateTime->subtractMonths($amount);

减秒

从当前日期减去一秒。

$newDateTime = $dateTime->subtractSecond();

减去秒数

从当前日期减去指定秒数。

$amount 表示要减去的秒数。

$newDateTime = $dateTime->subtractSeconds($amount);

减周

从当前日期减去一周。

$newDateTime = $dateTime->subtractWeek();

减去周数

从当前日期减去指定周数。

$amount 表示要减去的周数。

$newDateTime = $dateTime->subtractWeeks($amount);

减年

从当前日期减去一年。

$newDateTime = $dateTime->subtractYear();

减去年数

从当前日期减去指定年数。

$amount 表示要减去的年数。

$newDateTime = $dateTime->subtractYears($amount);

比较

差值

获取两个日期之间的毫秒差。

$other 是用于比较的 DateTime 对象。

$diff = $dateTime->diff($other);

日期差（天数）

获取两个日期之间的天数差。

$other 是用于比较的 DateTime 对象。
$relative 是一个布尔值，表示是否返回相对差值，默认为 true。

$diff = $dateTime->diffInDays($other, $relative);