[Clock] Add TimePoint: an immutable DateTime implementation with stricter error handling and return types

nicolas-grekas · nicolas-grekas · commit 2d1f62a3543d · 2023-09-14T10:52:31.000+02:00
diff --git a/.github/expected-missing-return-types.diff b/.github/expected-missing-return-types.diff
@@ -1512,6 +1512,16 @@ diff --git a/src/Symfony/Component/Cache/Traits/FilesystemCommonTrait.php b/src/
 +    public function __wakeup(): void
      {
          throw new \BadMethodCallException('Cannot unserialize '.__CLASS__);
+diff --git a/src/Symfony/Component/Clock/ClockAwareTrait.php b/src/Symfony/Component/Clock/ClockAwareTrait.php
+--- a/src/Symfony/Component/Clock/ClockAwareTrait.php
++++ b/src/Symfony/Component/Clock/ClockAwareTrait.php
+@@ -33,5 +33,5 @@ trait ClockAwareTrait
+      * @return TimePoint
+      */
+-    protected function now(): \DateTimeImmutable
++    protected function now(): TimePoint
+     {
+         $now = ($this->clock ??= new Clock())->now();
 diff --git a/src/Symfony/Component/Config/ConfigCacheInterface.php b/src/Symfony/Component/Config/ConfigCacheInterface.php
 --- a/src/Symfony/Component/Config/ConfigCacheInterface.php
 +++ b/src/Symfony/Component/Config/ConfigCacheInterface.php
diff --git a/src/Symfony/Component/Clock/CHANGELOG.md b/src/Symfony/Component/Clock/CHANGELOG.md
@@ -4,6 +4,7 @@ CHANGELOG
 6.4
 ---
 
+ * Add `TimePoint`: an immutable DateTime implementation with stricter error handling and return types
  * Throw `DateMalformedStringException`/`DateInvalidTimeZoneException` when appropriate
  * Add `$modifier` argument to the `now()` helper
 
diff --git a/src/Symfony/Component/Clock/Clock.php b/src/Symfony/Component/Clock/Clock.php
@@ -44,10 +44,14 @@ public static function set(PsrClockInterface $clock): void
         self::$globalClock = $clock instanceof ClockInterface ? $clock : new self($clock);
     }
 
-    public function now(): \DateTimeImmutable
+    public function now(): TimePoint
     {
         $now = ($this->clock ?? self::get())->now();
 
+        if (!$now instanceof TimePoint) {
+            $now = TimePoint::createFromInterface($now);
+        }
+
         return isset($this->timezone) ? $now->setTimezone($this->timezone) : $now;
     }
 
diff --git a/src/Symfony/Component/Clock/ClockAwareTrait.php b/src/Symfony/Component/Clock/ClockAwareTrait.php
@@ -29,8 +29,13 @@ public function setClock(ClockInterface $clock): void
         $this->clock = $clock;
     }
 
+    /**
+     * @return TimePoint
+     */
     protected function now(): \DateTimeImmutable
     {
-        return ($this->clock ??= new Clock())->now();
+        $now = ($this->clock ??= new Clock())->now();
+
+        return $now instanceof TimePoint ? $now : Moment::createFromInterface($now);
     }
 }
diff --git a/src/Symfony/Component/Clock/MockClock.php b/src/Symfony/Component/Clock/MockClock.php
@@ -20,7 +20,7 @@
  */
 final class MockClock implements ClockInterface
 {
-    private \DateTimeImmutable $now;
+    private TimePoint $now;
 
     /**
      * @throws \DateMalformedStringException When $now is invalid
@@ -38,20 +38,16 @@ public function __construct(\DateTimeImmutable|string $now = 'now', \DateTimeZon
             }
         }
 
-        if (\PHP_VERSION_ID >= 80300 && \is_string($now)) {
-            $now = new \DateTimeImmutable($now, $timezone ?? new \DateTimeZone('UTC'));
-        } elseif (\is_string($now)) {
-            try {
-                $now = new \DateTimeImmutable($now, $timezone ?? new \DateTimeZone('UTC'));
-            } catch (\Exception $e) {
-                throw new \DateMalformedStringException($e->getMessage(), $e->getCode(), $e);
-            }
+        if (\is_string($now)) {
+            $now = new TimePoint($now, $timezone ?? new \DateTimeZone('UTC'));
+        } elseif (!$now instanceof TimePoint) {
+            $now = TimePoint::createFromInterface($now);
         }
 
         $this->now = null !== $timezone ? $now->setTimezone($timezone) : $now;
     }
 
-    public function now(): \DateTimeImmutable
+    public function now(): TimePoint
     {
         return clone $this->now;
     }
@@ -62,7 +58,7 @@ public function sleep(float|int $seconds): void
         $now = substr_replace(sprintf('@%07.0F', $now), '.', -6, 0);
         $timezone = $this->now->getTimezone();
 
-        $this->now = (new \DateTimeImmutable($now, $timezone))->setTimezone($timezone);
+        $this->now = TimePoint::createFromInterface(new \DateTimeImmutable($now, $timezone))->setTimezone($timezone);
     }
 
     /**
diff --git a/src/Symfony/Component/Clock/MonotonicClock.php b/src/Symfony/Component/Clock/MonotonicClock.php
@@ -38,7 +38,7 @@ public function __construct(\DateTimeZone|string $timezone = null)
         $this->timezone = \is_string($timezone ??= date_default_timezone_get()) ? $this->withTimeZone($timezone)->timezone : $timezone;
     }
 
-    public function now(): \DateTimeImmutable
+    public function now(): TimePoint
     {
         [$s, $us] = hrtime();
 
@@ -56,7 +56,7 @@ public function now(): \DateTimeImmutable
 
         $now = '@'.($s + $this->sOffset).'.'.$now;
 
-        return (new \DateTimeImmutable($now, $this->timezone))->setTimezone($this->timezone);
+        return TimePoint::createFromInterface(new \DateTimeImmutable($now, $this->timezone))->setTimezone($this->timezone);
     }
 
     public function sleep(float|int $seconds): void
diff --git a/src/Symfony/Component/Clock/NativeClock.php b/src/Symfony/Component/Clock/NativeClock.php
@@ -28,9 +28,9 @@ public function __construct(\DateTimeZone|string $timezone = null)
         $this->timezone = \is_string($timezone ??= date_default_timezone_get()) ? $this->withTimeZone($timezone)->timezone : $timezone;
     }
 
-    public function now(): \DateTimeImmutable
+    public function now(): TimePoint
     {
-        return new \DateTimeImmutable('now', $this->timezone);
+        return TimePoint::createFromInterface(new \DateTimeImmutable('now', $this->timezone));
     }
 
     public function sleep(float|int $seconds): void
diff --git a/src/Symfony/Component/Clock/Resources/now.php b/src/Symfony/Component/Clock/Resources/now.php
@@ -15,27 +15,14 @@
     /**
      * @throws \DateMalformedStringException When the modifier is invalid
      */
-    function now(string $modifier = null): \DateTimeImmutable
+    function now(string $modifier = 'now'): TimePoint
     {
-        if (null === $modifier || 'now' === $modifier) {
-            return Clock::get()->now();
+        if ('now' !== $modifier) {
+            return new TimePoint($modifier);
         }
 
         $now = Clock::get()->now();
 
-        if (\PHP_VERSION_ID < 80300) {
-            try {
-                $tz = (new \DateTimeImmutable($modifier, $now->getTimezone()))->getTimezone();
-            } catch (\Exception $e) {
-                throw new \DateMalformedStringException($e->getMessage(), $e->getCode(), $e);
-            }
-            $now = $now->setTimezone($tz);
-
-            return @$now->modify($modifier) ?: throw new \DateMalformedStringException(error_get_last()['message'] ?? sprintf('Invalid date modifier "%s".', $modifier));
-        }
-
-        $tz = (new \DateTimeImmutable($modifier, $now->getTimezone()))->getTimezone();
-
-        return $now->setTimezone($tz)->modify($modifier);
+        return $now instanceof TimePoint ? $now : Moment::createFromInterface($now);
     }
 }
diff --git a/src/Symfony/Component/Clock/Tests/ClockAwareTraitTest.php b/src/Symfony/Component/Clock/Tests/ClockAwareTraitTest.php
@@ -14,18 +14,15 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Clock\ClockAwareTrait;
 use Symfony\Component\Clock\MockClock;
+use Symfony\Component\Clock\TimePoint;
 
 class ClockAwareTraitTest extends TestCase
 {
     public function testTrait()
     {
-        $sut = new class() {
-            use ClockAwareTrait {
-                now as public;
-            }
-        };
+        $sut = new ClockAwareTestImplem();
 
-        $this->assertInstanceOf(\DateTimeImmutable::class, $sut->now());
+        $this->assertInstanceOf(TimePoint::class, $sut->now());
 
         $clock = new MockClock();
         $sut = new $sut();
@@ -38,3 +35,10 @@ public function testTrait()
         $this->assertSame(1.0, round($sut->now()->getTimestamp() - $ts, 1));
     }
 }
+
+class ClockAwareTestImplem
+{
+    use ClockAwareTrait {
+        now as public;
+    }
+}
diff --git a/src/Symfony/Component/Clock/Tests/ClockTest.php b/src/Symfony/Component/Clock/Tests/ClockTest.php
@@ -17,6 +17,7 @@
 use Symfony\Component\Clock\MockClock;
 use Symfony\Component\Clock\NativeClock;
 use Symfony\Component\Clock\Test\ClockSensitiveTrait;
+use Symfony\Component\Clock\TimePoint;
 
 use function Symfony\Component\Clock\now;
 
@@ -35,7 +36,7 @@ public function testMockClock()
 
     public function testNativeClock()
     {
-        $this->assertInstanceOf(\DateTimeImmutable::class, now());
+        $this->assertInstanceOf(TimePoint::class, now());
         $this->assertInstanceOf(NativeClock::class, Clock::get());
     }
 
diff --git a/src/Symfony/Component/Clock/Tests/TimePointTest.php b/src/Symfony/Component/Clock/Tests/TimePointTest.php
@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Clock\Test\ClockSensitiveTrait;
+use Symfony\Component\Clock\TimePoint;
+
+class TimePointTest extends TestCase
+{
+    use ClockSensitiveTrait;
+
+    public function testTimePoint()
+    {
+        self::mockTime('2010-01-28 15:00:00');
+
+        $date = new TimePoint();
+        $this->assertSame('2010-01-28 15:00:00 UTC', $date->format('Y-m-d H:i:s e'));
+
+        $date = new TimePoint('+1 day Europe/Paris');
+        $this->assertSame('2010-01-29 16:00:00 Europe/Paris', $date->format('Y-m-d H:i:s e'));
+
+        $date = new TimePoint('2022-01-28 15:00:00 Europe/Paris');
+        $this->assertSame('2022-01-28 15:00:00 Europe/Paris', $date->format('Y-m-d H:i:s e'));
+    }
+
+    public function testCreateFromFormat()
+    {
+        $date = TimePoint::createFromFormat('Y-m-d H:i:s', '2010-01-28 15:00:00');
+
+        $this->assertInstanceOf(TimePoint::class, $date);
+        $this->assertSame('2010-01-28 15:00:00', $date->format('Y-m-d H:i:s'));
+
+        $this->expectException(\DateMalformedStringException::class);
+        $this->expectExceptionMessage('A four digit year could not be found');
+        TimePoint::createFromFormat('Y-m-d H:i:s', 'Bad Date');
+    }
+
+    public function testModify()
+    {
+        $date = new TimePoint('2010-01-28 15:00:00');
+        $date = $date->modify('+1 day');
+
+        $this->assertInstanceOf(TimePoint::class, $date);
+        $this->assertSame('2010-01-29 15:00:00', $date->format('Y-m-d H:i:s'));
+
+        $this->expectException(\DateMalformedStringException::class);
+        $this->expectExceptionMessage('Failed to parse time string (Bad Date)');
+        $date->modify('Bad Date');
+    }
+}
diff --git a/src/Symfony/Component/Clock/TimePoint.php b/src/Symfony/Component/Clock/TimePoint.php

Original file line number	Diff line number	Diff line change
`@@ -44,10 +44,14 @@ public static function set(PsrClockInterface $clock): void`
`44`	`44`	`self::$globalClock = $clock instanceof ClockInterface ? $clock : new self($clock);`
`45`	`45`	`}`
`46`	`46`
`47`		`- public function now(): \DateTimeImmutable`
	`47`	`+ public function now(): TimePoint`
`48`	`48`	`{`
`49`	`49`	`$now = ($this->clock ?? self::get())->now();`
`50`	`50`
	`51`	`+ if (!$now instanceof TimePoint) {`
	`52`	`+ $now = TimePoint::createFromInterface($now);`
	`53`	`+ }`
	`54`	`+`
`51`	`55`	`return isset($this->timezone) ? $now->setTimezone($this->timezone) : $now;`
`52`	`56`	`}`
`53`	`57`
Original file line number	Diff line number	Diff line change
`@@ -29,8 +29,13 @@ public function setClock(ClockInterface $clock): void`
`29`	`29`	`$this->clock = $clock;`
`30`	`30`	`}`
`31`	`31`
	`32`	`+ /**`
	`33`	`+ * @return TimePoint`
	`34`	`+ */`
`32`	`35`	`protected function now(): \DateTimeImmutable`
`33`	`36`	`{`
`34`		`- return ($this->clock ??= new Clock())->now();`
	`37`	`+ $now = ($this->clock ??= new Clock())->now();`
	`38`	`+`
	`39`	`+ return $now instanceof TimePoint ? $now : Moment::createFromInterface($now);`
`35`	`40`	`}`
`36`	`41`	`}`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@`
`20`	`20`	`*/`
`21`	`21`	`final class MockClock implements ClockInterface`
`22`	`22`	`{`
`23`		`- private \DateTimeImmutable $now;`
	`23`	`+ private TimePoint $now;`
`24`	`24`
`25`	`25`	`/**`
`26`	`26`	`* @throws \DateMalformedStringException When $now is invalid`
`@@ -38,20 +38,16 @@ public function __construct(\DateTimeImmutable\|string $now = 'now', \DateTimeZon`
`38`	`38`	`}`
`39`	`39`	`}`
`40`	`40`
`41`		`- if (\PHP_VERSION_ID >= 80300 && \is_string($now)) {`
`42`		`- $now = new \DateTimeImmutable($now, $timezone ?? new \DateTimeZone('UTC'));`
`43`		`- } elseif (\is_string($now)) {`
`44`		`- try {`
`45`		`- $now = new \DateTimeImmutable($now, $timezone ?? new \DateTimeZone('UTC'));`
`46`		`- } catch (\Exception $e) {`
`47`		`- throw new \DateMalformedStringException($e->getMessage(), $e->getCode(), $e);`
`48`		`- }`
	`41`	`+ if (\is_string($now)) {`
	`42`	`+ $now = new TimePoint($now, $timezone ?? new \DateTimeZone('UTC'));`
	`43`	`+ } elseif (!$now instanceof TimePoint) {`
	`44`	`+ $now = TimePoint::createFromInterface($now);`
`49`	`45`	`}`
`50`	`46`
`51`	`47`	`$this->now = null !== $timezone ? $now->setTimezone($timezone) : $now;`
`52`	`48`	`}`
`53`	`49`
`54`		`- public function now(): \DateTimeImmutable`
	`50`	`+ public function now(): TimePoint`
`55`	`51`	`{`
`56`	`52`	`return clone $this->now;`
`57`	`53`	`}`
`@@ -62,7 +58,7 @@ public function sleep(float\|int $seconds): void`
`62`	`58`	`$now = substr_replace(sprintf('@%07.0F', $now), '.', -6, 0);`
`63`	`59`	`$timezone = $this->now->getTimezone();`
`64`	`60`
`65`		`- $this->now = (new \DateTimeImmutable($now, $timezone))->setTimezone($timezone);`
	`61`	`+ $this->now = TimePoint::createFromInterface(new \DateTimeImmutable($now, $timezone))->setTimezone($timezone);`
`66`	`62`	`}`
`67`	`63`
`68`	`64`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@ public function __construct(\DateTimeZone\|string $timezone = null)`
`38`	`38`	`$this->timezone = \is_string($timezone ??= date_default_timezone_get()) ? $this->withTimeZone($timezone)->timezone : $timezone;`
`39`	`39`	`}`
`40`	`40`
`41`		`- public function now(): \DateTimeImmutable`
	`41`	`+ public function now(): TimePoint`
`42`	`42`	`{`
`43`	`43`	`[$s, $us] = hrtime();`
`44`	`44`
`@@ -56,7 +56,7 @@ public function now(): \DateTimeImmutable`
`56`	`56`
`57`	`57`	`$now = '@'.($s + $this->sOffset).'.'.$now;`
`58`	`58`
`59`		`- return (new \DateTimeImmutable($now, $this->timezone))->setTimezone($this->timezone);`
	`59`	`+ return TimePoint::createFromInterface(new \DateTimeImmutable($now, $this->timezone))->setTimezone($this->timezone);`
`60`	`60`	`}`
`61`	`61`
`62`	`62`	`public function sleep(float\|int $seconds): void`
Original file line number	Diff line number	Diff line change
`@@ -28,9 +28,9 @@ public function __construct(\DateTimeZone\|string $timezone = null)`
`28`	`28`	`$this->timezone = \is_string($timezone ??= date_default_timezone_get()) ? $this->withTimeZone($timezone)->timezone : $timezone;`
`29`	`29`	`}`
`30`	`30`
`31`		`- public function now(): \DateTimeImmutable`
	`31`	`+ public function now(): TimePoint`
`32`	`32`	`{`
`33`		`- return new \DateTimeImmutable('now', $this->timezone);`
	`33`	`+ return TimePoint::createFromInterface(new \DateTimeImmutable('now', $this->timezone));`
`34`	`34`	`}`
`35`	`35`
`36`	`36`	`public function sleep(float\|int $seconds): void`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@`
`17`	`17`	`use Symfony\Component\Clock\MockClock;`
`18`	`18`	`use Symfony\Component\Clock\NativeClock;`
`19`	`19`	`use Symfony\Component\Clock\Test\ClockSensitiveTrait;`
	`20`	`+use Symfony\Component\Clock\TimePoint;`
`20`	`21`
`21`	`22`	`use function Symfony\Component\Clock\now;`
`22`	`23`
`@@ -35,7 +36,7 @@ public function testMockClock()`
`35`	`36`
`36`	`37`	`public function testNativeClock()`
`37`	`38`	`{`
`38`		`- $this->assertInstanceOf(\DateTimeImmutable::class, now());`
	`39`	`+ $this->assertInstanceOf(TimePoint::class, now());`
`39`	`40`	`$this->assertInstanceOf(NativeClock::class, Clock::get());`
`40`	`41`	`}`
`41`	`42`