Add StringUuidV4 type with strict UUID v4 validation and comprehensive tests

- Introduced `StringUuidV4` class to validate and normalize UUID v4 values (RFC 4122).
- Added detailed error messages for invalid UUID 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/StringUuidV4.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;
+
+/**
+ * RFC 4122 version 4 (random).
+ *
+ * @psalm-immutable
+ */
+readonly class StringUuidV4 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);
+
+        // Most popular UUID type: RFC 4122 version 4 (random)
+        // Format: xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx (hex, case-insensitive)
+        if ($normalized === '') {
+            // Provide a distinct message for empty input to ensure mutation testing can distinguish the branch
+            throw new StringTypeException(sprintf('Expected non-empty UUID v4 (xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx), got "%s"', $value));
+        }
+
+        if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/', $normalized) !== 1) {
+            throw new StringTypeException(sprintf('Expected UUID v4 (xxxxxxxx-xxxx-4xxx-[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/StringUuidV4Test.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Code\Exception\StringTypeException;
+use PhpTypedValues\String\StringUuidV4;
+
+it('accepts a valid lowercase UUID v4 and preserves value', function (): void {
+    $uuid = '550e8400-e29b-41d4-a716-446655440000';
+    $s = new StringUuidV4($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 = '550E8400-E29B-41D4-A716-446655440000';
+    $s = StringUuidV4::fromString($upper);
+
+    expect($s->value())->toBe('550e8400-e29b-41d4-a716-446655440000')
+        ->and($s->toString())->toBe('550e8400-e29b-41d4-a716-446655440000');
+});
+
+it('throws on empty string', function (): void {
+    expect(fn() => new StringUuidV4(''))
+        ->toThrow(StringTypeException::class, 'Expected non-empty UUID v4 (xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx), got ""');
+});
+
+it('throws when UUID version is not 4 (e.g., version 1)', function (): void {
+    $v1 = '550e8400-e29b-11d4-a716-446655440000';
+    expect(fn() => StringUuidV4::fromString($v1))
+        ->toThrow(StringTypeException::class, 'Expected UUID v4 (xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $v1 . '"');
+});
+
+it('throws when UUID variant nibble is invalid (must be 8,9,a,b)', function (): void {
+    $badVariant = '550e8400-e29b-41d4-7716-446655440000';
+    expect(fn() => new StringUuidV4($badVariant))
+        ->toThrow(StringTypeException::class, 'Expected UUID v4 (xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $badVariant . '"');
+});
+
+it('throws on invalid characters or format (non-hex character)', function (): void {
+    $badChar = '550e8400-e29b-41d4-a716-44665544000g';
+    expect(fn() => StringUuidV4::fromString($badChar))
+        ->toThrow(StringTypeException::class, 'Expected UUID v4 (xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $badChar . '"');
+});