mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-13 15:46:53 +03:00
Ben Ramsey
87 lines
3.2 KiB
ReStructuredText
87 lines
3.2 KiB
ReStructuredText
.. _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/
|