.. _customize.timestamp-first-comb-codec:

========================== Timestamp-first COMB Codec

.. attention::

The :php:class:`Ramsey\\Uuid\\Codec\\TimestampFirstCombCodec` class is deprecated. Please migrate to
:ref:`version 7, Unix Epoch time UUIDs <rfc4122.version7>`.

:ref:Version 4, random UUIDs <rfc4122.version4> are doubly problematic when it comes to sorting and storing to databases (see :ref:database.order), since their values are random, and there is no timestamp associated with them that may be rearranged, like with the :ref:ordered-time codec <customize.ordered-time-codec>. In 2002, Jimmy Nilsson recognized this problem with random UUIDs and proposed a solution he called "COMBs" (see "The Cost of GUIDs as Primary Keys_").

So-called because they combine random bytes with a timestamp, the timestamp-first COMB codec replaces the first 48 bits of a version 4, random UUID with a Unix timestamp and microseconds, creating an identifier that 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 timestamp-first COMB codec to generate a version 4 UUID :name: customize.timestamp-first-comb-codec-example

use Ramsey\Uuid\Codec\TimestampFirstCombCodec;
use Ramsey\Uuid\Generator\CombGenerator;
use Ramsey\Uuid\UuidFactory;

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

$factory->setCodec($codec);

$factory->setRandomGenerator(new CombGenerator(
    $factory->getRandomGenerator(),
    $factory->getNumberConverter()
));

$timestampFirstComb = $factory->uuid4();

printf(
    "UUID: %s\nVersion: %d\nBytes: %s\n",
    $timestampFirstComb->toString(),
    $timestampFirstComb->getFields()->getVersion(),
    bin2hex($timestampFirstComb->getBytes())
);

This will use the timestamp-first COMB codec to generate a version 4 UUID with the timestamp replacing the first 48 bits and will print out details about the UUID similar to these:

.. code-block:: text

UUID: 9009ebcc-cd99-4b5f-90cf-9155607d2de9
Version: 4
Bytes: 9009ebcccd994b5f90cf9155607d2de9

Note that the bytes are in the same order as the string representation. Unlike the :ref:ordered-time codec <customize.ordered-time-codec>, the timestamp-first COMB codec affects both the string representation and the byte representation. This means either the string UUID or the bytes may be stored to a datastore and sorted. To learn more, see :ref:database.

.. _The Cost of GUIDs as Primary Keys: https://web.archive.org/web/20240118030355/https://www.informit.com/articles/printerfriendly/25862