From 98b620676a23275b4bb12823398bab2fa1a8b9a4 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 9 Apr 2021 13:05:33 +0200
Subject: [PATCH] [Uid] Document the ::from() methods for UUIDs and ULIDs

---
 components/uid.rst | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

diff --git a/components/uid.rst b/components/uid.rst
index 1bf66021fe1..b262768195a 100644
--- a/components/uid.rst
+++ b/components/uid.rst
@@ -71,12 +71,20 @@ to create each type of UUID::
 
     The ``Uuid::NAMESPACE_*`` constants were introduced in Symfony 5.3.
 
-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::
+If your UUID value is already generated in another format, use any of the
+following methods to create a ``Uuid`` object from it::
 
-    // this value is generated somewhere else (can also be in binary format)
-    $uuidValue = 'd9e7a184-5d5b-11ea-a62a-3499710062d0';
-    $uuid = Uuid::fromString($uuidValue);
+    // all the following examples would generate the same Uuid object
+    $uuid = Uuid::fromString('d9e7a184-5d5b-11ea-a62a-3499710062d0');
+    $uuid = Uuid::fromBinary("\xd9\xe7\xa1\x84\x5d\x5b\x11\xea\xa6\x2a\x34\x99\x71\x00\x62\xd0");
+    $uuid = Uuid::fromBase32('6SWYGR8QAV27NACAHMK5RG0RPG');
+    $uuid = Uuid::fromBase58('TuetYWNHhmuSQ3xPoVLv9M');
+    $uuid = Uuid::fromRfc4122('d9e7a184-5d5b-11ea-a62a-3499710062d0');
+
+.. versionadded:: 5.3
+
+    The ``fromBinary()``, ``fromBase32()``, ``fromBase58()`` and ``fromRfc4122()``
+    methods were introduced in Symfony 5.3.
 
 Converting UUIDs
 ~~~~~~~~~~~~~~~~
@@ -85,7 +93,7 @@ Use these methods to transform the UUID object into different bases::
 
     $uuid = Uuid::fromString('d9e7a184-5d5b-11ea-a62a-3499710062d0');
 
-    $uuid->toBinary();  // string(16) "..." (binary contents can't be printed)
+    $uuid->toBinary();  // string(16) "\xd9\xe7\xa1\x84\x5d\x5b\x11\xea\xa6\x2a\x34\x99\x71\x00\x62\xd0"
     $uuid->toBase32();  // string(26) "6SWYGR8QAV27NACAHMK5RG0RPG"
     $uuid->toBase58();  // string(22) "TuetYWNHhmuSQ3xPoVLv9M"
     $uuid->toRfc4122(); // string(36) "d9e7a184-5d5b-11ea-a62a-3499710062d0"
@@ -238,12 +246,20 @@ Instantiate the ``Ulid`` class to generate a random ULID value::
 
     $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::
+If your ULID value is already generated in another format, use any of the
+following methods to create a ``Ulid`` object from it::
+
+    // all the following examples would generate the same Ulid object
+    $ulid = Ulid::fromString('01E439TP9XJZ9RPFH3T1PYBCR8');
+    $ulid = Ulid::fromBinary("\x01\x71\x06\x9d\x59\x3d\x97\xd3\x8b\x3e\x23\xd0\x6d\xe5\xb3\x08");
+    $ulid = Ulid::fromBase32('01E439TP9XJZ9RPFH3T1PYBCR8');
+    $ulid = Ulid::fromBase58('1BKocMc5BnrVcuq2ti4Eqm');
+    $ulid = Ulid::fromRfc4122('0171069d-593d-97d3-8b3e-23d06de5b308');
+
+.. versionadded:: 5.3
 
-    // this value is generated somewhere else (can also be in binary format)
-    $ulidValue = '01E439TP9XJZ9RPFH3T1PYBCR8';
-    $ulid = Ulid::fromString($ulidValue);
+    The ``fromBinary()``, ``fromBase32()``, ``fromBase58()`` and ``fromRfc4122()``
+    methods were introduced in Symfony 5.3.
 
 Converting ULIDs
 ~~~~~~~~~~~~~~~~
@@ -252,7 +268,7 @@ 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->toBinary();  // string(16) "\x01\x71\x06\x9d\x59\x3d\x97\xd3\x8b\x3e\x23\xd0\x6d\xe5\xb3\x08"
     $ulid->toBase32();  // string(26) "01E439TP9XJZ9RPFH3T1PYBCR8"
     $ulid->toBase58();  // string(22) "1BKocMc5BnrVcuq2ti4Eqm"
     $ulid->toRfc4122(); // string(36) "0171069d-593d-97d3-8b3e-23d06de5b308"