README

PHP7 日期/时间库。

先决条件

• PHP 7.0+

安装

通过 Composer 安装

要使用 Composer 安装 datetime，请运行以下命令

$ composer require krixon/datetime

您可以在 Packagist 上看到这个库。

从源代码安装

# HTTP
$ git clone https://github.com/krixon/datetime.git
# SSH
$ git clone git@github.com:krixon/datetime.git

简介

这个库是 PHP 内置日期和时间类的包装层，提供了额外的功能和改进，例如微秒精度和不可变性（避免了 \DateTime、\DateTimeImmutable 和 DateTimeInterface 之间的不一致性）。

创建日期

有各种方式来创建一个新的 DateTime 实例。

使用当前时间和默认时区

// These objects all represent the current time.
$date = DateTime::now();
$date = DateTime::create();
$date = new DateTime();

使用 UNIX 时间戳

// Standard (second) precision.
DateTime::fromTimestamp(1499789008)->format('Y-m-d H:i:s.u');
// 2017-07-11 16:03:28.000000

// Millisecond precision.
DateTime::fromTimestampWithMilliseconds(1499789008123)->format('Y-m-d H:i:s.u');
// 2017-07-11 16:03:28.123000

// Microsecond precision.
DateTime::fromTimestampWithMicroseconds(1499789008123456)->format('Y-m-d H:i:s.u');
// 2017-07-11 16:03:28.123456

使用指定的格式解析字符串

$date = DateTime::fromFormat('Y-m-d H:i:s.u', '2017-07-11 16:03:28.123456');

解析包含任何 支持的日期和时间格式 的字符串

$date = DateTime::create('yesterday');
$date = DateTime::create('1 month ago');
$date = DateTime::create('first day of January 2008');
$date = DateTime::create('+5 weeks');
$date = DateTime::create('Monday next week');
// etc

使用现有的内置 \DateTime 实例

$date = DateTime::fromInternalDateTime(new \DateTime());

使用现有的 \IntlCalendar 实例

$calendar = \IntlCalendar::createInstance();
$calendar->setTime(1499789008123);
$date = DateTime::fromIntlCalendar($calendar);

修改日期

所有 DateTime 实例都是不可变的。然而，提供了创建应用了修改的新实例的方法。

调整日期

$date = DateTime::create('21st March 2017 09:45:00');

$date->withDateAt(2016, 09, 15); // 2016-09-15 09:45:00

// Any components not specified will not be changed.
$date->withDateAt(null, null, 15); // 2017-01-15 09:45:00

// There are also methods for setting the components individually.
$date->withYear(1981);           // 1981-03-21 09:45:00
$date->withMonth(DateTime::JAN); // 2017-01-21 09:45:00
$date->withDay(15);              // 2017-03-15 09:45:00

// Convenience methods for common date adjustments.
$date->withDateAtStartOfYear();                       // 2017-01-01 00:00:00
$date->withDateAtStartOfMonth();                      // 2017-03-01 00:00:00
$date->withDateAtEndOfMonth();                        // 2017-03-31 00:00:00
$date->withDateAtDayOfWeekInMonth(DateTime::TUE, 4);  // 2017-03-28 00:00:00 (4th Tuesday in March 2017)
$date->withDateAtDayOfWeekInMonth(DateTime::MON, -2); // 2017-03-20 00:00:00 (Penultimate Tuesday in March 2017)
$date->withDateAtStartOfWeek('en_GB');                // 2017-03-20 00:00:00 (Monday, start of the week of 21st Match 2017 in Great Britain).
$date->withDateAtStartOfWeek('en_US');                // 2017-03-19 00:00:00 (Sunday, start of the week of 21st Match 2017 in USA).

如果您正在对 DateTime 进行多次更改而不需要中间对象，您可以使用 DateTimeCalculator 类。这个类支持您可以在 DateTime 对象本身上执行的所有操作，但不会产生创建新对象然后丢弃的开销。

例如，假设您想要多次向一个基本日期添加间隔，但您只对最终结果感兴趣。虽然您可以反复调用 $date = $date->add('PT1D')，但更有效的方法是

$calculator = DateTime::create('2017-01-01')->calculator();

for ($i = 0; $i < 50; $i++) {
    $calculator->addInterval('PT1D');
}

$date = $calculator->result(); // 2017-02-19

当然这是一个假设的例子，在现实中您会直接调用 $date = $date->add('PT50D')，但您可以使用计算器执行许多算术运算，这些运算不能通过仅使用 DateTime API 以同样高效的方式完成。