.. index::
   single: UID
   single: Components; UID

The UID Component
=================

    The UID component provides utilities to work with `unique identifiers`_ (UIDs)
    such as UUIDs and ULIDs.

.. versionadded:: 5.1

    The UID component was introduced in Symfony 5.1 as an
    :doc:`experimental feature </contributing/code/experimental>`.

Installation
------------

.. code-block:: terminal

    $ composer require symfony/uid

.. include:: /components/require_autoload.rst.inc

UUIDs
-----

`UUIDs`_ (*universally unique identifiers*) are one of the most popular UIDs in
the software industry. UUIDs are 128-bit numbers usually represented as five
groups of hexadecimal characters: ``xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx``
(the ``M`` digit is the UUID version and the ``N`` digit is the UUID variant).

Generating UUIDs
~~~~~~~~~~~~~~~~

Use the named constructors of the ``Uuid`` class or any of the specific classes
to create each type of UUID::

    use Symfony\Component\Uid\Uuid;

    // UUID type 1 generates the UUID using the MAC address of your device and a timestamp.
    // Both are obtained automatically, so you don't have to pass any constructor argument.
    $uuid = Uuid::v1(); // $uuid is an instance of Symfony\Component\Uid\UuidV1

    // UUID type 4 generates a random UUID, so you don't have to pass any constructor argument.
    $uuid = Uuid::v4(); // $uuid is an instance of Symfony\Component\Uid\UuidV4

    // UUID type 3 and 5 generate a UUID hashing the given namespace and name. Type 3 uses
    // MD5 hashes and Type 5 uses SHA-1. The namespace is another UUID (e.g. a Type 4 UUID)
    // and the name is an arbitrary string (e.g. a product name; if it's unique).
    $namespace = Uuid::v4();
    $name = $product->getUniqueName();

    $uuid = Uuid::v3($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV3
    $uuid = Uuid::v5($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV5

    // UUID type 6 is not part of the UUID standard. It's lexicographically sortable
    // (like ULIDs) and contains a 60-bit timestamp and 63 extra unique bits.
    // It's defined in http://gh.peabody.io/uuidv6/
    $uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6

If your UUID is generated by another system, use the ``fromString()`` method to
create an object and make use of the utilities available for Symfony UUIDs::

    // this value is generated somewhere else
    $uuidValue = 'd9e7a184-5d5b-11ea-a62a-3499710062d0';
    $uuid = Uuid::fromString($uuidValue);

If your UUIDs are generated in binary format, use the ``fromBinary()`` method
to create the objects for them::

    $uuid = Uuid::fromBinary($uuidBinaryContents);

Converting UUIDs
~~~~~~~~~~~~~~~~

Use these methods to transform the UUID object into different bases::

    $uuid = new Uuid::fromString('d9e7a184-5d5b-11ea-a62a-3499710062d0');

    $uuid->toBinary();  // string(16) "..." (binary contents can't be printed)
    $uuid->toBase32();  // string(26) "6SWYGR8QAV27NACAHMK5RG0RPG"
    $uuid->toBase58();  // string(22) "TuetYWNHhmuSQ3xPoVLv9M"
    $uuid->toRfc4122(); // string(36) "d9e7a184-5d5b-11ea-a62a-3499710062d0"

Working with UUIDs
~~~~~~~~~~~~~~~~~~

UUID objects created with the ``Uuid`` class can use the following methods
(which are equivalent to the ``uuid_*()`` method of the PHP extension)::

    use Symfony\Component\Uid\NilUuid;
    use Symfony\Component\Uid\Uuid;

    // checking if the UUID is null (note that the class is called
    // NilUuid instead of NullUuid to follow the UUID standard notation)
    $uuid = Uuid::v4();
    $uuid instanceof NilUuid; // false

    // checking the type of UUID
    use Symfony\Component\Uid\UuidV4;
    $uuid = Uuid::v4();
    $uuid instanceof UuidV4; // true

    // getting the UUID time (it's only available in certain UUID types)
    $uuid = Uuid::v1();
    $uuid->getTime();  // e.g. float(1584111384.2613)

    // comparing UUIDs and checking for equality
    $uuid1 = Uuid::v1();
    $uuid4 = Uuid::v4();
    $uuid1->equals($uuid4); // false

    // this method returns:
    //   * int(0) if $uuid1 and $uuid4 are equal
    //   * int > 0 if $uuid1 is greater than $uuid4
    //   * int < 0 if $uuid1 is less than $uuid4
    $uuid1->compare($uuid4); // e.g. int(4)

ULIDs
-----

`ULIDs`_ (*Universally Unique Lexicographically Sortable Identifier*) are 128-bit
numbers usually represented as a 26-character string: ``TTTTTTTTTTRRRRRRRRRRRRRRRR``
(where ``T`` represents a timestamp and ``R`` represents the random bits).

ULIDs are an alternative to UUIDs when using those is impractical. They provide
128-bit compatibility with UUID, they are lexicographically sortable and they
are encoded as 26-character strings (vs 36-character UUIDs).

Generating ULIDs
~~~~~~~~~~~~~~~~

Instantiate the ``Ulid`` class to generate a random ULID value::

    use Symfony\Component\Uid\Ulid;

    $ulid = new Ulid();  // e.g. 01AN4Z07BY79KA1307SR9X4MV3

If your ULID is generated by another system, use the ``fromString()`` method to
create an object and make use of the utilities available for Symfony ULIDs::

    // this value is generated somewhere else
    $ulidValue = '01E439TP9XJZ9RPFH3T1PYBCR8';
    $ulid = Ulid::fromString($ulidValue);

If your ULIDs are generated in binary format, use the ``fromBinary()`` method
to create the objects for them::

    $ulid = Ulid::fromBinary($ulidBinaryContents);

Converting ULIDs
~~~~~~~~~~~~~~~~

Use these methods to transform the ULID object into different bases::

    $ulid = Ulid::fromString('01E439TP9XJZ9RPFH3T1PYBCR8');

    $ulid->toBinary();  // string(16) "..." (binary contents can't be printed)
    $ulid->toBase32();  // string(26) "01E439TP9XJZ9RPFH3T1PYBCR8"
    $ulid->toBase58();  // string(22) "1BKocMc5BnrVcuq2ti4Eqm"
    $ulid->toRfc4122(); // string(36) "0171069d-593d-97d3-8b3e-23d06de5b308"

Working with ULIDs
~~~~~~~~~~~~~~~~~~

ULID objects created with the ``Ulid`` class can use the following methods::

    use Symfony\Component\Uid\Ulid;

    $ulid1 = new Ulid();
    $ulid2 = new Ulid();

    // checking if a given value is valid as ULID
    $isValid = Ulid::isValid($ulidValue); // true or false

    // getting the ULID time
    $ulid1->getTime(); // e.g. float(1584111384.2613)

    // comparing ULIDs and checking for equality
    $ulid1->equals($ulid2); // false
    // this method returns $ulid1 <=> $ulid2
    $ulid1->compare($ulid2); // e.g. int(-1)

.. _`unique identifiers`: https://en.wikipedia.org/wiki/UID
.. _`UUIDs`: https://en.wikipedia.org/wiki/Universally_unique_identifier
.. _`ULIDs`: https://github.com/ulid/spec