[Clock] Add Clock class and now() function

Author: nicolas-grekas

CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add `ClockAwareTrait` to help write time-sensitive classes
+ * Add `Clock` class and `now()` function
 
 6.2
 ---

Clock.php

@@ -0,0 +1,72 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock;
+
+use Psr\Clock\ClockInterface as PsrClockInterface;
+
+/**
+ * A global clock.
+ *
+ * @author Nicolas Grekas <[email protected]>
+ */
+final class Clock implements ClockInterface
+{
+    private static ClockInterface $globalClock;
+
+    public function __construct(
+        private readonly ?PsrClockInterface $clock = null,
+        private ?\DateTimeZone $timezone = null,
+    ) {
+    }
+
+    /**
+     * Returns the current global clock.
+     *
+     * Note that you should prefer injecting a ClockInterface or using
+     * ClockAwareTrait when possible instead of using this method.
+     */
+    public static function get(): ClockInterface
+    {
+        return self::$globalClock ??= new NativeClock();
+    }
+
+    public static function set(PsrClockInterface $clock): void
+    {
+        self::$globalClock = $clock instanceof ClockInterface ? $clock : new self($clock);
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        $now = ($this->clock ?? self::$globalClock)->now();
+
+        return isset($this->timezone) ? $now->setTimezone($this->timezone) : $now;
+    }
+
+    public function sleep(float|int $seconds): void
+    {
+        $clock = $this->clock ?? self::$globalClock;
+
+        if ($clock instanceof ClockInterface) {
+            $clock->sleep($seconds);
+        } else {
+            (new NativeClock())->sleep($seconds);
+        }
+    }
+
+    public function withTimeZone(\DateTimeZone|string $timezone): static
+    {
+        $clone = clone $this;
+        $clone->timezone = \is_string($timezone) ? new \DateTimeZone($timezone) : $timezone;
+
+        return $clone;
+    }
+}

MockClock.php

@@ -14,6 +14,8 @@
 /**
  * A clock that always returns the same date, suitable for testing time-sensitive logic.
  *
+ * Consider using ClockSensitiveTrait in your test cases instead of using this class directly.
+ *
  * @author Nicolas Grekas <[email protected]>
  */
 final class MockClock implements ClockInterface

Resources/now.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock;
+
+/**
+ * Returns the current time as a DateTimeImmutable.
+ *
+ * Note that you should prefer injecting a ClockInterface or using
+ * ClockAwareTrait when possible instead of using this function.
+ */
+function now(): \DateTimeImmutable
+{
+    return Clock::get()->now();
+}

Test/ClockSensitiveTrait.php

@@ -0,0 +1,65 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock\Test;
+
+use Psr\Clock\ClockInterface;
+use Symfony\Component\Clock\Clock;
+use Symfony\Component\Clock\MockClock;
+
+use function Symfony\Component\Clock\now;
+
+/**
+ * Helps with mocking the time in your test cases.
+ *
+ * This trait provides one self::mockTime() method that freezes the time.
+ * It restores the global clock after each test case.
+ * self::mockTime() accepts either a string (eg '+1 days' or '2022-12-22'),
+ * a DateTimeImmutable, or a boolean (to freeze/restore the global clock).
+ *
+ * @author Nicolas Grekas <[email protected]>
+ */
+trait ClockSensitiveTrait
+{
+    public static function mockTime(string|\DateTimeImmutable|bool $when = true): ClockInterface
+    {
+        Clock::set(match (true) {
+            false === $when => self::saveClockBeforeTest(false),
+            true === $when => new MockClock(),
+            $when instanceof \DateTimeImmutable => new MockClock($when),
+            default => new MockClock(now()->modify($when)),
+        });
+
+        return Clock::get();
+    }
+
+    /**
+     * @before
+     *
+     * @internal
+     */
+    protected static function saveClockBeforeTest(bool $save = true): ClockInterface
+    {
+        static $originalClock;
+
+        return $save ? $originalClock = Clock::get() : $originalClock;
+    }
+
+    /**
+     * @after
+     *
+     * @internal
+     */
+    protected static function restoreClockAfterTest(): void
+    {
+        Clock::set(self::saveClockBeforeTest(false));
+    }
+}

Tests/ClockTest.php

@@ -0,0 +1,82 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Psr\Clock\ClockInterface;
+use Symfony\Component\Clock\Clock;
+use Symfony\Component\Clock\MockClock;
+use Symfony\Component\Clock\NativeClock;
+use Symfony\Component\Clock\Test\ClockSensitiveTrait;
+
+use function Symfony\Component\Clock\now;
+
+class ClockTest extends TestCase
+{
+    use ClockSensitiveTrait;
+
+    public function testMockClock()
+    {
+        $this->assertInstanceOf(NativeClock::class, Clock::get());
+
+        $clock = self::mockTime();
+        $this->assertInstanceOf(MockClock::class, Clock::get());
+        $this->assertSame(Clock::get(), $clock);
+    }
+
+    public function testNativeClock()
+    {
+        $this->assertInstanceOf(\DateTimeImmutable::class, now());
+        $this->assertInstanceOf(NativeClock::class, Clock::get());
+    }
+
+    public function testMockClockDisable()
+    {
+        $this->assertInstanceOf(NativeClock::class, Clock::get());
+
+        $this->assertInstanceOf(MockClock::class, self::mockTime(true));
+        $this->assertInstanceOf(NativeClock::class, self::mockTime(false));
+    }
+
+    public function testMockClockFreeze()
+    {
+        self::mockTime(new \DateTimeImmutable('2021-12-19'));
+
+        $this->assertSame('2021-12-19', now()->format('Y-m-d'));
+
+        self::mockTime('+1 days');
+        $this->assertSame('2021-12-20', now()->format('Y-m-d'));
+    }
+
+    public function testPsrClock()
+    {
+        $psrClock = new class() implements ClockInterface {
+            public function now(): \DateTimeImmutable
+            {
+                return new \DateTimeImmutable('@1234567');
+            }
+        };
+
+        Clock::set($psrClock);
+
+        $this->assertInstanceOf(Clock::class, Clock::get());
+
+        $this->assertSame(1234567, now()->getTimestamp());
+
+        $this->assertSame('UTC', Clock::get()->withTimeZone('UTC')->now()->getTimezone()->getName());
+        $this->assertSame('Europe/Paris', Clock::get()->withTimeZone('Europe/Paris')->now()->getTimezone()->getName());
+
+        Clock::get()->sleep(0.1);
+
+        $this->assertSame(1234567, now()->getTimestamp());
+    }
+}

composer.json

@@ -23,6 +23,7 @@
         "psr/clock": "^1.0"
     },
     "autoload": {
+        "files": [ "Resources/now.php" ],
         "psr-4": { "Symfony\\Component\\Clock\\": "" },
         "exclude-from-classmap": [
             "/Tests/"