README

此包旨在使处理时间（如日期、范围和/或持续时间）变得容易。它包含时间值对象、解析器、范围、持续时间、舍入等。

要求

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

安装

您可以通过 composer 安装此包

composer require vdhicts/time

用法

此包旨在提供易于使用，与 PHP 的 DateTime 和 Carbon 有一些相似之处。接口就是一个例子。

时间

可以通过以下方式初始化 Time 对象

$time = new Time(14, 30, 15);

从输入构建

要从几个不同的输入构建 Time 对象，可以使用以下方法

TimeFactory::createFromString('14:30:15'); // Time object with 14 hours, 30 minutes and 15 seconds
TimeFactory::createFromDateTime(new \DateTime('2023-01-01 14:30:15')); // Time object with 14 hours, 30 minutes and 15 seconds
TimeFactory::createFromTimestamp(1640000000); // Time object with 11 hours, 33 minutes and 20 seconds
TimeFactory::createFromDurationInSeconds(9000); // Time object with 2 hours and 30 minutes
TimeFactory::createFromDurationInMinutes(150); // Time object with 2 hours and 30 minutes

比较

Time 对象使比较其他 Time 对象变得容易。它提供了以下方法

$time->isEqualTo(Time $anotherTime);
$time->isBefore(Time $anotherTime);
$time->isBeforeOrEqualTo(Time $anotherTime);
$time->isAfter(Time $anotherTime);
$time->isAfterOrEqualTo(Time $anotherTime);

差异

时间对象还可以用于计算时间对象之间的差异

$timeStart = new Time(10, 30);
$timeEnd = new Time(14);

$timeStart->diffInHours($timeEnd); // 3.5
$timeEnd->diffInHours($timeStart); // -3.5

差异可以按小时（diffInHours）、分钟（diffInMinutes）和秒（diffInSeconds）计算。

持续时间

时间可以是日期的一部分，即 2022-03-01 10:00:00，但也可以用于持续时间，例如：“我花了 1 小时 46 分钟才到达那里。”。

$time = new Time(1, 46);

sprintf('It took me %s hours', $time->durationInHours());
sprintf('It took me %s minutes', $time->durationInMinutes());
sprintf('It took me %s seconds', $time->durationInSeconds());

结果

string(32) "It took me 1.7666666666667 hours"
string(22) "It took me 106 minutes"
string(23) "It took me 6360 seconds"

舍入

处理非常具体的时间可能并不总是您想要的结果，例如用于时间跟踪。此包允许您将时间舍入到您喜欢的精度。默认情况下，它舍入到 5 分钟

$time = new Time(2, 46, 23);

$time->roundNatural(); // 02:45:00
$time->roundUp(); // 02:50:00
$time->roundDown(); // 02:45:00

还可以舍入秒数和/或更改精度。例如，舍入到 15 秒

$time = new Time(2, 21, 33);

$time->roundNatural(15, true); // 02:21:30
$time->roundUp(15, true); // 02:21:45
$time->roundDown(15, true); // 02:21:30

表示

Time 对象可以通过 toString 方法表示为字符串，或者直接将对象转换为字符串 (string)$time。这将输出：14:30:15。

还有两种其他表示方法，即 toNumericalTime 和 toReadableTime

$time = new Time(12, 30, 45);
$time->toNumericalTime(); // 12:50
$time->toNumericalTime(true); // 12:50:75

$time->toReadableTime(); // 12:30
$time->toReadableTime(true); // 12:30:45

时间集合

Time 对象可以收集到 TimeCollection 中。可以通过以下方式初始化 TimeCollection

$timeCollection = new TimeCollection();

可以提供 Time 对象的数组或使用集合上的 add 和 set 方法。contains 方法提供了检查集合是否包含 Time 对象的能力。

时间范围

TimeRange 对象包含两个 Time 对象，一个开始时间和一个结束时间。可以通过以下方式初始化 TimeRange 对象

$timeRange = new TimeRange($time, $anotherTime);

要获取范围的持续时间，可以获取 Time 对象作为持续时间

$timeRange->getRangeDuration();

比较

TimeRange 对象使比较单个 Time 或另一个 TimeRange 变得容易。

要确定 Time 是否在范围内

$time = new Time(14, 30, 15);
$timeRange->inRange($time);

要确定另一个范围是否与范围重叠

$anotherTimeRange = new TimeRange($time, $anotherTime);
$timeRange->isOverlapping($anotherTimeRange);

测试

单元测试位于测试文件夹中。使用以下命令运行：

composer test

如果您需要代码覆盖率报告，该报告将生成在 build/report 文件夹中。使用以下命令运行：

composer test-coverage

贡献

欢迎任何贡献，但它应该符合 PER 2.0 代码风格，并且请为每个功能/错误创建一个拉取请求。作为交换，您将被列为贡献者。

安全性

如果您在此或 Vdhicts 的其他包中发现任何与安全相关的问题，请通过电子邮件 security@vdhicts.nl 联系，而不是使用问题跟踪器。

许可证

此软件包是开源软件，受MIT许可证许可。