Debian Codegraph @

vendor/ramsey/uuid/src/Rfc4122/Fields.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\Rfc4122;
16
17 use Ramsey\Uuid\Exception\InvalidArgumentException;
18 use Ramsey\Uuid\Fields\SerializableFieldsTrait;
19 use Ramsey\Uuid\Type\Hexadecimal;
20 use Ramsey\Uuid\Uuid;
21
22 use function bin2hex;
23 use function dechex;
24 use function hexdec;
25 use function sprintf;
26 use function str_pad;
27 use function strlen;
28 use function substr;
29 use function unpack;
30
31 use const STR_PAD_LEFT;
32
33 /**
34 * RFC 9562 (formerly RFC 4122) variant UUIDs consist of a set of named fields
35 *
36 * Internally, this class represents the fields together as a 16-byte binary string.
37 *
38 * @immutable
39 */
40 final class Fields implements FieldsInterface
41 {
42 use MaxTrait;
43 use NilTrait;
44 use SerializableFieldsTrait;
45 use VariantTrait;
46 use VersionTrait;
47
48 /**
49 * @param string $bytes A 16-byte binary string representation of a UUID
50 *
51 * @throws InvalidArgumentException if the byte string is not exactly 16 bytes
52 * @throws InvalidArgumentException if the byte string does not represent an RFC 9562 (formerly RFC 4122) UUID
53 * @throws InvalidArgumentException if the byte string does not contain a valid version
54 */
55 public function __construct(private string $bytes)
56 {
57 if (strlen($this->bytes) !== 16) {
58 throw new InvalidArgumentException(
59 'The byte string must be 16 bytes long; ' . 'received ' . strlen($this->bytes) . ' bytes',
60 );
61 }
62
63 if (!$this->isCorrectVariant()) {
64 throw new InvalidArgumentException(
65 'The byte string received does not conform to the RFC 9562 (formerly RFC 4122) variant',
66 );
67 }
68
69 if (!$this->isCorrectVersion()) {
70 throw new InvalidArgumentException(
71 'The byte string received does not contain a valid RFC 9562 (formerly RFC 4122) version',
72 );
73 }
74 }
75
76 /**
77 * @pure
78 */
79 public function getBytes(): string
80 {
81 return $this->bytes;
82 }
83
84 public function getClockSeq(): Hexadecimal
85 {
86 if ($this->isMax()) {
87 $clockSeq = 0xffff;
88 } elseif ($this->isNil()) {
89 $clockSeq = 0x0000;
90 } else {
91 $clockSeq = hexdec(bin2hex(substr($this->bytes, 8, 2))) & 0x3fff;
92 }
93
94 return new Hexadecimal(str_pad(dechex($clockSeq), 4, '0', STR_PAD_LEFT));
95 }
96
97 public function getClockSeqHiAndReserved(): Hexadecimal
98 {
99 return new Hexadecimal(bin2hex(substr($this->bytes, 8, 1)));
100 }
101
102 public function getClockSeqLow(): Hexadecimal
103 {
104 return new Hexadecimal(bin2hex(substr($this->bytes, 9, 1)));
105 }
106
107 public function getNode(): Hexadecimal
108 {
109 return new Hexadecimal(bin2hex(substr($this->bytes, 10)));
110 }
111
112 public function getTimeHiAndVersion(): Hexadecimal
113 {
114 return new Hexadecimal(bin2hex(substr($this->bytes, 6, 2)));
115 }
116
117 public function getTimeLow(): Hexadecimal
118 {
119 return new Hexadecimal(bin2hex(substr($this->bytes, 0, 4)));
120 }
121
122 public function getTimeMid(): Hexadecimal
123 {
124 return new Hexadecimal(bin2hex(substr($this->bytes, 4, 2)));
125 }
126
127 /**
128 * Returns the full 60-bit timestamp, without the version
129 *
130 * For version 2 UUIDs, the time_low field is the local identifier and should not be returned as part of the time.
131 * For this reason, we set the bottom 32 bits of the timestamp to 0's. As a result, there is some loss of timestamp
132 * fidelity, for version 2 UUIDs. The timestamp can be off by a range of 0 to 429.4967295 seconds (or 7 minutes, 9
133 * seconds, and 496,730 microseconds).
134 *
135 * For version 6 UUIDs, the timestamp order is reversed from the typical RFC 9562 (formerly RFC 4122) order (the
136 * time bits are in the correct bit order, so that it is monotonically increasing). In returning the timestamp
137 * value, we put the bits in the order: time_low + time_mid + time_hi.
138 */
139 public function getTimestamp(): Hexadecimal
140 {
141 return new Hexadecimal(match ($this->getVersion()) {
142 Uuid::UUID_TYPE_DCE_SECURITY => sprintf(
143 '%03x%04s%08s',
144 hexdec($this->getTimeHiAndVersion()->toString()) & 0x0fff,
145 $this->getTimeMid()->toString(),
146 ''
147 ),
148 Uuid::UUID_TYPE_REORDERED_TIME => sprintf(
149 '%08s%04s%03x',
150 $this->getTimeLow()->toString(),
151 $this->getTimeMid()->toString(),
152 hexdec($this->getTimeHiAndVersion()->toString()) & 0x0fff
153 ),
154 // The Unix timestamp in version 7 UUIDs is a 48-bit number, but for consistency, we will return a 60-bit
155 // number, padded to the left with zeros.
156 Uuid::UUID_TYPE_UNIX_TIME => sprintf(
157 '%011s%04s',
158 $this->getTimeLow()->toString(),
159 $this->getTimeMid()->toString(),
160 ),
161 default => sprintf(
162 '%03x%04s%08s',
163 hexdec($this->getTimeHiAndVersion()->toString()) & 0x0fff,
164 $this->getTimeMid()->toString(),
165 $this->getTimeLow()->toString()
166 ),
167 });
168 }
169
170 public function getVersion(): ?int
171 {
172 if ($this->isNil() || $this->isMax()) {
173 return null;
174 }
175
176 /** @var int[] $parts */
177 $parts = unpack('n*', $this->bytes);
178
179 return $parts[4] >> 12;
180 }
181
182 private function isCorrectVariant(): bool
183 {
184 if ($this->isNil() || $this->isMax()) {
185 return true;
186 }
187
188 return $this->getVariant() === Uuid::RFC_4122;
189 }
190 }