From e7fb0780d1f48431a1a93fc72d3751529ad04cc4 Mon Sep 17 00:00:00 2001
From: Ben Ramsey <ben@benramsey.com>
Date: Mon, 9 Mar 2020 17:07:58 -0500
Subject: [PATCH] [ci skip] Add documentation for replacing default factory

---
 docs/customize.rst         |  7 +++
 docs/customize/factory.rst | 93 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 docs/customize/factory.rst

diff --git a/docs/customize.rst b/docs/customize.rst
index 25ddf8e..76a61de 100644
--- a/docs/customize.rst
+++ b/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
diff --git a/docs/customize/factory.rst b/docs/customize/factory.rst
new file mode 100644
index 0000000..4d8eed7
--- /dev/null
+++ b/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.