Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit149d21a

Browse files
committed
Merge branch '7.0' into 7.1
* 7.0: [Uid] Expand the explanation about the different UUID variants
2 parents93a217e +702840f commit149d21a

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)
[8]ページ先頭
©2009-2025 Movatter.jp