Debian Codegraph @

vendor/ramsey/uuid/src/UuidFactoryInterface.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 DateTimeInterface;
18 use Ramsey\Uuid\Type\Hexadecimal;
19 use Ramsey\Uuid\Type\Integer as IntegerObject;
20 use Ramsey\Uuid\Validator\ValidatorInterface;
21
22 /**
23 * UuidFactoryInterface defines the common functionality all `UuidFactory` instances must implement
24 */
25 interface UuidFactoryInterface
26 {
27 /**
28 * Creates a UUID from a byte string
29 *
30 * @param string $bytes A binary string
31 *
32 * @return UuidInterface A UuidInterface instance created from a binary string representation
33 *
34 * @pure
35 */
36 public function fromBytes(string $bytes): UuidInterface;
37
38 /**
39 * Creates a UUID from a DateTimeInterface instance
40 *
41 * @param DateTimeInterface $dateTime The date and time
42 * @param Hexadecimal | null $node A 48-bit number representing the hardware address
43 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
44 * backwards in time or if the node ID changes
45 *
46 * @return UuidInterface A UuidInterface instance that represents a version 1 UUID created from a DateTimeInterface instance
47 */
48 public function fromDateTime(
49 DateTimeInterface $dateTime,
50 ?Hexadecimal $node = null,
51 ?int $clockSeq = null,
52 ): UuidInterface;
53
54 /**
55 * Creates a UUID from a 128-bit integer string
56 *
57 * @param string $integer String representation of 128-bit integer
58 *
59 * @return UuidInterface A UuidInterface instance created from the string representation of a 128-bit integer
60 *
61 * @pure
62 */
63 public function fromInteger(string $integer): UuidInterface;
64
65 /**
66 * Creates a UUID from the string standard representation
67 *
68 * @param string $uuid A hexadecimal string
69 *
70 * @return UuidInterface A UuidInterface instance created from a hexadecimal string representation
71 *
72 * @pure
73 */
74 public function fromString(string $uuid): UuidInterface;
75
76 /**
77 * Returns the validator used by the factory
78 */
79 public function getValidator(): ValidatorInterface;
80
81 /**
82 * Returns a version 1 (Gregorian time) UUID from a host ID, sequence number, and the current time
83 *
84 * @param Hexadecimal | int | string | null $node A 48-bit number representing the hardware address; this number may
85 * be represented as an integer or a hexadecimal string
86 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
87 * backwards in time or if the node ID changes
88 *
89 * @return UuidInterface A UuidInterface instance that represents a version 1 UUID
90 */
91 public function uuid1($node = null, ?int $clockSeq = null): UuidInterface;
92
93 /**
94 * Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the
95 * current time
96 *
97 * @param int $localDomain The local domain to use when generating bytes, according to DCE Security
98 * @param IntegerObject | null $localIdentifier The local identifier for the given domain; this may be a UID or GID
99 * on POSIX systems, if the local domain is a person or group, or it may be a site-defined identifier if the
100 * local domain is org
101 * @param Hexadecimal | null $node A 48-bit number representing the hardware address
102 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
103 * backwards in time or if the node ID changes
104 *
105 * @return UuidInterface A UuidInterface instance that represents a version 2 UUID
106 */
107 public function uuid2(
108 int $localDomain,
109 ?IntegerObject $localIdentifier = null,
110 ?Hexadecimal $node = null,
111 ?int $clockSeq = null,
112 ): UuidInterface;
113
114 /**
115 * Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name
116 *
117 * @param UuidInterface | string $ns The namespace (must be a valid UUID)
118 * @param string $name The name to use for creating a UUID
119 *
120 * @return UuidInterface A UuidInterface instance that represents a version 3 UUID
121 *
122 * @pure
123 */
124 public function uuid3($ns, string $name): UuidInterface;
125
126 /**
127 * Returns a version 4 (random) UUID
128 *
129 * @return UuidInterface A UuidInterface instance that represents a version 4 UUID
130 */
131 public function uuid4(): UuidInterface;
132
133 /**
134 * Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name
135 *
136 * @param UuidInterface | string $ns The namespace (must be a valid UUID)
137 * @param string $name The name to use for creating a UUID
138 *
139 * @return UuidInterface A UuidInterface instance that represents a version 5 UUID
140 *
141 * @pure
142 */
143 public function uuid5($ns, string $name): UuidInterface;
144
145 /**
146 * Returns a version 6 (reordered Gregorian time) UUID from a host ID, sequence number, and the current time
147 *
148 * @param Hexadecimal | null $node A 48-bit number representing the hardware address
149 * @param int | null $clockSeq A 14-bit number used to help avoid duplicates that could arise when the clock is set
150 * backwards in time or if the node ID changes
151 *
152 * @return UuidInterface A UuidInterface instance that represents a version 6 UUID
153 */
154 public function uuid6(?Hexadecimal $node = null, ?int $clockSeq = null): UuidInterface;
155 }