Debian Codegraph @

vendor/ramsey/uuid/src/Uuid.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;
16
17 use BadMethodCallException;
18 use DateTimeInterface;
19 use Ramsey\Uuid\Codec\CodecInterface;
20 use Ramsey\Uuid\Converter\NumberConverterInterface;
21 use Ramsey\Uuid\Converter\TimeConverterInterface;
22 use Ramsey\Uuid\Exception\InvalidArgumentException;
23 use Ramsey\Uuid\Exception\UnsupportedOperationException;
24 use Ramsey\Uuid\Fields\FieldsInterface;
25 use Ramsey\Uuid\Lazy\LazyUuidFromString;
26 use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
27 use Ramsey\Uuid\Type\Hexadecimal;
28 use Ramsey\Uuid\Type\Integer as IntegerObject;
29 use ValueError;
30
31 use function assert;
32 use function bin2hex;
33 use function method_exists;
34 use function preg_match;
35 use function sprintf;
36 use function str_replace;
37 use function strcmp;
38 use function strlen;
39 use function strtolower;
40 use function substr;
41
42 /**
43 * Uuid provides constants and static methods for working with and generating UUIDs
44 *
45 * @immutable
46 */
47 class Uuid implements UuidInterface
48 {
49 use DeprecatedUuidMethodsTrait;
50
51 /**
52 * When this namespace is specified, the name string is a fully qualified domain name
53 *
54 * @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
55 */
56 public const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
57
58 /**
59 * When this namespace is specified, the name string is a URL
60 *
61 * @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
62 */
63 public const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
64
65 /**
66 * When this namespace is specified, the name string is an ISO OID
67 *
68 * @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
69 */
70 public const NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
71
72 /**
73 * When this namespace is specified, the name string is an X.500 DN (in DER or a text output format)
74 *
75 * @link https://www.rfc-editor.org/rfc/rfc9562#section-6.6 RFC 9562, 6.6. Namespace ID Usage and Allocation
76 */
77 public const NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8';
78
79 /**
80 * The Nil UUID is a special form of UUID that is specified to have all 128 bits set to zero
81 *
82 * @link https://www.rfc-editor.org/rfc/rfc9562#section-5.9 RFC 9562, 5.9. Nil UUID
83 */
84 public const NIL = '00000000-0000-0000-0000-000000000000';
85
86 /**
87 * The Max UUID is a special form of UUID that is specified to have all 128 bits set to one
88 *
89 * @link https://www.rfc-editor.org/rfc/rfc9562#section-5.10 RFC 9562, 5.10. Max UUID
90 */
91 public const MAX = 'ffffffff-ffff-ffff-ffff-ffffffffffff';
92
93 /**
94 * Variant: reserved, NCS backward compatibility
95 *
96 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
97 */
98 public const RESERVED_NCS = 0;
99
100 /**
101 * Variant: the UUID layout specified in RFC 9562 (formerly RFC 4122)
102 *
103 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
104 * @see Uuid::RFC_9562
105 */
106 public const RFC_4122 = 2;
107
108 /**
109 * Variant: the UUID layout specified in RFC 9562 (formerly RFC 4122)
110 *
111 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
112 */
113 public const RFC_9562 = 2;
114
115 /**
116 * Variant: reserved, Microsoft Corporation backward compatibility
117 *
118 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
119 */
120 public const RESERVED_MICROSOFT = 6;
121
122 /**
123 * Variant: reserved for future definition
124 *
125 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
126 */
127 public const RESERVED_FUTURE = 7;
128
129 /**
130 * @deprecated Use {@see ValidatorInterface::getPattern()} instead.
131 */
132 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}$';
133
134 /**
135 * Version 1 (Gregorian time) UUID
136 *
137 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
138 */
139 public const UUID_TYPE_TIME = 1;
140
141 /**
142 * Version 2 (DCE Security) UUID
143 *
144 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
145 */
146 public const UUID_TYPE_DCE_SECURITY = 2;
147
148 /**
149 * @deprecated Use {@see Uuid::UUID_TYPE_DCE_SECURITY} instead.
150 */
151 public const UUID_TYPE_IDENTIFIER = 2;
152
153 /**
154 * Version 3 (name-based and hashed with MD5) UUID
155 *
156 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
157 */
158 public const UUID_TYPE_HASH_MD5 = 3;
159
160 /**
161 * Version 4 (random) UUID
162 *
163 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
164 */
165 public const UUID_TYPE_RANDOM = 4;
166
167 /**
168 * Version 5 (name-based and hashed with SHA1) UUID
169 *
170 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
171 */
172 public const UUID_TYPE_HASH_SHA1 = 5;
173
174 /**
175 * @deprecated Use {@see Uuid::UUID_TYPE_REORDERED_TIME} instead.
176 */
177 public const UUID_TYPE_PEABODY = 6;
178
179 /**
180 * Version 6 (reordered Gregorian time) UUID
181 *
182 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
183 */
184 public const UUID_TYPE_REORDERED_TIME = 6;
185
186 /**
187 * Version 7 (Unix Epoch time) UUID
188 *
189 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
190 */
191 public const UUID_TYPE_UNIX_TIME = 7;
192
193 /**
194 * Version 8 (custom format) UUID
195 *
196 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
197 */
198 public const UUID_TYPE_CUSTOM = 8;
199
200 /**
201 * DCE Security principal domain
202 *
203 * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
204 */
205 public const DCE_DOMAIN_PERSON = 0;
206
207 /**
208 * DCE Security group domain
209 *
210 * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
211 */
212 public const DCE_DOMAIN_GROUP = 1;
213
214 /**
215 * DCE Security organization domain
216 *
217 * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
218 */
219 public const DCE_DOMAIN_ORG = 2;
220
221 /**
222 * DCE Security domain string names
223 *
224 * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1
225 */
226 public const DCE_DOMAIN_NAMES = [
227 self::DCE_DOMAIN_PERSON => 'person',
228 self::DCE_DOMAIN_GROUP => 'group',
229 self::DCE_DOMAIN_ORG => 'org',
230 ];
231
232 /**
233 * @phpstan-ignore property.readOnlyByPhpDocDefaultValue
234 */
235 private static ?UuidFactoryInterface $factory = null;
236
237 /**
238 * @var bool flag to detect if the UUID factory was replaced internally, which disables all optimizations for the
239 * default/happy path internal scenarios
240 * @phpstan-ignore property.readOnlyByPhpDocDefaultValue
241 */
242 private static bool $factoryReplaced = false;
243
244 protected CodecInterface $codec;
245 protected NumberConverterInterface $numberConverter;
246 protected Rfc4122FieldsInterface $fields;
247 protected TimeConverterInterface $timeConverter;
248
249 /**
250 * Creates a universally unique identifier (UUID) from an array of fields
251 *
252 * Unless you're making advanced use of this library to generate identifiers that deviate from RFC 9562 (formerly
253 * RFC 4122), you probably do not want to instantiate a UUID directly. Use the static methods, instead:
254 *
255 * ```
256 * use Ramsey\Uuid\Uuid;
257 *
258 * $timeBasedUuid = Uuid::uuid1();
259 * $namespaceMd5Uuid = Uuid::uuid3(Uuid::NAMESPACE_URL, 'http://php.net/');
260 * $randomUuid = Uuid::uuid4();
261 * $namespaceSha1Uuid = Uuid::uuid5(Uuid::NAMESPACE_URL, 'http://php.net/');
262 * ```
263 *
264 * @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
265 * @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
266 * @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
267 * @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
268 * UUID to unix timestamps
269 */
270 public function __construct(
271 Rfc4122FieldsInterface $fields,
272 NumberConverterInterface $numberConverter,
273 CodecInterface $codec,
274 TimeConverterInterface $timeConverter,
275 ) {
276 $this->fields = $fields;
277 $this->codec = $codec;
278 $this->numberConverter = $numberConverter;
279 $this->timeConverter = $timeConverter;
280 }
281
282 /**
283 * @return non-empty-string
284 */
285 public function __toString(): string
286 {
287 return $this->toString();
288 }
289
290 /**
291 * Converts the UUID to a string for JSON serialization
292 */
293 public function jsonSerialize(): string
294 {
295 return $this->toString();
296 }
297
298 /**
299 * Converts the UUID to a string for PHP serialization
300 */
301 public function serialize(): string
302 {
303 return $this->codec->encode($this);
304 }
305
306 /**
307 * @return array{bytes: string}
308 */
309 public function __serialize(): array
310 {
311 return ['bytes' => $this->serialize()];
312 }
313
314 /**
315 * Re-constructs the object from its serialized form
316 *
317 * @param string $data The serialized PHP string to unserialize into a UuidInterface instance
318 */
319 public function unserialize(string $data): void
320 {
321 if (strlen($data) === 16) {
322 /** @var Uuid $uuid */
323 $uuid = self::getFactory()->fromBytes($data);
324 } else {
325 /** @var Uuid $uuid */
326 $uuid = self::getFactory()->fromString($data);
327 }
328
329 /** @phpstan-ignore property.readOnlyByPhpDocAssignNotInConstructor */
330 $this->codec = $uuid->codec;
331
332 /** @phpstan-ignore property.readOnlyByPhpDocAssignNotInConstructor */
333 $this->numberConverter = $uuid->numberConverter;
334
335 /** @phpstan-ignore property.readOnlyByPhpDocAssignNotInConstructor */
336 $this->fields = $uuid->fields;
337
338 /** @phpstan-ignore property.readOnlyByPhpDocAssignNotInConstructor */
339 $this->timeConverter = $uuid->timeConverter;
340 }
341
342 /**
343 * @param array{bytes?: string} $data
344 */
345 public function __unserialize(array $data): void
346 {
347 // @codeCoverageIgnoreStart
348 if (!isset($data['bytes'])) {
349 throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
350 }
351 // @codeCoverageIgnoreEnd
352
353 $this->unserialize($data['bytes']);
354 }
355
356 public function compareTo(UuidInterface $other): int
357 {
358 $compare = strcmp($this->toString(), $other->toString());
359
360 if ($compare < 0) {
361 return -1;
362 }
363
364 if ($compare > 0) {
365 return 1;
366 }
367
368 return 0;
369 }
370
371 public function equals(?object $other): bool
372 {
373 if (!$other instanceof UuidInterface) {
374 return false;
375 }
376
377 return $this->compareTo($other) === 0;
378 }
379
380 /**
381 * @return non-empty-string
382 */
383 public function getBytes(): string
384 {
385 return $this->codec->encodeBinary($this);
386 }
387
388 public function getFields(): FieldsInterface
389 {
390 return $this->fields;
391 }
392
393 public function getHex(): Hexadecimal
394 {
395 return new Hexadecimal(str_replace('-', '', $this->toString()));
396 }
397
398 public function getInteger(): IntegerObject
399 {
400 return new IntegerObject($this->numberConverter->fromHex($this->getHex()->toString()));
401 }
402
403 public function getUrn(): string
404 {
405 return 'urn:uuid:' . $this->toString();
406 }
407
408 /**
409 * @return non-empty-string
410 */
411 public function toString(): string
412 {
413 return $this->codec->encode($this);
414 }
415
416 /**
417 * Returns the factory used to create UUIDs
418 */
419 public static function getFactory(): UuidFactoryInterface
420 {
421 if (self::$factory === null) {
422 self::$factory = new UuidFactory();
423 }
424
425 return self::$factory;
426 }
427
428 /**
429 * Sets the factory used to create UUIDs
430 *
431 * @param UuidFactoryInterface $factory A factory that will be used by this class to create UUIDs
432 */
433 public static function setFactory(UuidFactoryInterface $factory): void
434 {
435 // Note: non-strict equality is intentional here. If the factory is configured differently, every assumption
436 // around purity is broken, and we have to internally decide everything differently.
437 // phpcs:ignore SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedNotEqualOperator
438 self::$factoryReplaced = ($factory != new UuidFactory());
439
440 self::$factory = $factory;
441 }
442
443 /**
444 * Creates a UUID from a byte string
445 *
446 * @param string $bytes A binary string
447 *
448 * @return UuidInterface A UuidInterface instance created from a binary string representation
449 *
450 * @throws InvalidArgumentException
451 *
452 * @pure
453 */
454 public static function fromBytes(string $bytes): UuidInterface
455 {
456 /** @phpstan-ignore impure.staticPropertyAccess */
457 if (!self::$factoryReplaced && strlen($bytes) === 16) {
458 $base16Uuid = bin2hex($bytes);
459
460 // Note: we are calling `fromString` internally because we don't know if the given `$bytes` is a valid UUID
461 return self::fromString(
462 substr($base16Uuid, 0, 8)
463 . '-'
464 . substr($base16Uuid, 8, 4)
465 . '-'
466 . substr($base16Uuid, 12, 4)
467 . '-'
468 . substr($base16Uuid, 16, 4)
469 . '-'
470 . substr($base16Uuid, 20, 12),
471 );
472 }
473
474 /** @phpstan-ignore possiblyImpure.methodCall */
475 return self::getFactory()->fromBytes($bytes);
476 }
477
478 /**
479 * Creates a UUID from the string standard representation
480 *
481 * @param string $uuid A hexadecimal string
482 *
483 * @return UuidInterface A UuidInterface instance created from a hexadecimal string representation
484 *
485 * @throws InvalidArgumentException
486 *
487 * @pure
488 */
489 public static function fromString(string $uuid): UuidInterface
490 {
491 $uuid = strtolower($uuid);
492 /** @phpstan-ignore impure.staticPropertyAccess, possiblyImpure.functionCall */
493 if (!self::$factoryReplaced && preg_match(LazyUuidFromString::VALID_REGEX, $uuid) === 1) {
494 /** @phpstan-ignore possiblyImpure.new */
495 return new LazyUuidFromString($uuid);
496 }
497
498 /** @phpstan-ignore possiblyImpure.methodCall */
499 return self::getFactory()->fromString($uuid);
500 }
501
502 /**
503 * Creates a UUID from a DateTimeInterface instance
504 *
505 * @param DateTimeInterface $dateTime The date and time
506 * @param Hexadecimal | null $node A 48-bit number representing the hardware address
507 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
508 * backwards in time or if the node ID changes
509 *
510 * @return UuidInterface A UuidInterface instance that represents a version 1 UUID created from a DateTimeInterface instance
511 */
512 public static function fromDateTime(
513 DateTimeInterface $dateTime,
514 ?Hexadecimal $node = null,
515 ?int $clockSeq = null
516 ): UuidInterface {
517 return self::getFactory()->fromDateTime($dateTime, $node, $clockSeq);
518 }
519
520 /**
521 * Creates a UUID from the Hexadecimal object
522 *
523 * @param Hexadecimal $hex Hexadecimal object representing a hexadecimal number
524 *
525 * @return UuidInterface A UuidInterface instance created from the Hexadecimal object representing a hexadecimal number
526 *
527 * @throws InvalidArgumentException
528 *
529 * @pure
530 */
531 public static function fromHexadecimal(Hexadecimal $hex): UuidInterface
532 {
533 /** @phpstan-ignore possiblyImpure.methodCall */
534 $factory = self::getFactory();
535
536 if (method_exists($factory, 'fromHexadecimal')) {
537 /** @phpstan-ignore possiblyImpure.methodCall */
538 $uuid = $factory->fromHexadecimal($hex);
539 /** @phpstan-ignore possiblyImpure.functionCall */
540 assert($uuid instanceof UuidInterface);
541
542 return $uuid;
543 }
544
545 throw new BadMethodCallException('The method fromHexadecimal() does not exist on the provided factory');
546 }
547
548 /**
549 * Creates a UUID from a 128-bit integer string
550 *
551 * @param string $integer String representation of 128-bit integer
552 *
553 * @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer
554 *
555 * @throws InvalidArgumentException
556 *
557 * @pure
558 */
559 public static function fromInteger(string $integer): UuidInterface
560 {
561 /** @phpstan-ignore possiblyImpure.methodCall */
562 return self::getFactory()->fromInteger($integer);
563 }
564
565 /**
566 * Returns true if the provided string is a valid UUID
567 *
568 * @param string $uuid A string to validate as a UUID
569 *
570 * @return bool True if the string is a valid UUID, false otherwise
571 *
572 * @phpstan-assert-if-true =non-empty-string $uuid
573 *
574 * @pure
575 */
576 public static function isValid(string $uuid): bool
577 {
578 /** @phpstan-ignore possiblyImpure.methodCall, possiblyImpure.methodCall */
579 return self::getFactory()->getValidator()->validate($uuid);
580 }
581
582 /**
583 * Returns a version 1 (Gregorian time) UUID from a host ID, sequence number, and the current time
584 *
585 * @param Hexadecimal | int | string | null $node A 48-bit number representing the hardware address; this number may
586 * be represented as an integer or a hexadecimal string
587 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
588 * backwards in time or if the node ID changes
589 *
590 * @return UuidInterface A UuidInterface instance that represents a version 1 UUID
591 */
592 public static function uuid1($node = null, ?int $clockSeq = null): UuidInterface
593 {
594 return self::getFactory()->uuid1($node, $clockSeq);
595 }
596
597 /**
598 * Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the current time
599 *
600 * @param int $localDomain The local domain to use when generating bytes, according to DCE Security
601 * @param IntegerObject | null $localIdentifier The local identifier for the given domain; this may be a UID or GID
602 * on POSIX systems, if the local domain is "person" or "group," or it may be a site-defined identifier if the
603 * local domain is "org"
604 * @param Hexadecimal | null $node A 48-bit number representing the hardware address
605 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
606 * backwards in time or if the node ID changes (in a version 2 UUID, the lower 8 bits of this number are
607 * replaced with the domain).
608 *
609 * @return UuidInterface A UuidInterface instance that represents a version 2 UUID
610 */
611 public static function uuid2(
612 int $localDomain,
613 ?IntegerObject $localIdentifier = null,
614 ?Hexadecimal $node = null,
615 ?int $clockSeq = null
616 ): UuidInterface {
617 return self::getFactory()->uuid2($localDomain, $localIdentifier, $node, $clockSeq);
618 }
619
620 /**
621 * Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name
622 *
623 * @param UuidInterface | string $ns The namespace (must be a valid UUID)
624 * @param string $name The name to use for creating a UUID
625 *
626 * @return UuidInterface A UuidInterface instance that represents a version 3 UUID
627 *
628 * @pure
629 */
630 public static function uuid3($ns, string $name): UuidInterface
631 {
632 /** @phpstan-ignore possiblyImpure.methodCall */
633 return self::getFactory()->uuid3($ns, $name);
634 }
635
636 /**
637 * Returns a version 4 (random) UUID
638 *
639 * @return UuidInterface A UuidInterface instance that represents a version 4 UUID
640 */
641 public static function uuid4(): UuidInterface
642 {
643 return self::getFactory()->uuid4();
644 }
645
646 /**
647 * Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name
648 *
649 * @param UuidInterface | string $ns The namespace (must be a valid UUID)
650 * @param string $name The name to use for creating a UUID
651 *
652 * @return UuidInterface A UuidInterface instance that represents a version 5 UUID
653 *
654 * @pure
655 */
656 public static function uuid5($ns, string $name): UuidInterface
657 {
658 /** @phpstan-ignore possiblyImpure.methodCall */
659 return self::getFactory()->uuid5($ns, $name);
660 }
661
662 /**
663 * Returns a version 6 (reordered Gregorian time) UUID from a host ID, sequence number, and the current time
664 *
665 * @param Hexadecimal | null $node A 48-bit number representing the hardware address
666 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
667 * backwards in time or if the node ID changes
668 *
669 * @return UuidInterface A UuidInterface instance that represents a version 6 UUID
670 */
671 public static function uuid6(
672 ?Hexadecimal $node = null,
673 ?int $clockSeq = null
674 ): UuidInterface {
675 return self::getFactory()->uuid6($node, $clockSeq);
676 }
677
678 /**
679 * Returns a version 7 (Unix Epoch time) UUID
680 *
681 * @param DateTimeInterface | null $dateTime An optional date/time from which to create the version 7 UUID. If not
682 * provided, the UUID is generated using the current date/time.
683 *
684 * @return UuidInterface A UuidInterface instance that represents a version 7 UUID
685 */
686 public static function uuid7(?DateTimeInterface $dateTime = null): UuidInterface
687 {
688 $factory = self::getFactory();
689
690 if (method_exists($factory, 'uuid7')) {
691 /** @var UuidInterface */
692 return $factory->uuid7($dateTime);
693 }
694
695 throw new UnsupportedOperationException('The provided factory does not support the uuid7() method');
696 }
697
698 /**
699 * Returns a version 8 (custom format) UUID
700 *
701 * The bytes provided may contain any value according to your application's needs. Be aware, however, that other
702 * applications may not understand the semantics of the value.
703 *
704 * @param string $bytes A 16-byte octet string. This is an open blob of data that you may fill with 128 bits of
705 * information. Be aware, however, bits 48 through 51 will be replaced with the UUID version field, and bits 64
706 * and 65 will be replaced with the UUID variant. You MUST NOT rely on these bits for your application needs.
707 *
708 * @return UuidInterface A UuidInterface instance that represents a version 8 UUID
709 *
710 * @pure
711 */
712 public static function uuid8(string $bytes): UuidInterface
713 {
714 /** @phpstan-ignore possiblyImpure.methodCall */
715 $factory = self::getFactory();
716
717 if (method_exists($factory, 'uuid8')) {
718 /**
719 * @var UuidInterface
720 * @phpstan-ignore possiblyImpure.methodCall
721 */
722 return $factory->uuid8($bytes);
723 }
724
725 throw new UnsupportedOperationException('The provided factory does not support the uuid8() method');
726 }
727 }