Normalize timezone handling across DateTime and Timestamp classes by defaulting to UTC. Implement FromString interface. Update tests to validate adjustments.

Author: georgedeploy

src/Base/Primitive/Bool/BoolType.php

@@ -5,6 +5,7 @@
 namespace PhpTypedValues\Base\Primitive\Bool;
 
 use PhpTypedValues\Base\Primitive\PrimitiveType;
+use PhpTypedValues\Base\Shared\FromString;
 
 /**
  * Base implementation for boolean typed values.
@@ -23,6 +24,6 @@
  *
  * @psalm-immutable
  */
-abstract readonly class BoolType extends PrimitiveType implements BoolTypeInterface
+abstract readonly class BoolType extends PrimitiveType implements BoolTypeInterface, FromString
 {
 }

src/Base/Primitive/DateTime/DateTimeType.php

@@ -35,7 +35,7 @@
 abstract readonly class DateTimeType extends PrimitiveType implements DateTimeTypeInterface
 {
     protected const FORMAT = '';
-    protected const ZONE = 'UTC';
+    public const ZONE = 'UTC';
     protected const MIN_TIMESTAMP_SECONDS = -62135596800; // 0001-01-01
     protected const MAX_TIMESTAMP_SECONDS = 253402300799; // 9999-12-31 23:59:59
 

src/Base/Primitive/DateTime/DateTimeTypeInterface.php

@@ -22,6 +22,8 @@
  */
 interface DateTimeTypeInterface
 {
+    public const ZONE = 'UTC';
+
     public function value(): DateTimeImmutable;
 
     public static function fromDateTime(DateTimeImmutable $value): static;
@@ -30,8 +32,17 @@ public static function tryFromMixed(mixed $value): static|Undefined;
 
     public static function tryFromString(string $value): static|Undefined;
 
+    /**
+     * @param non-empty-string $timezone
+     */
+    public static function fromString(string $value, string $timezone = self::ZONE): static;
+
     /**
      * @param non-empty-string $timezone
      */
     public function withTimeZone(string $timezone): static;
+
+    public static function getFormat(): string;
+
+    public function toString(): string;
 }

src/Base/Primitive/Float/FloatType.php

@@ -5,6 +5,7 @@
 namespace PhpTypedValues\Base\Primitive\Float;
 
 use PhpTypedValues\Base\Primitive\PrimitiveType;
+use PhpTypedValues\Base\Shared\FromString;
 use PhpTypedValues\Exception\FloatTypeException;
 
 use function sprintf;
@@ -26,7 +27,7 @@
  *
  * @psalm-immutable
  */
-abstract readonly class FloatType extends PrimitiveType implements FloatTypeInterface
+abstract readonly class FloatType extends PrimitiveType implements FloatTypeInterface, FromString
 {
     /**
      * @throws FloatTypeException

src/Base/Primitive/Integer/IntType.php

@@ -5,6 +5,7 @@
 namespace PhpTypedValues\Base\Primitive\Integer;
 
 use PhpTypedValues\Base\Primitive\PrimitiveType;
+use PhpTypedValues\Base\Shared\FromString;
 use PhpTypedValues\Exception\IntegerTypeException;
 
 use function sprintf;
@@ -26,7 +27,7 @@
  *
  * @psalm-immutable
  */
-abstract readonly class IntType extends PrimitiveType implements IntTypeInterface
+abstract readonly class IntType extends PrimitiveType implements IntTypeInterface, FromString
 {
     /**
      * @throws IntegerTypeException

src/Base/Primitive/PrimitiveTypeInterface.php

@@ -8,14 +8,13 @@
 use PhpTypedValues\Base\Shared\IsEmptyInterface;
 use PhpTypedValues\Base\Shared\IsUndefinedInterface;
 use PhpTypedValues\Base\TypeInterface;
-use PhpTypedValues\Exception\TypeException;
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Base contract for all immutable typed values in this library.
  *
  * Responsibilities
- *  - Provide strict construction from a validated string via {@see fromString}.
+ *  - Provide strict construction from a validated string via {@see FromString}.
  *  - Provide a lossless string representation via {@see toString} and {@see __toString}.
  *  - Concrete implementations may also provide tolerant factories like
  *    `tryFromMixed(mixed): static|Undefined` that return {@see Undefined} on failure.
@@ -27,17 +26,6 @@
  */
 interface PrimitiveTypeInterface extends TypeInterface, JsonSerializable, IsEmptyInterface, IsUndefinedInterface
 {
-    /**
-     * Create an instance from a validated string representation.
-     *
-     * Implementations should perform strict validation and may throw a
-     * domain-specific subtype of {@see TypeException}
-     * when the provided value is invalid.
-     *
-     * @throws TypeException
-     */
-    public static function fromString(string $value): static;
-
     /**
      * Returns a normalized string representation of the underlying value.
      */

src/Base/Primitive/String/StrType.php

@@ -5,6 +5,7 @@
 namespace PhpTypedValues\Base\Primitive\String;
 
 use PhpTypedValues\Base\Primitive\PrimitiveType;
+use PhpTypedValues\Base\Shared\FromString;
 
 /**
  * Base implementation for string-typed values.
@@ -23,6 +24,6 @@
  *
  * @psalm-immutable
  */
-abstract readonly class StrType extends PrimitiveType implements StrTypeInterface
+abstract readonly class StrType extends PrimitiveType implements StrTypeInterface, FromString
 {
 }

src/Base/Primitive/Undefined/UndefinedType.php

@@ -5,6 +5,7 @@
 namespace PhpTypedValues\Base\Primitive\Undefined;
 
 use PhpTypedValues\Base\Primitive\PrimitiveType;
+use PhpTypedValues\Base\Shared\FromString;
 
 /**
  * Base implementation for a special "Undefined/Unknown" typed value.
@@ -22,6 +23,6 @@
  *
  * @psalm-immutable
  */
-abstract readonly class UndefinedType extends PrimitiveType implements UndefinedTypeInterface
+abstract readonly class UndefinedType extends PrimitiveType implements UndefinedTypeInterface, FromString
 {
 }

src/Base/Shared/FromString.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Base\Shared;
+
+use PhpTypedValues\Exception\TypeException;
+
+/**
+ * Base contract to convert string to an object.
+ *
+ * @psalm-immutable
+ */
+interface FromString
+{
+    /**
+     * Create an instance from a validated string representation.
+     *
+     * Implementations should perform strict validation and may throw a
+     * domain-specific subtype of {@see TypeException}
+     * when the provided value is invalid.
+     *
+     * @throws TypeException
+     */
+    public static function fromString(string $value): static;
+}

src/DateTime/DateTimeAtom.php

@@ -36,7 +36,8 @@
 
     public function __construct(DateTimeImmutable $value)
     {
-        $this->value = $value;
+        // normalized time zone
+        $this->value = $value->setTimezone(new DateTimeZone(static::ZONE));
     }
 
     /**
@@ -96,10 +97,7 @@ public function toString(): string
 
     public static function fromDateTime(DateTimeImmutable $value): static
     {
-        // normalized timezone
-        return new static(
-            $value->setTimezone(new DateTimeZone(static::ZONE))
-        );
+        return new static($value);
     }
 
     public function jsonSerialize(): string