[Clock] Add DatePoint

Author: alexandre-daubois

components/clock.rst

@@ -30,6 +30,8 @@ Installation
 
 .. include:: /components/require_autoload.rst.inc
 
+.. _clock_usage:
+
 Usage
 -----
 
@@ -60,7 +62,7 @@ The Clock component also provides the ``now()`` function::
 
     use function Symfony\Component\Clock\now;
 
-    // Get the current time as a DateTimeImmutable instance
+    // Get the current time as a DatePoint instance
     $now = now();
 
 The ``now()`` function takes an optional ``modifier`` argument
@@ -73,6 +75,9 @@ which will be applied to the current time::
 You can use any string `accepted by the DateTime constructor`_.
 
 Later on this page you can learn how to use this clock in your services and tests.
+When using the Clock component, you manipulate
+:class:`Symfony\\Component\\Clock\\DatePoint` instances. You can learn more
+about it in :ref:`the dedicated section <clock_date-point>`.
 
 .. versionadded:: 6.3
 
@@ -207,6 +212,54 @@ being in a month or another.
 
     The :class:`Symfony\\Component\\Clock\\ClockAwareTrait` was introduced in Symfony 6.3.
 
+.. _clock_date-point:
+
+The ``DatePoint`` Class
+-----------------------
+
+When using the Clock component, you manipulate instances of
+:class:`Symfony\\Component\\Clock\\DatePoint`. The main purpose of this
+class is to leverage the Clock component to get the "current time". When
+creating a new ``DatePoint`` object, the date and time are being fetched
+from the :class:`Symfony\\Component\\Clock\\Clock` class. This means
+that if you did any changes to the clock as stated in the
+:ref:`usage section <clock_usage>`, it will be reflected when creating
+a new ``DatePoint``. This can be particularly useful when
+:ref:`writing time-sensitive tests <clock_writing-tests>`.
+
+Creating a new ``DatePoint`` is as straightforward as creating other date
+objects::
+
+    use Symfony\Component\Clock\DatePoint;
+
+    // create a DatePoint set at the current date and time
+    $now = new DatePoint();
+
+    // you can specify a timezone
+    $withTimezone = new DatePoint(timezone: new \DateTimezone('UTC'));
+
+    // you can also create a DatePoint from a reference date
+    $referenceDate = new \DateTimeImmutable();
+    $relativeDate = new DatePoint('+1month', reference: $referenceDate);
+
+``DatePoint`` extends ``DateTimeImmutable`` so that you can use it seamlessly
+everywhere a ``DateTimeImmutable`` is needed. In addition ``DatePoint`` offers
+stricter return types and provides consistent error handling across versions of
+PHP, thanks to polyfilling `PHP 8.3's behavior`_ on the topic.
+
+Also, ``DatePoint`` offers a stricter alternative to ``DateTimeImmutable`` by
+having stricter error handling, as well as stricter return types. ``DatePoint``
+actually extends ``DateTimeImmutable``, which means you can widely use it in
+your application if you already type against ``DateTimeImmutable`` across your
+code base.
+
+.. versionadded:: 6.4
+
+    The :class:`Symfony\\Component\\Clock\\DatePoint` class was introduced
+    in Symfony 6.4.
+
+.. _clock_writing-tests:
+
 Writing Time-Sensitive Tests
 ----------------------------
 
@@ -294,3 +347,4 @@ use them even if your project doesn't use PHP 8.3 yet.
 .. _`accepted by the DateTime constructor`: https://www.php.net/manual/en/datetime.formats.php
 .. _`PHP DateTime exceptions`: https://wiki.php.net/rfc/datetime-exceptions
 .. _`symfony/polyfill-php83`: https://github.com/symfony/polyfill-php83
+.. _`PHP 8.3's behavior`: https://wiki.php.net/rfc/datetime-exceptions