Clock

Factory for creating datetime objects.

What

It's really as simple as the name suggests: this is a clock, used to indicate what time it is.

Since it produces DateTime objects, this clock is somewhat special in the sense that it can also read the date.

Why

• As soon as you use "unadulterated" datetime objects in your code, any test you've written for it immediately risks being flaky, because if there's a tiny bit of time between new DateTime and your assertion, the test fails.
• Instantiating a new DateTime or new DateTimeImmutable in client code, is a static invocation. This introduces coupling and reduces testability. This obviously goes double for date_create() and the like.
• It's a lot more natural to get the time from a clock than to instantiate a new instant each time you want to know how late it is.

Installing

Install with composer require stratadox/clock

Examples

Clock example

In a service that needs to know the time:

<?phpnamespaceYour\Project;
useStratadox\Clock\Clock;
class SomeFactory
{
private$clock;
publicfunction__construct(Clock$clock)
{
$this->clock = $clock;
}
publicfunctioncreateSomething(): Something
{
returnnewSomething($this->clock->now());
}
}
class Something
{
private$creationDate;
publicfunction__construct(\DateTimeInterface$creationDate)
{
$this->creationDate = $creationDate;
}
publicfunctioncreationDate(): \DateTimeInterface
{
return$this->creationDate;
}
}

Rewindable clock example

In a service that needs to rewind or fast-forward the clock:

<?phpnamespaceYour\Project;
useStratadox\Clock\RewindableClock;
class Scheduler
{
private$clock;
publicfunction__construct(RewindableClock$clock)
{
$this->clock = $clock;
}
publicfunctionscheduleForTheNextThreeHours(): Schedule
{
returnnewSchedule(
newActivity($this->clock->now()),
newActivity($this->clock->fastForward(new \DateInterval('PT1H'))->now()),
newActivity($this->clock->fastForward(new \DateInterval('PT2H'))->now())
);
}
publicfunctionwhenDoIWantThisOnMyDesk(): \DateTimeInterface
{
return$this->clock->rewind(new \DateInterval('P1D'))->now();
}
}

Choosing a clock

The default implementation is the DateTimeClock. It produces a new DateTimeImmutable object whenever now is called.

If the datetime object needs to be passed into something that has a DateTime type hint, or otherwise relies on mutable datetime objects, it is preferable to solve that issue. For example by replacing the DateTime hint with DateTimeIterface or DateTimeImmutable, or passing along a RewindableClock. In cases where that is not an option, the DateTimeMutableClock clock can be used instead.

In case timezones are important in your context, there is also a TimeZoneAwareClock, which takes a timezone as constructor parameter.

To prevent the clock from ticking while other code is running, your tests can instantiate and inject an UnmovingClock.

In a service definition:

<?phpuseStratadox\Clock\Clock;
useStratadox\Clock\DateTimeClock;
$container->set(Clock::class, function () {
return DateTimeClock::create();
});

In a unit test:

<?phpuseYour\Project\SomeFactory;
usePHPUnit\Framework\TestCase;
useStratadox\Clock\UnmovingClock;
class SomethingTest extends TestCase
{
publicfunctiontestCreatingSomething(): void
{
$testTime = newDateTimeImmutable('1-1-1960');
$factory = newSomeFactory(
UnmovingClock::standingStillAt($testTime)
);
$something = $factory->createSomething();
$this->assertEquals($testTime, $something->creationDate());
}
}

When the clock needs to be able to rewind or fast-forward, use the RewindableDateTimeClock implementation.

In a service definition:

<?phpuseStratadox\Clock\RewindableClock;
useStratadox\Clock\RewindableDateTimeClock;
$container->set(RewindableClock::class, function () {
return RewindableDateTimeClock::create();
});

In a unit test:

<?phpuseYour\Project\Scheduler;
usePHPUnit\Framework\TestCase;
useStratadox\Clock\RewindableDateTimeClock;
useStratadox\Clock\UnmovingClock;
class SchedulerTest extends TestCase
{
publicfunctiontestWhenItShouldBeOnTheirDesk(): void
{
$scheduler = newScheduler(
RewindableDateTimeClock::using(UnmovingClock::standingStillAt(
newDateTimeImmutable('16-5-1991')
))
);
$this->assertEquals(
newDateTimeImmutable('15-5-1991'),
$scheduler->whenDoIWantThisOnMyDesk()
);
}
}

Here's an overview of which clock to use when:

Clock	When to use
DateTimeClock	In most situations
DateTimeMutableClock	When you can't use DateTimeImmutable
TimeZoneAwareClock	When the default timezone isn't enough
TimeZoneAwareMutableClock	When both two previous reasons apply
UnmovingClock	During testing
RewindableDateTimeClock	If the clock needs to be set back or forth

Note that the rewindable clock can be combined with any other clocks, in order to produce, for instance, rewinded mutable datetime objects in a particular timezone.