diff --git a/docs/customize.rst b/docs/customize.rst index 1dc0c19..a67fbc0 100644 --- a/docs/customize.rst +++ b/docs/customize.rst @@ -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 diff --git a/docs/customize/ordered-time-codec.rst b/docs/customize/ordered-time-codec.rst index bad166f..b71a7eb 100644 --- a/docs/customize/ordered-time-codec.rst +++ b/docs/customize/ordered-time-codec.rst @@ -6,8 +6,8 @@ Ordered-time Codec .. hint:: - :ref:`Version 6, ordered-time UUIDs ` are a proposed - new version of UUID that take the place of ordered time UUIDs. + :ref:`Version 6, reordered time UUIDs ` 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 diff --git a/docs/database.rst b/docs/database.rst index 3607dfd..9459862 100644 --- a/docs/database.rst +++ b/docs/database.rst @@ -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 ` are a proposed - new version of UUID that take the place of ordered time UUIDs. + :ref:`Version 6, reordered time UUIDs ` 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 diff --git a/docs/nonstandard.rst b/docs/nonstandard.rst index b35002e..83ed900 100644 --- a/docs/nonstandard.rst +++ b/docs/nonstandard.rst @@ -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 ` with a *monotonically increasing* UUID. For more details, see :ref:`nonstandard.version6`. diff --git a/docs/nonstandard/version6.rst b/docs/nonstandard/version6.rst index aca5443..c45482e 100644 --- a/docs/nonstandard/version6.rst +++ b/docs/nonstandard/version6.rst @@ -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 `. -Version 6 UUIDs solve `two problems that have long existed`_ with the use of -:ref:`version 1 ` 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 `. 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 `, 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 ` 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 `, 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`. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 6cd310c..871fd1c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -96,7 +96,7 @@ library. * - :php:meth:`Uuid::uuid5() ` - This generates a :ref:`rfc4122.version5` UUID. * - :php:meth:`Uuid::uuid6() ` - - This generates a :ref:`nonstandard.version6` UUID. + - This generates a :ref:`rfc4122.version6` UUID. * - :php:meth:`Uuid::isValid() ` - Checks whether a string is a valid UUID. * - :php:meth:`Uuid::fromString() ` diff --git a/docs/reference.rst b/docs/reference.rst index 00e27b6..b04e1bd 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -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 diff --git a/docs/reference/helper.rst b/docs/reference/helper.rst index 9c410e1..6ab3aff 100644 --- a/docs/reference/helper.rst +++ b/docs/reference/helper.rst @@ -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 diff --git a/docs/reference/nonstandard-uuidv6.rst b/docs/reference/nonstandard-uuidv6.rst index cc77067..9ca743e 100644 --- a/docs/reference/nonstandard-uuidv6.rst +++ b/docs/reference/nonstandard-uuidv6.rst @@ -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 `. 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 diff --git a/docs/reference/rfc4122-uuidv1.rst b/docs/reference/rfc4122-uuidv1.rst index c28c27c..985fd5b 100644 --- a/docs/reference/rfc4122-uuidv1.rst +++ b/docs/reference/rfc4122-uuidv1.rst @@ -10,7 +10,7 @@ Rfc4122\\UuidV1 Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`. - UuidV1 represents a :ref:`version 1, time-based UUID `. + UuidV1 represents a :ref:`version 1, Gregorian time UUID `. In addition to providing the methods defined on the interface, this class additionally provides the following methods. diff --git a/docs/reference/rfc4122-uuidv6.rst b/docs/reference/rfc4122-uuidv6.rst new file mode 100644 index 0000000..0b15f7e --- /dev/null +++ b/docs/reference/rfc4122-uuidv6.rst @@ -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 + `. 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 diff --git a/docs/reference/uuid.rst b/docs/reference/uuid.rst index f3c2f32..447dbad 100644 --- a/docs/reference/uuid.rst +++ b/docs/reference/uuid.rst @@ -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) diff --git a/docs/reference/uuidfactoryinterface.rst b/docs/reference/uuidfactoryinterface.rst index 842f71d..c68a61d 100644 --- a/docs/reference/uuidfactoryinterface.rst +++ b/docs/reference/uuidfactoryinterface.rst @@ -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) diff --git a/docs/rfc4122.rst b/docs/rfc4122.rst index ec74b59..d6c19d6 100644 --- a/docs/rfc4122.rst +++ b/docs/rfc4122.rst @@ -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 ` with a *monotonically increasing* + UUID. For more details, see :ref:`rfc4122.version6`. + .. _RFC 4122: https://tools.ietf.org/html/rfc4122 diff --git a/docs/rfc4122/version1.rst b/docs/rfc4122/version1.rst index e0bf719..8ac3147 100644 --- a/docs/rfc4122/version1.rst +++ b/docs/rfc4122/version1.rst @@ -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; diff --git a/docs/rfc4122/version5.rst b/docs/rfc4122/version5.rst index 86f8ba4..7af3158 100644 --- a/docs/rfc4122/version5.rst +++ b/docs/rfc4122/version5.rst @@ -83,8 +83,8 @@ The best way to do this is to generate a :ref:`version 1 ` 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 diff --git a/docs/rfc4122/version6.rst b/docs/rfc4122/version6.rst new file mode 100644 index 0000000..49e3ccf --- /dev/null +++ b/docs/rfc4122/version6.rst @@ -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 ` 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 `. 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 `, 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 ` 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 `, 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