8000 minor #13338 [UID] Added the docs for the component (javiereguiluz) · symfony/symfony-docs@459e09f · GitHub
[go: up one dir, main page]
Skip to content

Commit 459e09f

Browse files
javiereguiluzjaviereguiluz
committed
minor #13338 [UID] Added the docs for the component (javiereguiluz)
This PR was squashed before being merged into the master branch (closes #13338). Discussion ---------- [UID] Added the docs for the component Fixes #13333, #13341 and #13346. Commits ------- 8d04a27 [UID] Added the docs for the component
2 parents a9f63e3 + 8d04a27 commit 459e09f

File tree

1 file changed

+187
-0
lines changed

1 file changed

+187
-0
lines changed

‎components/uid.rst

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
.. index::
2+
single: UID
3+
single: Components; UID
4+
5+
The UID Component
6+
=================
7+
8+
The UID component provides utilities to work with `unique identifiers`_ (UIDs)
9+
such as UUIDs and ULIDs.
10+
11+
.. versionadded:: 5.1
12+
13+
The UID component was introduced in Symfony 5.1 as an
14+
:doc:`experimental feature </contributing/code/experimental>`.
15+
16+
Installation
17+
------------
18+
19+
.. code-block:: terminal
20+
21+
$ composer require symfony/uid
22+
23+
.. include:: /components/require_autoload.rst.inc
24+
25+
UUIDs
26+
-----
27+
28+
`UUIDs`_ (*universally unique identifiers*) are one of the most popular UIDs in
29+
the software industry. UUIDs are 128-bit numbers usually represented as five
30+
groups of hexadecimal characters: ``xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx``
31+
(the ``M`` digit is the UUID version and the ``N`` digit is the UUID variant).
32+
33+
Generating UUIDs
34+
~~~~~~~~~~~~~~~~
35+
36+
Use the named constructors of the ``Uuid`` class or any of the specific classes
37+
to create each type of UUID::
38+
39+
use Symfony\Component\Uid\Uuid;
40+
41+
// UUID type 1 generates the UUID using the MAC address of your device and a timestamp.
42+
// Both are obtained automatically, so you don't have to pass any constructor argument.
43+
$uuid = Uuid::v1(); // $uuid is an instance of Symfony\Component\Uid\UuidV1
44+
45+
// UUID type 4 generates a random UUID, so you don't have to pass any constructor argument.
46+
$uuid = Uuid::v4(); // $uuid is an instance of Symfony\Component\Uid\UuidV4
47+
48+
// UUID type 3 and 5 generate a UUID hashing the given namespace and name. Type 3 uses
49+
// MD5 hashes and Type 5 uses SHA-1. The namespace is another UUID (e.g. a Type 4 UUID)
50+
// and the name is an arbitrary string (e.g. a product name; if it's unique).
51+
$namespace = Uuid::v4();
52+
$name = $product->getUniqueName();
53+
54+
$uuid = Uuid::v3($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV3
55+
$uuid = Uuid::v5($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV5
56+
57+
// UUID type 6 is not part of the UUID standard. It's lexicographically sortable
58+
// (like ULIDs) and contains a 60-bit timestamp and 63 extra unique bits.
59+
// It's defined in http://gh.peabody.io/uuidv6/
60+
$uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6
61+
62+
If your UUID is generated by another system, use the ``fromString()`` method to
63+
create an object and make use of the utilities available for Symfony UUIDs::
64+
65+
// this value is generated somewhere else
66+
$uuidValue = 'd9e7a184-5d5b-11ea-a62a-3499710062d0';
67+
$uuid = Uuid::fromString($uuidValue);
68+
69+
If your UUIDs are generated in binary format, use the ``fromBinary()`` method
70+
to create the objects for them::
71+
72+
$uuid = Uuid::fromBinary($uuidBinaryContents);
73+
74+
Converting UUIDs
75+
~~~~~~~~~~~~~~~~
76+
77+
Use these methods to transform the UUID object into different bases::
78+
79+
$uuid = new Uuid::fromString('d9e7a184-5d5b-11ea-a62a-3499710062d0');
80+
81+
$uuid->toBinary(); // string(16) "..." (binary contents can't be printed)
82+
$uuid->toBase32(); // string(26) "6SWYGR8QAV27NACAHMK5RG0RPG"
83+
$uuid->toBase58(); // string(22) "TuetYWNHhmuSQ3xPoVLv9M"
84+
$uuid->toRfc4122(); // string(36) "d9e7a184-5d5b-11ea-a62a-3499710062d0"
85+
86+
Working with UUIDs
87+
~~~~~~~~~~~~~~~~~~
88+
89+
UUID objects created with the ``Uuid`` class can use the following methods
90+
(which are equivalent to the ``uuid_*()`` method of the PHP extension)::
91+
92+
use Symfony\Component\Uid\NilUuid;
93+
use Symfony\Component\Uid\Uuid;
94+
95+
// checking if the UUID is null (note that the class is called
96+
// NilUuid instead of NullUuid to follow the UUID standard notation)
97+
$uuid = Uuid::v4();
98+
$uuid instanceof NilUuid; // false
99+
100+
// checking the type of UUID
101+
use Symfony\Component\Uid\UuidV4;
102+
$uuid = Uuid::v4();
103+
$uuid instanceof UuidV4; // true
104+
105+
// getting the UUID time (it's only available in certain UUID types)
106+
$uuid = Uuid::v1();
107+
$uuid->getTime(); // e.g. float(1584111384.2613)
108+
109+
// comparing UUIDs and checking for equality
110+
$uuid1 = Uuid::v1();
111+
$uuid4 = Uuid::v4();
112+
$uuid1->equals($uuid4); // false
113+
114+
// this method returns:
115+
// * int(0) if $uuid1 and $uuid4 are equal
116+
// * int > 0 if $uuid1 is greater than $uuid4
117+
// * int < 0 if $uuid1 is less than $uuid4
118+
$uuid1->compare($uuid4); // e.g. int(4)
119+
120+
ULIDs
121+
-----
122+
123+
`ULIDs`_ (*Universally Unique Lexicographically Sortable Identifier*) are 128-bit
124+
numbers usually represented as a 26-character string: ``TTTTTTTTTTRRRRRRRRRRRRRRRR``
125+
(where ``T`` represents a timestamp and ``R`` represents the random bits).
126+
127+
ULIDs are an alternative to UUIDs when using those is impractical. They provide
128+
128-bit compatibility with UUID, they are lexicographically sortable and they
129+
are encoded as 26-character strings (vs 36-character UUIDs).
130+
131+
Generating ULIDs
132+
~~~~~~~~~~~~~~~~
133+
134+
Instantiate the ``Ulid`` class to generate a random ULID value::
135+
136+
use Symfony\Component\Uid\Ulid;
137+
138+
$ulid = new Ulid(); // e.g. 01AN4Z07BY79KA1307SR9X4MV3
139+
140+
If your UUID is generated by another system, use the ``fromString()`` method to
141+
create an object and make use of the utilities available for Symfony ULIDs::
142+
143+
// this value is generated somewhere else
144+
$ulidValue = '01E439TP9XJZ9RPFH3T1PYBCR8';
145+
$ulid = Ulid::fromString($ulidValue);
146+
147+
If your ULIDs are generated in binary format, use the ``fromBinary()`` method
148+
to create the objects for them::
149+
150+
$ulid = Ulid::fromBinary($ulidBinaryContents);
151+
152+
Converting ULIDs
153+
~~~~~~~~~~~~~~~~
154+
155+
Use these methods to transform the ULID object into different bases::
156+
157+
$ulid = Ulid::fromString('01E439TP9XJZ9RPFH3T1PYBCR8');
158+
159+
$ulid->toBinary(); // string(16) "..." (binary contents can't be printed)
160+
$ulid->toBase32(); // string(26) "01E439TP9XJZ9RPFH3T1PYBCR8"
161+
$ulid->toBase58(); // string(22) "1BKocMc5BnrVcuq2ti4Eqm"
162+
$ulid->toRfc4122(); // string(36) "0171069d-593d-97d3-8b3e-23d06de5b308"
163+
164+
Working with ULIDs
165+
~~~~~~~~~~~~~~~~~~
166+
167+
ULID objects created with the ``Ulid`` class can use the following methods::
168+
169+
use Symfony\Component\Uid\Ulid;
170+
171+
$ulid1 = new Ulid();
172+
$ulid2 = new Ulid();
173+
174+
// checking if a given value is valid as ULID
175+
$isValid = Ulid::isValid($ulidValue); // true or false
176+
177+
// getting the ULID time
178+
$ulid1->getTime(); // e.g. float(1584111384.2613)
179+
180+
// comparing ULIDs and checking for equality
181+
$ulid1->equals($ulid2); // false
182+
// this method returns $ulid1 <=> $ulid2
183+
$uuid1->compare($uuid4); // e.g. int(-1)
184+
185+
.. _`unique identifiers`: https://en.wikipedia.org/wiki/UID
186+
.. _`UUIDs`: https://en.wikipedia.org/wiki/Universally_unique_identifier
187+
.. _`ULIDs`: https://github.com/ulid/spec

0 commit comments

Comments
 (0)
0