mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-14 15:56:48 +03:00
Ben Ramsey
214 lines
6.7 KiB
ReStructuredText
214 lines
6.7 KiB
ReStructuredText
.. _rfc4122.version6:
|
|
|
|
=========================
|
|
Version 6: Reordered Time
|
|
=========================
|
|
|
|
.. note::
|
|
|
|
Version 6, reordered time UUIDs are a new format of UUID, proposed in an
|
|
`Internet-Draft under review`_ at the IETF. While the draft is still going
|
|
through the IETF process, the version 6 format is not expected to change
|
|
in any way that breaks compatibility.
|
|
|
|
.. attention::
|
|
|
|
If you need a time-based UUID, and you don't need the other features
|
|
included in version 6 UUIDs, we recommend using
|
|
:ref:`version 7 UUIDs <rfc4122.version7>`.
|
|
|
|
Version 6 UUIDs solve `two problems that have long existed`_ with the use of
|
|
:ref:`version 1 <rfc4122.version1>` UUIDs:
|
|
|
|
1. Scattered database records
|
|
2. Inability to sort by an identifier in a meaningful way (i.e., insert order)
|
|
|
|
To overcome these issues, we need the ability to generate UUIDs that are
|
|
*monotonically increasing* while still providing all the benefits of version
|
|
1 UUIDs.
|
|
|
|
Version 6 UUIDs do this by storing the time in standard byte order, instead of
|
|
breaking it up and rearranging the time bytes, according to the `RFC 4122`_
|
|
definition. All other fields remain the same, and the version maintains its
|
|
position, according to RFC 4122.
|
|
|
|
In all other ways, version 6 UUIDs function like version 1 UUIDs.
|
|
|
|
.. tip::
|
|
|
|
Prior to version 4.0.0, ramsey/uuid provided a solution for this with the
|
|
:ref:`ordered-time codec <customize.ordered-time-codec>`. Use of the
|
|
ordered-time codec is still valid and acceptable. However, you may replace
|
|
UUIDs generated using the ordered-time codec with version 6 UUIDs. Keep
|
|
reading to find out how.
|
|
|
|
.. code-block:: php
|
|
:caption: Generate a version 6, reordered time UUID
|
|
:name: rfc4122.version6.example
|
|
|
|
use Ramsey\Uuid\Uuid;
|
|
|
|
$uuid = Uuid::uuid6();
|
|
|
|
printf(
|
|
"UUID: %s\nVersion: %d\nDate: %s\nNode: %s\n",
|
|
$uuid->toString(),
|
|
$uuid->getFields()->getVersion(),
|
|
$uuid->getDateTime()->format('r'),
|
|
$uuid->getFields()->getNode()->toString()
|
|
);
|
|
|
|
This will generate a version 6 UUID and print out its string representation, the
|
|
time the UUID was created, and the node used to create the UUID.
|
|
|
|
It will look something like this:
|
|
|
|
.. code-block:: text
|
|
|
|
UUID: 1ea60f56-b67b-61fc-829a-0242ac130003
|
|
Version: 6
|
|
Date: Sun, 08 Mar 2020 04:29:37 +0000
|
|
Node: 0242ac130003
|
|
|
|
You may provide custom values for version 6 UUIDs, including node and clock
|
|
sequence.
|
|
|
|
.. code-block:: php
|
|
:caption: Provide custom node and clock sequence to create a version 6,
|
|
reordered time UUID
|
|
:name: rfc4122.version6.custom-example
|
|
|
|
use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
|
|
use Ramsey\Uuid\Type\Hexadecimal;
|
|
use Ramsey\Uuid\Uuid;
|
|
|
|
$nodeProvider = new StaticNodeProvider(new Hexadecimal('121212121212'));
|
|
$clockSequence = 16383;
|
|
|
|
$uuid = Uuid::uuid6($nodeProvider->getNode(), $clockSequence);
|
|
|
|
.. tip::
|
|
|
|
Version 6 UUIDs generated in ramsey/uuid are instances of UuidV6. Check out
|
|
the :php:class:`Ramsey\\Uuid\\Rfc4122\\UuidV6` API documentation to
|
|
learn more about what you can do with a UuidV6 instance.
|
|
|
|
|
|
.. _rfc4122.version6.nodes:
|
|
|
|
Custom and Random Nodes
|
|
#######################
|
|
|
|
In the :ref:`example above <rfc4122.version6.custom-example>`, we provided a
|
|
custom node when generating a version 6 UUID. You may also generate random
|
|
node values.
|
|
|
|
To learn more, see the :ref:`rfc4122.version1.custom` and
|
|
:ref:`rfc4122.version1.random` sections under :ref:`rfc4122.version1`.
|
|
|
|
|
|
.. _rfc4122.version6.clock:
|
|
|
|
Clock Sequence
|
|
##############
|
|
|
|
In a version 6 UUID, the clock sequence serves the same purpose as in a version
|
|
1 UUID. See :ref:`rfc4122.version1.clock` to learn more.
|
|
|
|
|
|
.. _rfc4122.version6.version1-conversion:
|
|
|
|
Version 1-to-6 Conversion
|
|
#########################
|
|
|
|
It is possible to convert back-and-forth between version 6 and version 1 UUIDs.
|
|
|
|
.. code-block:: php
|
|
:caption: Convert a version 1 UUID to a version 6 UUID
|
|
:name: rfc4122.version6.convert-version1-example
|
|
|
|
use Ramsey\Uuid\Rfc4122\UuidV1;
|
|
use Ramsey\Uuid\Rfc4122\UuidV6;
|
|
use Ramsey\Uuid\Uuid;
|
|
|
|
$uuid1 = Uuid::fromString('3960c5d8-60f8-11ea-bc55-0242ac130003');
|
|
|
|
if ($uuid1 instanceof UuidV1) {
|
|
$uuid6 = UuidV6::fromUuidV1($uuid1);
|
|
}
|
|
|
|
.. code-block:: php
|
|
:caption: Convert a version 6 UUID to a version 1 UUID
|
|
:name: rfc4122.version6.convert-version6-example
|
|
|
|
use Ramsey\Uuid\Rfc4122\UuidV6;
|
|
use Ramsey\Uuid\Uuid;
|
|
|
|
$uuid6 = Uuid::fromString('1ea60f83-960c-65d8-bc55-0242ac130003');
|
|
|
|
if ($uuid6 instanceof UuidV6) {
|
|
$uuid1 = $uuid6->toUuidV1();
|
|
}
|
|
|
|
|
|
.. _rfc4122.version6.ordered-time-conversion:
|
|
|
|
Ordered-time to Version 6 Conversion
|
|
####################################
|
|
|
|
You may convert UUIDs previously generated and stored using the
|
|
:ref:`ordered-time codec <customize.ordered-time-codec>` into version 6 UUIDs.
|
|
|
|
.. caution::
|
|
|
|
If you perform this conversion, the bytes and string representation of your
|
|
UUIDs will change. This will break any software that expects your
|
|
identifiers to be fixed.
|
|
|
|
.. code-block:: php
|
|
:caption: Convert an ordered-time codec encoded UUID to a version 6 UUID
|
|
:name: rfc4122.version6.convert-ordered-time-example
|
|
|
|
use Ramsey\Uuid\Codec\OrderedTimeCodec;
|
|
use Ramsey\Uuid\Rfc4122\UuidV1;
|
|
use Ramsey\Uuid\Rfc4122\UuidV6;
|
|
use Ramsey\Uuid\UuidFactory;
|
|
|
|
// The bytes of a version 1 UUID previously stored in some datastore
|
|
// after encoding to bytes with the OrderedTimeCodec.
|
|
$bytes = hex2bin('11ea60faf17c8af6ad23acde48001122');
|
|
|
|
$factory = new UuidFactory();
|
|
$codec = new OrderedTimeCodec($factory->getUuidBuilder());
|
|
|
|
$factory->setCodec($codec);
|
|
|
|
$orderedTimeUuid = $factory->fromBytes($bytes);
|
|
|
|
if ($orderedTimeUuid instanceof UuidV1) {
|
|
$uuid6 = UuidV6::fromUuidV1($orderedTimeUuid);
|
|
}
|
|
|
|
|
|
.. _rfc4122.version6.privacy:
|
|
|
|
Privacy Concerns
|
|
################
|
|
|
|
Like :ref:`version 1 UUIDs <rfc4122.version1>`, version 6 UUIDs use a MAC
|
|
address from a local hardware network interface. This means it is possible to
|
|
uniquely identify the machine on which a version 6 UUID was created.
|
|
|
|
If the value provided by the timestamp of a version 6 UUID is important to you,
|
|
but you do not wish to expose the interface address of any of your local
|
|
machines, see :ref:`rfc4122.version6.nodes`.
|
|
|
|
If you do not need an identifier with a node value embedded in it, but you still
|
|
need the benefit of a monotonically increasing unique identifier, see
|
|
:ref:`rfc4122.version7`.
|
|
|
|
|
|
.. _Internet-Draft under review: https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.6
|
|
.. _two problems that have long existed: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/
|
|
.. _RFC 4122: https://tools.ietf.org/html/rfc4122
|