Debian Codegraph @

vendor/ramsey/uuid/src/Generator/CombGenerator.php

raw
1 <?php
2
3 /**
4 * This file is part of the ramsey/uuid library
5 *
6 * For the full copyright and license information, please view the LICENSE
7 * file that was distributed with this source code.
8 *
9 * @copyright Copyright (c) Ben Ramsey <[email protected]>
10 * @license http://opensource.org/licenses/MIT MIT
11 */
12
13 declare(strict_types=1);
14
15 namespace Ramsey\Uuid\Generator;
16
17 use Ramsey\Uuid\Converter\NumberConverterInterface;
18 use Ramsey\Uuid\Exception\InvalidArgumentException;
19
20 use function bin2hex;
21 use function explode;
22 use function hex2bin;
23 use function microtime;
24 use function str_pad;
25 use function substr;
26
27 use const STR_PAD_LEFT;
28
29 /**
30 * CombGenerator generates COMBs (combined UUID/timestamp)
31 *
32 * The CombGenerator, when used with the StringCodec (and, by proxy, the TimestampLastCombCodec) or the
33 * TimestampFirstCombCodec, combines the current timestamp with a UUID (hence the name "COMB"). The timestamp either
34 * appears as the first or last 48 bits of the COMB, depending on the codec used.
35 *
36 * By default, COMBs will have the timestamp set as the last 48 bits of the identifier.
37 *
38 * ```
39 * $factory = new UuidFactory();
40 *
41 * $factory->setRandomGenerator(new CombGenerator(
42 * $factory->getRandomGenerator(),
43 * $factory->getNumberConverter(),
44 * ));
45 *
46 * $comb = $factory->uuid4();
47 * ```
48 *
49 * To generate a COMB with the timestamp as the first 48 bits, set the TimestampFirstCombCodec as the codec.
50 *
51 * ```
52 * $factory->setCodec(new TimestampFirstCombCodec($factory->getUuidBuilder()));
53 * ```
54 *
55 * @deprecated Please migrate to {@link https://uuid.ramsey.dev/en/stable/rfc4122/version7.html Version 7, Unix Epoch Time UUIDs}.
56 *
57 * @link https://web.archive.org/web/20240118030355/https://www.informit.com/articles/printerfriendly/25862 The Cost of GUIDs as Primary Keys
58 */
59 class CombGenerator implements RandomGeneratorInterface
60 {
61 public const TIMESTAMP_BYTES = 6;
62
63 public function __construct(
64 private RandomGeneratorInterface $generator,
65 private NumberConverterInterface $numberConverter
66 ) {
67 }
68
69 /**
70 * @throws InvalidArgumentException if $length is not a positive integer greater than or equal to CombGenerator::TIMESTAMP_BYTES
71 *
72 * @inheritDoc
73 */
74 public function generate(int $length): string
75 {
76 if ($length < self::TIMESTAMP_BYTES) {
77 throw new InvalidArgumentException(
78 'Length must be a positive integer greater than or equal to ' . self::TIMESTAMP_BYTES
79 );
80 }
81
82 if ($length % 2 !== 0) {
83 throw new InvalidArgumentException('Length must be an even number');
84 }
85
86 $hash = '';
87
88 /** @phpstan-ignore greater.alwaysTrue (TIMESTAMP_BYTES constant could change in child classes) */
89 if (self::TIMESTAMP_BYTES > 0 && $length > self::TIMESTAMP_BYTES) {
90 $hash = $this->generator->generate($length - self::TIMESTAMP_BYTES);
91 }
92
93 $lsbTime = str_pad(
94 $this->numberConverter->toHex($this->timestamp()),
95 self::TIMESTAMP_BYTES * 2,
96 '0',
97 STR_PAD_LEFT,
98 );
99
100 return (string) hex2bin(str_pad(bin2hex($hash), $length - self::TIMESTAMP_BYTES, '0') . $lsbTime);
101 }
102
103 /**
104 * Returns the current timestamp as a string integer, precise to 0.00001 seconds
105 */
106 private function timestamp(): string
107 {
108 $time = explode(' ', microtime(false));
109
110 return $time[1] . substr($time[0], 2, 5);
111 }
112 }