Debian Codegraph @

vendor/ramsey/uuid/src/Lazy/LazyUuidFromString.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\Lazy;
16
17 use DateTimeInterface;
18 use Ramsey\Uuid\Converter\NumberConverterInterface;
19 use Ramsey\Uuid\Exception\UnsupportedOperationException;
20 use Ramsey\Uuid\Fields\FieldsInterface;
21 use Ramsey\Uuid\Rfc4122\UuidV1;
22 use Ramsey\Uuid\Rfc4122\UuidV6;
23 use Ramsey\Uuid\Type\Hexadecimal;
24 use Ramsey\Uuid\Type\Integer as IntegerObject;
25 use Ramsey\Uuid\UuidFactory;
26 use Ramsey\Uuid\UuidInterface;
27 use ValueError;
28
29 use function assert;
30 use function bin2hex;
31 use function hex2bin;
32 use function sprintf;
33 use function str_replace;
34 use function substr;
35
36 /**
37 * Lazy version of a UUID: its format has not been determined yet, so it is mostly only usable for string/bytes
38 * conversion. This object optimizes instantiation, serialization and string conversion time, at the cost of increased
39 * overhead for more advanced UUID operations.
40 *
41 * > [!NOTE]
42 * > The {@see FieldsInterface} does not declare methods that deprecated API relies upon: the API has been ported from
43 * > the {@see \Ramsey\Uuid\Uuid} definition, and is deprecated anyway.
44 *
45 * > [!NOTE]
46 * > The deprecated API from {@see \Ramsey\Uuid\Uuid} is in use here (on purpose): it will be removed once the
47 * > deprecated API is gone from this class too.
48 *
49 * @internal this type is used internally for performance reasons and is not supposed to be directly referenced in consumer libraries.
50 */
51 final class LazyUuidFromString implements UuidInterface
52 {
53 public const VALID_REGEX = '/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/ms';
54
55 private ?UuidInterface $unwrapped = null;
56
57 /**
58 * @param non-empty-string $uuid
59 */
60 public function __construct(private string $uuid)
61 {
62 }
63
64 public static function fromBytes(string $bytes): self
65 {
66 $base16Uuid = bin2hex($bytes);
67
68 return new self(
69 substr($base16Uuid, 0, 8)
70 . '-'
71 . substr($base16Uuid, 8, 4)
72 . '-'
73 . substr($base16Uuid, 12, 4)
74 . '-'
75 . substr($base16Uuid, 16, 4)
76 . '-'
77 . substr($base16Uuid, 20, 12)
78 );
79 }
80
81 public function serialize(): string
82 {
83 return $this->uuid;
84 }
85
86 /**
87 * @return array{string: non-empty-string}
88 */
89 public function __serialize(): array
90 {
91 return ['string' => $this->uuid];
92 }
93
94 /**
95 * {@inheritDoc}
96 *
97 * @param non-empty-string $data
98 */
99 public function unserialize(string $data): void
100 {
101 $this->uuid = $data;
102 }
103
104 /**
105 * @param array{string?: non-empty-string} $data
106 */
107 public function __unserialize(array $data): void
108 {
109 // @codeCoverageIgnoreStart
110 if (!isset($data['string'])) {
111 throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
112 }
113 // @codeCoverageIgnoreEnd
114
115 $this->unserialize($data['string']);
116 }
117
118 public function getNumberConverter(): NumberConverterInterface
119 {
120 return ($this->unwrapped ?? $this->unwrap())->getNumberConverter();
121 }
122
123 /**
124 * @inheritDoc
125 */
126 public function getFieldsHex(): array
127 {
128 return ($this->unwrapped ?? $this->unwrap())->getFieldsHex();
129 }
130
131 public function getClockSeqHiAndReservedHex(): string
132 {
133 return ($this->unwrapped ?? $this->unwrap())->getClockSeqHiAndReservedHex();
134 }
135
136 public function getClockSeqLowHex(): string
137 {
138 return ($this->unwrapped ?? $this->unwrap())->getClockSeqLowHex();
139 }
140
141 public function getClockSequenceHex(): string
142 {
143 return ($this->unwrapped ?? $this->unwrap())->getClockSequenceHex();
144 }
145
146 public function getDateTime(): DateTimeInterface
147 {
148 return ($this->unwrapped ?? $this->unwrap())->getDateTime();
149 }
150
151 public function getLeastSignificantBitsHex(): string
152 {
153 return ($this->unwrapped ?? $this->unwrap())->getLeastSignificantBitsHex();
154 }
155
156 public function getMostSignificantBitsHex(): string
157 {
158 return ($this->unwrapped ?? $this->unwrap())->getMostSignificantBitsHex();
159 }
160
161 public function getNodeHex(): string
162 {
163 return ($this->unwrapped ?? $this->unwrap())->getNodeHex();
164 }
165
166 public function getTimeHiAndVersionHex(): string
167 {
168 return ($this->unwrapped ?? $this->unwrap())->getTimeHiAndVersionHex();
169 }
170
171 public function getTimeLowHex(): string
172 {
173 return ($this->unwrapped ?? $this->unwrap())->getTimeLowHex();
174 }
175
176 public function getTimeMidHex(): string
177 {
178 return ($this->unwrapped ?? $this->unwrap())->getTimeMidHex();
179 }
180
181 public function getTimestampHex(): string
182 {
183 return ($this->unwrapped ?? $this->unwrap())->getTimestampHex();
184 }
185
186 public function getUrn(): string
187 {
188 return ($this->unwrapped ?? $this->unwrap())->getUrn();
189 }
190
191 public function getVariant(): ?int
192 {
193 return ($this->unwrapped ?? $this->unwrap())->getVariant();
194 }
195
196 public function getVersion(): ?int
197 {
198 return ($this->unwrapped ?? $this->unwrap())->getVersion();
199 }
200
201 public function compareTo(UuidInterface $other): int
202 {
203 return ($this->unwrapped ?? $this->unwrap())->compareTo($other);
204 }
205
206 public function equals(?object $other): bool
207 {
208 if (!$other instanceof UuidInterface) {
209 return false;
210 }
211
212 return $this->uuid === $other->toString();
213 }
214
215 public function getBytes(): string
216 {
217 /**
218 * @var non-empty-string
219 * @phpstan-ignore possiblyImpure.functionCall, possiblyImpure.functionCall
220 */
221 return (string) hex2bin(str_replace('-', '', $this->uuid));
222 }
223
224 public function getFields(): FieldsInterface
225 {
226 return ($this->unwrapped ?? $this->unwrap())->getFields();
227 }
228
229 public function getHex(): Hexadecimal
230 {
231 return ($this->unwrapped ?? $this->unwrap())->getHex();
232 }
233
234 public function getInteger(): IntegerObject
235 {
236 return ($this->unwrapped ?? $this->unwrap())->getInteger();
237 }
238
239 public function toString(): string
240 {
241 return $this->uuid;
242 }
243
244 public function __toString(): string
245 {
246 return $this->uuid;
247 }
248
249 public function jsonSerialize(): string
250 {
251 return $this->uuid;
252 }
253
254 /**
255 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
256 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}
257 * and use the arbitrary-precision math library of your choice to convert it to a string integer.
258 */
259 public function getClockSeqHiAndReserved(): string
260 {
261 $instance = ($this->unwrapped ?? $this->unwrap());
262
263 $fields = $instance->getFields();
264 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
265
266 return $instance->getNumberConverter()->fromHex($fields->getClockSeqHiAndReserved()->toString());
267 }
268
269 /**
270 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
271 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()} and use
272 * the arbitrary-precision math library of your choice to convert it to a string integer.
273 */
274 public function getClockSeqLow(): string
275 {
276 $instance = ($this->unwrapped ?? $this->unwrap());
277
278 $fields = $instance->getFields();
279 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
280
281 return $instance->getNumberConverter()->fromHex($fields->getClockSeqLow()->toString());
282 }
283
284 /**
285 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
286 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()} and use the
287 * arbitrary-precision math library of your choice to convert it to a string integer.
288 */
289 public function getClockSequence(): string
290 {
291 $instance = ($this->unwrapped ?? $this->unwrap());
292
293 $fields = $instance->getFields();
294 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
295
296 return $instance->getNumberConverter()->fromHex($fields->getClockSeq()->toString());
297 }
298
299 /**
300 * @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
301 * obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
302 */
303 public function getLeastSignificantBits(): string
304 {
305 $instance = ($this->unwrapped ?? $this->unwrap());
306
307 return $instance->getNumberConverter()->fromHex(substr($instance->getHex()->toString(), 16));
308 }
309
310 /**
311 * @deprecated This method will be removed in 5.0.0. There is no direct alternative, but the same information may be
312 * obtained by splitting in half the value returned by {@see UuidInterface::getHex()}.
313 */
314 public function getMostSignificantBits(): string
315 {
316 $instance = ($this->unwrapped ?? $this->unwrap());
317
318 return $instance->getNumberConverter()->fromHex(substr($instance->getHex()->toString(), 0, 16));
319 }
320
321 /**
322 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
323 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getNode()} and use the
324 * arbitrary-precision math library of your choice to convert it to a string integer.
325 */
326 public function getNode(): string
327 {
328 $instance = ($this->unwrapped ?? $this->unwrap());
329
330 $fields = $instance->getFields();
331 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
332
333 return $instance->getNumberConverter()->fromHex($fields->getNode()->toString());
334 }
335
336 /**
337 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
338 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()} and
339 * use the arbitrary-precision math library of your choice to convert it to a string integer.
340 */
341 public function getTimeHiAndVersion(): string
342 {
343 $instance = ($this->unwrapped ?? $this->unwrap());
344
345 $fields = $instance->getFields();
346 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
347
348 return $instance->getNumberConverter()->fromHex($fields->getTimeHiAndVersion()->toString());
349 }
350
351 /**
352 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
353 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()} and use the
354 * arbitrary-precision math library of your choice to convert it to a string integer.
355 */
356 public function getTimeLow(): string
357 {
358 $instance = ($this->unwrapped ?? $this->unwrap());
359
360 $fields = $instance->getFields();
361 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
362
363 return $instance->getNumberConverter()->fromHex($fields->getTimeLow()->toString());
364 }
365
366 /**
367 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
368 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()} and use the
369 * arbitrary-precision math library of your choice to convert it to a string integer.
370 */
371 public function getTimeMid(): string
372 {
373 $instance = ($this->unwrapped ?? $this->unwrap());
374
375 $fields = $instance->getFields();
376 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
377
378 return $instance->getNumberConverter()->fromHex($fields->getTimeMid()->toString());
379 }
380
381 /**
382 * @deprecated Use {@see UuidInterface::getFields()} to get a {@see FieldsInterface} instance. If it is a
383 * {@see Rfc4122FieldsInterface} instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()} and use
384 * the arbitrary-precision math library of your choice to convert it to a string integer.
385 */
386 public function getTimestamp(): string
387 {
388 $instance = ($this->unwrapped ?? $this->unwrap());
389
390 $fields = $instance->getFields();
391 assert($fields instanceof \Ramsey\Uuid\Rfc4122\FieldsInterface);
392
393 if ($fields->getVersion() !== 1) {
394 throw new UnsupportedOperationException('Not a time-based UUID');
395 }
396
397 return $instance->getNumberConverter()->fromHex($fields->getTimestamp()->toString());
398 }
399
400 public function toUuidV1(): UuidV1
401 {
402 $instance = ($this->unwrapped ?? $this->unwrap());
403
404 if ($instance instanceof UuidV1) {
405 return $instance;
406 }
407
408 assert($instance instanceof UuidV6);
409
410 return $instance->toUuidV1();
411 }
412
413 public function toUuidV6(): UuidV6
414 {
415 $instance = ($this->unwrapped ?? $this->unwrap());
416
417 assert($instance instanceof UuidV6);
418
419 return $instance;
420 }
421
422 private function unwrap(): UuidInterface
423 {
424 return $this->unwrapped = (new UuidFactory())->fromString($this->uuid);
425 }
426 }