media-cloud-sync / includes / sdk / google / ramsey / uuid / src / Uuid.php

Uuid.php in Media Cloud Sync 1.2.0, at includes/sdk/google/ramsey/uuid/src/Uuid.php

568 lines 21.6 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 <ben@benramsey.com>
10	* @license http://opensource.org/licenses/MIT MIT
11	*/
12	declare (strict_types=1);
13	namespace Dudlewebs\WPMCS\Ramsey\Uuid;
14
15	use DateTimeInterface;
16	use Dudlewebs\WPMCS\Ramsey\Uuid\Codec\CodecInterface;
17	use Dudlewebs\WPMCS\Ramsey\Uuid\Converter\NumberConverterInterface;
18	use Dudlewebs\WPMCS\Ramsey\Uuid\Converter\TimeConverterInterface;
19	use Dudlewebs\WPMCS\Ramsey\Uuid\Fields\FieldsInterface;
20	use Dudlewebs\WPMCS\Ramsey\Uuid\Lazy\LazyUuidFromString;
21	use Dudlewebs\WPMCS\Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
22	use Dudlewebs\WPMCS\Ramsey\Uuid\Type\Hexadecimal;
23	use Dudlewebs\WPMCS\Ramsey\Uuid\Type\Integer as IntegerObject;
24	use ValueError;
25	use function assert;
26	use function bin2hex;
27	use function preg_match;
28	use function sprintf;
29	use function str_replace;
30	use function strcmp;
31	use function strlen;
32	use function strtolower;
33	use function substr;
34	/**
35	* Uuid provides constants and static methods for working with and generating UUIDs
36	*
37	* @psalm-immutable
38	*/
39	class Uuid implements UuidInterface
40	{
41	use DeprecatedUuidMethodsTrait;
42	/**
43	* When this namespace is specified, the name string is a fully-qualified
44	* domain name
45	*
46	* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
47	*/
48	public const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
49	/**
50	* When this namespace is specified, the name string is a URL
51	*
52	* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
53	*/
54	public const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
55	/**
56	* When this namespace is specified, the name string is an ISO OID
57	*
58	* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
59	*/
60	public const NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
61	/**
62	* When this namespace is specified, the name string is an X.500 DN in DER
63	* or a text output format
64	*
65	* @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs
66	*/
67	public const NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8';
68	/**
69	* The nil UUID is a special form of UUID that is specified to have all 128
70	* bits set to zero
71	*
72	* @link http://tools.ietf.org/html/rfc4122#section-4.1.7 RFC 4122, § 4.1.7: Nil UUID
73	*/
74	public const NIL = '00000000-0000-0000-0000-000000000000';
75	/**
76	* Variant: reserved, NCS backward compatibility
77	*
78	* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
79	*/
80	public const RESERVED_NCS = 0;
81	/**
82	* Variant: the UUID layout specified in RFC 4122
83	*
84	* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
85	*/
86	public const RFC_4122 = 2;
87	/**
88	* Variant: reserved, Microsoft Corporation backward compatibility
89	*
90	* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
91	*/
92	public const RESERVED_MICROSOFT = 6;
93	/**
94	* Variant: reserved for future definition
95	*
96	* @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant
97	*/
98	public const RESERVED_FUTURE = 7;
99	/**
100	* @deprecated Use {@see ValidatorInterface::getPattern()} instead.
101	*/
102	public const VALID_PATTERN = '^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$';
103	/**
104	* Version 1 (time-based) UUID
105	*
106	* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
107	*/
108	public const UUID_TYPE_TIME = 1;
109	/**
110	* Version 2 (DCE Security) UUID
111	*
112	* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
113	*/
114	public const UUID_TYPE_DCE_SECURITY = 2;
115	/**
116	* @deprecated Use {@see Uuid::UUID_TYPE_DCE_SECURITY} instead.
117	*/
118	public const UUID_TYPE_IDENTIFIER = 2;
119	/**
120	* Version 3 (name-based and hashed with MD5) UUID
121	*
122	* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
123	*/
124	public const UUID_TYPE_HASH_MD5 = 3;
125	/**
126	* Version 4 (random) UUID
127	*
128	* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
129	*/
130	public const UUID_TYPE_RANDOM = 4;
131	/**
132	* Version 5 (name-based and hashed with SHA1) UUID
133	*
134	* @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version
135	*/
136	public const UUID_TYPE_HASH_SHA1 = 5;
137	/**
138	* Version 6 (ordered-time) UUID
139	*
140	* This is named `UUID_TYPE_PEABODY`, since the specification is still in
141	* draft form, and the primary author/editor's name is Brad Peabody.
142	*
143	* @link https://github.com/uuid6/uuid6-ietf-draft UUID version 6 IETF draft
144	* @link http://gh.peabody.io/uuidv6/ "Version 6" UUIDs
145	*/
146	public const UUID_TYPE_PEABODY = 6;
147	/**
148	* DCE Security principal domain
149	*
150	* @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
151	*/
152	public const DCE_DOMAIN_PERSON = 0;
153	/**
154	* DCE Security group domain
155	*
156	* @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
157	*/
158	public const DCE_DOMAIN_GROUP = 1;
159	/**
160	* DCE Security organization domain
161	*
162	* @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
163	*/
164	public const DCE_DOMAIN_ORG = 2;
165	/**
166	* DCE Security domain string names
167	*
168	* @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
169	*/
170	public const DCE_DOMAIN_NAMES = [self::DCE_DOMAIN_PERSON => 'person', self::DCE_DOMAIN_GROUP => 'group', self::DCE_DOMAIN_ORG => 'org'];
171	/**
172	* @var UuidFactoryInterface\|null
173	*/
174	private static $factory = null;
175	/**
176	* @var bool flag to detect if the UUID factory was replaced internally, which disables all optimizations
177	* for the default/happy path internal scenarios
178	*/
179	private static $factoryReplaced = \false;
180	/**
181	* @var CodecInterface
182	*/
183	protected $codec;
184	/**
185	* The fields that make up this UUID
186	*
187	* @var Rfc4122FieldsInterface
188	*/
189	protected $fields;
190	/**
191	* @var NumberConverterInterface
192	*/
193	protected $numberConverter;
194	/**
195	* @var TimeConverterInterface
196	*/
197	protected $timeConverter;
198	/**
199	* Creates a universally unique identifier (UUID) from an array of fields
200	*
201	* Unless you're making advanced use of this library to generate identifiers
202	* that deviate from RFC 4122, you probably do not want to instantiate a
203	* UUID directly. Use the static methods, instead:
204	*
205	* ```
206	* use Ramsey\Uuid\Uuid;
207	*
208	* $timeBasedUuid = Uuid::uuid1();
209	* $namespaceMd5Uuid = Uuid::uuid3(Uuid::NAMESPACE_URL, 'http://php.net/');
210	* $randomUuid = Uuid::uuid4();
211	* $namespaceSha1Uuid = Uuid::uuid5(Uuid::NAMESPACE_URL, 'http://php.net/');
212	* ```
213	*
214	* @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
215	* @param NumberConverterInterface $numberConverter The number converter to use
216	* for converting hex values to/from integers
217	* @param CodecInterface $codec The codec to use when encoding or decoding
218	* UUID strings
219	* @param TimeConverterInterface $timeConverter The time converter to use
220	* for converting timestamps extracted from a UUID to unix timestamps
221	*/
222	public function __construct(Rfc4122FieldsInterface $fields, NumberConverterInterface $numberConverter, CodecInterface $codec, TimeConverterInterface $timeConverter)
223	{
224	$this->fields = $fields;
225	$this->codec = $codec;
226	$this->numberConverter = $numberConverter;
227	$this->timeConverter = $timeConverter;
228	}
229	/**
230	* @psalm-return non-empty-string
231	*/
232	public function __toString(): string
233	{
234	return $this->toString();
235	}
236	/**
237	* Converts the UUID to a string for JSON serialization
238	*/
239	public function jsonSerialize(): string
240	{
241	return $this->toString();
242	}
243	/**
244	* Converts the UUID to a string for PHP serialization
245	*/
246	public function serialize(): string
247	{
248	return $this->getFields()->getBytes();
249	}
250	/**
251	* @return array{bytes: string}
252	*/
253	public function __serialize(): array
254	{
255	return ['bytes' => $this->serialize()];
256	}
257	/**
258	* Re-constructs the object from its serialized form
259	*
260	* @param string $serialized The serialized PHP string to unserialize into
261	* a UuidInterface instance
262	*
263	* @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
264	*/
265	public function unserialize($serialized): void
266	{
267	if (strlen($serialized) === 16) {
268	/** @var Uuid $uuid */
269	$uuid = self::getFactory()->fromBytes($serialized);
270	} else {
271	/** @var Uuid $uuid */
272	$uuid = self::getFactory()->fromString($serialized);
273	}
274	$this->codec = $uuid->codec;
275	$this->numberConverter = $uuid->numberConverter;
276	$this->fields = $uuid->fields;
277	$this->timeConverter = $uuid->timeConverter;
278	}
279	/**
280	* @param array{bytes: string} $data
281	*/
282	public function __unserialize(array $data): void
283	{
284	// @codeCoverageIgnoreStart
285	if (!isset($data['bytes'])) {
286	throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
287	}
288	// @codeCoverageIgnoreEnd
289	$this->unserialize($data['bytes']);
290	}
291	public function compareTo(UuidInterface $other): int
292	{
293	$compare = strcmp($this->toString(), $other->toString());
294	if ($compare < 0) {
295	return -1;
296	}
297	if ($compare > 0) {
298	return 1;
299	}
300	return 0;
301	}
302	public function equals(?object $other): bool
303	{
304	if (!$other instanceof UuidInterface) {
305	return \false;
306	}
307	return $this->compareTo($other) === 0;
308	}
309	/**
310	* @psalm-return non-empty-string
311	*/
312	public function getBytes(): string
313	{
314	return $this->codec->encodeBinary($this);
315	}
316	public function getFields(): FieldsInterface
317	{
318	return $this->fields;
319	}
320	public function getHex(): Hexadecimal
321	{
322	return new Hexadecimal(str_replace('-', '', $this->toString()));
323	}
324	public function getInteger(): IntegerObject
325	{
326	return new IntegerObject($this->numberConverter->fromHex($this->getHex()->toString()));
327	}
328	/**
329	* @psalm-return non-empty-string
330	*/
331	public function toString(): string
332	{
333	return $this->codec->encode($this);
334	}
335	/**
336	* Returns the factory used to create UUIDs
337	*/
338	public static function getFactory(): UuidFactoryInterface
339	{
340	if (self::$factory === null) {
341	self::$factory = new UuidFactory();
342	}
343	return self::$factory;
344	}
345	/**
346	* Sets the factory used to create UUIDs
347	*
348	* @param UuidFactoryInterface $factory A factory that will be used by this
349	* class to create UUIDs
350	*/
351	public static function setFactory(UuidFactoryInterface $factory): void
352	{
353	// Note: non-strict equality is intentional here. If the factory is configured differently, every assumption
354	// around purity is broken, and we have to internally decide everything differently.
355	// phpcs:ignore SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedNotEqualOperator
356	self::$factoryReplaced = $factory != new UuidFactory();
357	self::$factory = $factory;
358	}
359	/**
360	* Creates a UUID from a byte string
361	*
362	* @param string $bytes A binary string
363	*
364	* @return UuidInterface A UuidInterface instance created from a binary
365	* string representation
366	*
367	* @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,
368	* but under constant factory setups, this method operates in functionally pure manners
369	*
370	* @psalm-suppress ImpureStaticProperty we know that the factory being replaced can lead to massive
371	* havoc across all consumers: that should never happen, and
372	* is generally to be discouraged. Until the factory is kept
373	* un-replaced, this method is effectively pure.
374	*/
375	public static function fromBytes(string $bytes): UuidInterface
376	{
377	if (!self::$factoryReplaced && strlen($bytes) === 16) {
378	$base16Uuid = bin2hex($bytes);
379	// Note: we are calling `fromString` internally because we don't know if the given `$bytes` is a valid UUID
380	return self::fromString(substr($base16Uuid, 0, 8) . '-' . substr($base16Uuid, 8, 4) . '-' . substr($base16Uuid, 12, 4) . '-' . substr($base16Uuid, 16, 4) . '-' . substr($base16Uuid, 20, 12));
381	}
382	return self::getFactory()->fromBytes($bytes);
383	}
384	/**
385	* Creates a UUID from the string standard representation
386	*
387	* @param string $uuid A hexadecimal string
388	*
389	* @return UuidInterface A UuidInterface instance created from a hexadecimal
390	* string representation
391	*
392	* @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,
393	* but under constant factory setups, this method operates in functionally pure manners
394	*
395	* @psalm-suppress ImpureStaticProperty we know that the factory being replaced can lead to massive
396	* havoc across all consumers: that should never happen, and
397	* is generally to be discouraged. Until the factory is kept
398	* un-replaced, this method is effectively pure.
399	*/
400	public static function fromString(string $uuid): UuidInterface
401	{
402	if (!self::$factoryReplaced && preg_match(LazyUuidFromString::VALID_REGEX, $uuid) === 1) {
403	assert($uuid !== '');
404	return new LazyUuidFromString(strtolower($uuid));
405	}
406	return self::getFactory()->fromString($uuid);
407	}
408	/**
409	* Creates a UUID from a DateTimeInterface instance
410	*
411	* @param DateTimeInterface $dateTime The date and time
412	* @param Hexadecimal\|null $node A 48-bit number representing the hardware
413	* address
414	* @param int\|null $clockSeq A 14-bit number used to help avoid duplicates
415	* that could arise when the clock is set backwards in time or if the
416	* node ID changes
417	*
418	* @return UuidInterface A UuidInterface instance that represents a
419	* version 1 UUID created from a DateTimeInterface instance
420	*/
421	public static function fromDateTime(DateTimeInterface $dateTime, ?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface
422	{
423	return self::getFactory()->fromDateTime($dateTime, $node, $clockSeq);
424	}
425	/**
426	* Creates a UUID from a 128-bit integer string
427	*
428	* @param string $integer String representation of 128-bit integer
429	*
430	* @return UuidInterface A UuidInterface instance created from the string
431	* representation of a 128-bit integer
432	*
433	* @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,
434	* but under constant factory setups, this method operates in functionally pure manners
435	*/
436	public static function fromInteger(string $integer): UuidInterface
437	{
438	return self::getFactory()->fromInteger($integer);
439	}
440	/**
441	* Returns true if the provided string is a valid UUID
442	*
443	* @param string $uuid A string to validate as a UUID
444	*
445	* @return bool True if the string is a valid UUID, false otherwise
446	*
447	* @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,
448	* but under constant factory setups, this method operates in functionally pure manners
449	*/
450	public static function isValid(string $uuid): bool
451	{
452	return self::getFactory()->getValidator()->validate($uuid);
453	}
454	/**
455	* Returns a version 1 (time-based) UUID from a host ID, sequence number,
456	* and the current time
457	*
458	* @param Hexadecimal\|int\|string\|null $node A 48-bit number representing the
459	* hardware address; this number may be represented as an integer or a
460	* hexadecimal string
461	* @param int $clockSeq A 14-bit number used to help avoid duplicates that
462	* could arise when the clock is set backwards in time or if the node ID
463	* changes
464	*
465	* @return UuidInterface A UuidInterface instance that represents a
466	* version 1 UUID
467	*/
468	public static function uuid1($node = null, ?int $clockSeq = null): UuidInterface
469	{
470	return self::getFactory()->uuid1($node, $clockSeq);
471	}
472	/**
473	* Returns a version 2 (DCE Security) UUID from a local domain, local
474	* identifier, host ID, clock sequence, and the current time
475	*
476	* @param int $localDomain The local domain to use when generating bytes,
477	* according to DCE Security
478	* @param IntegerObject\|null $localIdentifier The local identifier for the
479	* given domain; this may be a UID or GID on POSIX systems, if the local
480	* domain is person or group, or it may be a site-defined identifier
481	* if the local domain is org
482	* @param Hexadecimal\|null $node A 48-bit number representing the hardware
483	* address
484	* @param int\|null $clockSeq A 14-bit number used to help avoid duplicates
485	* that could arise when the clock is set backwards in time or if the
486	* node ID changes (in a version 2 UUID, the lower 8 bits of this number
487	* are replaced with the domain).
488	*
489	* @return UuidInterface A UuidInterface instance that represents a
490	* version 2 UUID
491	*/
492	public static function uuid2(int $localDomain, ?IntegerObject $localIdentifier = null, ?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface
493	{
494	return self::getFactory()->uuid2($localDomain, $localIdentifier, $node, $clockSeq);
495	}
496	/**
497	* Returns a version 3 (name-based) UUID based on the MD5 hash of a
498	* namespace ID and a name
499	*
500	* @param string\|UuidInterface $ns The namespace (must be a valid UUID)
501	* @param string $name The name to use for creating a UUID
502	*
503	* @return UuidInterface A UuidInterface instance that represents a
504	* version 3 UUID
505	*
506	* @psalm-suppress ImpureMethodCall we know that the factory being replaced can lead to massive
507	* havoc across all consumers: that should never happen, and
508	* is generally to be discouraged. Until the factory is kept
509	* un-replaced, this method is effectively pure.
510	*
511	* @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,
512	* but under constant factory setups, this method operates in functionally pure manners
513	*/
514	public static function uuid3($ns, string $name): UuidInterface
515	{
516	return self::getFactory()->uuid3($ns, $name);
517	}
518	/**
519	* Returns a version 4 (random) UUID
520	*
521	* @return UuidInterface A UuidInterface instance that represents a
522	* version 4 UUID
523	*/
524	public static function uuid4(): UuidInterface
525	{
526	return self::getFactory()->uuid4();
527	}
528	/**
529	* Returns a version 5 (name-based) UUID based on the SHA-1 hash of a
530	* namespace ID and a name
531	*
532	* @param string\|UuidInterface $ns The namespace (must be a valid UUID)
533	* @param string $name The name to use for creating a UUID
534	*
535	* @return UuidInterface A UuidInterface instance that represents a
536	* version 5 UUID
537	*
538	* @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,
539	* but under constant factory setups, this method operates in functionally pure manners
540	*
541	* @psalm-suppress ImpureMethodCall we know that the factory being replaced can lead to massive
542	* havoc across all consumers: that should never happen, and
543	* is generally to be discouraged. Until the factory is kept
544	* un-replaced, this method is effectively pure.
545	*/
546	public static function uuid5($ns, string $name): UuidInterface
547	{
548	return self::getFactory()->uuid5($ns, $name);
549	}
550	/**
551	* Returns a version 6 (ordered-time) UUID from a host ID, sequence number,
552	* and the current time
553	*
554	* @param Hexadecimal\|null $node A 48-bit number representing the hardware
555	* address
556	* @param int $clockSeq A 14-bit number used to help avoid duplicates that
557	* could arise when the clock is set backwards in time or if the node ID
558	* changes
559	*
560	* @return UuidInterface A UuidInterface instance that represents a
561	* version 6 UUID
562	*/
563	public static function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface
564	{
565	return self::getFactory()->uuid6($node, $clockSeq);
566	}
567	}
568