[Clock] Add DatePoint

Author: alexandre-daubois

components/clock.rst

@@ -30,6 +30,8 @@ Installation
 
 .. include:: /components/require_autoload.rst.inc
 
+.. _clock_usage:
+
 Usage
 -----
 
@@ -193,6 +195,47 @@ being in a month or another.
 
     The :class:`Symfony\\Component\\Clock\\ClockAwareTrait` was introduced in Symfony 6.3.
 
+The ``DatePoint`` Class
+-----------------------
+
+The Clock component comes with the
+:class:`Symfony\\Component\\Clock\\DatePoint` class. The main purpose of this
+class is to offer a stricter alternative to ``DateTimeImmutable`` by offering
+a 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 use ``DateTimeImmutable`` across your code base.
+
+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 even create a DatePoint from a DateTimeImmutable
+    $immutable = new \DateTimeImmutable();
+    $fromImmutable = new DatePoint(reference: $immutable);
+
+One big advantage of ``DatePoint`` is that it fully uses the Clock
+component. Indeed, 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>`.
+
+.. versionadded:: 6.4
+
+    The :class:`Symfony\\Component\\Clock\\DatePoint` class was introduced
+    in Symfony 6.4.
+
+.. _clock_writing-tests:
+
 Writing Time-Sensitive Tests
 ----------------------------