New in Symfony 6.2: Clock Component

Contributed by Nicolas Grekas in #46715

Testing time-related functions is difficult and produces transient test errors. That's why we introduced Clock mocking for tests in Symfony 2.8, more than six years ago. In Symfony 6.2 we're expanding those efforts with the introduction of a new component called Clock.

This new component will improve the testability of your time-sensitive code. The PHP-FIG group is working on a similar proposal in PSR-20, so we designed Symfony Clock component to ease compatibility with it.

First, this component defines the following ClockInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13

namespace Symfony\Component\Clock;

interface ClockInterface
{
    // returns the current datetime (it's designed to be compatible with PSR-20)
    public function now(): \DateTimeImmutable;

    // advances the clock by the provided number of seconds
    public function sleep(float|int $seconds): void;

    // changes the time zone returned by now()
    public function withTimeZone(\DateTimeZone|string $timezone): static;
}

In addition to the interface, the component provides three concrete implementations:

• NativeClock, uses the system clock, so it returns the real current time, it sleeps the actual number of seconds given, etc.;
• MockClock, suited for tests, it always returns the same datetime (the one passed to its constructor) and it advances time instantly, without calling to the real sleep() function of PHP;
• MonotonicClock, suited for performance profiling, it uses the monotonic clock provided by PHP via hrtime() function and it sleeps the actual number of seconds given).

Related to this, in Symfony 6.2 we've also improved the existing ClockMock class of PHPUnit Bridge component. In #47295, Christian Flothmann added support for mocking the hrtime() function.