Contributed by Nicolas Grekas
in #51415.

In Symfony 6.2 we introduced the Clock component to improve the testability
of your time-sensitive code. In Symfony 6.4 we're introducing DatePoint, a
new PHP date/time class that integrates seamlessly with the Clock component.
The main advantage of DatePoint over PHP's DateTime and DateTimeImmutable
it that is uses the global static clock of the Clock component to set the
current time. This means that if you did any changes to the clock, it will be
reflected when creating new DatePoint instances:

use Symfony\Component\Clock\DatePoint;

// gets the current time from the date/time defined by Clock
$createdAt = new DatePoint();

The DatePoint class extends DateTimeImmutable, so you can use it in your
code anywhere a DateTimeImmutable or DateTimeInterface is expected.
DatePoint also includes some utilities to handle date/time values, although
is not meant to replace third-party libraries that provide lots of utilities to
work with date/time values:

// set the current time explicitly
$firstPublicCommitOfSymfony = new DatePoint('2005-10-18 16:27:36 Europe/Paris');

// use current Clock time but specify a timezone
$orderCreatedAt = new DatePoint(timezone: new \DateTimezone('UTC'));

// use an existing date as the reference to create a DatePoint
$welcomeDiscountValidUntil = new DatePoint('+1 month', reference: $user->getSignedUpAt());

Another improvement of the DatePoint class is that errors (such as creating
invalid dates or trying to do invalid date modifications) no longer return false
but throw a \DateMalformedStringException. This exception was introduced in PHP 8.3
but thanks to Symfony PHP 8.3 polyfill you can use it starting from PHP 7.1.
In summary, DatePoint is a drop-in replacement of PHP date/time classes that
provides full integration with the Clock component, some utilities and better
error handling.

Sponsor the Symfony project.