The Clock Component

Installation

1

$ composer require symfony/clock

Usage

The Clock class returns the current time and allows to use any PSR-20 compatible implementation as a global clock in your application:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

use Symfony\Component\Clock\Clock;
use Symfony\Component\Clock\MockClock;

// by default, Clock uses the NativeClock implementation, but you can change
// this by setting any other implementation
Clock::set(new MockClock());

// Then, you can get the clock instance
$clock = Clock::get();

// Additionally, you can set a timezone
$clock->withTimeZone('Europe/Paris');

// From here, you can get the current time
$now = $clock->now();

// And sleep for any number of seconds
$clock->sleep(2.5);

The Clock component also provides the now() function:

1
2
3
4

use function Symfony\Component\Clock\now;

// Get the current time as a DateTimeImmutable instance
$now = now();

Later on this page you can learn how to use this clock in your services and tests.

Available Clocks Implementations

The Clock component provides some ready-to-use implementations of the ClockInterface, which you can use as global clocks in your application depending on your needs.

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

use Symfony\Component\Clock\ClockInterface;

class ExpirationChecker
{
    public function __construct(
        private ClockInterface $clock
    ) {}

    public function isExpired(DateTimeInterface $validUntil): bool
    {
        return $this->clock->now() > $validUntil;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

use PHPUnit\Framework\TestCase;
use Symfony\Component\Clock\MockClock;

class ExpirationCheckerTest extends TestCase
{
    public function testIsExpired(): void
    {
        $clock = new MockClock('2022-11-16 15:20:00');
        $expirationChecker = new ExpirationChecker($clock);
        $validUntil = new DateTimeImmutable('2022-11-16 15:25:00');

        // $validUntil is in the future, so it is not expired
        static::assertFalse($expirationChecker->isExpired($validUntil));

        // Clock sleeps for 10 minutes, so now is '2022-11-16 15:30:00'
        $clock->sleep(600); // Instantly changes time as if we waited for 10 minutes (600 seconds)

        // modify the clock, accepts all formats supported by DateTimeImmutable::modify()
        static::assertTrue($expirationChecker->isExpired($validUntil));

        $clock->modify('2022-11-16 15:00:00');

        // $validUntil is in the future again, so it is no longer expired
        static::assertFalse($expirationChecker->isExpired($validUntil));
    }
}

Using a Clock inside a Service

Using the Clock component in your services to retrieve the current time makes them easier to test. For example, by using the MockClock implementation as the default one during tests, you will have full control to set the "current time" to any arbitrary date/time.

In order to use this component in your services, make their classes use the ClockAwareTrait. Thanks to service autoconfiguration, the setClock() method of the trait will automatically be called by the service container.

You can now call the $this->now() method to get the current time:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

namespace App\TimeUtils;

use Symfony\Component\Clock\ClockAwareTrait;

class MonthSensitive
{
    use ClockAwareTrait;

    public function isWinterMonth(): bool
    {
        $now = $this->now();

        return match ($now->format('F')) {
            'December', 'January', 'February', 'March' => true,
            default => false,
        };
    }
}

Thanks to the ClockAwareTrait, and by using the MockClock implementation, you can set the current time arbitrarily without having to change your service code. This will help you test every case of your method without the need of actually being in a month or another.

Writing Time-Sensitive Tests

The Clock component provides another trait, called ClockSensitiveTrait, to help you write time-sensitive tests. This trait provides methods to freeze time and restore the global clock after each test.

Use the ClockSensitiveTrait::mockTime() method to interact with the mocked clock in your tests. This method accepts different types as its only argument:

• A string, which can be a date to set the clock at (e.g. 1996-07-01) or an interval to modify the clock (e.g. +2 days);
• A DateTimeImmutable to set the clock at;
• A boolean, to freeze or restore the global clock.

Let's say you want to test the method MonthSensitive::isWinterMonth() of the above example. This is how you can write that test:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

namespace App\Tests\TimeUtils;

use App\TimeUtils\MonthSensitive;
use PHPUnit\Framework\TestCase;
use Symfony\Component\Clock\Test\ClockSensitiveTrait;

class MonthSensitiveTest extends TestCase
{
    use ClockSensitiveTrait;

    public function testIsWinterMonth(): void
    {
        $clock = static::mockTime(new \DateTimeImmutable('2022-03-02'));

        $monthSensitive = new MonthSensitive();
        $monthSensitive->setClock($clock);

        $this->assertTrue($monthSensitive->isWinterMonth());
    }

    public function testIsNotWinterMonth(): void
    {
        $clock = static::mockTime(new \DateTimeImmutable('2023-06-02'));

        $monthSensitive = new MonthSensitive();
        $monthSensitive->setClock($clock);

        $this->assertFalse($monthSensitive->isWinterMonth());
    }
}

This test will behave the same no matter which time of the year you run it. By combining the ClockAwareTrait and ClockSensitiveTrait, you have full control on your time-sensitive code's behavior.