[Clock] Documentation for new Clock component

Author: Denis Brumann

components/clock.rst

@@ -0,0 +1,95 @@
+.. index::
+   single: Clock
+   single: Components; Clock
+
+.. _`clock-component`:
+
+The Clock Component
+===================
+
+.. versionadded:: 6.2
+
+    The Clock component was introduced in Symfony 6.2
+
+The Clock component decouples applications from the system clock. This improves
+testability of time-sensitive logic.
+
+The component provides a ``ClockInterface`` with the following implementations
+for different use cases:
+
+* ``NativeClock`` provides a way to interact with the system clock;
+* ``MockClock`` is commonly used in tests as a replacement for the
+  ``NativeClock`` to be able to freeze and change the current time using either
+  ``sleep()`` or ``modify()``;
+* ``MonotonicClock`` relies on ``hrtime()`` and provides a high resolution,
+  monotonic clock, when you need a precise stopwatch.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/clock
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+A clock service replaces creating a new ``DateTime`` or
+``DateTimeImmutable`` object for the current time. Instead, you inject the
+``ClockInterface`` and call ``now()``. By default, your application will likely
+use a ``NativeClock``, which always returns the current system time. In tests it is replaced with a ``MockClock``. The
+The ``MockClock`` is instantiated with a time and does not move forward on its own. The time is
+fixed until ``sleep()`` or ``modify()`` are called. This gives you full control over what your code
+assumes is the current time.
+
+The following example introduces a service utilizing the Clock component to
+determine the current time::
+
+    use Symfony\Component\Clock\ClockInterface;
+
+    class ExpirationChecker
+    {
+        public function __construct(
+            private readonly ClockInterface $clock
+        ) {}
+
+        public function isExpired(DateTimeInterface $validUntil): bool
+        {
+            return $this->clock->now() > $validUntil;
+        }
+    }
+
+Testing
+-------
+
+When writing a test for this service, you can check both cases where something
+is expired or not, by modifying the clock's time::
+
+    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 (600secs)
+
+            // $validUntil is in the past after advancing the clock, so it is expired
+            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));
+        }
+    }