feat: add UUID v7 generator helper method

src/Helpers/UUID.php

@@ -26,6 +26,54 @@
 			return "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF";
 		}
 
+		/**
+		 * Generate a version 7 UUID
+		 *
+		 * @return string
+		 */
+		function v7(): string {
+			static $last_unix_epoch = null;
+			static $sequence = 0;
+
+			// Get current time in milliseconds
+			$unix_ms = (int) microtime(true) * 1000;
+
+			// Compensate for same-ms collisions
+			if ($unix_ms === $last_unix_epoch) {
+				$sequence++;
+				// Keep within the 14-bit sequence range
+				$sequence &= 0x3FFF;
+
+				// Bump time slightly to avoid collision
+				if ($sequence === 0) {
+					$unix_ms++;
+				}
+			} else {
+				// Random start per ms
+				$sequence = random_int(0, 0x3FFF);
+				$last_unix_epoch = $unix_ms;
+			}
+
+			$time_high = ($unix_ms >> 16) & 0xFFFFFFFF;
+			$time_low = $unix_ms & 0xFFFF;
+
+			$time_hi_and_version = ($time_low & 0x0FFF) | (0x7 << 12);
+			$clock_seq_hi_and_reserved = ($sequence & 0x3FFF) | 0x8000;
+
+			// Generate 6 bytes (48 bits) of randomness
+			$rand_bytes = random_bytes(6);
+			$rand_hex = bin2hex($rand_bytes);
+
+			return sprintf(
+				"%08x-%04x-%04x-%04x-%012s",
+				$time_high,
+				$time_low,
+				$time_hi_and_version,
+				$clock_seq_hi_and_reserved,
+				$rand_hex
+			);
+		}
+
 		/**
 		 * Generate a version 4 UUID
 		 *