[Clock] Documentation for new Clock component

Author: Denis Brumann

components/clock.rst

@@ -0,0 +1,88 @@
+.. index::
+   single: Clock
+   single: Components; Clock
+
+.. _`clock-component`:
+
+The Clock Component
+===================
+
+The Clock component decouples applications from the system clock. This improves
+testability of time-sensitive logic.
+
+The component provides a ``ClockInterface`` with 3 different clock
+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 by a ``MockClock``. The
+``MockClock`` is instantiated with a time and does not move forward on its own, meaning when you create an
+instance with a time, it is always kept, unless you change it using
+either ``sleep()`` or ``modify()``. 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 $time): bool
+        {
+            return $this->clock->now() > $time;
+        }
+    }
+
+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 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);
+            $time = new DateTimeImmutable('2022-11-16 15:25:00');
+
+            // $time is in the future, so it is not expired
+            static::assertFalse($expirationChecker->isExpired($time));
+
+            // Clock sleeps for 10min, so now is '2022-11-16 15:20:00'
+            $clock->sleep(600); // Instantly changes time as if we waited for 10min (600secs)
+
+            // $time is in the past after advancing the clock, so it is expired
+            static::assertTrue($expirationChecker->isExpired($time));
+
+            $clock->modify('2022-11-16 15:00:00');
+
+            // $time is in the future again, so it is no longer expired
+            static::assertFalse($expirationChecker->isExpired($time));
+        }
+    }