From 98b620676a23275b4bb12823398bab2fa1a8b9a4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz 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"