NN2024010801/vendor/ramsey/uuid/docs/customize/factory.rst

.. _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::uuid1()`` 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.