Skip to content

Commit e3ddac6

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '6.4' into 7.0
* 6.4: [Uid] Update some RST syntax
2 parents a72ba70 + 1607d7d commit e3ddac6

File tree

1 file changed

+74
-66
lines changed

1 file changed

+74
-66
lines changed

‎components/uid.rst

Lines changed: 74 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -30,105 +30,113 @@ Use the named constructors of the ``Uuid`` class or any of the specific classes
3030
to create each type of UUID:
3131

3232
**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::
3633

37-
use Symfony\Component\Uid\Uuid;
34+
Generates the UUID using a timestamp and the MAC address of your device
35+
(`read UUIDv1 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-1>`__).
36+
Both are obtained automatically, so you don't have to pass any constructor argument::
3837

39-
// $uuid is an instance of Symfony\Component\Uid\UuidV1
40-
$uuid = Uuid::v1();
38+
use Symfony\Component\Uid\Uuid;
39+
40+
// $uuid is an instance of Symfony\Component\Uid\UuidV1
41+
$uuid = Uuid::v1();
4142

42-
.. tip::
43+
.. tip::
4344

44-
It's recommended to use UUIDv7 instead of UUIDv1 because it provides
45-
better entropy.
45+
It's recommended to use UUIDv7 instead of UUIDv1 because it provides
46+
better entropy.
4647

4748
**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.
49+
50+
Similar to UUIDv1 but with a very high likelihood of ID collision
51+
(`read UUIDv2 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-2>`__).
52+
It's part of the authentication mechanism of DCE (Distributed Computing Environment)
53+
and the UUID includes the POSIX UIDs (user/group ID) of the user who generated it.
54+
This UUID variant is **not implemented** by the Uid component.
5355

5456
**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::
6057

61-
use Symfony\Component\Uid\Uuid;
58+
Generates UUIDs from names that belong, and are unique within, some given namespace
59+
(`read UUIDv3 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-3>`__).
60+
This variant is useful to generate deterministic UUIDs from arbitrary strings.
61+
It works by populating the UUID contents with the``md5`` hash of concatenating
62+
the namespace and the name::
6263

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();
64+
use Symfony\Component\Uid\Uuid;
65+
66+
// you can use any of the predefined namespaces...
67+
$namespace = Uuid::fromString(Uuid::NAMESPACE_OID);
68+
// ...or use a random namespace:
69+
// $namespace = Uuid::v4();
6770

68-
// $name can be any arbitrary string
69-
// $uuid is an instance of Symfony\Component\Uid\UuidV3
70-
$uuid = Uuid::v3($namespace, $name);
71+
// $name can be any arbitrary string
72+
// $uuid is an instance of Symfony\Component\Uid\UuidV3
73+
$uuid = Uuid::v3($namespace, $name);
7174

72-
These are the default namespaces defined by the standard:
75+
These are the default namespaces defined by the standard:
7376

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>`__
77+
* ``Uuid::NAMESPACE_DNS`` if you are generating UUIDs for `DNS entries <https://en.wikipedia.org/wiki/Domain_Name_System>`__
78+
* ``Uuid::NAMESPACE_URL`` if you are generating UUIDs for `URLs <https://en.wikipedia.org/wiki/URL>`__
79+
* ``Uuid::NAMESPACE_OID`` if you are generating UUIDs for `OIDs (object identifiers) <https://en.wikipedia.org/wiki/Object_identifier>`__
80+
* ``Uuid::NAMESPACE_X500`` if you are generating UUIDs for `X500 DNs (distinguished names) <https://en.wikipedia.org/wiki/X.500>`__
7881

7982
**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::
8483

85-
use Symfony\Component\Uid\Uuid;
84+
Generates a random UUID (`read UUIDv4 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-4>`__).
85+
Because of its randomness, it ensures uniqueness across distributed systems
86+
without the need for a central coordinating entity. It's privacy-friendly
87+
because it doesn't contain any information about where and when it was generated::
88+
89+
use Symfony\Component\Uid\Uuid;
8690

87-
// $uuid is an instance of Symfony\Component\Uid\UuidV4
88-
$uuid = Uuid::v4();
91+
// $uuid is an instance of Symfony\Component\Uid\UuidV4
92+
$uuid = Uuid::v4();
8993

9094
**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.
95+
96+
It's the same as UUIDv3 (explained above) but it uses ``sha1`` instead of
97+
``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>`__).
98+
This makes it more secure and less prone to hash collisions.
9499

95100
**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>`__)::
99101

100-
use Symfony\Component\Uid\Uuid;
102+
It rearranges the time-based fields of the UUIDv1 to make it lexicographically
103+
sortable (like :ref:`ULIDs <ulid>`). It's more efficient for database indexing
104+
(`read UUIDv6 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-6>`__)::
105+
106+
use Symfony\Component\Uid\Uuid;
101107

102-
// $uuid is an instance of Symfony\Component\Uid\UuidV6
103-
$uuid = Uuid::v6();
108+
// $uuid is an instance of Symfony\Component\Uid\UuidV6
109+
$uuid = Uuid::v6();
104110

105-
.. tip::
111+
.. tip::
106112

107-
It's recommended to use UUIDv7 instead of UUIDv6 because it provides
108-
better entropy.
113+
It's recommended to use UUIDv7 instead of UUIDv6 because it provides
114+
better entropy.
109115

110116
**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)::
116117

117-
use Symfony\Component\Uid\Uuid;
118+
Generates time-ordered UUIDs based on a high-resolution Unix Epoch timestamp
119+
source (the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded)
120+
(`read UUIDv7 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-7>`__).
121+
It's recommended to use this version over UUIDv1 and UUIDv6 because it provides
122+
better entropy (and a more strict chronological order of UUID generation)::
118123

119-
// $uuid is an instance of Symfony\Component\Uid\UuidV7
120-
$uuid = Uuid::v7();
124+
use Symfony\Component\Uid\Uuid;
125+
126+
// $uuid is an instance of Symfony\Component\Uid\UuidV7
127+
$uuid = Uuid::v7();
121128

122129
**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::
127130

128-
use Symfony\Component\Uid\Uuid;
131+
Provides an RFC-compatible format for experimental or vendor-specific use cases
132+
(`read UUIDv8 spec <https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-8>`__).
133+
The only requirement is to set the variant and version bits of the UUID. The rest
134+
of the UUID value is specific to each implementation and no format should be assumed::
135+
136+
use Symfony\Component\Uid\Uuid;
129137

130-
// $uuid is an instance of Symfony\Component\Uid\UuidV8
131-
$uuid = Uuid::v8();
138+
// $uuid is an instance of Symfony\Component\Uid\UuidV8
139+
$uuid = Uuid::v8();
132140

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

0 commit comments

Comments
 (0)