README

此仓库包含PHP FIG PSR-20 时钟实现。

安装

通过Composer包，在Packagist上可用，您可以使用Composer进行安装。

$ composer require vulpes/clock

详细信息

Clock\Clock和Clock\FrozenClock是Clock\ClockInterface和Psr\Clock\ClockInterface的实例。

时钟

时钟从dateTime字符串（默认：now）工作，因此它可以接受strtotime()可以处理的任何值，
以及当调用Clock::now()函数时，其构造函数中DateTimeImmutable可以处理的任何值。

冻结时钟

冻结时钟从DateTimeImmutable对象工作，因此其值永远不会改变，
当调用FrozenClock::now()函数时，它将在时区内始终返回相同的值。

用法

use Clock\ClockInterface; 
use Clock\ClockExceptionInterface; 
use Clock\Clock;
use Clock\FrozenClock;

// with default parameters, the `Clock::dateTime` parameter will
// always be interpreted as a string
$clock = new Clock(
    /* DateTimeInterface|string|int */ dateTime: ClockInterface::NOW,
    /* DateTimeZone|string */          timeZone: ClockInterface::UTC
);

// with default parameters, the `FrozenClock::dateTime` parameter will
// always be interpreted as a DateTimeImmutable object
$clock = new FrozenClock(
    /* DateTimeInterface|string|int|null */ dateTime: 
    new DateTimeImmutable(
        datetime: ClockInterface::NOW, 
        timezone: new DateTimeZone(ClockInterface::UTC)
    )
);

// Clock and FrozenClock are identical in behavior below in this section

$clock->now() // DateTimeImmutable
$clock->now()->format('P'); // +01:00
$clock->now()->getTimezone()->getName(); // UTC

// Clock used UTC default, so here $clock will be the same as $utcClock
$utcClock = $clock->withUTC();
$utcClock->now()->getTimezone()->getName() // UTC

$systemTimezoneClock = $clock->withSystemTimezone();
$systemTimezoneClock->now()->getTimezone()->getName() // (system-timezone)

$withCustomTZ = $clock->withDateTimeZone('Europe/Vatican');
$withCustomTZ = $clock->withDateTimeZone(new DateTimeZone('Europe/Vatican'));
$withCustomTZ->now()->getTimezone()->getName() // Europe/Vatican

$with = $clock->with(new DateTime("1989-01-13"));          
// $with->now()->format("Y-m-d") > "1989-01-13"

$with = $clock->with(new DateTimeImmutable("2011-01-13")); 
// $with->now()->format("Y-m-d") > "2011-01-13"

$with = $clock->with('2022-02-02'); 
// $with->now()->format("Y-m-d") >  "2022-02-02"

$with = $clock->with(1643756400);   
// $with->now()->format("Y-m-d") > ~"2022-02-02"

$with = $clock->with(1111111111);   
// $with->now()->getTimestamp() > 1111111111

$withCustomTZ = $clock->withDateTimeZone(new DateTimeZone('Europe/Vatican'));
$withCustomTZ->now()->getTimezone()->getName() // Europe/Vatican

try {
    $clock = new Clock(dateTime: 'unknown-or-bad-timezone');
    $clock->now();
    // ...
} catch (ClockExceptionInterface) {
    // Failed to parse time string...
}

try {
    $clock = new Clock(timeZone: 'bad-timezone');
} catch (ClockExceptionInterface) {
    // Unknown or bad timezone (unknown datetime zone: "bad-timezone")
}

Clock和FrozenClock在用法上的区别

use Clock\Clock;
use Clock\FrozenClock;

$systemClock = new Clock('now');
$frozenClock = new FrozenClock('now');

$systemClock->now()->format('i:s') // 10:02
$frozenClock->now()->format('i:s') // 10:02

// five minutes and 30 seconds later
$systemClock->now()->format('i:s') // 15:32
$frozenClock->now()->format('i:s') // 10:02

// BUT if you set Clock::dateTime with a timestamp, it will retain
// its value as a string from then on and behave like FrozenClock.
$frozenSystemClock = $systemClock->with($frozenClock)
$frozenSystemClockc // 10:02

// The clock works from a dateTime string (default: `now`), so it
// can take any value that `strtotime()` can handle, and that
// `DateTimeImmutable` in its constructor can handle when calling
// `Clock::now()` function.

$alwaysTomorrow = $systemClock->with('+1 day'); // on 2021-01-01
$alwaysTomorrow->now()->format('Y-m-d') // 2021-01-02

// two days later (on 2021-01-03) - sleep(60 * 60 * 24 * 2)
$alwaysTomorrow->now()->format('Y-m-d') // 2021-01-04