Updated the contents

Author: javiereguiluz

components/uid.rst

@@ -22,12 +22,6 @@ Installation
 
 .. 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
 -----
 
@@ -39,40 +33,69 @@ groups of hexadecimal characters: ``xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx``
 Generating UUIDs
 ~~~~~~~~~~~~~~~~
 
-Use any of the following named constructors depending on your needs::
+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;
+    use Symfony\Component\Uid\UuidV1;
+    use Symfony\Component\Uid\UuidV3;
+    use Symfony\Component\Uid\UuidV4;
+    use Symfony\Component\Uid\UuidV5;
+    use Symfony\Component\Uid\UuidV6;
 
     // 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 = new UuidV1();
 
     // UUID type 4 generates a random UUID, so you don't have to pass any constructor argument.
     $uuid = Uuid::v4();
+    $uuid = new 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();
+    $namespace = new UuidV4();
     $name = $product->getUniqueName();
+
     $uuid = Uuid::v3($namespace, $name);
+    $uuid = new UuidV3($namespace, $name);
+
     $uuid = Uuid::v5($namespace, $name);
+    $uuid = new UuidV5($namespace, $name);
+
+    // 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 = new UuidV6();
 
 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::
+``Uuid`` class (or the static ``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 = new Uuid($uuidValue);
+    $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);
 
-    // the opposite method is also available
-    $uuidAsBinary = $uuid->toBinary();
+Converting UUIDs
+~~~~~~~~~~~~~~~~
+
+Use these methods to transform the UUID object into different bases::
+
+    $uuidValue = 'd9e7a184-5d5b-11ea-a62a-3499710062d0';
+    $uuid = new Uuid($uuidValue);
+
+    $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
 ~~~~~~~~~~~~~~~~~~
@@ -81,19 +104,25 @@ 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;
+    use Symfony\Component\Uid\NilUuid;
 
-    $uuid4 = Uuid::v4();
+    // 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
 
-    $uuid4->isNull(); // false
+    // checking the type of UUID
+    use Symfony\Component\Uid\UuidV4;
+    $uuid = Uuid::v4();
+    $uuid instanceof UuidV4; // true
 
-    // the Uuid class defines public constants for all versions (Uuid::TYPE_1, Uuid::TYPE_3, etc.)
-    $uuid4->getType(); // int(4)
+    // getting the UUID time (it's only available in certain UUID types)
+    $uuid = Uuid::v1();
+    $uuid->getTime();  // e.g. float(1584111384.2613)
 
-    // the time and MAC address is only available in certain UUID types
+    // comparing UUIDs and checking for equality
     $uuid1 = Uuid::v1();
-    $uuid1->getTime();  // e.g. float(1584111384.2613)
-    $uuid1->getMac();   // e.g. string(12) "27cb420bea01"
-
+    $uuid4 = Uuid::v4();
     $uuid1->equals($uuid4); // false
 
     // this method returns:
@@ -124,16 +153,26 @@ Instantiate the ``Ulid`` class to generate a random ULID value::
 
 If your ULID is generated by another system, pass its value to the constructor::
 
-    $ulidValue = 'X7NR9KZ0A4Y9BV1431S70A03M7';
+    $ulidValue = '01E439TP9XJZ9RPFH3T1PYBCR8';
     $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();
+Converting ULIDs
+~~~~~~~~~~~~~~~~
+
+Use these methods to transform the ULID object into different bases::
+
+    $ulidValue = '01E439TP9XJZ9RPFH3T1PYBCR8';
+    $ulid = new Ulid($ulidValue);
+
+    $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
 ~~~~~~~~~~~~~~~~~~
@@ -145,8 +184,14 @@ ULID objects created with the ``Ulid`` class can use the following methods::
     $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
-    $ulid1->getTime();      // e.g. float(1584111384.2613)
     // this method returns $ulid1 <=> $ulid2
     $uuid1->compare($uuid4); // e.g. int(-1)