README

Chrono 是一个与系统时钟解耦的 PHP 日期和时间库。

composer require icecave/chrono

原理

PHP 核心库中的许多日期和时间操作需要访问系统状态，例如当前墙时间或时区数据库等资源。这些硬编码的依赖关系使得在处理与时间相关的操作时编写良好抽象和可测试的代码变得非常困难。

Chrono 提供了一组与系统完全解耦的日期和时间类，因此它们的行为是一致的，无论系统状态和配置如何（例如，date.timezone INI 指令）。

在执行任何全局日期和时间操作之前，必须显式构建一个 SystemClock 实例。需要使用时钟的类可以接受一个 ClockInterface 作为 依赖，提高了解耦和可测试性。

概念

• 时钟：时间测量的工厂。
• 时间：具有时间组件的历法测量。
• 日期：具有日期组件的历法测量。
• 时间点：时间连续体上的离散点。
• 时间跨度：一个未锚定的时间跨度。
• 间隔：两个 时间点 之间的时间跨度。

实现

• 系统时钟：使用系统时钟进行历法测量的工厂。
• 测试时钟：可用于测试目的的手动操作的时钟。
• 日期：表示日期。模拟了 时间点 和 日期 概念。
• 一天中的时间：表示一天中的时间。模拟了 时间 概念。
• 日期时间：表示特定日期的一天中的时间。模拟了 时间点、日期 和 时间 概念。
• 间隔：两个 时间点 之间的时间跨度。模拟了 间隔 概念。
• 月份：一个月的时间跨度。模拟了 间隔 概念。
• 年份：一年的时间跨度。模拟了 间隔 概念。
• 持续时间：以秒为单位测量的时间跨度，没有开始或结束。模拟了 时间跨度 概念。
• Period：以组件形式指定的时段时间（例如：3个月，4天），模拟了时段时间概念。

示例

获取当前时间

为了获取当前时间，您需要使用一个时钟。在大多数生产代码中，您将使用SystemClock类，该类使用机器的当前系统时间和时区信息。

use Icecave\Chrono\Clock\SystemClock;

// Construct a new system clock ...
$clock = new SystemClock;

// Obtain a DateTime instance representing the current date and time ...
$now = $clock->localDateTime();

// Obtain a Date instance representing the current date ...
$today = $clock->localDate();

// Obtain the current time of day ...
$timeOfDay = $clock->localTime();

上面显示的每个时钟方法都有一个UTC对应方法。例如，要获取当前的UTC时间，可以使用以下代码

$nowUtc = $clock->utcDateTime();

字符串格式化

要生成表示Date、DateTime、TimeOfDay或TimeZone实例的格式化字符串，请使用format()方法。

输出使用与PHP的内置date()函数相同的格式。

$now = $clock->localDateTime();
$string = $now->format('Y-m-d H:i:s');

将对象转换为字符串（或调用isoString()）将生成一个ISO-8601字符串表示。

Unix时间戳

Date和DateTime实例可以通过使用fromUnixTime()静态方法从Unix时间戳生成。可以使用unixTime()检索Unix时间戳。

$dateTime = DateTime::fromUnixTime(1367823963);
$timestamp = $dateTime->unixTime();

PHP原生的"DateTime"对象

Date和DateTime实例可以通过使用fromNativeDateTime()静态方法从原生的PHP DateTime实例生成，并可以使用nativeDateTime()转换为原生的DateTime。

use DateTime as NativeDateTime;
use Icecave\Chrono\DateTime;

$dateTime = DateTime::fromNativeDateTime(new NativeDateTime);
$nativeDateTime = $dateTime->nativeDateTime();