diff --git a/components/uid.rst b/components/uid.rst index 0b292020041..2f3b2118c5b 100644 --- a/components/uid.rst +++ b/components/uid.rst @@ -30,105 +30,113 @@ Use the named constructors of the ``Uuid`` class or any of the specific classes to create each type of UUID: **UUID v1** (time-based) - Generates the UUID using a timestamp and the MAC address of your device - (`read UUIDv1 spec `__). - Both are obtained automatically, so you don't have to pass any constructor argument:: - use Symfony\Component\Uid\Uuid; +Generates the UUID using a timestamp and the MAC address of your device +(`read UUIDv1 spec `__). +Both are obtained automatically, so you don't have to pass any constructor argument:: - // $uuid is an instance of Symfony\Component\Uid\UuidV1 - $uuid = Uuid::v1(); + use Symfony\Component\Uid\Uuid; + + // $uuid is an instance of Symfony\Component\Uid\UuidV1 + $uuid = Uuid::v1(); - .. tip:: +.. tip:: - It's recommended to use UUIDv7 instead of UUIDv1 because it provides - better entropy. + It's recommended to use UUIDv7 instead of UUIDv1 because it provides + better entropy. **UUID v2** (DCE security) - Similar to UUIDv1 but with a very high likelihood of ID collision - (`read UUIDv2 spec `__). - It's part of the authentication mechanism of DCE (Distributed Computing Environment) - and the UUID includes the POSIX UIDs (user/group ID) of the user who generated it. - This UUID variant is **not implemented** by the Uid component. + +Similar to UUIDv1 but with a very high likelihood of ID collision +(`read UUIDv2 spec `__). +It's part of the authentication mechanism of DCE (Distributed Computing Environment) +and the UUID includes the POSIX UIDs (user/group ID) of the user who generated it. +This UUID variant is **not implemented** by the Uid component. **UUID v3** (name-based, MD5) - Generates UUIDs from names that belong, and are unique within, some given namespace - (`read UUIDv3 spec `__). - This variant is useful to generate deterministic UUIDs from arbitrary strings. - It works by populating the UUID contents with the``md5`` hash of concatenating - the namespace and the name:: - use Symfony\Component\Uid\Uuid; +Generates UUIDs from names that belong, and are unique within, some given namespace +(`read UUIDv3 spec `__). +This variant is useful to generate deterministic UUIDs from arbitrary strings. +It works by populating the UUID contents with the``md5`` hash of concatenating +the namespace and the name:: - // you can use any of the predefined namespaces... - $namespace = Uuid::fromString(Uuid::NAMESPACE_OID); - // ...or use a random namespace: - // $namespace = Uuid::v4(); + use Symfony\Component\Uid\Uuid; - // $name can be any arbitrary string - // $uuid is an instance of Symfony\Component\Uid\UuidV3 - $uuid = Uuid::v3($namespace, $name); + // you can use any of the predefined namespaces... + $namespace = Uuid::fromString(Uuid::NAMESPACE_OID); + // ...or use a random namespace: + // $namespace = Uuid::v4(); - These are the default namespaces defined by the standard: + // $name can be any arbitrary string + // $uuid is an instance of Symfony\Component\Uid\UuidV3 + $uuid = Uuid::v3($namespace, $name); - * ``Uuid::NAMESPACE_DNS`` if you are generating UUIDs for `DNS entries `__ - * ``Uuid::NAMESPACE_URL`` if you are generating UUIDs for `URLs `__ - * ``Uuid::NAMESPACE_OID`` if you are generating UUIDs for `OIDs (object identifiers) `__ - * ``Uuid::NAMESPACE_X500`` if you are generating UUIDs for `X500 DNs (distinguished names) `__ +These are the default namespaces defined by the standard: + +* ``Uuid::NAMESPACE_DNS`` if you are generating UUIDs for `DNS entries `__ +* ``Uuid::NAMESPACE_URL`` if you are generating UUIDs for `URLs `__ +* ``Uuid::NAMESPACE_OID`` if you are generating UUIDs for `OIDs (object identifiers) `__ +* ``Uuid::NAMESPACE_X500`` if you are generating UUIDs for `X500 DNs (distinguished names) `__ **UUID v4** (random) - Generates a random UUID (`read UUIDv4 spec `__). - Because of its randomness, it ensures uniqueness across distributed systems - without the need for a central coordinating entity. It's privacy-friendly - because it doesn't contain any information about where and when it was generated:: - use Symfony\Component\Uid\Uuid; +Generates a random UUID (`read UUIDv4 spec `__). +Because of its randomness, it ensures uniqueness across distributed systems +without the need for a central coordinating entity. It's privacy-friendly +because it doesn't contain any information about where and when it was generated:: + + use Symfony\Component\Uid\Uuid; - // $uuid is an instance of Symfony\Component\Uid\UuidV4 - $uuid = Uuid::v4(); + // $uuid is an instance of Symfony\Component\Uid\UuidV4 + $uuid = Uuid::v4(); **UUID v5** (name-based, SHA-1) - It's the same as UUIDv3 (explained above) but it uses ``sha1`` instead of - ``md5`` to hash the given namespace and name (`read UUIDv5 spec `__). - This makes it more secure and less prone to hash collisions. + +It's the same as UUIDv3 (explained above) but it uses ``sha1`` instead of +``md5`` to hash the given namespace and name (`read UUIDv5 spec `__). +This makes it more secure and less prone to hash collisions. **UUID v6** (reordered time-based) - It rearranges the time-based fields of the UUIDv1 to make it lexicographically - sortable (like :ref:`ULIDs `). It's more efficient for database indexing - (`read UUIDv6 spec `__):: - use Symfony\Component\Uid\Uuid; +It rearranges the time-based fields of the UUIDv1 to make it lexicographically +sortable (like :ref:`ULIDs `). It's more efficient for database indexing +(`read UUIDv6 spec `__):: + + use Symfony\Component\Uid\Uuid; - // $uuid is an instance of Symfony\Component\Uid\UuidV6 - $uuid = Uuid::v6(); + // $uuid is an instance of Symfony\Component\Uid\UuidV6 + $uuid = Uuid::v6(); - .. tip:: +.. tip:: - It's recommended to use UUIDv7 instead of UUIDv6 because it provides - better entropy. + It's recommended to use UUIDv7 instead of UUIDv6 because it provides + better entropy. **UUID v7** (UNIX timestamp) - Generates time-ordered UUIDs based on a high-resolution Unix Epoch timestamp - source (the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded) - (`read UUIDv7 spec `__). - It's recommended to use this version over UUIDv1 and UUIDv6 because it provides - better entropy (and a more strict chronological order of UUID generation):: - use Symfony\Component\Uid\Uuid; +Generates time-ordered UUIDs based on a high-resolution Unix Epoch timestamp +source (the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded) +(`read UUIDv7 spec `__). +It's recommended to use this version over UUIDv1 and UUIDv6 because it provides +better entropy (and a more strict chronological order of UUID generation):: - // $uuid is an instance of Symfony\Component\Uid\UuidV7 - $uuid = Uuid::v7(); + use Symfony\Component\Uid\Uuid; + + // $uuid is an instance of Symfony\Component\Uid\UuidV7 + $uuid = Uuid::v7(); **UUID v8** (custom) - Provides an RFC-compatible format for experimental or vendor-specific use cases - (`read UUIDv8 spec `__). - The only requirement is to set the variant and version bits of the UUID. The rest - of the UUID value is specific to each implementation and no format should be assumed:: - use Symfony\Component\Uid\Uuid; +Provides an RFC-compatible format for experimental or vendor-specific use cases +(`read UUIDv8 spec `__). +The only requirement is to set the variant and version bits of the UUID. The rest +of the UUID value is specific to each implementation and no format should be assumed:: + + use Symfony\Component\Uid\Uuid; - // $uuid is an instance of Symfony\Component\Uid\UuidV8 - $uuid = Uuid::v8(); + // $uuid is an instance of Symfony\Component\Uid\UuidV8 + $uuid = Uuid::v8(); If your UUID value is already generated in another format, use any of the following methods to create a ``Uuid`` object from it::