Ordered-time Codec

Attention

Version 6, reordered time UUIDs 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.

Use the ordered-time codec to generate a version 1 UUID
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:

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 Storing As 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.

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