README

PHP 库，提供处理日期和时间的附加功能。🐘 🕒 📅

需求

• PHP 8.3

安装 🌱

composer req fresh/datetime

特性 🎁

常用时间常量

每分钟的秒数，每小时的分钟数等。

use Fresh\DateTime\TimeConstants;

echo TimeConstants::NUMBER_OF_SECONDS_IN_AN_HOUR; // etc.

创建当前 \DateTime 和 \DateTimeImmutable 对象的方法（方便测试）

如果您使用单独的类来创建日期时间对象，您可以在代码中模拟这些方法，并得到所需的 \DateTime 对象。

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$now1 = $dateTimeHelper->getCurrentDatetime();
$now2 = $dateTimeHelper->getCurrentDatetime(new \DateTimeZone('Europe/Kyiv')); // Or with custom timezone
$now3 = $dateTimeHelper->getCurrentDatetimeUtc(); // Always in UTC
$now4 = $dateTimeHelper->getCurrentDatetimeImmutable();
$now5 = $dateTimeHelper->getCurrentDatetimeImmutable(new \DateTimeZone('Europe/Kyiv')); // Or with custom timezone
$now6 = $dateTimeHelper->getCurrentDatetimeImmutableUtc(); // Always in UTC

与 PSR-20: Clock 兼容。

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$now = $dateTimeHelper->now(); // \DateTimeImmutable in UTC

获取当前时间戳的方法

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$timestamp = $dateTimeHelper->getCurrentTimestamp();

从格式创建 \DateTime 或 \DateTimeImmutable 的方法

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

// By default with format Y-m-d H:i:s and UTC timezone
$dateTime = $dateTimeHelper->createDateTimeFromFormat('2000-01-01 00:00:00');
$dateTimeImmutable = $dateTimeHelper->createDateTimeImmutableFromFormat('2000-01-01 00:00:00');

// With custom format
$dateTime = $dateTimeHelper->createDateTimeFromFormat('01.01.2000 00:00:00', 'd.m.Y H:i:s');

// With custom timezone
$dateTime = $dateTimeHelper->createDateTimeFromFormat('01.01.2000 00:00:00', 'd.m.Y H:i:s', new \DateTimeZone('Europe/Kyiv'));

创建 \DateTimeZone 对象的方法

如果您在代码中直接创建 \DateTimeZone 对象，您将无法在测试中进行模拟。因此，有一个专门用于创建时区对象的方法。

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$dateTimeZone1 = $dateTimeHelper->createDateTimeZone(); // UTC by default
$dateTimeZone2 = $dateTimeHelper->createDateTimeZone('Europe/Kyiv'); // Or with custom timezone
$dateTimeZone3 = $dateTimeHelper->createDateTimeZoneUtc(); // Another method to get UTC timezone

不可变 DateRange 值对象

您经常需要处理所谓的日期范围（从/到日期）。从本质上讲，日期范围是一个 ValueObject，它可以被重复多次用于不同的目的。此库提供了一个不可变的 DateRange 类，创建后无法更改。 DateRange 仅与日期操作，忽略时间。

use Fresh\DateTime\DateRange;

$dateRange1 = new DateRange(new \DateTime('yesterday'), new \DateTime('tomorrow'));
$dateRange2 = new DateRange(new \DateTime('yesterday'), new \DateTime('tomorrow', new \DateTimeZone('Europe/Kyiv')));

// There is also the `isEqual` method to compare two DateRange objects.
$dateRange1->isEqual($dateRange2); // Returns FALSE, because date ranges have different timezones

不可变 DateTimeRange 值对象

此库还提供了一个不可变的 DateTimeRange 类，而不是 DateRange，它检查日期和时间。

use Fresh\DateTime\DateTimeRange;

$dateTimeRange1 = new DateTimeRange(new \DateTime('2000-01-01 19:00:00'), new \DateTime('2000-01-01 21:00:00'));
$dateTimeRange2 = new DateTimeRange(new \DateTime('2000-01-01 19:00:00'), new \DateTime('2000-01-01 21:00:00', new \DateTimeZone('Europe/Kyiv')));
$dateTimeRange3 = new DateTimeRange(new \DateTime('2000-01-01 20:00:00'), new \DateTime('2000-01-01 22:00:00'));

// There is also the `isEqual` method to compare two DateTimeRange objects.
$dateTimeRange1->isEqual($dateTimeRange2); // Returns FALSE, because datetime ranges have different timezones

// There is also the `intersects` method to check if datetime range intersected each other.
$dateTimeRange1->intersects($dateTimeRange3); // Returns TRUE, because datetime ranges are intersected

具有交集的日期范围示例

没有交集的日期范围示例

获取日期范围内所有日期的对象/字符串数组

use Fresh\DateTime\DateTimeHelper;
use Fresh\DateTime\DateRange;

$dateTimeHelper = new DateTimeHelper();

$dateRange = new DateRange(new \DateTime('1970-01-01'), new \DateTime('1970-01-03'));

// Creates array with values ['1970-01-01', '1970-01-02', '1970-01-03']
$datesAsStrings = $dateTimeHelper->getDatesFromDateRangeAsArrayOfStrings($dateRange);

// Creates array of \DateTime objects for dates: '1970-01-01', '1970-01-02', '1970-01-03'
$datesAsObjects = $dateTimeHelper->getDatesFromDateRangeAsArrayOfObjects($dateRange);

DateTimeCloner 允许将日期克隆到 \DateTime 或 \DateTimeImmutable 实例中

use Fresh\DateTime\DateTimeCloner;

$dateTimeCloner = new DateTimeCloner();

$date1 = new \DateTime();
$dateImmutable1 = $dateTimeCloner::cloneIntoDateTimeImmutable($date1); // Returns \DateTimeImmutable object
$date2 = $dateTimeCloner::cloneIntoDateTime($dateImmutable1); // Returns \DateTime object

贡献 🤝

查看 CONTRIBUTING 文件。