mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-13 15:46:53 +03:00
doc: update for Rfc4122\UuidV6
This commit is contained in:
Ben Ramsey
+2
-2
@@ -22,8 +22,8 @@ to replace just about any `builder`_, `codec`_, `converter`_, `generator`_,
|
||||
|
||||
Ordered-time Codec
|
||||
The ordered-time codec exists to rearrange the bytes of a version 1,
|
||||
time-based UUID so that the timestamp portion of the UUID is monotonically
|
||||
increasing. To learn more, see :ref:`customize.ordered-time-codec`.
|
||||
Gregorian time UUID so that the timestamp portion of the UUID is
|
||||
monotonically increasing. To learn more, see :ref:`customize.ordered-time-codec`.
|
||||
|
||||
Timestamp-first COMB Codec
|
||||
The timestamp-first COMB codec replaces part of a version 4, random UUID
|
||||
|
||||
@@ -6,8 +6,8 @@ Ordered-time Codec
|
||||
|
||||
.. hint::
|
||||
|
||||
:ref:`Version 6, ordered-time UUIDs <nonstandard.version6>` are a proposed
|
||||
new version of UUID that take the place of ordered time UUIDs.
|
||||
:ref:`Version 6, reordered time UUIDs <rfc4122.version6>` are a
|
||||
new version of UUID that take the place of ordered-time UUIDs.
|
||||
|
||||
UUIDs arrange their bytes according to the standard recommended by `RFC 4122`_.
|
||||
Unfortunately, this means the bytes aren't in an arrangement that supports
|
||||
@@ -15,9 +15,9 @@ sorting by creation time or an otherwise incrementing value. The Percona
|
||||
article, "`Storing UUID Values in MySQL`_," explains at length the problems this
|
||||
can cause. It also recommends a solution: the *ordered-time UUID*.
|
||||
|
||||
RFC 4122 version 1, time-based UUIDs rearrange the bytes of the time fields so
|
||||
that the lowest bytes appear first, the middle bytes are next, and the highest
|
||||
bytes come last. Logical sorting is not possible with this arrangement.
|
||||
RFC 4122 version 1, Gregorian time UUIDs rearrange the bytes of the time fields
|
||||
so that the lowest bytes appear first, the middle bytes are next, and the
|
||||
highest bytes come last. Logical sorting is not possible with this arrangement.
|
||||
|
||||
An ordered-time UUID is a version 1 UUID with the time fields arranged in
|
||||
logical order so that the UUIDs can be sorted by creation time. These UUIDs are
|
||||
|
||||
+3
-4
@@ -242,7 +242,7 @@ will become slower and slower.
|
||||
To minimize these problems, two solutions have been devised:
|
||||
|
||||
1. Timestamp first COMBs
|
||||
2. Ordered Time UUIDs
|
||||
2. Ordered-time UUIDs
|
||||
|
||||
:ref:`customize.timestamp-first-comb-codec` explains the first solution and how
|
||||
to use ramsey/uuid to implement it, while :ref:`customize.ordered-time-codec`
|
||||
@@ -250,8 +250,8 @@ explains how to use ramsey/uuid to implement the second solution.
|
||||
|
||||
.. hint::
|
||||
|
||||
:ref:`Version 6, ordered-time UUIDs <nonstandard.version6>` are a proposed
|
||||
new version of UUID that take the place of ordered time UUIDs.
|
||||
:ref:`Version 6, reordered time UUIDs <rfc4122.version6>` are a
|
||||
new version of UUID that take the place of ordered-time UUIDs.
|
||||
|
||||
|
||||
.. _ramsey/uuid-doctrine: https://github.com/ramsey/uuid-doctrine
|
||||
@@ -259,4 +259,3 @@ explains how to use ramsey/uuid to implement the second solution.
|
||||
.. _MariaDB: https://mariadb.org
|
||||
.. _PHP Data Objects (PDO): https://www.php.net/pdo
|
||||
.. _Storing UUID Values in MySQL: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/
|
||||
.. _Version 6, ordered-time UUIDs: nonstandard.version6
|
||||
|
||||
@@ -20,8 +20,8 @@ completely random and do not follow any rules.
|
||||
For these cases, ramsey/uuid provides a special functionality to handle these
|
||||
alternate, nonstandard forms.
|
||||
|
||||
Version 6: Ordered-time
|
||||
This is a proposed version of UUID that combines the features of a
|
||||
Version 6: Reordered Time
|
||||
This is a new version of UUID that combines the features of a
|
||||
:ref:`version 1 UUID <rfc4122.version1>` with a *monotonically increasing*
|
||||
UUID. For more details, see :ref:`nonstandard.version6`.
|
||||
|
||||
|
||||
+11
-203
@@ -1,209 +1,17 @@
|
||||
.. _nonstandard.version6:
|
||||
|
||||
=======================
|
||||
Version 6: Ordered-Time
|
||||
=======================
|
||||
=========================
|
||||
Version 6: Reordered Time
|
||||
=========================
|
||||
|
||||
.. admonition:: Experimental
|
||||
:class: warning
|
||||
.. attention::
|
||||
|
||||
Version 6, ordered-time UUIDs are an experimental feature based on an
|
||||
`Internet-Draft under review`_ at the IETF. While the basic layout is not
|
||||
expected to change, be aware that the draft is a moving target. If there
|
||||
are significant changes to the layout, ramsey/uuid will attempt to maintain
|
||||
backward compatibility but cannot guarantee it.
|
||||
This documentation has moved to :ref:`RFC 4122 UUIDs: Version 6: Reordered
|
||||
Time <rfc4122.version6>`.
|
||||
|
||||
Version 6 UUIDs solve `two problems that have long existed`_ with the use of
|
||||
:ref:`version 1 <rfc4122.version1>` UUIDs:
|
||||
Version 6 UUIDs have been promoted to the ``Rfc4122`` namespace. While still
|
||||
in draft form, the version 6 format is not expected to change in any way
|
||||
that breaks compatibility.
|
||||
|
||||
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, ordered-time UUID
|
||||
:name: nonstandard.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,
|
||||
ordered-time UUID
|
||||
:name: nonstandard.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\\Nonstandard\\UuidV6` API documentation to
|
||||
learn more about what you can do with a UuidV6 instance.
|
||||
|
||||
|
||||
.. _nonstandard.version6.nodes:
|
||||
|
||||
Custom and Random Nodes
|
||||
#######################
|
||||
|
||||
In the :ref:`example above <nonstandard.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`.
|
||||
|
||||
|
||||
.. _nonstandard.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.
|
||||
|
||||
|
||||
.. _nonstandard.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: nonstandard.version6.convert-version1-example
|
||||
|
||||
use Ramsey\Uuid\Nonstandard\UuidV6;
|
||||
use Ramsey\Uuid\Rfc4122\UuidV1;
|
||||
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: nonstandard.version6.convert-version6-example
|
||||
|
||||
use Ramsey\Uuid\Nonstandard\UuidV6;
|
||||
use Ramsey\Uuid\Uuid;
|
||||
|
||||
$uuid6 = Uuid::fromString('1ea60f83-960c-65d8-bc55-0242ac130003');
|
||||
|
||||
if ($uuid6 instanceof UuidV6) {
|
||||
$uuid1 = $uuid6->toUuidV1();
|
||||
}
|
||||
|
||||
|
||||
.. _nonstandard.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: nonstandard.version6.convert-ordered-time-example
|
||||
|
||||
use Ramsey\Uuid\Codec\OrderedTimeCodec;
|
||||
use Ramsey\Uuid\Nonstandard\UuidV6;
|
||||
use Ramsey\Uuid\Rfc4122\UuidV1;
|
||||
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);
|
||||
}
|
||||
|
||||
|
||||
.. _nonstandard.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:`nonstandard.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:`customize.timestamp-first-comb-codec`.
|
||||
|
||||
|
||||
.. _Internet-Draft under review: https://tools.ietf.org/html/draft-peabody-dispatch-new-uuid-format
|
||||
.. _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
|
||||
The :php:class:`Ramsey\\Uuid\\Nonstandard\\UuidV6` class is deprecated in
|
||||
favor of :php:class:`Ramsey\\Uuid\\Rfc4122\\UuidV6`.
|
||||
|
||||
+1
-1
@@ -96,7 +96,7 @@ library.
|
||||
* - :php:meth:`Uuid::uuid5() <Ramsey\\Uuid\\Uuid::uuid5>`
|
||||
- This generates a :ref:`rfc4122.version5` UUID.
|
||||
* - :php:meth:`Uuid::uuid6() <Ramsey\\Uuid\\Uuid::uuid6>`
|
||||
- This generates a :ref:`nonstandard.version6` UUID.
|
||||
- This generates a :ref:`rfc4122.version6` UUID.
|
||||
* - :php:meth:`Uuid::isValid() <Ramsey\\Uuid\\Uuid::isValid>`
|
||||
- Checks whether a string is a valid UUID.
|
||||
* - :php:meth:`Uuid::fromString() <Ramsey\\Uuid\\Uuid::fromString>`
|
||||
|
||||
+2
-1
@@ -17,11 +17,12 @@ Reference
|
||||
reference/rfc4122-uuidv3
|
||||
reference/rfc4122-uuidv4
|
||||
reference/rfc4122-uuidv5
|
||||
reference/nonstandard-uuidv6
|
||||
reference/rfc4122-uuidv6
|
||||
reference/guid-fields
|
||||
reference/guid-guid
|
||||
reference/nonstandard-fields
|
||||
reference/nonstandard-uuid
|
||||
reference/nonstandard-uuidv6
|
||||
reference/uuidfactoryinterface
|
||||
reference/types
|
||||
reference/exceptions
|
||||
|
||||
@@ -9,7 +9,7 @@ only the string standard representation of a UUID.
|
||||
|
||||
.. php:function:: Ramsey\\Uuid\\v1([$node[, $clockSeq]])
|
||||
|
||||
Generates a string standard representation of a version 1, time-based UUID.
|
||||
Generates a string standard representation of a version 1, Gregorian time UUID.
|
||||
|
||||
:param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
|
||||
:param int|null $clockSeq: An optional clock sequence to use
|
||||
@@ -54,7 +54,7 @@ only the string standard representation of a UUID.
|
||||
|
||||
.. php:function:: Ramsey\\Uuid\\v6([$node[, $clockSeq]])
|
||||
|
||||
Generates a string standard representation of a version 6, ordered-time UUID.
|
||||
Generates a string standard representation of a version 6, reordered time UUID.
|
||||
|
||||
:param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
|
||||
:param int|null $clockSeq: An optional clock sequence to use
|
||||
|
||||
@@ -8,13 +8,16 @@ Nonstandard\\UuidV6
|
||||
|
||||
.. php:class:: UuidV6
|
||||
|
||||
.. attention::
|
||||
|
||||
:php:class:`Ramsey\\Uuid\\Nonstandard\\UuidV6` is deprecated in favor of
|
||||
:php:class:`Ramsey\\Uuid\\Rfc4122\\UuidV6`. Please migrate any code
|
||||
using ``Nonstandard\UuidV6`` to ``Rfc4122\UuidV6``. The interface is
|
||||
otherwise identical.
|
||||
|
||||
Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
|
||||
|
||||
While in the Nonstandard sub-namespace, UuidV6 implements the same interface
|
||||
as the RFC 4122 UUIDs. This is because the definition for version 6 UUIDs is
|
||||
`currently in draft form`_, with the intent to update RFC 4122.
|
||||
|
||||
UuidV6 represents a :ref:`version 6, ordered-time UUID
|
||||
UuidV6 represents a :ref:`version 6, reordered time UUID
|
||||
<nonstandard.version6>`. In addition to providing the methods defined on the
|
||||
interface, this class additionally provides the following methods.
|
||||
|
||||
@@ -32,7 +35,4 @@ Nonstandard\\UuidV6
|
||||
|
||||
:param Ramsey\\Uuid\\Rfc4122\\UuidV1 $uuidV1: A version 1 UUID
|
||||
:returns: A version 6 UUID, converted from the given version 1 UUID
|
||||
:returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6
|
||||
|
||||
|
||||
.. _currently in draft form: https://tools.ietf.org/html/draft-peabody-dispatch-new-uuid-format-00
|
||||
:returntype: Ramsey\\Uuid\\Rfc4122\\UuidV6
|
||||
|
||||
@@ -10,7 +10,7 @@ Rfc4122\\UuidV1
|
||||
|
||||
Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
|
||||
|
||||
UuidV1 represents a :ref:`version 1, time-based UUID <rfc4122.version1>`.
|
||||
UuidV1 represents a :ref:`version 1, Gregorian time UUID <rfc4122.version1>`.
|
||||
In addition to providing the methods defined on the interface, this class
|
||||
additionally provides the following methods.
|
||||
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _reference.rfc4122.uuidv6:
|
||||
|
||||
===============
|
||||
Rfc4122\\UuidV6
|
||||
===============
|
||||
|
||||
.. php:namespace:: Ramsey\Uuid\Rfc4122
|
||||
|
||||
.. php:class:: UuidV6
|
||||
|
||||
Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
|
||||
|
||||
UuidV6 represents a :ref:`version 6, reordered time UUID
|
||||
<rfc4122.version6>`. In addition to providing the methods defined on the
|
||||
interface, this class additionally provides the following methods.
|
||||
|
||||
.. php:method:: getDateTime()
|
||||
|
||||
:returns: A date object representing the timestamp associated with the UUID
|
||||
:returntype: ``\DateTimeInterface``
|
||||
|
||||
.. php:method:: toUuidV1()
|
||||
|
||||
:returns: A version 1 UUID, converted from this version 6 UUID
|
||||
:returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1
|
||||
|
||||
.. php:staticmethod:: fromUuidV1()
|
||||
|
||||
:param Ramsey\\Uuid\\Rfc4122\\UuidV1 $uuidV1: A version 1 UUID
|
||||
:returns: A version 6 UUID, converted from the given version 1 UUID
|
||||
:returntype: Ramsey\\Uuid\\Rfc4122\\UuidV6
|
||||
@@ -32,9 +32,13 @@ the ramsey/uuid library.
|
||||
|
||||
:ref:`rfc4122.version5` UUID.
|
||||
|
||||
.. php:const:: UUID_TYPE_REORDERED_TIME
|
||||
|
||||
:ref:`rfc4122.version6` UUID.
|
||||
|
||||
.. php:const:: UUID_TYPE_PEABODY
|
||||
|
||||
:ref:`nonstandard.version6` UUID.
|
||||
*Deprecated.* Use :php:const:`Uuid::UUID_TYPE_REORDERED_TIME` instead.
|
||||
|
||||
.. php:const:: NAMESPACE_DNS
|
||||
|
||||
@@ -87,7 +91,7 @@ the ramsey/uuid library.
|
||||
|
||||
.. php:staticmethod:: uuid1([$node[, $clockSeq]])
|
||||
|
||||
Generates a version 1, time-based UUID. See :ref:`rfc4122.version1`.
|
||||
Generates a version 1, Gregorian time UUID. See :ref:`rfc4122.version1`.
|
||||
|
||||
:param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
|
||||
:param int|null $clockSeq: An optional clock sequence to use
|
||||
@@ -132,12 +136,12 @@ the ramsey/uuid library.
|
||||
|
||||
.. php:staticmethod:: uuid6([$node[, $clockSeq]])
|
||||
|
||||
Generates a version 6, ordered-time UUID. See :ref:`nonstandard.version6`.
|
||||
Generates a version 6, reordered time UUID. See :ref:`rfc4122.version6`.
|
||||
|
||||
:param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
|
||||
:param int|null $clockSeq: An optional clock sequence to use
|
||||
:returns: A version 6 UUID
|
||||
:returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6
|
||||
:returntype: Ramsey\\Uuid\\Rfc4122\\UuidV6
|
||||
|
||||
.. php:staticmethod:: fromString($uuid)
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ UuidFactoryInterface
|
||||
|
||||
.. php:method:: uuid1([$node[, $clockSeq]])
|
||||
|
||||
Generates a version 1, time-based UUID. See :ref:`rfc4122.version1`.
|
||||
Generates a version 1, Gregorian time UUID. See :ref:`rfc4122.version1`.
|
||||
|
||||
:param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
|
||||
:param int|null $clockSeq: An optional clock sequence to use
|
||||
@@ -61,12 +61,12 @@ UuidFactoryInterface
|
||||
|
||||
.. php:method:: uuid6([$node[, $clockSeq]])
|
||||
|
||||
Generates a version 6, ordered-time UUID. See :ref:`nonstandard.version6`.
|
||||
Generates a version 6, reordered time UUID. See :ref:`rfc4122.version6`.
|
||||
|
||||
:param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
|
||||
:param int|null $clockSeq: An optional clock sequence to use
|
||||
:returns: A version 6 UUID
|
||||
:returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6
|
||||
:returntype: Ramsey\\Uuid\\Rfc4122\\UuidV6
|
||||
|
||||
.. php:method:: fromString($uuid)
|
||||
|
||||
|
||||
+7
-1
@@ -13,13 +13,14 @@ RFC 4122 UUIDs
|
||||
rfc4122/version3
|
||||
rfc4122/version4
|
||||
rfc4122/version5
|
||||
rfc4122/version6
|
||||
|
||||
`RFC 4122`_ defines five versions of UUID. Each version has different generation
|
||||
algorithms and properties. Which one you choose to use depends on your use-case.
|
||||
You can find out more about their applications on the specific page for that
|
||||
version.
|
||||
|
||||
Version 1: Time-based
|
||||
Version 1: Gregorian Time
|
||||
This version of UUID combines a timestamp, node value (in the form of a MAC
|
||||
address from the local computer's network interface), and a clock sequence
|
||||
to ensure uniqueness. For more details, see :doc:`rfc4122/version1`.
|
||||
@@ -44,5 +45,10 @@ Version 5: Named-based (SHA-1)
|
||||
deterministic UUID. The hashing algorithm used is SHA-1. For more details,
|
||||
see :doc:`rfc4122/version5`.
|
||||
|
||||
Version 6: Reordered Time
|
||||
This version of UUID combines the features of a
|
||||
:ref:`version 1 UUID <rfc4122.version1>` with a *monotonically increasing*
|
||||
UUID. For more details, see :ref:`rfc4122.version6`.
|
||||
|
||||
|
||||
.. _RFC 4122: https://tools.ietf.org/html/rfc4122
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
.. _rfc4122.version1:
|
||||
|
||||
=====================
|
||||
Version 1: Time-based
|
||||
=====================
|
||||
=========================
|
||||
Version 1: Gregorian Time
|
||||
=========================
|
||||
|
||||
A version 1 UUID uses the current time, along with the MAC address (or *node*)
|
||||
for a network interface on the local machine. This serves two purposes:
|
||||
@@ -27,7 +27,7 @@ is running on, using this value as the node. If it cannot find a MAC address, it
|
||||
will generate a random node.
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Generate a version 1, time-based UUID
|
||||
:caption: Generate a version 1, Gregorian time UUID
|
||||
:name: rfc4122.version1.example
|
||||
|
||||
use Ramsey\Uuid\Uuid;
|
||||
@@ -59,7 +59,7 @@ sequence.
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Provide custom node and clock sequence to create a version 1,
|
||||
time-based UUID
|
||||
Gregorian time UUID
|
||||
:name: rfc4122.version1.custom-example
|
||||
|
||||
use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
|
||||
@@ -123,7 +123,7 @@ generate a random node value, and like the StaticNodeProvider, it also sets the
|
||||
unicast/multicast bit for you.
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Provide a random node value to create a version 1, time-based UUID
|
||||
:caption: Provide a random node value to create a version 1, Gregorian time UUID
|
||||
:name: rfc4122.version1.random-example
|
||||
|
||||
use Ramsey\Uuid\Provider\Node\RandomNodeProvider;
|
||||
|
||||
@@ -83,8 +83,8 @@ The best way to do this is to generate a :ref:`version 1 <rfc4122.version1>` or
|
||||
|
||||
printf("My namespace UUID is %s\n", $uuid->toString());
|
||||
|
||||
This will generate a version 1, time-based UUID, which we'll store to a constant
|
||||
so we can reuse it as our own custom namespace.
|
||||
This will generate a version 1, Gregorian time UUID, which we'll store to a
|
||||
constant so we can reuse it as our own custom namespace.
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Use a custom namespace to create version 5, name-based UUIDs
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
.. _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.
|
||||
|
||||
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:`customize.timestamp-first-comb-codec`.
|
||||
|
||||
|
||||
.. _Internet-Draft under review: https://datatracker.ietf.org/doc/draft-peabody-dispatch-new-uuid-format/
|
||||
.. _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
|
||||
Reference in New Issue
Block a user