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/License.php

@@ -0,0 +1,34 @@
+<?php
+
+	namespace vlw\Scaffold\Helpers;
+
+	class License {
+		public const MAGNET_END = PHP_EOL . "// @license-end";
+
+		public const GPL_V3_MAGNET = "// @license magnet:?xt=urn:btih:1f739d935676111cfff4b4693e3816e664797050&dn=gpl-3.0.txt GPL-v3-or-Later";
+		public const GPL_V3_BLOCK = "<script><!--//--><![CDATA[//><!--
+			/**
+			 * @licstart The following is the entire license notice for the JavaScript
+			 * code in this page.
+			 *
+			 * Copyright (C) 2020  Free Software Foundation.
+			 *
+			 * The JavaScript code in this page is free software: you can redistribute
+			 * it and/or modify it under the terms of the GNU General Public License
+			 * (GNU GPL) as published by the Free Software Foundation, either version 3
+			 * of the License, or (at your option) any later version.  The code is
+			 * distributed WITHOUT ANY WARRANTY; without even the implied warranty of
+			 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU GPL
+			 * for more details.
+			 *
+			 * As additional permission under GNU GPL version 3 section 7, you may
+			 * distribute non-source (e.g., minimized or compacted) forms of that code
+			 * without the copy of the GNU GPL normally required by section 4, provided
+			 * you include this license notice and a URL through which recipients can
+			 * access the Corresponding Source.
+			 *
+			 * @licend The above is the entire license notice for the JavaScript code
+			 * in this page.
+			 */
+		//--><!]]></script>";
+	}

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
 		 *