Add StringUuidV7::generate method with UUID v7 generation and test cases

- Implemented `StringUuidV7::generate` to produce valid, lowercase UUID v7 values as per RFC 4122 standard.
- Integrated `GenerateInterface` for reusable value generation capabilities.
- Enhanced unit tests to verify UUID v7 validity, uniqueness, lexicographic time-ordering, and format compliance.

Author: georgedeploy

src/String/StringUuidV7.php

@@ -4,9 +4,14 @@
 
 namespace PhpTypedValues\String;
 
+use const STR_PAD_LEFT;
+
+use PhpTypedValues\Code\Contract\GenerateInterface;
 use PhpTypedValues\Code\Exception\StringTypeException;
 use PhpTypedValues\Code\String\StrType;
+use Random\RandomException;
 
+use function ord;
 use function preg_match;
 use function sprintf;
 use function strtolower;
@@ -16,7 +21,7 @@
  *
  * @psalm-immutable
  */
-readonly class StringUuidV7 extends StrType
+readonly class StringUuidV7 extends StrType implements GenerateInterface
 {
     /** @var non-empty-string */
     protected string $value;
@@ -56,4 +61,53 @@ public function value(): string
     {
         return $this->value;
     }
+
+    /**
+     * @throws RandomException
+     * @throws StringTypeException
+     */
+    public static function generate(): static
+    {
+        // Get current Unix time in milliseconds (48 bits)
+        // Use a float literal for the multiplier to satisfy Psalm strict operands (float*float)
+        $timeMs = (int) floor(microtime(true) * 1000.0);
+
+        // Split timestamp into 48 bits: high 32 bits and low 16 bits
+        $timeHigh = ($timeMs & 0xFFFFFFFF0000) >> 16; // upper 32 bits of 48-bit timestamp
+        $timeLow = $timeMs & 0xFFFF;                 // lower 16 bits
+
+        // Generate 10 random bytes for the remaining fields
+        $random = random_bytes(10);
+
+        // Build the UUID fields (all integers) according to UUID v7 layout
+        // time_high (32 bits)
+        $timeHighHex = str_pad(dechex($timeHigh), 8, '0', STR_PAD_LEFT);
+
+        // time_mid (16 bits)
+        $timeMidHex = str_pad(dechex($timeLow), 4, '0', STR_PAD_LEFT);
+
+        // time_hi_and_version (16 bits): high 4 bits = version 7 (0b0111)
+        $timeHiAndVersion = (ord($random[0]) & 0x0F) | 0x70; // clear high 4 bits, set to 0111
+        $timeHiAndVersionHex = sprintf('%02x%02x', $timeHiAndVersion, ord($random[1]));
+
+        // clock_seq_hi_and_reserved (8 bits): set variant to 0b10xx
+        $clockSeqHi = (ord($random[2]) & 0x3F) | 0x80; // clear top 2 bits, set to 10
+        $clockSeqLow = ord($random[3]);
+        $clockSeqHex = sprintf('%02x%02x', $clockSeqHi, $clockSeqLow);
+
+        // node (48 bits) = remaining 6 random bytes
+        $nodeHex = bin2hex(substr($random, 4, 6));
+
+        // Assemble canonical UUID string: 8-4-4-4-12
+        $uuid = sprintf(
+            '%s-%s-%s-%s-%s',
+            $timeHighHex,
+            $timeMidHex,
+            $timeHiAndVersionHex,
+            $clockSeqHex,
+            $nodeHex
+        );
+
+        return new static($uuid);
+    }
 }

tests/Unit/String/StringUuidV7Test.php

@@ -45,3 +45,28 @@
     expect(fn() => StringUuidV7::fromString($badChar))
         ->toThrow(StringTypeException::class, 'Expected UUID v7 (xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx), got "' . $badChar . '"');
 });
+
+it('generate produces a valid lowercase UUID v7 and different values across calls', function (): void {
+    $a = StringUuidV7::generate();
+    $b = StringUuidV7::generate();
+
+    $regex = '/^[0-9a-f]{8}-[0-9a-f]{4}-7[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()))
+        ->and($b->toString())->toMatch($regex)
+        ->and($b->toString())->toBe(strtolower($b->toString()))
+        // Two generated UUIDs should almost certainly differ
+        ->and($a->toString())->not->toBe($b->toString());
+});
+
+it('generate produces time-ordered UUID v7 (lexicographic order increases over time)', function (): void {
+    $first = StringUuidV7::generate();
+    // Sleep a little to ensure the next millisecond is different on most systems
+    usleep(2000); // 2 ms
+    $second = StringUuidV7::generate();
+
+    // For UUID v7, the canonical string representation is time-ordered; later values should compare greater
+    expect(strcmp($first->toString(), $second->toString()))->toBeLessThan(0);
+});