[Clock] Add Clock class and now() function

[nicolas-grekas]

Q	A
Branch?	6.3
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	Fix #48564
License	MIT
Doc PR	-

See discussion on #48564.

This PR adds 2 static methods and one function:

namespace Symfony\Component\Clock;

Clock::get(): ClockInterface;
Clock::set(PsrClockInterface $clock): void;

now(): \DateTimeImmutable;

It also wires this global clock as a service so that injecting the ClockInterface or using now / Clock::get() returns the same time.

Last but not least, this PR also provides a ClockSensitiveTrait to help write test cases that rely on the clock. This trait provides one self::mockTime() method and it restores the global clock after each test case.

mockTime() accepts either a string (eg '+1 days' or '2022-12-22'), a DTI instance, or a boolean (to freeze/restore the global clock).

[chalasr]

Not sure that hijacked enum is better than a regular class with private+final construct, but it works and made me laugh :)

[nicolas-grekas]

Less boilerplate FTW (+ newInstanceWithoutConstructor won't allow bypassing ;) )

[nicolas-grekas]

Thanks to various comments, I figured out a better API for this global clock.

There is no setter anymore.

To use a custom clock, one now has to call Clock::with($clock, $callable, ...$arguments). This ensures the previous clock is restored after $callable has completed.

[upyx]

Do not add it to the API, please! I'm begging you! 🙏 It is easy to achieve by simple wrapper when it is really needed.

Static calls to some global state can be useful in some code, but most of the time it leads to maintenance problems and bugs. People would use it without reason if that was in the API.

The feature looks like Laravels Facades. Every time I've seen them used, they are used wrong. Not because the Facades are something bad, but because developers (especially not very experienced) do bad things with them. Facades are constantly overused/abused just because it is convenient, they are described in guides, and "they all do that, why I shouldn't?"

The good answer to how to inject time (and other dependencies) into Doctrines' entities is repository. Repositories are the best place to provide entities, including new ones. If it's difficult in your case or doesn't suit your needs, there are many other options #48564 (comment) But... Please, do not add static calls to the API.

[GromNaN]

I plead guilty to having a Clock singleton class on my project. It is indeed the simplest way to replace the new DateTime(); even if a dependency injection properly done would be clearer.

With this implementation, I don't see how I could override the current time for functional testing. I can redefine the clock service, but how do I override Clock::now()? Encapsulate the transaction like this?

$client = static::createClient();
$crawler = Clock::with($mockClock, fn() => $client->request('GET', '/'));

[nicolas-grekas]

@GromNaN you nailed it :)

[nicolas-grekas]

I added Clock::get([$newClock]): ClockInterface back since I realized that forcing a closure around might not fit all styles - eg a pre+post event listener.

[nicolas-grekas]

Thanks for the feedback. PR updated. It now provides integration with services + phpunit.

PR description updated.

[stof]

wouldn't this be confusing if now() is not a native clock currently ?

[nicolas-grekas]

If it's not a native clock, it's usually a mock clock. This behavior is desired to me, to do eg:

self::mockTime(); // freeze
//...
self::mockTime('+1 days'); // frozen time + 1 day

[ro0NL]

[BafS]

Why is there a now() function exactly? If we have a singleton already it seems simple enough to do Clock::get()->now(). Functions are not "lazily" imported (not autoloaded) and it can be added easily in userland if needed, in the other hands we need to add some rules to be sure we don't use this function in our code.