Introduce DateTimeTimestamp type with strict Unix timestamp validation and comprehensive tests

- Added `DateTimeTimestamp` class for immutable Unix timestamp (UTC) representation.
- Extended `DateTimeType` with Unix timestamp-specific format and utilities.
- Implemented rigorous unit tests for parsing, formatting, and error scenarios.
- Updated documentation (`USAGE.md`) with examples showcasing `DateTimeTimestamp` usage.
- Enhanced `psalmTest.php` with additional `DateTimeTimestamp` demonstrations.

Author: georgedeploy

docs/USAGE.md

@@ -35,6 +35,7 @@ Floats (PhpTypedValues\Float):
 DateTime (PhpTypedValues\DateTime):
 
 - DateTimeAtom — immutable DateTime in RFC3339 (ATOM) format
+- DateTimeTimestamp — immutable DateTime represented as Unix timestamp (seconds since epoch, UTC)
 
 Static usage examples
 ---------------------
@@ -49,6 +50,7 @@ use PhpTypedValues\String\NonEmptyStr;
 use PhpTypedValues\Float\FloatBasic;
 use PhpTypedValues\Float\NonNegativeFloat;
 use PhpTypedValues\DateTime\DateTimeAtom;
+use PhpTypedValues\DateTime\DateTimeTimestamp;
 
 // Integers
 $any = IntegerBasic::fromInt(-10);
@@ -71,11 +73,15 @@ $ratio = NonNegativeFloat::fromFloat(0.5);  // >= 0
 // DateTime (RFC 3339 / ATOM)
 $dt = DateTimeAtom::fromString('2025-01-02T03:04:05+00:00');
 
+// DateTime (Unix timestamp, seconds)
+$unix = DateTimeTimestamp::fromString('1735787045');
+
 // Accessing value and string form
 $posValue = $pos->value();        // 1 (int)
 $wdText   = $wd->toString();      // "7"
 $priceStr = $price->toString();   // "19.99"
 $isoText  = $dt->toString();      // "2025-01-02T03:04:05+00:00"
+$unixText = $unix->toString();    // e.g. "1735787045"
 ```
 
 Validation errors (static constructors)

src/DateTime/DateTimeTimestamp.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\DateTime;
+
+use DateTimeImmutable;
+use DateTimeZone;
+use PhpTypedValues\Code\DateTime\DateTimeType;
+use PhpTypedValues\Code\Exception\DateTimeTypeException;
+
+/**
+ * Unix timestamp (seconds since Unix epoch, UTC).
+ *
+ * @psalm-immutable
+ */
+readonly class DateTimeTimestamp extends DateTimeType
+{
+    /**
+     * DateTime::format() pattern for Unix timestamp.
+     *
+     * @see https://www.php.net/manual/en/datetime.format.php
+     */
+    protected const FORMAT = 'U';
+
+    /**
+     * Parse from a numeric Unix timestamp string (seconds).
+     *
+     * @throws DateTimeTypeException
+     */
+    public static function fromString(string $value): self
+    {
+        return new self(
+            self::createFromFormat(
+                $value,
+                static::FORMAT,
+                new DateTimeZone(self::ZONE)
+            )
+        );
+    }
+
+    public function toString(): string
+    {
+        return $this->value()->format(self::FORMAT);
+    }
+
+    public static function fromDateTime(DateTimeImmutable $value): self
+    {
+        return new self($value);
+    }
+}

src/psalmTest.php

@@ -10,6 +10,7 @@
 
 use PhpTypedValues\DateTime\DateTimeAtom;
 use PhpTypedValues\DateTime\DateTimeRFC3339;
+use PhpTypedValues\DateTime\DateTimeTimestamp;
 use PhpTypedValues\Float\FloatBasic;
 use PhpTypedValues\Float\NonNegativeFloat;
 use PhpTypedValues\Integer\IntegerBasic;
@@ -59,6 +60,10 @@
 $dt = DateTimeRFC3339::fromString('2025-01-02T03:04:05+00:00')->value();
 echo DateTimeRFC3339::fromDateTime($dt)->toString() . \PHP_EOL;
 
+// Timestamp
+$tsVo = DateTimeTimestamp::fromString('1735787045');
+echo DateTimeTimestamp::fromDateTime($tsVo->value())->toString() . \PHP_EOL;
+
 /**
  * Artificial functions.
  */

tests/Unit/DateTime/DateTimeTimestampTest.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\DateTime\DateTimeTimestamp;
+
+it('fromDateTime returns same instant and toString is unix timestamp', function (): void {
+    $dt = new DateTimeImmutable('2001-09-09 01:46:40');
+    $vo = DateTimeTimestamp::fromString('1000000000');
+
+    expect($vo->value()->format('U'))->toBe($dt->format('U'))
+        ->and($vo->toString())->toBe($dt->format('U'));
+});
+
+it('fromDateTime returns same instant and toString is ISO 8601', function (): void {
+    $dt = new DateTimeImmutable('2025-01-02T03:04:05+00:00');
+    $vo = DateTimeTimestamp::fromDateTime($dt);
+
+    expect($vo->value()->format('U'))->toBe('1735787045')
+        ->and($vo->toString())->toBe('1735787045');
+});
+
+it('getFormat returns unix timestamp format U', function (): void {
+    expect(DateTimeTimestamp::getFormat())->toBe('U');
+});
+
+it('fromString throws on non-numeric input and reports details', function (): void {
+    try {
+        DateTimeTimestamp::fromString('not-a-number');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        $msg = $e->getMessage();
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\DateTimeTypeException::class)
+            ->and($msg)->toContain('Invalid date time value')
+            ->and((bool) preg_match('/(Error at|Warning at)/', $msg))->toBeTrue();
+    }
+});
+
+it('fromString throws on trailing data (warnings/errors path)', function (): void {
+    try {
+        DateTimeTimestamp::fromString('1000000000 ');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        $msg = $e->getMessage();
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\DateTimeTypeException::class)
+            ->and($msg)->toContain('Invalid date time value')
+            ->and((bool) preg_match('/(Error at|Warning at)/', $msg))->toBeTrue();
+    }
+});
+
+it('round-trip mismatch produces Unexpected conversion error for leading zeros', function (): void {
+    try {
+        DateTimeTimestamp::fromString('0000000005');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\DateTimeTypeException::class)
+            ->and($e->getMessage())->toContain('Unexpected conversion')
+            ->and($e->getMessage())->toContain('0000000005')
+            ->and($e->getMessage())->toContain('5');
+    }
+});