Add StringUuidV4::generate implementation with RFC 4122 UUID v4 generation and tests

- Implemented `StringUuidV4::generate` method to produce valid, lowercase UUID v4 values as per RFC 4122 standard.
- Introduced `GenerateInterface` for reusable value generation.
- Enhanced unit tests to verify UUID validity, uniqueness, and proper formatting.
- Updated `psalmTest.php` with `StringUuidV4::generate` demonstration.

Author: georgedeploy

src/Code/Contract/GenerateInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Code\Contract;
+
+/**
+ * @psalm-immutable
+ */
+interface GenerateInterface
+{
+    public static function generate(): static;
+}

src/String/StringUuidV4.php

@@ -4,9 +4,13 @@
 
 namespace PhpTypedValues\String;
 
+use PhpTypedValues\Code\Contract\GenerateInterface;
 use PhpTypedValues\Code\Exception\StringTypeException;
 use PhpTypedValues\Code\String\StrType;
+use Random\RandomException;
 
+use function chr;
+use function ord;
 use function preg_match;
 use function sprintf;
 use function strtolower;
@@ -16,7 +20,7 @@
  *
  * @psalm-immutable
  */
-readonly class StringUuidV4 extends StrType
+readonly class StringUuidV4 extends StrType implements GenerateInterface
 {
     /** @var non-empty-string */
     protected string $value;
@@ -56,4 +60,33 @@ public function value(): string
     {
         return $this->value;
     }
+
+    /**
+     * @throws RandomException
+     * @throws StringTypeException
+     */
+    public static function generate(): static
+    {
+        // UUID v4: 16 random bytes, with version and variant bits set as per RFC 4122
+        $bytes = random_bytes(16);
+
+        // Set version to 4 (0100xxxx)
+        $bytes[6] = chr((ord($bytes[6]) & 0x0F) | 0x40);
+
+        // Set variant to RFC 4122 (10xxxxxx)
+        $bytes[8] = chr((ord($bytes[8]) & 0x3F) | 0x80);
+
+        $hex = bin2hex($bytes);
+
+        $uuid = sprintf(
+            '%s-%s-%s-%s-%s',
+            substr($hex, 0, 8),
+            substr($hex, 8, 4),
+            substr($hex, 12, 4),
+            substr($hex, 16, 4),
+            substr($hex, 20, 12)
+        );
+
+        return new static($uuid);
+    }
 }

src/psalmTest.php

@@ -25,6 +25,8 @@
 use PhpTypedValues\String\Alias\NonEmptyStr;
 use PhpTypedValues\String\StringNonEmpty;
 use PhpTypedValues\String\StringStandard;
+use PhpTypedValues\String\StringUuidV4;
+use PhpTypedValues\String\StringUuidV7;
 
 /**
  * Integer.
@@ -47,6 +49,8 @@
 
 echo StringStandard::fromString('hi')->toString() . \PHP_EOL;
 echo NonEmptyStr::fromString('hi')->toString() . \PHP_EOL;
+echo StringUuidV7::generate()->toString() . \PHP_EOL;
+echo StringUuidV4::generate()->toString() . \PHP_EOL;
 
 /**
  * Float.

tests/Unit/String/StringUuidV4Test.php

@@ -43,3 +43,18 @@
     expect(fn() => StringUuidV4::fromString($badChar))
         ->toThrow(StringTypeException::class, 'Expected UUID v4 (xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $badChar . '"');
 });
+
+it('generate produces a valid lowercase UUID v4 and different values across calls', function (): void {
+    $a = StringUuidV4::generate();
+    $b = StringUuidV4::generate();
+
+    $regex = '/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/';
+
+    expect($a->toString())->toMatch($regex)
+        ->and($a->value())->toBe($a->toString())
+        ->and($a->toString())->toBe(strtolower($a->toString()))
+        // Two subsequently generated UUIDs should not be equal with overwhelmingly high probability
+        ->and($a->toString())->not->toBe($b->toString())
+        ->and($b->toString())->toMatch($regex)
+        ->and($b->toString())->toBe(strtolower($b->toString()));
+});