feat: Provide time zone functions

Author: pl-github

src/NotConvertable.php

@@ -38,6 +38,11 @@ public static function toDateTime(mixed $value): self
         return self::withMessage(sprintf('%s is not convertable to date time object', get_debug_type($value)));
     }
 
+    public static function toDateTimeZone(mixed $value): self
+    {
+        return self::withMessage(sprintf('%s is not convertable to date time zone', get_debug_type($value)));
+    }
+
     private static function withMessage(string $message): self
     {
         $me = new self($message);

src/TypeGuard.php

@@ -147,6 +147,28 @@ public function asDateTimeImmutable(mixed $value, DateTimeZone|string|null $time
         return new DateTimeImmutable(asString($value), $tz);
     }
 
+    /** @return ($value is null ? null : DateTimeZone) */
+    public function asDateTimeZone(mixed $value): DateTimeZone|null
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if ($value instanceof DateTimeZone) {
+            return $value;
+        }
+
+        if ($value instanceof Stringable) {
+            $value = (string) $value;
+        }
+
+        if (!is_string($value)) {
+            throw NotConvertable::toDateTimeZone($value);
+        }
+
+        return new DateTimeZone($value);
+    }
+
     /** @return ($value is null ? null : string) */
     public function asDateTimeString(mixed $value): string|null
     {

src/functions.php

@@ -58,6 +58,15 @@ function asDateTimeImmutable(
     }
 }
 
+if (!function_exists('\Plook\TypeGuard\asDateTimeZone')) { // @codeCoverageIgnore
+
+    /** @return ($value is null ? null : DateTimeZone) */
+    function asDateTimeZone(mixed $value): DateTimeZone|null
+    {
+        return TypeGuard::instance()->asDateTimeZone($value);
+    }
+}
+
 if (!function_exists('\Plook\TypeGuard\asDateTimeString')) { // @codeCoverageIgnore
 
     /** @return ($value is null ? null : string) */

tests/AsDateTimeZoneTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Plook\Tests\TypeGuard;
+
+use DateTimeZone;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversFunction;
+use PHPUnit\Framework\TestCase;
+use Plook\Tests\TypeGuard\Helper\StringableString;
+use Plook\TypeGuard\NotConvertable;
+use Plook\TypeGuard\TypeGuard;
+
+use function basename;
+use function Plook\TypeGuard\asDateTimeZone;
+use function sprintf;
+
+#[CoversClass(TypeGuard::class)]
+#[CoversClass(NotConvertable::class)]
+#[CoversFunction('Plook\TypeGuard\asDateTimeZone')]
+final class AsDateTimeZoneTest extends TestCase
+{
+    public function testConvertsStrings(): void
+    {
+        $dateTimeZone = asDateTimeZone('Europe/Berlin');
+
+        self::assertInstanceOf(DateTimeZone::class, $dateTimeZone);
+        self::assertSame('Europe/Berlin', $dateTimeZone->getName());
+    }
+
+    public function testConvertsStringables(): void
+    {
+        $dateTimeZone = asDateTimeZone(new StringableString('Australia/Adelaide'));
+
+        self::assertInstanceOf(DateTimeZone::class, $dateTimeZone);
+        self::assertSame('Australia/Adelaide', $dateTimeZone->getName());
+    }
+
+    public function testReturnsSameDateTimeZone(): void
+    {
+        $dateTimeZone = new DateTimeZone('Europe/Berlin');
+
+        $result = asDateTimeZone($dateTimeZone);
+
+        self::assertSame($dateTimeZone, $result);
+    }
+
+    public function testDoesNotTouchNull(): void
+    {
+        self::assertNull(asDateTimeZone(null));
+    }
+
+    public function testOnlyStringsAreConvertable(): void
+    {
+        $this->expectException(NotConvertable::class);
+        $this->expectExceptionMessageMatches(
+            sprintf(
+                '/Closure is not convertable to date time zone in %s:%s/',
+                basename(__FILE__),
+                __LINE__ + 4,
+            ),
+        );
+
+        asDateTimeZone(static fn (): null => null);
+    }
+}