feat: add UUID v7 generator helper method (#17)

This PR adds a `UUID::v7()` method for generating version 7 UUIDs, which have several performace advantages over v4 when stored in database indecies.

Reviewed-on: https://codeberg.org/vlw/scaffold/pulls/17

src/Database/Model.php

@@ -97,14 +97,16 @@
 		 *
 		 * @param string $key Target column to update
 		 * @param mixed $value New value of target column
-		 * @return bool Update was successful
+		 * @return mixed The value that was sent to $value
 		 */
-		public function set(string $key, mixed $value): bool {
+		public function set(string $key, mixed $value): mixed {
 			$this->_row[$key] = $value;
 
-			return $this->db
+			$this->db
 				->from($this->table)
 				->where($this->where)
 				->update([$key => $value]);
+
+			return $value;
 		}
 	}

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
 		 *