[ci skip] Add documentation for replacing default factory

docs/customize.rst

@@ -12,6 +12,7 @@ Customization
     customize/timestamp-first-comb-codec
     customize/calculators
     customize/validators
+    customize/factory
 
 ramsey/uuid offers a variety of ways to modify the standard behavior of the
 library through dependency injection. Using `FeatureSet`_, `UuidFactory`_, and
@@ -39,6 +40,12 @@ Using a Custom Validator
     UUID format, you may replace the default validator. See
     :ref:`customize.validators`, to learn more.
 
+Replace the Default Factory
+    Not only are you able to inject alternate builders, codecs, etc. into the
+    factory and use the factory to generate UUIDs, you may also replace the
+    global, static factory used by the static methods on the Uuid class. To find
+    out how, see :ref:`customize.factory`.
+
 
 .. _UuidFactory: https://github.com/ramsey/uuid/blob/master/src/UuidFactory.php
 .. _FeatureSet: https://github.com/ramsey/uuid/blob/master/src/FeatureSet.php

docs/customize/factory.rst

@@ -0,0 +1,93 @@
+.. _customize.factory:
+
+===========================
+Replace the Default Factory
+===========================
+
+In many of the examples throughout this documentation, we've seen how to
+configure the factory and then use that factory to generate and work with UUIDs.
+
+For example:
+
+.. code-block:: php
+    :caption: Configure the factory and use it to generate a version 1 UUID
+    :name: customize.factory.example
+
+    use Ramsey\Uuid\Codec\OrderedTimeCodec;
+    use Ramsey\Uuid\UuidFactory;
+
+    $factory = new UuidFactory();
+    $codec = new OrderedTimeCodec($factory->getUuidBuilder());
+
+    $factory->setCodec($codec);
+
+    $orderedTimeUuid = $factory->uuid1();
+
+When doing this, the default behavior of ramsey/uuid is left intact. If we call
+``Uuid::uuid()`` to generate a version 1 UUID after configuring the factory as
+shown above, it won't use :ref:`OrderedTimeCodec <customize.ordered-time-codec>`
+to generate the UUID.
+
+.. code-block:: php
+    :caption: The behavior differs between $factory->uuid1() and Uuid::uuid1()
+    :name: customize.factory.behavior-example
+
+    $orderedTimeUuid = $factory->uuid1();
+
+    printf(
+        "UUID: %s\nBytes: %s\n\n",
+        $orderedTimeUuid->toString(),
+        bin2hex($orderedTimeUuid->getBytes())
+    );
+
+    $uuid = Uuid::uuid1();
+
+    printf(
+        "UUID: %s\nBytes: %s\n\n",
+        $uuid->toString(),
+        bin2hex($uuid->getBytes())
+    );
+
+In this example, we print out details for two different UUIDs. The first was
+generated with the :ref:`OrderedTimeCodec <customize.ordered-time-codec>` using
+``$factory->uuid1()``. The second was generated using ``Uuid::uuid1()``. It
+looks something like this:
+
+.. code-block:: text
+
+    UUID: 2ff06620-6251-11ea-9791-0242ac130003
+    Bytes: 11ea62512ff0662097910242ac130003
+
+    UUID: 2ff09730-6251-11ea-ba64-0242ac130003
+    Bytes: 2ff09730625111eaba640242ac130003
+
+Notice the arrangement of the bytes. The first set of bytes has been rearranged,
+according to the ordered-time codec rules, but the second set of bytes remains
+in the same order as the UUID string.
+
+*Configuring the factory does not change the default behavior.*
+
+If we want to change the default behavior, we must *replace* the factory used
+by the Uuid static methods, and we can do this using the
+:php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory>` static method.
+
+.. code-block:: php
+    :caption: Replace the factory to globally affect Uuid behavior
+    :name: customize.factory.replace-factory-example
+
+    Uuid::setFactory($factory);
+
+    $uuid = Uuid::uuid1();
+
+Now, every time we call :php:meth:`Uuid::uuid() <Ramsey\\Uuid\\Uuid::uuid1>`,
+ramsey/uuid will use the factory configured with the :ref:`OrderedTimeCodec
+<customize.ordered-time-codec>` to generate version 1 UUIDs.
+
+.. warning::
+
+    Calling :php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory>` to
+    replace the factory will change the behavior of Uuid no matter where it is
+    used, so keep this in mind when replacing the factory. If you replace the
+    factory deep inside a method somewhere, any later code that calls a static
+    method on :php:class:`Ramsey\\Uuid\\Uuid` will use the new factory to
+    generate UUIDs.