NN2024010801/vendor/ramsey/uuid/docs/customize/ordered-time-codec.rst

.. _customize.ordered-time-codec:

==================
Ordered-time Codec
==================

.. attention::

    :ref:`Version 6, reordered time UUIDs <rfc4122.version6>` are a new version
    of UUID that eliminate the need for the ordered-time codec. If you aren't
    currently using the ordered-time codec, and you need time-based, sortable
    UUIDs, consider using version 6 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
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, 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
*monotonically increasing*, each one coming after the previously-created one, in
a proper sort order.

.. code-block:: php
    :caption: Use the ordered-time codec to generate a version 1 UUID
    :name: customize.ordered-time-codec-example

    use Ramsey\Uuid\Codec\OrderedTimeCodec;
    use Ramsey\Uuid\UuidFactory;

    $factory = new UuidFactory();
    $codec = new OrderedTimeCodec($factory->getUuidBuilder());

    $factory->setCodec($codec);

    $orderedTimeUuid = $factory->uuid1();

    printf(
        "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\nBytes: %s\n",
        $orderedTimeUuid->toString(),
        $orderedTimeUuid->getFields()->getVersion(),
        $orderedTimeUuid->getDateTime()->format('r'),
        $orderedTimeUuid->getFields()->getNode()->toString(),
        bin2hex($orderedTimeUuid->getBytes())
    );

This will use the ordered-time codec to generate a version 1 UUID and will print
out details about the UUID similar to these:

.. code-block:: text

    UUID: 593200aa-61ae-11ea-bbf2-0242ac130003
    Version: 1
    Date: Mon, 09 Mar 2020 02:33:23 +0000
    Node: 0242ac130003
    Bytes: 11ea61ae593200aabbf20242ac130003

.. attention::

    Only the byte representation is rearranged. The string representation
    follows the format of a standard version 1 UUID. This means only the byte
    representation of an ordered-time codec encoded UUID may be used for
    sorting, such as with database results.

    To store the byte representation to a database field, see
    :ref:`database.bytes`.

.. hint::

    If you use this codec and store the bytes of the UUID to the database, as
    recommended above, you will need to use this codec to decode the bytes, as
    well. Otherwise, the UUID string value will be incorrect.

    .. code-block:: php

        // Using a factory configured with the OrderedTimeCodec, as shown above.
        $orderedTimeUuid = $factory->fromBytes($bytes);


.. _RFC 4122: https://tools.ietf.org/html/rfc4122
.. _Storing UUID Values in MySQL: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/