[UID] Aded the docs for the component

Author: javiereguiluz

components/uid.rst

@@ -0,0 +1,157 @@
+.. 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
+
+Usage
+-----
+
+This component provides different classes to generate each type of UID. The
+following sections explain each of them.
+
+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 any of the following named constructors depending on your needs::
+
+    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 type 4 generates a random UUID, so you don't have to pass any constructor argument.
+    $uuid = Uuid::v4();
+
+    // 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 = Uuid::v5($namespace, $name);
+
+If your UUID is generated by another system, use the regular constructor of the
+``Uuid`` class 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 = new Uuid($uuidValue);
+
+If your UUIDs are generated in binary format, use the ``fromBinary()`` method
+to create the objects for them::
+
+    $uuid = Uuid::fromBinary($uuidBinaryContents);
+
+    // the opposite method is also available
+    $uuidAsBinary = $uuid->toBinary();
+
+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\Uuid;
+
+    $uuid4 = Uuid::v4();
+
+    $uuid4->isNull(); // false
+
+    // the Uuid class defines public constants for all versions and variants
+    // (e.g. Uuid::TYPE_1, Uuid::TYPE_3, Uuid::VARIANT_NCS, etc.)
+    $uuid4->getType();    // int(4)
+    $uuid4->getVariant(); // int(1)
+
+    // the time and MAC address is only available in certain UUID types
+    $uuid1 = Uuid::v1();
+    $uuid1->getTime();  // e.g. float(1584111384.2613)
+    $uuid1->getMac();   // e.g. string(12) "27cb420bea01"
+
+    $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, pass its value to the constructor:
+
+    $ulidValue = 'X7NR9KZ0A4Y9BV1431S70A03M7';
+    $ulid = new Ulid($ulidValue);
+
+If your ULIDs are generated in binary format, use the ``fromBinary()`` method
+to create the objects for them::
+
+    $ulid = Ulid::fromBinary($ulidBinaryContents);
+
+    // the opposite method is also available
+    $ulidAsBinary = $ulid->toBinary();
+
+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();
+
+    $ulid1->equals($ulid2); // false
+    $ulid1->getTime();      // e.g. float(1584111384.2613)
+    // this method returns $ulid1 <=> $ulid2
+    $uuid1->compare($uuid4); // 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