woocommerce-pos / vendor / ramsey / uuid / src / Lazy / LazyUuidFromString.php

LazyUuidFromString.php in WCPOS – Point of Sale (POS) plugin for WooCommerce 1.10.21, at vendor/ramsey/uuid/src/Lazy/LazyUuidFromString.php

576 lines 17.5 KB

Raw Download Zip

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\Nonstandard\UuidV6;
22	use Ramsey\Uuid\Rfc4122\UuidV1;
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
39	* increased overhead for more advanced UUID operations.
40	*
41	* @internal this type is used internally for performance reasons, and is not supposed to be directly referenced
42	* in consumer libraries.
43	*
44	* @psalm-immutable
45	*
46	* Note: the {@see FieldsInterface} does not declare methods that deprecated API
47	* relies upon: the API has been ported from the {@see \Ramsey\Uuid\Uuid} definition,
48	* and is deprecated anyway.
49	* Note: the deprecated API from {@see \Ramsey\Uuid\Uuid} is in use here (on purpose): it will be removed
50	* once the deprecated API is gone from this class too.
51	*
52	* @psalm-suppress UndefinedInterfaceMethod
53	* @psalm-suppress DeprecatedMethod
54	*/
55	final class LazyUuidFromString implements UuidInterface
56	{
57	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';
58	/**
59	* @var string
60	* @psalm-var non-empty-string
61	*/
62	private $uuid;
63	/** @var UuidInterface\|null */
64	private $unwrapped;
65
66	/** @psalm-param non-empty-string $uuid */
67	public function __construct(string $uuid)
68	{
69	$this->uuid = $uuid;
70	}
71
72	/** @psalm-pure */
73	public static function fromBytes(string $bytes): self
74	{
75	$base16Uuid = bin2hex($bytes);
76
77	return new self(
78	substr($base16Uuid, 0, 8)
79	. '-'
80	. substr($base16Uuid, 8, 4)
81	. '-'
82	. substr($base16Uuid, 12, 4)
83	. '-'
84	. substr($base16Uuid, 16, 4)
85	. '-'
86	. substr($base16Uuid, 20, 12)
87	);
88	}
89
90	public function serialize(): string
91	{
92	return $this->uuid;
93	}
94
95	/**
96	* @return array{string: string}
97	*
98	* @psalm-return array{string: non-empty-string}
99	*/
100	public function __serialize(): array
101	{
102	return ['string' => $this->uuid];
103	}
104
105	/**
106	* {@inheritDoc}
107	*
108	* @param string $serialized
109	*
110	* @psalm-param non-empty-string $serialized
111	*/
112	public function unserialize($serialized): void
113	{
114	$this->uuid = $serialized;
115	}
116
117	/**
118	* @param array{string: string} $data
119	*
120	* @psalm-param array{string: non-empty-string} $data
121	*/
122	public function __unserialize(array $data): void
123	{
124	// @codeCoverageIgnoreStart
125	if (!isset($data['string'])) {
126	throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
127	}
128	// @codeCoverageIgnoreEnd
129
130	$this->unserialize($data['string']);
131	}
132
133	/** @psalm-suppress DeprecatedMethod */
134	public function getNumberConverter(): NumberConverterInterface
135	{
136	return ($this->unwrapped ?? $this->unwrap())
137	->getNumberConverter();
138	}
139
140	/**
141	* {@inheritDoc}
142	*
143	* @psalm-suppress DeprecatedMethod
144	*/
145	public function getFieldsHex(): array
146	{
147	return ($this->unwrapped ?? $this->unwrap())
148	->getFieldsHex();
149	}
150
151	/** @psalm-suppress DeprecatedMethod */
152	public function getClockSeqHiAndReservedHex(): string
153	{
154	return ($this->unwrapped ?? $this->unwrap())
155	->getClockSeqHiAndReservedHex();
156	}
157
158	/** @psalm-suppress DeprecatedMethod */
159	public function getClockSeqLowHex(): string
160	{
161	return ($this->unwrapped ?? $this->unwrap())
162	->getClockSeqLowHex();
163	}
164
165	/** @psalm-suppress DeprecatedMethod */
166	public function getClockSequenceHex(): string
167	{
168	return ($this->unwrapped ?? $this->unwrap())
169	->getClockSequenceHex();
170	}
171
172	/** @psalm-suppress DeprecatedMethod */
173	public function getDateTime(): DateTimeInterface
174	{
175	return ($this->unwrapped ?? $this->unwrap())
176	->getDateTime();
177	}
178
179	/** @psalm-suppress DeprecatedMethod */
180	public function getLeastSignificantBitsHex(): string
181	{
182	return ($this->unwrapped ?? $this->unwrap())
183	->getLeastSignificantBitsHex();
184	}
185
186	/** @psalm-suppress DeprecatedMethod */
187	public function getMostSignificantBitsHex(): string
188	{
189	return ($this->unwrapped ?? $this->unwrap())
190	->getMostSignificantBitsHex();
191	}
192
193	/** @psalm-suppress DeprecatedMethod */
194	public function getNodeHex(): string
195	{
196	return ($this->unwrapped ?? $this->unwrap())
197	->getNodeHex();
198	}
199
200	/** @psalm-suppress DeprecatedMethod */
201	public function getTimeHiAndVersionHex(): string
202	{
203	return ($this->unwrapped ?? $this->unwrap())
204	->getTimeHiAndVersionHex();
205	}
206
207	/** @psalm-suppress DeprecatedMethod */
208	public function getTimeLowHex(): string
209	{
210	return ($this->unwrapped ?? $this->unwrap())
211	->getTimeLowHex();
212	}
213
214	/** @psalm-suppress DeprecatedMethod */
215	public function getTimeMidHex(): string
216	{
217	return ($this->unwrapped ?? $this->unwrap())
218	->getTimeMidHex();
219	}
220
221	/** @psalm-suppress DeprecatedMethod */
222	public function getTimestampHex(): string
223	{
224	return ($this->unwrapped ?? $this->unwrap())
225	->getTimestampHex();
226	}
227
228	/** @psalm-suppress DeprecatedMethod */
229	public function getUrn(): string
230	{
231	return ($this->unwrapped ?? $this->unwrap())
232	->getUrn();
233	}
234
235	/** @psalm-suppress DeprecatedMethod */
236	public function getVariant(): ?int
237	{
238	return ($this->unwrapped ?? $this->unwrap())
239	->getVariant();
240	}
241
242	/** @psalm-suppress DeprecatedMethod */
243	public function getVersion(): ?int
244	{
245	return ($this->unwrapped ?? $this->unwrap())
246	->getVersion();
247	}
248
249	public function compareTo(UuidInterface $other): int
250	{
251	return ($this->unwrapped ?? $this->unwrap())
252	->compareTo($other);
253	}
254
255	public function equals(?object $other): bool
256	{
257	if (! $other instanceof UuidInterface) {
258	return false;
259	}
260
261	return $this->uuid === $other->toString();
262	}
263
264	/**
265	* {@inheritDoc}
266	*
267	* @psalm-suppress MoreSpecificReturnType
268	* @psalm-suppress LessSpecificReturnStatement we know that {@see self::$uuid} is a non-empty string, so
269	* we know that {@see hex2bin} will retrieve a non-empty string too.
270	*/
271	public function getBytes(): string
272	{
273	/** @phpstan-ignore-next-line PHPStan complains that this is not a non-empty-string. */
274	return (string) hex2bin(str_replace('-', '', $this->uuid));
275	}
276
277	public function getFields(): FieldsInterface
278	{
279	return ($this->unwrapped ?? $this->unwrap())
280	->getFields();
281	}
282
283	public function getHex(): Hexadecimal
284	{
285	return ($this->unwrapped ?? $this->unwrap())
286	->getHex();
287	}
288
289	public function getInteger(): IntegerObject
290	{
291	return ($this->unwrapped ?? $this->unwrap())
292	->getInteger();
293	}
294
295	public function toString(): string
296	{
297	return $this->uuid;
298	}
299
300	public function __toString(): string
301	{
302	return $this->uuid;
303	}
304
305	public function jsonSerialize(): string
306	{
307	return $this->uuid;
308	}
309
310	/**
311	* @deprecated Use {@see UuidInterface::getFields()} to get a
312	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
313	* instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}
314	* and use the arbitrary-precision math library of your choice to
315	* convert it to a string integer.
316	*
317	* @psalm-suppress UndefinedInterfaceMethod
318	* @psalm-suppress DeprecatedMethod
319	* @psalm-suppress MixedArgument
320	* @psalm-suppress MixedMethodCall
321	*/
322	public function getClockSeqHiAndReserved(): string
323	{
324	$instance = ($this->unwrapped ?? $this->unwrap());
325
326	return $instance->getNumberConverter()
327	->fromHex(
328	$instance->getFields()
329	->getClockSeqHiAndReserved()
330	->toString()
331	);
332	}
333
334	/**
335	* @deprecated Use {@see UuidInterface::getFields()} to get a
336	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
337	* instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()}
338	* and use the arbitrary-precision math library of your choice to
339	* convert it to a string integer.
340	*
341	* @psalm-suppress UndefinedInterfaceMethod
342	* @psalm-suppress DeprecatedMethod
343	* @psalm-suppress MixedArgument
344	* @psalm-suppress MixedMethodCall
345	*/
346	public function getClockSeqLow(): string
347	{
348	$instance = ($this->unwrapped ?? $this->unwrap());
349
350	return $instance->getNumberConverter()
351	->fromHex(
352	$instance->getFields()
353	->getClockSeqLow()
354	->toString()
355	);
356	}
357
358	/**
359	* @deprecated Use {@see UuidInterface::getFields()} to get a
360	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
361	* instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()}
362	* and use the arbitrary-precision math library of your choice to
363	* convert it to a string integer.
364	*
365	* @psalm-suppress UndefinedInterfaceMethod
366	* @psalm-suppress DeprecatedMethod
367	* @psalm-suppress MixedArgument
368	* @psalm-suppress MixedMethodCall
369	*/
370	public function getClockSequence(): string
371	{
372	$instance = ($this->unwrapped ?? $this->unwrap());
373
374	return $instance->getNumberConverter()
375	->fromHex(
376	$instance->getFields()
377	->getClockSeq()
378	->toString()
379	);
380	}
381
382	/**
383	* @deprecated This method will be removed in 5.0.0. There is no direct
384	* alternative, but the same information may be obtained by splitting
385	* in half the value returned by {@see UuidInterface::getHex()}.
386	*
387	* @psalm-suppress UndefinedInterfaceMethod
388	* @psalm-suppress DeprecatedMethod
389	* @psalm-suppress MixedArgument
390	* @psalm-suppress MixedMethodCall
391	*/
392	public function getLeastSignificantBits(): string
393	{
394	$instance = ($this->unwrapped ?? $this->unwrap());
395
396	return $instance->getNumberConverter()
397	->fromHex(substr($instance->getHex()->toString(), 16));
398	}
399
400	/**
401	* @deprecated This method will be removed in 5.0.0. There is no direct
402	* alternative, but the same information may be obtained by splitting
403	* in half the value returned by {@see UuidInterface::getHex()}.
404	*
405	* @psalm-suppress UndefinedInterfaceMethod
406	* @psalm-suppress DeprecatedMethod
407	* @psalm-suppress MixedArgument
408	* @psalm-suppress MixedMethodCall
409	*/
410	public function getMostSignificantBits(): string
411	{
412	$instance = ($this->unwrapped ?? $this->unwrap());
413
414	return $instance->getNumberConverter()
415	->fromHex(substr($instance->getHex()->toString(), 0, 16));
416	}
417
418	/**
419	* @deprecated Use {@see UuidInterface::getFields()} to get a
420	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
421	* instance, you may call {@see Rfc4122FieldsInterface::getNode()}
422	* and use the arbitrary-precision math library of your choice to
423	* convert it to a string integer.
424	*
425	* @psalm-suppress UndefinedInterfaceMethod
426	* @psalm-suppress DeprecatedMethod
427	* @psalm-suppress MixedArgument
428	* @psalm-suppress MixedMethodCall
429	*/
430	public function getNode(): string
431	{
432	$instance = ($this->unwrapped ?? $this->unwrap());
433
434	return $instance->getNumberConverter()
435	->fromHex(
436	$instance->getFields()
437	->getNode()
438	->toString()
439	);
440	}
441
442	/**
443	* @deprecated Use {@see UuidInterface::getFields()} to get a
444	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
445	* instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()}
446	* and use the arbitrary-precision math library of your choice to
447	* convert it to a string integer.
448	*
449	* @psalm-suppress UndefinedInterfaceMethod
450	* @psalm-suppress DeprecatedMethod
451	* @psalm-suppress MixedArgument
452	* @psalm-suppress MixedMethodCall
453	*/
454	public function getTimeHiAndVersion(): string
455	{
456	$instance = ($this->unwrapped ?? $this->unwrap());
457
458	return $instance->getNumberConverter()
459	->fromHex(
460	$instance->getFields()
461	->getTimeHiAndVersion()
462	->toString()
463	);
464	}
465
466	/**
467	* @deprecated Use {@see UuidInterface::getFields()} to get a
468	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
469	* instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()}
470	* and use the arbitrary-precision math library of your choice to
471	* convert it to a string integer.
472	*
473	* @psalm-suppress UndefinedInterfaceMethod
474	* @psalm-suppress DeprecatedMethod
475	* @psalm-suppress MixedArgument
476	* @psalm-suppress MixedMethodCall
477	*/
478	public function getTimeLow(): string
479	{
480	$instance = ($this->unwrapped ?? $this->unwrap());
481
482	return $instance->getNumberConverter()
483	->fromHex(
484	$instance->getFields()
485	->getTimeLow()
486	->toString()
487	);
488	}
489
490	/**
491	* @deprecated Use {@see UuidInterface::getFields()} to get a
492	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
493	* instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()}
494	* and use the arbitrary-precision math library of your choice to
495	* convert it to a string integer.
496	*
497	* @psalm-suppress UndefinedInterfaceMethod
498	* @psalm-suppress DeprecatedMethod
499	* @psalm-suppress MixedArgument
500	* @psalm-suppress MixedMethodCall
501	*/
502	public function getTimeMid(): string
503	{
504	$instance = ($this->unwrapped ?? $this->unwrap());
505
506	return $instance->getNumberConverter()
507	->fromHex(
508	$instance->getFields()
509	->getTimeMid()
510	->toString()
511	);
512	}
513
514	/**
515	* @deprecated Use {@see UuidInterface::getFields()} to get a
516	* {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
517	* instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()}
518	* and use the arbitrary-precision math library of your choice to
519	* convert it to a string integer.
520	*
521	* @psalm-suppress UndefinedInterfaceMethod
522	* @psalm-suppress DeprecatedMethod
523	* @psalm-suppress MixedArgument
524	* @psalm-suppress MixedMethodCall
525	*/
526	public function getTimestamp(): string
527	{
528	$instance = ($this->unwrapped ?? $this->unwrap());
529	$fields = $instance->getFields();
530
531	if ($fields->getVersion() !== 1) {
532	throw new UnsupportedOperationException('Not a time-based UUID');
533	}
534
535	return $instance->getNumberConverter()
536	->fromHex($fields->getTimestamp()->toString());
537	}
538
539	public function toUuidV1(): UuidV1
540	{
541	$instance = ($this->unwrapped ?? $this->unwrap());
542
543	if ($instance instanceof UuidV1) {
544	return $instance;
545	}
546
547	assert($instance instanceof UuidV6);
548
549	return $instance->toUuidV1();
550	}
551
552	public function toUuidV6(): UuidV6
553	{
554	$instance = ($this->unwrapped ?? $this->unwrap());
555
556	assert($instance instanceof UuidV6);
557
558	return $instance;
559	}
560
561	/**
562	* @psalm-suppress ImpureMethodCall the retrieval of the factory is a clear violation of purity here: this is a
563	* known pitfall of the design of this library, where a value object contains
564	* a mutable reference to a factory. We use a fixed factory here, so the violation
565	* will not have real-world effects, as this object is only instantiated with the
566	* default factory settings/features.
567	* @psalm-suppress InaccessibleProperty property {@see $unwrapped} is used as a cache: we don't expose it to the
568	* outside world, so we should be fine here.
569	*/
570	private function unwrap(): UuidInterface
571	{
572	return $this->unwrapped = (new UuidFactory())
573	->fromString($this->uuid);
574	}
575	}
576