Debian Codegraph @

vendor/ramsey/uuid/src/Rfc4122/VariantTrait.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\InvalidBytesException;
18 use Ramsey\Uuid\Uuid;
19
20 use function decbin;
21 use function str_pad;
22 use function str_starts_with;
23 use function strlen;
24 use function substr;
25 use function unpack;
26
27 use const STR_PAD_LEFT;
28
29 /**
30 * Provides common functionality for handling the variant, as defined by RFC 9562 (formerly RFC 4122)
31 *
32 * @immutable
33 */
34 trait VariantTrait
35 {
36 /**
37 * Returns the bytes that comprise the fields
38 */
39 abstract public function getBytes(): string;
40
41 /**
42 * Returns the variant
43 *
44 * The variant number describes the layout of the UUID. The variant number has the following meaning:
45 *
46 * - 0 - Reserved for NCS backward compatibility
47 * - 2 - The RFC 9562 (formerly RFC 4122) variant
48 * - 6 - Reserved, Microsoft Corporation backward compatibility
49 * - 7 - Reserved for future definition
50 *
51 * For RFC 9562 (formerly RFC 4122) variant UUIDs, this value should always be the integer `2`.
52 *
53 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
54 */
55 public function getVariant(): int
56 {
57 if (strlen($this->getBytes()) !== 16) {
58 throw new InvalidBytesException('Invalid number of bytes');
59 }
60
61 // According to RFC 9562, sections {@link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 4.1} and
62 // {@link https://www.rfc-editor.org/rfc/rfc9562#section-5.10 5.10}, the Max UUID falls within the range
63 // of the future variant.
64 if ($this->isMax()) {
65 return Uuid::RESERVED_FUTURE;
66 }
67
68 // According to RFC 9562, sections {@link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 4.1} and
69 // {@link https://www.rfc-editor.org/rfc/rfc9562#section-5.9 5.9}, the Nil UUID falls within the range
70 // of the Apollo NCS variant.
71 if ($this->isNil()) {
72 return Uuid::RESERVED_NCS;
73 }
74
75 /** @var int[] $parts */
76 $parts = unpack('n*', $this->getBytes());
77
78 // $parts[5] is a 16-bit, unsigned integer containing the variant bits of the UUID. We convert this integer into
79 // a string containing a binary representation, padded to 16 characters. We analyze the first three characters
80 // (three most-significant bits) to determine the variant.
81 $msb = substr(str_pad(decbin($parts[5]), 16, '0', STR_PAD_LEFT), 0, 3);
82
83 if ($msb === '111') {
84 return Uuid::RESERVED_FUTURE;
85 } elseif ($msb === '110') {
86 return Uuid::RESERVED_MICROSOFT;
87 } elseif (str_starts_with($msb, '10')) {
88 return Uuid::RFC_4122;
89 }
90
91 return Uuid::RESERVED_NCS;
92 }
93 }