mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-14 15:56:48 +03:00
Ben Ramsey
69 lines
2.4 KiB
ReStructuredText
69 lines
2.4 KiB
ReStructuredText
.. _rfc4122.version3:
|
|
|
|
===========================
|
|
Version 3: Name-based (MD5)
|
|
===========================
|
|
|
|
.. attention::
|
|
|
|
`RFC 4122`_ states, "If backward compatibility is not an issue, SHA-1 is
|
|
preferred." As a result, the use of :ref:`version 5 UUIDs
|
|
<rfc4122.version5>` is preferred over version 3 UUIDs, unless you have a
|
|
specific use-case for version 3 UUIDs.
|
|
|
|
.. note::
|
|
|
|
To learn about name-based UUIDs, read the section :ref:`rfc4122.version5`.
|
|
Version 3 UUIDs behave exactly the same as :ref:`version 5 UUIDs
|
|
<rfc4122.version5>`. The only difference is the hashing algorithm used to
|
|
generate the UUID.
|
|
|
|
Version 3 UUIDs use `MD5`_ as the hashing algorithm for combining
|
|
the namespace and the name.
|
|
|
|
Due to the use of a different hashing algorithm, version 3 UUIDs generated with
|
|
any given namespace and name will differ from version 5 UUIDs generated using
|
|
the same namespace and name.
|
|
|
|
As an example, let's take a look at generating a version 3 UUID using the same
|
|
namespace and name used in ":ref:`rfc4122.version5.url-example`."
|
|
|
|
.. code-block:: php
|
|
:caption: Generate a version 3, name-based UUID for a URL
|
|
:name: rfc4122.version3.url-example
|
|
|
|
use Ramsey\Uuid\Uuid;
|
|
|
|
$uuid = Uuid::uuid3(Uuid::NAMESPACE_URL, 'https://www.php.net');
|
|
|
|
Even though the namespace and name are the same, the version 3 UUID generated
|
|
will always be ``3f703955-aaba-3e70-a3cb-baff6aa3b28f``.
|
|
|
|
Likewise, we can use the custom namespace we created in
|
|
":ref:`rfc4122.version5.create-namespace`" to generate a version 3 UUID, but the
|
|
result will be different from the version 5 UUID with the same custom namespace
|
|
and name.
|
|
|
|
.. code-block:: php
|
|
:caption: Use a custom namespace to create version 3, name-based UUIDs
|
|
:name: rfc4122.version3.custom-example
|
|
|
|
use Ramsey\Uuid\Uuid;
|
|
|
|
const WIDGET_NAMESPACE = '4bdbe8ec-5cb5-11ea-bc55-0242ac130003';
|
|
|
|
$uuid = Uuid::uuid3(WIDGET_NAMESPACE, 'widget/1234567890');
|
|
|
|
With this custom namespace, the version 3 UUID for the name "widget/1234567890"
|
|
will always be ``53564aa3-4154-3ca5-ac90-dba59dc7d3cb``.
|
|
|
|
.. tip::
|
|
|
|
Version 3 UUIDs generated in ramsey/uuid are instances of UuidV3. Check out
|
|
the :php:class:`Ramsey\\Uuid\\Rfc4122\\UuidV3` API documentation to learn
|
|
more about what you can do with a UuidV3 instance.
|
|
|
|
|
|
.. _RFC 4122: https://tools.ietf.org/html/rfc4122
|
|
.. _MD5: https://en.wikipedia.org/wiki/MD5
|