fix: Add possibility to override default timezone in asDateTimeImmutable()

Author: Stephan Wentz

src/TypeGuard.php

@@ -118,19 +118,22 @@ public function asString(mixed $value): string|null
         return (string) $value;
     }
 
-    /** @return DateTimeImmutable */
-    public function asDateTimeImmutable(mixed $value): DateTimeImmutable|null
+    public function asDateTimeImmutable(mixed $value, DateTimeZone|string|null $timeZone = null): DateTimeImmutable|null
     {
         if ($value === null) {
             return null;
         }
 
+        $tz = $timeZone instanceof DateTimeZone
+            ? $timeZone
+            : ($timeZone !== null ? new DateTimeZone($timeZone) : $this->timeZone());
+
         if ($value instanceof DateTimeImmutable) {
-            if ($value->getTimezone()->getName() === $this->timeZone()->getName()) {
+            if ($value->getTimezone()->getName() === $tz->getName()) {
                 return $value;
             }
 
-            return $value->setTimezone($this->timeZone());
+            return $value->setTimezone($tz);
         }
 
         if ($value instanceof Stringable) {
@@ -141,7 +144,7 @@ public function asDateTimeImmutable(mixed $value): DateTimeImmutable|null
             throw NotConvertable::toDateTime($value);
         }
 
-        return new DateTimeImmutable(asString($value), $this->timeZone());
+        return new DateTimeImmutable(asString($value), $tz);
     }
 
     /** @return ($value is null ? null : string) */

src/functions.php

@@ -5,6 +5,7 @@
 namespace Plook\TypeGuard;
 
 use DateTimeImmutable;
+use DateTimeZone;
 
 use function function_exists;
 
@@ -49,9 +50,11 @@ function asString(mixed $value): string|null
 if (!function_exists('\Plook\TypeGuard\asDateTimeImmutable')) { // @codeCoverageIgnore
 
     /** @return ($value is null ? null : DateTimeImmutable) */
-    function asDateTimeImmutable(mixed $value): DateTimeImmutable|null
-    {
-        return TypeGuard::instance()->asDateTimeImmutable($value);
+    function asDateTimeImmutable(
+        mixed $value,
+        DateTimeZone|string|null $timeZone = null,
+    ): DateTimeImmutable|null {
+        return TypeGuard::instance()->asDateTimeImmutable($value, $timeZone);
     }
 }
 

tests/AsDateTimeImmutableTest.php

@@ -94,6 +94,63 @@ public function testDoesNotTouchNull(): void
         self::assertNull(asDateTimeImmutable(null));
     }
 
+    public function testTimezoneParameterOverridesDefaultWithDateTimeZone(): void
+    {
+        $result = asDateTimeImmutable('2010-09-08 07:06:05', new DateTimeZone('Australia/Adelaide'));
+
+        self::assertInstanceOf(DateTimeImmutable::class, $result);
+        self::assertSame('2010-09-08T07:06:05+09:30', $result->format('c'));
+    }
+
+    public function testTimezoneParameterOverridesDefaultWithString(): void
+    {
+        $result = asDateTimeImmutable('2010-09-08 07:06:05', 'Australia/Adelaide');
+
+        self::assertInstanceOf(DateTimeImmutable::class, $result);
+        self::assertSame('2010-09-08T07:06:05+09:30', $result->format('c'));
+    }
+
+    public function testTimezoneParameterOverridesChangedDefault(): void
+    {
+        TypeGuard::instance()->timeZone('Europe/Berlin');
+
+        $result = asDateTimeImmutable('2010-09-08 07:06:05', 'Australia/Adelaide');
+
+        self::assertInstanceOf(DateTimeImmutable::class, $result);
+        self::assertSame('2010-09-08T07:06:05+09:30', $result->format('c'));
+    }
+
+    public function testTimezoneParameterConvertsSameDateTimeImmutable(): void
+    {
+        $input = new DateTimeImmutable('2010-09-08T07:06:05', new DateTimeZone('Australia/Adelaide'));
+
+        $result = asDateTimeImmutable($input, 'Australia/Adelaide');
+
+        self::assertInstanceOf(DateTimeImmutable::class, $result);
+        self::assertSame('Australia/Adelaide', $result->getTimezone()->getName());
+        self::assertSame('2010-09-08T07:06:05+09:30', $result->format('c'));
+    }
+
+    public function testTimezoneParameterConvertsDifferentDateTimeImmutable(): void
+    {
+        $input = new DateTimeImmutable('2010-09-08T07:06:05+00:00');
+
+        $result = asDateTimeImmutable($input, new DateTimeZone('Australia/Adelaide'));
+
+        self::assertInstanceOf(DateTimeImmutable::class, $result);
+        self::assertSame('2010-09-08T16:36:05+09:30', $result->format('c'));
+    }
+
+    public function testNullTimezoneParameterUsesDefault(): void
+    {
+        TypeGuard::instance()->timeZone('Australia/Adelaide');
+
+        $result = asDateTimeImmutable('2010-09-08 07:06:05', null);
+
+        self::assertInstanceOf(DateTimeImmutable::class, $result);
+        self::assertSame('2010-09-08T07:06:05+09:30', $result->format('c'));
+    }
+
     public function testOnlyScalarsAreConvertable(): void
     {
         $this->expectException(NotConvertable::class);