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

nicolas-grekas · nicolas-grekas · commit d158df1ae032 · 2023-08-17T12:26:15.000+02:00
diff --git a/src/Symfony/Component/Clock/CHANGELOG.md b/src/Symfony/Component/Clock/CHANGELOG.md
@@ -4,6 +4,7 @@ CHANGELOG
 6.4
 ---
 
+ * Add `DateTime`: an immutable implementation with strict error handling and return types
  * Throw `DateMalformedStringException`/`DateInvalidTimeZoneException` when appropriate
 
 6.3
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(): DateTime
     {
         $now = ($this->clock ?? self::get())->now();
 
+        if (!$now instanceof DateTime) {
+            $now = DateTime::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 DateTime
+     */
     protected function now(): \DateTimeImmutable
     {
-        return ($this->clock ??= new Clock())->now();
+        $now = ($this->clock ??= new Clock())->now();
+
+        return $now instanceof DateTime ? $now : DateTime::createFromInterface($now);
     }
 }
diff --git a/src/Symfony/Component/Clock/DateTime.php b/src/Symfony/Component/Clock/DateTime.php
@@ -0,0 +1,123 @@
+<?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;
+
+use Psr\Clock\ClockInterface;
+
+/**
+ * An immmutable DateTime with stricter error handling and return types than the native one.
+ *
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+final class DateTime extends \DateTimeImmutable
+{
+    /**
+     * @throws \DateMalformedStringException When $datetime is invalid
+     */
+    public function __construct(string $datetime = 'now', \DateTimeZone $timezone = null, parent $reference = null)
+    {
+        $now = $reference ?? Clock::get()->now();
+
+        if ('now' !== $datetime) {
+            if (!$now instanceof static) {
+                $now = static::createFromInterface($now);
+            }
+
+            $timezone = (new parent($datetime, $timezone ?? $now->getTimezone()))->getTimezone();
+            $now = $now->setTimeZone($timezone)->modify($datetime);
+        } elseif (null !== $timezone) {
+            $now = $now->setTimezone($timezone);
+        }
+
+        if (\PHP_VERSION_ID < 80200) {
+            $now = (array) $now;
+            $this->date = $now['date'];
+            $this->timezone_type = $now['timezone_type'];
+            $this->timezone = $now['timezone'];
+            $this->__wakeup();
+
+            return;
+        }
+
+        $this->__unserialize((array) $now);
+    }
+
+    /**
+     * @throws \DateMalformedStringException When $format or $datetime are invalid
+     */
+    public static function createFromFormat(string $format, string $datetime, \DateTimeZone $timezone = null): static
+    {
+        return parent::createFromFormat($format, $datetime, $timezone) ?: throw new \DateMalformedStringException(static::getLastErrors()['errors'][0] ?? 'Invalid date string or format.');
+    }
+
+    public static function createFromInterface(\DateTimeInterface $object): static
+    {
+        return parent::createFromInterface($object);
+    }
+
+    public static function createFromMutable(\DateTime $object): static
+    {
+        return parent::createFromMutable($object);
+    }
+
+    public function add(\DateInterval $interval): static
+    {
+        return parent::add($interval);
+    }
+
+    public function sub(\DateInterval $interval): static
+    {
+        return parent::sub($interval);
+    }
+
+    /**
+     * @throws \DateMalformedStringException When $modifier is invalid
+     */
+    public function modify(string $modifier): static
+    {
+        if (\PHP_VERSION_ID < 80300) {
+            return @parent::modify($modifier) ?: throw new \DateMalformedStringException(error_get_last()['message'] ?? sprintf('Invalid modifier: "%s".', $modifier));
+        }
+
+        return parent::modify($modifier);
+    }
+
+    public function setTimestamp(int $value): static
+    {
+        return parent::setTimestamp($value);
+    }
+
+    public function setDate(int $year, int $month, int $day): static
+    {
+        return parent::setDate($year, $month, $day);
+    }
+
+    public function setISODate(int $year, int $week, int $day = 1): static
+    {
+        return parent::setISODate($year, $week, $day);
+    }
+
+    public function setTime(int $hour, int $minute, int $second = 0, int $microsecond = 0): static
+    {
+        return parent::setTime($hour, $minute, $second, $microsecond);
+    }
+
+    public function setTimeZone(\DateTimeZone $timezone): static
+    {
+        return parent::setTimeZone($timezone);
+    }
+
+    public function getTimezone(): \DateTimeZone
+    {
+        return parent::getTimezone() ?: throw new \DateInvalidTimeZoneException('The DateTime object has no timezone.');
+    }
+}
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 DateTime $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 DateTime($now, $timezone ?? new \DateTimeZone('UTC'));
+        } elseif (!$now instanceof DateTime) {
+            $now = DateTime::createFromInterface($now);
         }
 
         $this->now = null !== $timezone ? $now->setTimezone($timezone) : $now;
     }
 
-    public function now(): \DateTimeImmutable
+    public function now(): DateTime
     {
         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 = DateTime::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(): DateTime
     {
         [$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 DateTime::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(): DateTime
     {
-        return new \DateTimeImmutable('now', $this->timezone);
+        return DateTime::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
@@ -13,13 +13,12 @@
 
 if (!\function_exists(now::class)) {
     /**
-     * Returns the current time as a DateTimeImmutable.
-     *
-     * Note that you should prefer injecting a ClockInterface or using
-     * ClockAwareTrait when possible instead of using this function.
+     * Returns the current time as a \Symfony\Component\Clock\DateTime.
      */
-    function now(): \DateTimeImmutable
+    function now(): DateTime
     {
-        return Clock::get()->now();
+        $now = Clock::get()->now();
+
+        return $now instanceof DateTime ? $now : DateTime::createFromInterface($now);
     }
 }
diff --git a/src/Symfony/Component/Clock/Tests/ClockAwareTraitTest.php b/src/Symfony/Component/Clock/Tests/ClockAwareTraitTest.php
@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Clock\ClockAwareTrait;
+use Symfony\Component\Clock\DateTime;
 use Symfony\Component\Clock\MockClock;
 
 class ClockAwareTraitTest extends TestCase
@@ -25,7 +26,7 @@ public function testTrait()
             }
         };
 
-        $this->assertInstanceOf(\DateTimeImmutable::class, $sut->now());
+        $this->assertInstanceOf(DateTime::class, $sut->now());
 
         $clock = new MockClock();
         $sut = new $sut();
diff --git a/src/Symfony/Component/Clock/Tests/ClockTest.php b/src/Symfony/Component/Clock/Tests/ClockTest.php
@@ -14,6 +14,7 @@
 use PHPUnit\Framework\TestCase;
 use Psr\Clock\ClockInterface;
 use Symfony\Component\Clock\Clock;
+use Symfony\Component\Clock\DateTime;
 use Symfony\Component\Clock\MockClock;
 use Symfony\Component\Clock\NativeClock;
 use Symfony\Component\Clock\Test\ClockSensitiveTrait;
@@ -35,7 +36,7 @@ public function testMockClock()
 
     public function testNativeClock()
     {
-        $this->assertInstanceOf(\DateTimeImmutable::class, now());
+        $this->assertInstanceOf(DateTime::class, now());
         $this->assertInstanceOf(NativeClock::class, Clock::get());
     }
 
diff --git a/src/Symfony/Component/Clock/Tests/DateTimeTest.php b/src/Symfony/Component/Clock/Tests/DateTimeTest.php
@@ -0,0 +1,62 @@
+<?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\DateTime;
+use Symfony\Component\Clock\Test\ClockSensitiveTrait;
+
+use function Symfony\Component\Clock\now;
+
+class DateTimeTest extends TestCase
+{
+    use ClockSensitiveTrait;
+
+    public function testDateTime()
+    {
+        self::mockTime('2010-01-28 15:00:00');
+
+        $date = new DateTime();
+        $this->assertSame('2010-01-28 15:00:00 UTC', $date->format('Y-m-d H:i:s e'));
+
+        $date = new DateTime('+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 DateTime('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 = DateTime::createFromFormat('Y-m-d H:i:s', '2010-01-28 15:00:00');
+
+        $this->assertInstanceOf(DateTime::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');
+        DateTime::createFromFormat('Y-m-d H:i:s', 'Bad Date');
+    }
+
+    public function testModify()
+    {
+        $date = new DateTime('2010-01-28 15:00:00');
+        $date = $date->modify('+1 day');
+
+        $this->assertInstanceOf(DateTime::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');
+    }
+}

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(): DateTime`
`48`	`48`	`{`
`49`	`49`	`$now = ($this->clock ?? self::get())->now();`
`50`	`50`
	`51`	`+ if (!$now instanceof DateTime) {`
	`52`	`+ $now = DateTime::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 DateTime`
	`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 DateTime ? $now : DateTime::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 DateTime $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 DateTime($now, $timezone ?? new \DateTimeZone('UTC'));`
	`43`	`+ } elseif (!$now instanceof DateTime) {`
	`44`	`+ $now = DateTime::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(): DateTime`
`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 = DateTime::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(): DateTime`
`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 DateTime::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(): DateTime`
`32`	`32`	`{`
`33`		`- return new \DateTimeImmutable('now', $this->timezone);`
	`33`	`+ return DateTime::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
`@@ -13,13 +13,12 @@`
`13`	`13`
`14`	`14`	`if (!\function_exists(now::class)) {`
`15`	`15`	`/**`
`16`		`- * Returns the current time as a DateTimeImmutable.`
`17`		`- *`
`18`		`- * Note that you should prefer injecting a ClockInterface or using`
`19`		`- * ClockAwareTrait when possible instead of using this function.`
	`16`	`+ * Returns the current time as a \Symfony\Component\Clock\DateTime.`
`20`	`17`	`*/`
`21`		`- function now(): \DateTimeImmutable`
	`18`	`+ function now(): DateTime`
`22`	`19`	`{`
`23`		`- return Clock::get()->now();`
	`20`	`+ $now = Clock::get()->now();`
	`21`	`+`
	`22`	`+ return $now instanceof DateTime ? $now : DateTime::createFromInterface($now);`
`24`	`23`	`}`
`25`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@`
`14`	`14`	`use PHPUnit\Framework\TestCase;`
`15`	`15`	`use Psr\Clock\ClockInterface;`
`16`	`16`	`use Symfony\Component\Clock\Clock;`
	`17`	`+use Symfony\Component\Clock\DateTime;`
`17`	`18`	`use Symfony\Component\Clock\MockClock;`
`18`	`19`	`use Symfony\Component\Clock\NativeClock;`
`19`	`20`	`use Symfony\Component\Clock\Test\ClockSensitiveTrait;`
`@@ -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(DateTime::class, now());`
`39`	`40`	`$this->assertInstanceOf(NativeClock::class, Clock::get());`
`40`	`41`	`}`
`41`	`42`