Add StringUuidV7 type with strict UUID v7 validation and comprehensive tests

- Introduced `StringUuidV7` class to validate and normalize UUID v7 values (Unix time-based, RFC 4122).
- Added detailed error messages for invalid formats, incorrect versions, empty values, or invalid variants.
- Implemented comprehensive unit tests covering valid UUID preservation, normalization, and various error scenarios.

Author: georgedeploy

src/String/StringUuidV7.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String;
+
+use PhpTypedValues\Code\Exception\StringTypeException;
+use PhpTypedValues\Code\String\StrType;
+
+use function preg_match;
+use function sprintf;
+use function strtolower;
+
+/**
+ * UUID version 7 (time-ordered, Unix time-based).
+ *
+ * @psalm-immutable
+ */
+readonly class StringUuidV7 extends StrType
+{
+    /** @var non-empty-string */
+    protected string $value;
+
+    /**
+     * @throws StringTypeException
+     */
+    public function __construct(string $value)
+    {
+        // Normalize to lowercase for consistent representation
+        $normalized = strtolower($value);
+
+        if ($normalized === '') {
+            // Distinct message for empty input
+            throw new StringTypeException(sprintf('Expected non-empty UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got "%s"', $value));
+        }
+
+        // RFC 4122-style UUID v7:
+        // xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx (hex, case-insensitive)
+        if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/', $normalized) !== 1) {
+            throw new StringTypeException(sprintf('Expected UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got "%s"', $value));
+        }
+
+        $this->value = $normalized;
+    }
+
+    /**
+     * @throws StringTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        return new static($value);
+    }
+
+    /** @return non-empty-string */
+    public function value(): string
+    {
+        return $this->value;
+    }
+}

tests/Unit/String/StringUuidV7Test.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Code\Exception\StringTypeException;
+use PhpTypedValues\String\StringUuidV7;
+
+it('accepts a valid lowercase UUID v7 and preserves value', function (): void {
+    // Matches: xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx
+    $uuid = '01890f2a-5bcd-7def-8abc-1234567890ab';
+    $s = new StringUuidV7($uuid);
+
+    expect($s->value())->toBe($uuid)
+        ->and($s->toString())->toBe($uuid);
+});
+
+it('normalizes uppercase input to lowercase while preserving the UUID semantics', function (): void {
+    $upper = '01890F2A-5BCD-7DEF-9ABC-1234567890AB';
+    $s = StringUuidV7::fromString($upper);
+
+    expect($s->value())->toBe('01890f2a-5bcd-7def-9abc-1234567890ab')
+        ->and($s->toString())->toBe('01890f2a-5bcd-7def-9abc-1234567890ab');
+});
+
+it('throws on empty string', function (): void {
+    expect(fn() => new StringUuidV7(''))
+        ->toThrow(StringTypeException::class, 'Expected non-empty UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got ""');
+});
+
+it('throws when UUID version is not 7 (e.g., version 4)', function (): void {
+    $v4 = '550e8400-e29b-41d4-a716-446655440000';
+    expect(fn() => StringUuidV7::fromString($v4))
+        ->toThrow(StringTypeException::class, 'Expected UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $v4 . '"');
+});
+
+it('throws when UUID variant nibble is invalid (must be 8,9,a,b)', function (): void {
+    // Fourth group starts with '7' which is invalid for RFC 4122 variant
+    $badVariant = '550e8400-e29b-7d14-7716-446655440000';
+    expect(fn() => new StringUuidV7($badVariant))
+        ->toThrow(StringTypeException::class, 'Expected UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $badVariant . '"');
+});
+
+it('throws on invalid characters or format (non-hex character)', function (): void {
+    $badChar = '01890f2a-5bcd-7def-8abc-1234567890ag';
+    expect(fn() => StringUuidV7::fromString($badChar))
+        ->toThrow(StringTypeException::class, 'Expected UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $badChar . '"');
+});