mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-14 15:56:48 +03:00
Ben Ramsey
65 lines
2.7 KiB
ReStructuredText
65 lines
2.7 KiB
ReStructuredText
.. _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
|