Skip to content

Commit 149d21a

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '7.0' into 7.1
* 7.0: [Uid] Expand the explanation about the different UUID variants
2 parents 93a217e + 702840f commit 149d21a

File tree

1 file changed

+100
-40
lines changed

1 file changed

+100
-40
lines changed

‎components/uid.rst

Lines changed: 100 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -27,48 +27,108 @@ Generating UUIDs
2727
~~~~~~~~~~~~~~~~
2828

2929
Use the named constructors of the ``Uuid`` class or any of the specific classes
30-
to create each type of UUID::
30+
to create each type of UUID:
3131

32-
use Symfony\Component\Uid\Uuid;
32+
**UUID v1** (time-based)
33+
Generates the UUID using a timestamp and the MAC address of your device
34+
(`read UUIDv1 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-1>`__).
35+
Both are obtained automatically, so you don't have to pass any constructor argument::
36+
37+
use Symfony\Component\Uid\Uuid;
38+
39+
// $uuid is an instance of Symfony\Component\Uid\UuidV1
40+
$uuid = Uuid::v1();
41+
42+
.. tip::
43+
44+
It's recommended to use UUIDv7 instead of UUIDv1 because it provides
45+
better entropy.
46+
47+
**UUID v2** (DCE security)
48+
Similar to UUIDv1 but with a very high likelihood of ID collision
49+
(`read UUIDv2 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-2>`__).
50+
It's part of the authentication mechanism of DCE (Distributed Computing Environment)
51+
and the UUID includes the POSIX UIDs (user/group ID) of the user who generated it.
52+
This UUID variant is **not implemented** by the Uid component.
53+
54+
**UUID v3** (name-based, MD5)
55+
Generates UUIDs from names that belong, and are unique within, some given namespace
56+
(`read UUIDv3 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-3>`__).
57+
This variant is useful to generate deterministic UUIDs from arbitrary strings.
58+
It works by populating the UUID contents with the``md5`` hash of concatenating
59+
the namespace and the name::
60+
61+
use Symfony\Component\Uid\Uuid;
62+
63+
// you can use any of the predefined namespaces...
64+
$namespace = Uuid::fromString(Uuid::NAMESPACE_OID);
65+
// ...or use a random namespace:
66+
// $namespace = Uuid::v4();
67+
68+
// $name can be any arbitrary string
69+
// $uuid is an instance of Symfony\Component\Uid\UuidV3
70+
$uuid = Uuid::v3($namespace, $name);
71+
72+
These are the default namespaces defined by the standard:
73+
74+
* ``Uuid::NAMESPACE_DNS`` if you are generating UUIDs for `DNS entries <https://en.wikipedia.org/wiki/Domain_Name_System>`__
75+
* ``Uuid::NAMESPACE_URL`` if you are generating UUIDs for `URLs <https://en.wikipedia.org/wiki/URL>`__
76+
* ``Uuid::NAMESPACE_OID`` if you are generating UUIDs for `OIDs (object identifiers) <https://en.wikipedia.org/wiki/Object_identifier>`__
77+
* ``Uuid::NAMESPACE_X500`` if you are generating UUIDs for `X500 DNs (distinguished names) <https://en.wikipedia.org/wiki/X.500>`__
78+
79+
**UUID v4** (random)
80+
Generates a random UUID (`read UUIDv4 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-4>`__).
81+
Because of its randomness, it ensures uniqueness across distributed systems
82+
without the need for a central coordinating entity. It's privacy-friendly
83+
because it doesn't contain any information about where and when it was generated::
84+
85+
use Symfony\Component\Uid\Uuid;
86+
87+
// $uuid is an instance of Symfony\Component\Uid\UuidV4
88+
$uuid = Uuid::v4();
89+
90+
**UUID v5** (name-based, SHA-1)
91+
It's the same as UUIDv3 (explained above) but it uses ``sha1`` instead of
92+
``md5`` to hash the given namespace and name (`read UUIDv5 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-5>`__).
93+
This makes it more secure and less prone to hash collisions.
94+
95+
**UUID v6** (reordered time-based)
96+
It rearranges the time-based fields of the UUIDv1 to make it lexicographically
97+
sortable (like :ref:`ULIDs <ulid>`). It's more efficient for database indexing
98+
(`read UUIDv6 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-6>`__)::
99+
100+
use Symfony\Component\Uid\Uuid;
101+
102+
// $uuid is an instance of Symfony\Component\Uid\UuidV6
103+
$uuid = Uuid::v6();
104+
105+
.. tip::
106+
107+
It's recommended to use UUIDv7 instead of UUIDv6 because it provides
108+
better entropy.
109+
110+
**UUID v7** (UNIX timestamp)
111+
Generates time-ordered UUIDs based on a high-resolution Unix Epoch timestamp
112+
source (the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded)
113+
(`read UUIDv7 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-7>`__).
114+
It's recommended to use this version over UUIDv1 and UUIDv6 because it provides
115+
better entropy (and a more strict chronological order of UUID generation)::
116+
117+
use Symfony\Component\Uid\Uuid;
118+
119+
// $uuid is an instance of Symfony\Component\Uid\UuidV7
120+
$uuid = Uuid::v7();
121+
122+
**UUID v8** (custom)
123+
Provides an RFC-compatible format for experimental or vendor-specific use cases
124+
(`read UUIDv8 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-8>`__).
125+
The only requirement is to set the variant and version bits of the UUID. The rest
126+
of the UUID value is specific to each implementation and no format should be assumed::
127+
128+
use Symfony\Component\Uid\Uuid;
33129

34-
// UUID type 1 generates the UUID using the MAC address of your device and a timestamp.
35-
// Both are obtained automatically, so you don't have to pass any constructor argument.
36-
$uuid = Uuid::v1(); // $uuid is an instance of Symfony\Component\Uid\UuidV1
37-
38-
// UUID type 4 generates a random UUID, so you don't have to pass any constructor argument.
39-
$uuid = Uuid::v4(); // $uuid is an instance of Symfony\Component\Uid\UuidV4
40-
41-
// UUID type 3 and 5 generate a UUID hashing the given namespace and name. Type 3 uses
42-
// MD5 hashes and Type 5 uses SHA-1. The namespace is another UUID (e.g. a Type 4 UUID)
43-
// and the name is an arbitrary string (e.g. a product name; if it's unique).
44-
$namespace = Uuid::v4();
45-
$name = $product->getUniqueName();
46-
47-
$uuid = Uuid::v3($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV3
48-
$uuid = Uuid::v5($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV5
49-
50-
// the namespaces defined by RFC 4122 (see https://tools.ietf.org/html/rfc4122#appendix-C)
51-
// are available as PHP constants and as string values
52-
$uuid = Uuid::v3(Uuid::NAMESPACE_DNS, $name); // same as: Uuid::v3('dns', $name);
53-
$uuid = Uuid::v3(Uuid::NAMESPACE_URL, $name); // same as: Uuid::v3('url', $name);
54-
$uuid = Uuid::v3(Uuid::NAMESPACE_OID, $name); // same as: Uuid::v3('oid', $name);
55-
$uuid = Uuid::v3(Uuid::NAMESPACE_X500, $name); // same as: Uuid::v3('x500', $name);
56-
57-
// UUID type 6 is not yet 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 https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-6
60-
$uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6
61-
62-
// UUID version 7 features a time-ordered value field derived from the well known
63-
// Unix Epoch timestamp source: the number of seconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
64-
// As well as improved entropy characteristics over versions 1 or 6.
65-
$uuid = Uuid::v7();
66-
67-
// UUID version 8 provides an RFC-compatible format for experimental or vendor-specific use cases.
68-
// The only requirement is that the variant and version bits MUST be set as defined in Section 4:
69-
// https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#variant_and_version_fields
70-
// UUIDv8 uniqueness will be implementation-specific and SHOULD NOT be assumed.
71-
$uuid = Uuid::v8();
130+
// $uuid is an instance of Symfony\Component\Uid\UuidV8
131+
$uuid = Uuid::v8();
72132

73133
If your UUID value is already generated in another format, use any of the
74134
following methods to create a ``Uuid`` object from it::

0 commit comments

Comments
 (0)