README

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

简介

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

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

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

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

安装

此库可以通过Composer安装。

composer require brick/date-time

要求

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

项目状态及发布流程

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

当前版本号为0.x.y。当引入非破坏性变更（添加新方法、优化现有代码等）时，y会递增。

当引入破坏性变更时，总是开始新的0.x版本周期。

因此，可以将您的项目锁定到给定的发布周期，例如0.7.*。

如果您需要升级到较新的发布周期，请检查发布历史中每个后续0.x.0版本引入的变更列表。

概述

主要类

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

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类

这些类属于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 映射

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

贡献

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

首先，安装依赖项

composer install

单元测试

运行 PHPUnit 测试

vendor/bin/phpunit

静态分析

在单独的文件夹中安装 Psalm

composer install --working-dir=tools/psalm

运行 Psalm 静态分析

tools/psalm/vendor/bin/psalm --no-cache --config=tools/psalm/psalm.xml

编码风格

在单独的文件夹中安装 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

brick / date-time

维护者

详情