README

一组强大的不可变类，用于处理日期和时间。

简介

此库在原生PHP日期时间类的基础上构建了一个广泛的API，并添加了如LocalDate、LocalTime、YearMonth、MonthDay等缺失的概念。

这些类遵循ISO 8601标准来表示日期和时间概念。

此组件遵循Java的JSR 310（日期和时间API）规范的重要部分。尽管如此，由于技术或实际原因存在一些差异，因此不要期望类和方法名称完全匹配。

所有类都是不可变的，它们可以在不受到影响的情况下安全地传递。

安装

此库可以通过Composer安装。

composer require solodkiy/brick-date-time

要求

此库需要PHP 8.1或更高版本。

关于此分支

虽然此库仍在开发中，但经过良好测试，应该足够稳定，可以在生产环境中使用。

新功能

• 新UtcDateTime类
• Instant::toUtcDateTime()方法
• LocalDateTime::fromSqlFormat()方法
• LocalDateTime::toSqlFormat()方法
• ZonedDateTime::fromSqlFormat()方法
• ZonedDateTime::toSqlFormat()方法
• ZonedDateTime::toUtcDateTime()方法
• ZonedDateTime::toNativeFormat()方法
• ZonedDateTime::toUtcSqlFormat()方法

与brick/date-time的兼容性

概述

主要类

以下类/枚举表示日期时间概念

• DayOfWeek：星期几，如星期一（枚举）
• Duration：以秒和纳秒为单位的持续时间
• Instant：时间点，精确到纳秒
• Interval：两个时间点之间的时间段
• LocalDate：如2014-08-31的独立日期
• LocalDateRange：如2014-01-01/2014-12-31的包含本地日期的范围
• LocalDateTime：不带时区的日期时间，如2014-08-31T10:15:30
• LocalTime：如10:15:30的独立时间
• Month：如一月（枚举）的年月
• MonthDay：不包含年份的月和日的组合，如--12-31
• Period：基于日期的时间量，如'2年，3个月和4天'
• TimeZoneOffset：基于偏移量的时区，如+01:00
• TimeZoneRegion：基于区域的时区，如Europe/London
• Year：公历中的年份
• YearMonth：年和月的组合，如2014-08
• ZonedDateTime：带时区的日期时间，如2014-08-31T10:15:30+01:00。此类在概念上等同于原生的DateTime类
• UtcDateTime：带UTC时区的日期时间，如2014-08-31T10:15:30Z。此类是ZonedDateTime的子类

这些类属于Brick\DateTime命名空间。

时钟

所有对象从Clock实现读取当前时间。以下实现可用

• SystemClock返回系统时间；它是默认时钟
• FixedClock：返回预先配置的时间
• OffsetClock：将偏移量添加到另一个时钟
• ScaleClock：使另一个时钟以比例因子快进

这些类属于 Brick\DateTime\Clock 命名空间。

在您的应用程序中，您可能永远不会触及默认设置，并且始终使用默认时钟

use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

echo LocalDate::now(TimeZone::utc()); // 2017-10-04

然而，在您的测试中，您可能需要将当前时间设置为测试已知条件下的应用程序。为此，您可以选择显式地将 Clock 实例传递给 now() 方法

use Brick\DateTime\Clock\FixedClock;
use Brick\DateTime\Instant;
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

$clock = new FixedClock(Instant::of(1000000000));
echo LocalDate::now(TimeZone::utc(), $clock); // 2001-09-09

或者您可以将所有日期时间类的 默认 时钟更改为。除非提供显式的时钟，否则所有如 now() 之类的所有方法都将使用您提供的默认时钟

use Brick\DateTime\Clock\FixedClock;
use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

DefaultClock::set(new FixedClock(Instant::of(1000000000)));
echo LocalDate::now(TimeZone::utc()); // 2001-09-09

DefaultClock::reset(); // do not forget to reset the clock to the system clock!

此外，还有一些有用的快捷方法来在测试中使用时钟，灵感来自 timecop

• freeze() 将时间冻结到特定的时间点
• travelTo() 前往时间中的一个 Instant，但允许时间从那里继续前进
• travelBy() 通过一个 Duration 时间段在时间中前进，这可能向前（正值）或向后（负值）
• scale() 使时间以给定的速度移动

将时间冻结到特定点

use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::freeze(Instant::of(2000000000));

$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20Z
echo $b, PHP_EOL; // 2033-05-18T03:33:20Z

DefaultClock::reset();

前往特定的时间点

use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::travelTo(Instant::of(2000000000));
$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20.000342Z
echo $b, PHP_EOL; // 2033-05-18T03:33:21.000606Z

DefaultClock::reset();

使时间以给定的速度移动

use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::travelTo(Instant::of(2000000000));
DefaultClock::scale(60); // 1 second becomes 60 seconds

$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20.00188Z
echo $b, PHP_EOL; // 2033-05-18T03:34:20.06632Z

DefaultClock::reset();

如您所见，您甚至可以将 travelTo() 和 scale() 方法结合使用。

请在每个测试后非常小心地 重置 默认时钟！ 如果您使用 PHPUnit，可以在 tearDown() 方法中这样做。

异常

以下异常可能被抛出

• 在执行非法操作时抛出 Brick\DateTime\DateTimeException
• 当 parse() 无效的字符串表示时抛出 Brick\DateTime\Parser\DateTimeParseException

Doctrine 映射

您可以在 Doctrine 实体中使用 brick/date-time 类型，使用 brick/date-time-doctrine 包。

贡献

在提交拉取请求之前，您可以使用以下工具检查代码。如果以下任何工具报告了任何问题，您的 CI 构建将失败。

首先，安装依赖项

composer install

单元测试

运行 PHPUnit 测试

vendor/bin/phpunit

静态分析

运行 Psalm 静态分析

vendor/bin/psalm --no-cache

编码风格

在单独的文件夹中安装 Easy Coding Standard

composer install --working-dir=tools/ecs

运行编码风格分析检查

tools/ecs/vendor/bin/ecs check --config tools/ecs/ecs.php

或直接修复发现的问题

tools/ecs/vendor/bin/ecs check --config tools/ecs/ecs.php --fix

Rector 自动重构

在单独的文件夹中安装 Rector

composer install --working-dir=tools/rector

运行自动重构

tools/rector/vendor/bin/rector --config tools/rector/rector.php