README

一系列PSR-20时钟实现。

目录

• 安装
• 时钟
  • SystemClock - 计算机知道的时间
  • LocalizedClock - 另一个时区中的时钟
  • UTCClock - 应该使用的时钟
  • FrozenClock - 停止移动的时钟（非常适合测试）
  • MinuteClock - 谁在乎秒或更少的时间？
  • WrappingClock - 允许将具有 now() 方法的非时钟包装在时钟中
• 运行测试

安装

composer require beste/clock

时钟

SystemClock

SystemClock 将返回与您使用 new DateTimeImmutable() 一样的时间。返回值的时区由时钟的环境决定，例如，由您的应用程序中配置的时区、之前使用的 date_default_timezone_set() 或 php.ini 中的 date.timezone 的值决定。如果没有明确设置这些，则使用 UTC 时区。

# examples/system_clock.php

use Beste\Clock\SystemClock;

$clock = SystemClock::create();

printf("On your system, the current date and time is %s\n", $clock->now()->format('Y-m-d H:i:s T (P)'));

date_default_timezone_set('America/Los_Angeles');

printf("Now it's %s\n", $clock->now()->format('Y-m-d H:i:s T (P)'));

date_default_timezone_set('Europe/Berlin');

printf("Now it's %s\n", $clock->now()->format('Y-m-d H:i:s T (P)'));

LocalizedClock

本地化时钟知道其所在的时区。虽然 SystemClock 的时区是由环境（您的 PHP 配置）决定的，但此时钟使用您初始化时设置的时区。

# examples/localized_clock.php

use Beste\Clock\LocalizedClock;

$berlin = LocalizedClock::in('Europe/Berlin');
$denver = LocalizedClock::in(new DateTimeZone('America/Denver'));

printf("Berlin: %s\n", $berlin->now()->format('Y-m-d H:i:s T (P)'));
printf("Denver: %s\n", $denver->now()->format('Y-m-d H:i:s T (P)'));

UTCClock

UTC 是协调世界时（CUT）的缩写，是一种不受夏令时影响的特殊时区。它通常用于在不同系统之间（例如，您的 PHP 应用程序和数据库之间或后端和前端之间）的时间通信。一个 UTCClock 实例的行为与 LocalizedClock::in('UTC') 实例的行为完全相同。

# examples/utc_clock.php

use Beste\Clock\UTCClock;

$clock = UTCClock::create();

$anotherTimeZone = 'Africa/Casablanca';

date_default_timezone_set($anotherTimeZone);

printf("The system time zone is %s.\n", $anotherTimeZone);
printf("The clock's time zone is %s.\n", $clock->now()->getTimezone()->getName());

FrozenClock

冻结时钟不会移动 - 我们设置的时间将保持不变...除非我们更改它。这使得冻结时钟非常适合测试基于时间的用例的行为，例如在单元测试中。

# examples/frozen_clock.php

use Beste\Clock\FrozenClock;
use Beste\Clock\SystemClock;

$frozenClock = FrozenClock::withNowFrom(SystemClock::create());

printf("\nThe clock is frozen at %s", $frozenClock->now()->format('Y-m-d H:i:s T (P)'));
printf("\nLet's wait a second…");
sleep(1);
printf("\nIt's one second later, but the clock is still frozen at %s", $frozenClock->now()->format('Y-m-d H:i:s T (P)'));

$frozenClock->setTo($frozenClock->now()->modify('-5 minutes'));
printf("\nAfter turning back the clock 5 minutes, it's %s", $frozenClock->now()->format('Y-m-d H:i:s T (P)'));

MinuteClock

在某些情况下，微秒、毫秒甚至秒对于某些用例来说过于精确 - 有时，如果某事在同一分钟内发生就足够了。使用分钟

# examples/minute_clock.php

use Beste\Clock\FrozenClock;
use Beste\Clock\MinuteClock;

$frozenClock = FrozenClock::at(new DateTimeImmutable('01:23:45'));
$clock = MinuteClock::wrapping($frozenClock);

printf("For %s, the minute clock returns %s\n",
    $frozenClock->now()->format('H:i:s'),
    $clock->now()->format('H:i:s')
);

$frozenClock->setTo($frozenClock->now()->modify('+10 seconds')); // 01:23:55

printf("For %s, the minute clock still returns %s\n",
    $frozenClock->now()->format('H:i:s'),
    $clock->now()->format('H:i:s')
);

WrappingClock

如果您已经有一个具有 now() 方法的对象，返回 DateTimeImmutable 对象，则可以将其包装在 WrappingClock 中以使其成为“真实”的时钟。

作为一个“真实”的时钟。

# examples/wrapping_clock.php

use Beste\Clock\WrappingClock;

// Create a frozen $now so that we can test the wrapping clock.
$now = new DateTimeImmutable('2012-04-24 12:00:00');

// Create an object that is NOT a clock, but has a now() method returning the frozen $now.
$clock = new class($now) {
    private \DateTimeImmutable $now;

    public function __construct(\DateTimeImmutable $now)
    {
        $this->now = $now;
    }

    public function now(): \DateTimeImmutable
    {
        return $this->now;
    }
};

// We can now wrap the object in a clock.
$wrappedClock = WrappingClock::wrapping($clock);

assert($now->format(DATE_ATOM) === $wrappedClock->now()->format(DATE_ATOM));

运行测试

composer test