Debian Codegraph @

vendor/ramsey/uuid/src/UuidInterface.php

raw
1 <?php
2 /**
3 * This file is part of the ramsey/uuid library
4 *
5 * For the full copyright and license information, please view the LICENSE
6 * file that was distributed with this source code.
7 *
8 * @copyright Copyright (c) Ben Ramsey <[email protected]>
9 * @license http://opensource.org/licenses/MIT MIT
10 * @link https://benramsey.com/projects/ramsey-uuid/ Documentation
11 * @link https://packagist.org/packages/ramsey/uuid Packagist
12 * @link https://github.com/ramsey/uuid GitHub
13 */
14
15 namespace Ramsey\Uuid;
16
17 use DateTime;
18 use JsonSerializable;
19 use Ramsey\Uuid\Converter\NumberConverterInterface;
20 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
21 use Ramsey\Uuid\Exception\UnsupportedOperationException;
22 use Serializable;
23
24 /**
25 * UuidInterface defines common functionality for all universally unique
26 * identifiers (UUIDs)
27 */
28 interface UuidInterface extends JsonSerializable, Serializable
29 {
30 /**
31 * Compares this UUID to the specified UUID.
32 *
33 * The first of two UUIDs is greater than the second if the most
34 * significant field in which the UUIDs differ is greater for the first
35 * UUID.
36 *
37 * * Q. What's the value of being able to sort UUIDs?
38 * * A. Use them as keys in a B-Tree or similar mapping.
39 *
40 * @param UuidInterface $other UUID to which this UUID is compared
41 * @return int -1, 0 or 1 as this UUID is less than, equal to, or greater than `$uuid`
42 */
43 public function compareTo(UuidInterface $other);
44
45 /**
46 * Compares this object to the specified object.
47 *
48 * The result is true if and only if the argument is not null, is a UUID
49 * object, has the same variant, and contains the same value, bit for bit,
50 * as this UUID.
51 *
52 * @param object $other
53 * @return bool True if `$other` is equal to this UUID
54 */
55 public function equals($other);
56
57 /**
58 * Returns the UUID as a 16-byte string (containing the six integer fields
59 * in big-endian byte order).
60 *
61 * @return string
62 */
63 public function getBytes();
64
65 /**
66 * Returns the number converter to use for converting hex values to/from integers.
67 *
68 * @return NumberConverterInterface
69 */
70 public function getNumberConverter();
71
72 /**
73 * Returns the hexadecimal value of the UUID.
74 *
75 * @return string
76 */
77 public function getHex();
78
79 /**
80 * Returns an array of the fields of this UUID, with keys named according
81 * to the RFC 4122 names for the fields.
82 *
83 * * **time_low**: The low field of the timestamp, an unsigned 32-bit integer
84 * * **time_mid**: The middle field of the timestamp, an unsigned 16-bit integer
85 * * **time_hi_and_version**: The high field of the timestamp multiplexed with
86 * the version number, an unsigned 16-bit integer
87 * * **clock_seq_hi_and_reserved**: The high field of the clock sequence
88 * multiplexed with the variant, an unsigned 8-bit integer
89 * * **clock_seq_low**: The low field of the clock sequence, an unsigned
90 * 8-bit integer
91 * * **node**: The spatially unique node identifier, an unsigned 48-bit
92 * integer
93 *
94 * @return array The UUID fields represented as hexadecimal values
95 */
96 public function getFieldsHex();
97
98 /**
99 * Returns the high field of the clock sequence multiplexed with the variant
100 * (bits 65-72 of the UUID).
101 *
102 * @return string Hexadecimal value of clock_seq_hi_and_reserved
103 */
104 public function getClockSeqHiAndReservedHex();
105
106 /**
107 * Returns the low field of the clock sequence (bits 73-80 of the UUID).
108 *
109 * @return string Hexadecimal value of clock_seq_low
110 */
111 public function getClockSeqLowHex();
112
113 /**
114 * Returns the clock sequence value associated with this UUID.
115 *
116 * @return string Hexadecimal value of clock sequence
117 */
118 public function getClockSequenceHex();
119
120 /**
121 * Returns a PHP `DateTime` object representing the timestamp associated
122 * with this UUID.
123 *
124 * The timestamp value is only meaningful in a time-based UUID, which
125 * has version type 1. If this UUID is not a time-based UUID then
126 * this method throws `UnsupportedOperationException`.
127 *
128 * @return DateTime A PHP DateTime representation of the date
129 * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
130 * @throws UnsatisfiedDependencyException if called in a 32-bit system and
131 * `Moontoast\Math\BigNumber` is not present
132 */
133 public function getDateTime();
134
135 /**
136 * Returns the integer value of the UUID, converted to an appropriate number
137 * representation.
138 *
139 * @return mixed Converted representation of the unsigned 128-bit integer value
140 * @throws UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present
141 */
142 public function getInteger();
143
144 /**
145 * Returns the least significant 64 bits of this UUID's 128 bit value.
146 *
147 * @return string Hexadecimal value of least significant bits
148 */
149 public function getLeastSignificantBitsHex();
150
151 /**
152 * Returns the most significant 64 bits of this UUID's 128 bit value.
153 *
154 * @return string Hexadecimal value of most significant bits
155 */
156 public function getMostSignificantBitsHex();
157
158 /**
159 * Returns the node value associated with this UUID
160 *
161 * For UUID version 1, the node field consists of an IEEE 802 MAC
162 * address, usually the host address. For systems with multiple IEEE
163 * 802 addresses, any available one can be used. The lowest addressed
164 * octet (octet number 10) contains the global/local bit and the
165 * unicast/multicast bit, and is the first octet of the address
166 * transmitted on an 802.3 LAN.
167 *
168 * For systems with no IEEE address, a randomly or pseudo-randomly
169 * generated value may be used; see RFC 4122, Section 4.5. The
170 * multicast bit must be set in such addresses, in order that they
171 * will never conflict with addresses obtained from network cards.
172 *
173 * For UUID version 3 or 5, the node field is a 48-bit value constructed
174 * from a name as described in RFC 4122, Section 4.3.
175 *
176 * For UUID version 4, the node field is a randomly or pseudo-randomly
177 * generated 48-bit value as described in RFC 4122, Section 4.4.
178 *
179 * @return string Hexadecimal value of node
180 * @link http://tools.ietf.org/html/rfc4122#section-4.1.6
181 */
182 public function getNodeHex();
183
184 /**
185 * Returns the high field of the timestamp multiplexed with the version
186 * number (bits 49-64 of the UUID).
187 *
188 * @return string Hexadecimal value of time_hi_and_version
189 */
190 public function getTimeHiAndVersionHex();
191
192 /**
193 * Returns the low field of the timestamp (the first 32 bits of the UUID).
194 *
195 * @return string Hexadecimal value of time_low
196 */
197 public function getTimeLowHex();
198
199 /**
200 * Returns the middle field of the timestamp (bits 33-48 of the UUID).
201 *
202 * @return string Hexadecimal value of time_mid
203 */
204 public function getTimeMidHex();
205
206 /**
207 * Returns the timestamp value associated with this UUID.
208 *
209 * The 60 bit timestamp value is constructed from the time_low,
210 * time_mid, and time_hi fields of this UUID. The resulting
211 * timestamp is measured in 100-nanosecond units since midnight,
212 * October 15, 1582 UTC.
213 *
214 * The timestamp value is only meaningful in a time-based UUID, which
215 * has version type 1. If this UUID is not a time-based UUID then
216 * this method throws UnsupportedOperationException.
217 *
218 * @return string Hexadecimal value of the timestamp
219 * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
220 * @link http://tools.ietf.org/html/rfc4122#section-4.1.4
221 */
222 public function getTimestampHex();
223
224 /**
225 * Returns the string representation of the UUID as a URN.
226 *
227 * @return string
228 * @link http://en.wikipedia.org/wiki/Uniform_Resource_Name
229 */
230 public function getUrn();
231
232 /**
233 * Returns the variant number associated with this UUID.
234 *
235 * The variant number describes the layout of the UUID. The variant
236 * number has the following meaning:
237 *
238 * * 0 - Reserved for NCS backward compatibility
239 * * 2 - The RFC 4122 variant (used by this class)
240 * * 6 - Reserved, Microsoft Corporation backward compatibility
241 * * 7 - Reserved for future definition
242 *
243 * @return int
244 * @link http://tools.ietf.org/html/rfc4122#section-4.1.1
245 */
246 public function getVariant();
247
248 /**
249 * Returns the version number associated with this UUID.
250 *
251 * The version number describes how this UUID was generated and has the
252 * following meaning:
253 *
254 * * 1 - Time-based UUID
255 * * 2 - DCE security UUID
256 * * 3 - Name-based UUID hashed with MD5
257 * * 4 - Randomly generated UUID
258 * * 5 - Name-based UUID hashed with SHA-1
259 *
260 * Returns null if this UUID is not an RFC 4122 variant, since version
261 * is only meaningful for this variant.
262 *
263 * @return int|null
264 * @link http://tools.ietf.org/html/rfc4122#section-4.1.3
265 */
266 public function getVersion();
267
268 /**
269 * Converts this UUID into a string representation.
270 *
271 * @return string
272 */
273 public function toString();
274 }