Introduce TimestampMilliseconds type and refactor DateTimeTimestamp to TimestampSeconds

- Added `TimestampMilliseconds` class for Unix timestamps in milliseconds, with strict validation and conversion utilities.
- Refactored `DateTimeTimestamp` to `TimestampSeconds` for naming consistency and enhanced functionality.
- Introduced `ReasonableRangeDateTimeTypeException` for range validation and improved error messaging.
- Updated documentation (`README.md`, `USAGE.md`) and enhanced examples with new timestamp types.
- Expanded unit tests to comprehensively cover parsing, formatting, and error scenarios for both milliseconds and seconds-based timestamps.

Author: georgedeploy

README.md

@@ -65,7 +65,7 @@ final class Profile
     public static function fromScalars(
         int $id,
         string $firstName,
-        string $lastName,
+        ?string $lastName,
     ): self {
         return new self(
             PositiveInt::fromInt($id),
@@ -78,6 +78,8 @@ final class Profile
 // Usage
 Profile::fromScalars(id: 101, firstName: 'Alice', lastName: 'Smith');
 Profile::fromScalars(id: 157, firstName: 'Tom', lastName: null);
+// From array
+$profile = Profile::fromScalars(...[157, 'Tom', null]);
 ```
 
 

docs/USAGE.md

@@ -41,16 +41,7 @@ Static usage examples
 ---------------------
 
 ```php
-use PhpTypedValues\Integer\IntegerBasic;
-use PhpTypedValues\Integer\PositiveInt;
-use PhpTypedValues\Integer\NonNegativeInt;
-use PhpTypedValues\Integer\WeekDayInt;
-use PhpTypedValues\String\StringBasic;
-use PhpTypedValues\String\NonEmptyStr;
-use PhpTypedValues\Float\FloatBasic;
-use PhpTypedValues\Float\NonNegativeFloat;
-use PhpTypedValues\DateTime\DateTimeAtom;
-use PhpTypedValues\DateTime\DateTimeTimestamp;
+use PhpTypedValues\DateTime\DateTimeAtom;use PhpTypedValues\DateTime\Timestamp\TimestampSeconds;use PhpTypedValues\Float\FloatBasic;use PhpTypedValues\Float\NonNegativeFloat;use PhpTypedValues\Integer\IntegerBasic;use PhpTypedValues\Integer\NonNegativeInt;use PhpTypedValues\Integer\PositiveInt;use PhpTypedValues\Integer\WeekDayInt;use PhpTypedValues\String\NonEmptyStr;use PhpTypedValues\String\StringBasic;
 
 // Integers
 $any = IntegerBasic::fromInt(-10);
@@ -74,7 +65,7 @@ $ratio = NonNegativeFloat::fromFloat(0.5);  // >= 0
 $dt = DateTimeAtom::fromString('2025-01-02T03:04:05+00:00');
 
 // DateTime (Unix timestamp, seconds)
-$unix = DateTimeTimestamp::fromString('1735787045');
+$unix = TimestampSeconds::fromString('1735787045');
 
 // Accessing value and string form
 $posValue = $pos->value();        // 1 (int)

src/Code/DateTime/DateTimeType.php

@@ -9,6 +9,7 @@
 use DateTimeImmutable;
 use DateTimeZone;
 use PhpTypedValues\Code\Exception\DateTimeTypeException;
+use PhpTypedValues\Code\Exception\ReasonableRangeDateTimeTypeException;
 
 use function count;
 use function sprintf;
@@ -20,11 +21,14 @@
 {
     protected const FORMAT = '';
     protected const ZONE = 'UTC';
+    protected const MIN_TIMESTAMP_SECONDS = -62135596800; // 0001-01-01
+    protected const MAX_TIMESTAMP_SECONDS = 253402300799; // 9999-12-31 23:59:59
 
     protected DateTimeImmutable $value;
 
     /**
      * @throws DateTimeTypeException
+     * @throws ReasonableRangeDateTimeTypeException
      */
     protected static function createFromFormat(
         string $value,
@@ -67,6 +71,16 @@ protected static function createFromFormat(
             throw new DateTimeTypeException(sprintf('Unexpected conversion, source string %s is not equal to formatted one %s', $value, $dt->format(static::FORMAT)));
         }
 
+        /**
+         * Assert that timestamp in a reasonable range.
+         *
+         * @psalm-suppress PossiblyFalseReference
+         */
+        $ts = $dt->format('U');
+        if ($ts < static::MIN_TIMESTAMP_SECONDS || $ts > static::MAX_TIMESTAMP_SECONDS) {
+            throw new ReasonableRangeDateTimeTypeException(sprintf('Timestamp "%s" out of supported range "%d"-"%d".', $ts, static::MIN_TIMESTAMP_SECONDS, static::MAX_TIMESTAMP_SECONDS));
+        }
+
         /**
          * $dt is not FALSE here, it will fail before on error checking.
          *
@@ -80,7 +94,13 @@ public function __construct(DateTimeImmutable $value)
         $this->value = $value;
     }
 
-    abstract public static function fromDateTime(DateTimeImmutable $value): self;
+    public static function fromDateTime(DateTimeImmutable $value): static
+    {
+        // normalized timezone
+        return new static(
+            $value->setTimezone(new DateTimeZone(static::ZONE))
+        );
+    }
 
     public function value(): DateTimeImmutable
     {

src/Code/Exception/ReasonableRangeDateTimeTypeException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Code\Exception;
+
+class ReasonableRangeDateTimeTypeException extends TypeException
+{
+}

src/DateTime/Timestamp/TimestampMilliseconds.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\DateTime\Timestamp;
+
+use DateTimeZone;
+use PhpTypedValues\Code\DateTime\DateTimeType;
+use PhpTypedValues\Code\Exception\DateTimeTypeException;
+
+use function intdiv;
+use function sprintf;
+
+/**
+ * Unix timestamp in milliseconds since Unix epoch (UTC), e.g. "1732445696123".
+ *
+ * @psalm-immutable
+ */
+readonly class TimestampMilliseconds extends DateTimeType
+{
+    /**
+     * Internal formatting pattern for seconds + microseconds.
+     *
+     * @see https://www.php.net/manual/en/datetime.format.php
+     */
+    protected const FORMAT = 'U.u';
+
+    /**
+     * Parse from a numeric Unix timestamp string (milliseconds).
+     *
+     * @throws DateTimeTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        if (!ctype_digit($value)) {
+            throw new DateTimeTypeException(sprintf('Expected milliseconds timestamp as digits, got "%s"', $value));
+        }
+
+        // "1732445696123" -> 1732445696 seconds, 123 milliseconds
+        $milliseconds = (int) $value;
+        $seconds = intdiv($milliseconds, 1000);
+        $msRemainder = $milliseconds % 1000;
+
+        // Convert the remainder to microseconds (pad to 3 digits, then * 1000)
+        $microseconds = $msRemainder * 1000;
+
+        // Build "seconds.microseconds" string for INTERNAL_FORMAT, e.g. "1732445696.123000"
+        $secondsWithMicro = sprintf('%d.%06d', $seconds, $microseconds);
+
+        return new static(
+            static::createFromFormat(
+                $secondsWithMicro,
+                self::FORMAT,
+                new DateTimeZone(static::ZONE)
+            )
+        );
+    }
+
+    /**
+     * Render as milliseconds since epoch, e.g. "1732445696123".
+     */
+    public function toString(): string
+    {
+        $dt = $this->value();
+
+        $seconds = (int) $dt->format('U');
+        $micros = (int) $dt->format('u');
+
+        $milliseconds = ($seconds * 1000) + intdiv($micros, 1000);
+
+        return (string) $milliseconds;
+    }
+}

src/DateTime/DateTimeTimestamp.php …/DateTime/Timestamp/TimestampSeconds.phpsrc/DateTime/DateTimeTimestamp.php renamed to src/DateTime/Timestamp/TimestampSeconds.php src/DateTime/DateTimeTimestamp.php renamed to src/DateTime/Timestamp/TimestampSeconds.php

@@ -2,19 +2,18 @@
 
 declare(strict_types=1);
 
-namespace PhpTypedValues\DateTime;
+namespace PhpTypedValues\DateTime\Timestamp;
 
-use DateTimeImmutable;
 use DateTimeZone;
 use PhpTypedValues\Code\DateTime\DateTimeType;
 use PhpTypedValues\Code\Exception\DateTimeTypeException;
 
 /**
- * Unix timestamp (seconds since Unix epoch, UTC).
+ * Unix timestamp (seconds since Unix epoch, UTC), e.g. "1732445696".
  *
  * @psalm-immutable
  */
-readonly class DateTimeTimestamp extends DateTimeType
+readonly class TimestampSeconds extends DateTimeType
 {
     /**
      * DateTime::format() pattern for Unix timestamp.
@@ -43,9 +42,4 @@ public function toString(): string
     {
         return $this->value()->format(static::FORMAT);
     }
-
-    public static function fromDateTime(DateTimeImmutable $value): static
-    {
-        return new static($value);
-    }
 }

src/psalmTest.php

@@ -10,7 +10,8 @@
 
 use PhpTypedValues\DateTime\DateTimeAtom;
 use PhpTypedValues\DateTime\DateTimeRFC3339;
-use PhpTypedValues\DateTime\DateTimeTimestamp;
+use PhpTypedValues\DateTime\Timestamp\TimestampMilliseconds;
+use PhpTypedValues\DateTime\Timestamp\TimestampSeconds;
 use PhpTypedValues\Float\FloatBasic;
 use PhpTypedValues\Float\NonNegativeFloat;
 use PhpTypedValues\Integer\IntegerBasic;
@@ -20,6 +21,21 @@
 use PhpTypedValues\String\NonEmptyStr;
 use PhpTypedValues\String\StringBasic;
 
+// try {
+//    echo DateTimeImmutable::createFromFormat('U.u', '953402300800.000000')->format('U.u');
+// } catch (Throwable $e) {
+//    var_dump('error');
+//    var_dump($e);
+// }
+//
+// try {
+//    echo TimestampMilliseconds::fromString('953402300800000')->toString(); // '253402300800000'
+// } catch (Throwable $e) {
+//    var_dump('error');
+//    var_dump($e);
+// }
+// exit('ssssssssss');
+
 /**
  * Integer.
  */
@@ -61,8 +77,11 @@
 echo DateTimeRFC3339::fromDateTime($dt)->toString() . \PHP_EOL;
 
 // Timestamp
-$tsVo = DateTimeTimestamp::fromString('1735787045');
-echo DateTimeTimestamp::fromDateTime($tsVo->value())->toString() . \PHP_EOL;
+$tsVo = TimestampSeconds::fromString('1735787045');
+echo TimestampSeconds::fromDateTime($tsVo->value())->toString() . \PHP_EOL;
+
+$tsVo = TimestampMilliseconds::fromString('1735787045123');
+echo TimestampMilliseconds::fromDateTime($tsVo->value())->toString() . \PHP_EOL;
 
 /**
  * Artificial functions.

tests/Unit/DateTime/Timestamp/TimestampMillisecondsTest.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\DateTime\Timestamp\TimestampMilliseconds;
+
+it('fromString returns same instant and toString is milliseconds', function (): void {
+    // 1,000,000,000,000 ms == 1,000,000,000 sec == 2001-09-09 01:46:40 UTC
+    $dt = new DateTimeImmutable('2001-09-09 01:46:40');
+    $vo = TimestampMilliseconds::fromString('1000000000000');
+
+    expect($vo->value()->format('U'))->toBe($dt->format('U'))
+        ->and($vo->toString())->toBe('1000000000000')
+        ->and($vo->value()->getTimezone()->getName())->toBe('+00:00');
+});
+
+it('fromDateTime preserves instant and renders milliseconds (truncates microseconds)', function (): void {
+    $dt = new DateTimeImmutable('2025-01-02T03:04:05.678+00:00');
+    $vo = TimestampMilliseconds::fromDateTime($dt);
+
+    // Expected milliseconds: 1735787045 seconds and 678 ms
+    expect($vo->value()->format('U'))->toBe('1735787045')
+        ->and($vo->toString())->toBe('1735787045678')
+        ->and($vo->value()->getTimezone()->getName())->toBe('UTC');
+});
+
+it('fromDateTime normalizes timezone to UTC while preserving the instant', function (): void {
+    // Source datetime has +03:00 offset, should be normalized to UTC internally
+    $dt = new DateTimeImmutable('2025-01-02T03:04:05.123+03:00');
+    $vo = TimestampMilliseconds::fromDateTime($dt);
+
+    // Unix timestamp in seconds must be equal regardless of timezone
+    expect($vo->value()->format('U'))->toBe($dt->format('U'))
+        ->and($vo->value()->getTimezone()->getName())->toBe('UTC')
+        // Milliseconds should reflect the source microseconds truncated to ms
+        ->and($vo->toString())->toBe((string) ((int) $dt->format('U') * 1000 + (int) ((int) $dt->format('u') / 1000)));
+});
+
+it('fromString throws on non-digit input', function (): void {
+    try {
+        TimestampMilliseconds::fromString('not-a-number');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\DateTimeTypeException::class)
+            ->and($e->getMessage())->toContain('Expected milliseconds timestamp as digits');
+    }
+});
+
+it('fromString throws on trailing data (non-digits)', function (): void {
+    try {
+        TimestampMilliseconds::fromString('1000000000000 ');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\DateTimeTypeException::class)
+            ->and($e->getMessage())->toContain('Expected milliseconds timestamp as digits');
+    }
+});
+
+it('fromString throws when value is out of supported range (createFromFormat returns false)', function (): void {
+    // 253402300800000 ms corresponds to 253402300800 seconds,
+    // which is just beyond 9999-12-31T23:59:59Z (the typical max supported date).
+    // This should make DateTimeImmutable::createFromFormat fail and return FALSE.
+    $tooLargeMs = '253402300800000';
+
+    try {
+        TimestampMilliseconds::fromString($tooLargeMs);
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\ReasonableRangeDateTimeTypeException::class)
+            ->and($e->getMessage())->toContain('Timestamp "253402300800" out of supported range "-62135596800"-"253402300799"')
+            ->and($e->getMessage())->toContain('253402300800');
+    }
+});