Merge branch 'master' into dependabot/composer/dealerdirect/phpcodesniffer-composer-installer-tw-0.5.0or-tw-0.6.0

.github/CONTRIBUTING.md

@@ -16,7 +16,6 @@ this project and its community, you are expected to uphold this code.
 You can find help and discussion in the following places:
 
 * GitHub Issues: <https://github.com/ramsey/uuid/issues>
-* GitHub Wiki: <https://github.com/ramsey/uuid/wiki>
 
 
 ## Reporting Bugs

composer.json

@@ -92,7 +92,6 @@
     "support": {
         "issues": "https://github.com/ramsey/uuid/issues",
         "rss": "https://github.com/ramsey/uuid/releases.atom",
-        "source": "https://github.com/ramsey/uuid",
-        "wiki": "https://github.com/ramsey/uuid/wiki"
+        "source": "https://github.com/ramsey/uuid"
     }
 }

docs/customize.rst

@@ -6,6 +6,32 @@ Customization
 
 .. toctree::
     :titlesonly:
+    :hidden:
 
     customize/ordered-time-codec
     customize/timestamp-first-comb-codec
+
+ramsey/uuid offers a variety of ways to modify the standard behavior of the
+library through dependency injection. Using `UuidFactory`_, `FeatureSet`_, and
+:php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory()>`, you are able
+to replace just about any `codec`_, `builder`_, `converter`_, `provider`_,
+`generator`_, and more.
+
+Ordered-time Codec
+    The ordered-time codec exists to rearrange the bytes of a version 1,
+    time-based UUID so that the timestamp portion of the UUID is monotonically
+    increasing. To learn more, see :ref:`customize.ordered-time-codec`.
+
+Timestamp-first COMB Codec
+    The timestamp-first COMB codec replaces part of a version 4, random UUID
+    with a timestamp, so that the UUID becomes monotonically increasing. To
+    learn more, see :ref:`customize.timestamp-first-comb-codec`.
+
+
+.. _UuidFactory: https://github.com/ramsey/uuid/blob/master/src/UuidFactory.php
+.. _FeatureSet: https://github.com/ramsey/uuid/blob/master/src/FeatureSet.php
+.. _codec: https://github.com/ramsey/uuid/tree/master/src/Codec
+.. _builder: https://github.com/ramsey/uuid/tree/master/src/Builder
+.. _converter: https://github.com/ramsey/uuid/tree/master/src/Converter
+.. _provider: https://github.com/ramsey/uuid/tree/master/src/Provider
+.. _generator: https://github.com/ramsey/uuid/tree/master/src/Generator

docs/customize/ordered-time-codec.rst

@@ -3,3 +3,82 @@
 ==================
 Ordered-time Codec
 ==================
+
+.. hint::
+
+    :ref:`Version 6, ordered-time UUIDs <nonstandard.version6>` are a proposed
+    new version of UUID that take the place of ordered time UUIDs.
+
+UUIDs arrange their bytes according to the standard recommended by `RFC 4122`_.
+Unfortunately, this means the bytes aren't in an arrangement that supports
+sorting by creation time or an otherwise incrementing value. The Percona
+article, "`Storing UUID Values in MySQL`_," explains at length the problems this
+can cause. It also recommends a solution: the *ordered-time UUID*.
+
+RFC 4122 version 1, time-based UUIDs rearrange the bytes of the time fields so
+that the lowest bytes appear first, the middle bytes are next, and the highest
+bytes come last. Logical sorting is not possible with this arrangement.
+
+An ordered-time UUID is a version 1 UUID with the time fields arranged in
+logical order so that the UUIDs can be sorted by creation time. These UUIDs are
+*monotonically increasing*, each one coming after the previously-created one, in
+a proper sort order.
+
+.. code-block:: php
+    :caption: Use the ordered-time codec to generate a version 1 UUID
+    :name: customize.ordered-time-codec-example
+
+    use Ramsey\Uuid\Codec\OrderedTimeCodec;
+    use Ramsey\Uuid\UuidFactory;
+
+    $factory = new UuidFactory();
+    $codec = new OrderedTimeCodec($factory->getUuidBuilder());
+
+    $factory->setCodec($codec);
+
+    $orderedTimeUuid = $factory->uuid1();
+
+    printf(
+        "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\nBytes: %s\n",
+        $orderedTimeUuid->toString(),
+        $orderedTimeUuid->getFields()->getVersion(),
+        $orderedTimeUuid->getDateTime()->format('r'),
+        $orderedTimeUuid->getFields()->getNode()->toString(),
+        bin2hex($orderedTimeUuid->getBytes())
+    );
+
+This will use the ordered-time codec to generate a version 1 UUID and will print
+out details about the UUID similar to these:
+
+.. code-block:: text
+
+    UUID: 593200aa-61ae-11ea-bbf2-0242ac130003
+    Version: 1
+    Date: Mon, 09 Mar 2020 02:33:23 +0000
+    Node: 0242ac130003
+    Bytes: 11ea61ae593200aabbf20242ac130003
+
+.. attention::
+
+    Only the byte representation is rearranged. The string representation
+    follows the format of a standard version 1 UUID. This means only the byte
+    representation of an ordered-time codec encoded UUID may be used for
+    sorting, such as with database results.
+
+    To store the byte representation to a database field, see
+    :ref:`database.bytes`.
+
+.. hint::
+
+    If you use this codec and store the bytes of the UUID to the database, as
+    recommended above, you will need to use this codec to decode the bytes, as
+    well. Otherwise, the UUID string value will be incorrect.
+
+    .. code-block:: php
+
+        // Using a factory configured with the OrderedTimeCodec, as shown above.
+        $orderedTimeUuid = $factory->fromBytes($bytes);
+
+
+.. _RFC 4122: https://tools.ietf.org/html/rfc4122
+.. _Storing UUID Values in MySQL: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/

docs/customize/timestamp-first-comb-codec.rst

@@ -3,3 +3,63 @@
 ==========================
 Timestamp-first COMB Codec
 ==========================
+
+:ref:`Version 4, random UUIDs <rfc4122.version4>` are doubly problematic when it
+comes to sorting and storing to databases (see :ref:`database.order`), since
+their values are random, and there is no timestamp associated with them that may
+be rearranged, like with the :ref:`ordered-time codec
+<customize.ordered-time-codec>`. In 2002, Jimmy Nilsson recognized this problem
+with random UUIDs and proposed a solution he called "COMBs" (see "`The Cost of
+GUIDs as Primary Keys`_").
+
+So-called because they *combine* random bytes with a timestamp, the
+timestamp-first COMB codec replaces the first 48 bits of a version 4, random
+UUID with a Unix timestamp and microseconds, creating an identifier that can be
+sorted by creation time. These UUIDs are *monotonically increasing*, each one
+coming after the previously-created one, in a proper sort order.
+
+.. code-block:: php
+    :caption: Use the timestamp-first COMB codec to generate a version 4 UUID
+    :name: customize.timestamp-first-comb-codec-example
+
+    use Ramsey\Uuid\Codec\TimestampFirstCombCodec;
+    use Ramsey\Uuid\Generator\CombGenerator;
+    use Ramsey\Uuid\UuidFactory;
+
+    $factory = new UuidFactory();
+    $codec = new TimestampFirstCombCodec($factory->getUuidBuilder());
+
+    $factory->setCodec($codec);
+
+    $factory->setRandomGenerator(new CombGenerator(
+        $factory->getRandomGenerator(),
+        $factory->getNumberConverter()
+    ));
+
+    $timestampFirstComb = $factory->uuid4();
+
+    printf(
+        "UUID: %s\nVersion: %d\nBytes: %s\n",
+        $timestampFirstComb->toString(),
+        $timestampFirstComb->getFields()->getVersion(),
+        bin2hex($timestampFirstComb->getBytes())
+    );
+
+This will use the timestamp-first COMB codec to generate a version 4 UUID with
+the timestamp replacing the first 48 bits and will print out details about the
+UUID similar to these:
+
+.. code-block:: text
+
+    UUID: 9009ebcc-cd99-4b5f-90cf-9155607d2de9
+    Version: 4
+    Bytes: 9009ebcccd994b5f90cf9155607d2de9
+
+Note that the bytes are in the same order as the string representation. Unlike
+the :ref:`ordered-time codec <customize.ordered-time-codec>`, the
+timestamp-first COMB codec affects both the string representation and the byte
+representation. This means either the string UUID or the bytes may be stored to
+a datastore and sorted. To learn more, see :ref:`database`.
+
+
+.. _The Cost of GUIDs as Primary Keys: https://www.informit.com/articles/printerfriendly/25862

docs/database.rst

@@ -0,0 +1,256 @@
+.. _database:
+
+===================
+Using In a Database
+===================
+
+.. tip::
+
+    `ramsey/uuid-doctrine`_ allows the use of ramsey/uuid as a `Doctrine field
+    type`_. If you use Doctrine, it's a great option for working with UUIDs and
+    databases.
+
+There are several strategies to consider when working with UUIDs in a database.
+Among these are whether to store the string representation or bytes and whether
+the UUID column should be treated as a primary key. We'll discuss a few of these
+approaches here, but the final decision on how to use UUIDs in a database is up
+to you, since your needs will be different from those of others.
+
+.. note::
+
+    All database code examples in this section assume the use of `MariaDB`_ and
+    `PHP Data Objects (PDO)`_. If using a different database engine or
+    connection library, your code will differ, but the general concepts should
+    remain the same.
+
+
+.. _database.string:
+
+Storing As a String
+###################
+
+Perhaps the easiest way to store a UUID to a database is to create a ``char(36)``
+column and store the UUID as a string. When stored as a string, UUIDs require
+no special treatment in SQL statements or when displaying them.
+
+The primary drawback is the size. At 36 characters, UUIDs can take up a lot of
+space, and when handling a lot of data, this can add up.
+
+.. code-block:: sql
+    :caption: Create a table with a column for UUIDs
+    :name: database.uuid-column-example
+
+    CREATE TABLE `notes` (
+        `uuid` char(36) NOT NULL,
+        `notes` text NOT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+
+Using this database table, we can store the string UUID using code similar to
+this (assume some of the variables in this example have been set beforehand):
+
+.. code-block:: php
+    :caption: Store a string UUID to the uuid column
+    :name: database.uuid-column-store-example
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid4();
+
+    $dbh = new PDO($dsn, $username, $password);
+
+    $sth = $dbh->prepare('
+        INSERT INTO notes (
+            uuid,
+            notes
+        ) VALUES (
+            :uuid,
+            :notes
+        )
+    ');
+
+    $sth->execute([
+        ':uuid' => $uuid->toString(),
+        ':notes' => $notes,
+    ]);
+
+
+.. _database.bytes:
+
+Storing As Bytes
+################
+
+In :ref:`the previous example <database.uuid-column-store-example>`, we saw how
+to store the string representation of a UUID to a ``char(36)`` column. As
+discussed, the primary drawback is the size. However, if we store the UUID in
+byte form, we only need a ``char(16)`` column, saving over half the space.
+
+The primary drawback with this approach is ease-of-use. Since the UUID bytes are
+stored in the database, querying and selecting data becomes more difficult.
+
+.. code-block:: sql
+    :caption: Create a table with a column for UUID bytes
+    :name: database.uuid-bytes-example
+
+    CREATE TABLE `notes` (
+        `uuid` char(16) NOT NULL,
+        `notes` text NOT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+
+Using this database table, we can store the UUID bytes using code similar to
+this (again, assume some of the variables in this example have been set
+beforehand):
+
+.. code-block:: php
+    :caption: Store a string UUID to the uuid column
+    :name: database.uuid-bytes-store-example
+
+    $sth->execute([
+        ':uuid' => $uuid->getBytes(),
+        ':notes' => $notes,
+    ]);
+
+Now, when we ``SELECT`` the records from the database, we will need to convert
+the ``notes.uuid`` column to a ramsey/uuid object, so that we are able to use
+it.
+
+.. code-block:: php
+    :caption: Covert database UUID bytes to UuidInterface instance
+    :name: database.uuid-bytes-convert-example
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid4();
+
+    $dbh = new PDO($dsn, $username, $password);
+
+    $sth = $dbh->prepare('SELECT uuid, notes FROM notes');
+    $sth->execute();
+
+    foreach ($sth->fetchAll() as $record) {
+        $uuid = Uuid::fromBytes($record['uuid']);
+
+        printf(
+            "UUID: %s\nNotes: %s\n\n",
+            $uuid->toString(),
+            $record['notes']
+        );
+    }
+
+We'll also need to query the database using the bytes.
+
+.. code-block:: php
+    :caption: Look-up the record from the database, using the UUID bytes
+    :name: database.uuid-bytes-select-example
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::fromString('278198d3-fa96-4833-abab-82f9e67f4712');
+
+    $dbh = new PDO($dsn, $username, $password);
+
+    $sth = $dbh->prepare('
+        SELECT uuid, notes
+        FROM notes
+        WHERE uuid = :uuid
+    ');
+
+    $sth->execute([
+        ':uuid' => $uuid->getBytes(),
+    ]);
+
+    $record = $sth->fetch();
+
+    if ($record) {
+        $uuid = Uuid::fromBytes($record['uuid']);
+
+        printf(
+            "UUID: %s\nNotes: %s\n\n",
+            $uuid->toString(),
+            $record['notes']
+        );
+    }
+
+
+.. _database.pk:
+
+Using As a Primary Key
+######################
+
+In the previous examples, we didn't use the UUID as a primary key, but it's
+logical to use the ``notes.uuid`` field as a primary key. There's nothing wrong
+with this approach, but there are a couple points to consider:
+
+* InnoDB stores data in the primary key order
+* All the secondary keys also contain the primary key (in InnoDB)
+
+We'll deal with the first point in the section, :ref:`database.order`. For the
+second point, if you are using the string version of the UUID (i.e.,
+``char(36)``), then not only will the primary key be large and take up a lot of
+space, but every secondary key that uses that primary key will also be must
+larger.
+
+For this reason, if you choose to use UUIDs as primary keys, it might be worth
+the drawbacks to use UUID bytes (i.e., ``char(16)``) instead of the string
+representation (see :ref:`database.bytes`).
+
+
+.. _database.uk:
+
+Using As a Unique Key
+#####################
+
+Instead of :ref:`using UUIDs as a primary key <database.pk>`, you may choose to
+use an ``AUTO_INCREMENT`` column with the ``int unsigned`` data type as a
+primary key, while using a ``char(36)`` for UUIDs and setting a ``UNIQUE KEY``
+on this column. This will aid in lookups, while helping keep your secondary keys
+small.
+
+.. code-block:: sql
+    :caption: Use auto-incrementing column as primary key, with UUID as unique key
+    :name: database.id-auto-increment-uuid-unique-key
+
+    CREATE TABLE `notes` (
+        `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
+        `uuid` char(36) NOT NULL,
+        `notes` text NOT NULL,
+        PRIMARY KEY (`id`),
+        UNIQUE KEY `notes_uuid_uk` (`uuid`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+
+
+.. _database.order:
+
+Insertion Order and Sorting
+###########################
+
+UUIDs are not *monotonically increasing*. Even time-based UUIDs are not. If
+using UUIDs as primary keys, the inserts will be random, and the data will be
+scattered on disk. Over time, as the database size grows, lookups will become
+slower and slower.
+
+.. note::
+
+    See Percona's "`Storing UUID Values in MySQL`_" post, for more details on
+    performance of UUIDs as primary keys.
+
+To minimize these problems, two solutions have been devised:
+
+1. Timestamp first COMBs
+2. Ordered Time UUIDs
+
+:ref:`customize.timestamp-first-comb-codec` explains the first solution and how
+to use ramsey/uuid to implement it, while :ref:`customize.ordered-time-codec`
+explains how to use ramsey/uuid to implement the second solution.
+
+.. hint::
+
+    :ref:`Version 6, ordered-time UUIDs <nonstandard.version6>` are a proposed
+    new version of UUID that take the place of ordered time UUIDs.
+
+
+.. _ramsey/uuid-doctrine: https://github.com/ramsey/uuid-doctrine
+.. _Doctrine field type: https://www.doctrine-project.org/projects/doctrine-dbal/en/2.10/reference/types.html
+.. _MariaDB: https://mariadb.org
+.. _PHP Data Objects (PDO): https://www.php.net/pdo
+.. _Storing UUID Values in MySQL: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/
+.. _Version 6, ordered-time UUIDs: nonstandard.version6

docs/index.rst

@@ -19,6 +19,7 @@ Contents
     quickstart
     rfc4122
     nonstandard
+    database
     customize
     upgrading
     FAQs <faq>

docs/nonstandard.rst

@@ -25,7 +25,7 @@ Version 6: Ordered-time
     :ref:`version 1 UUID <rfc4122.version1>` with a *monotonically increasing*
     UUID. For more details, see :ref:`nonstandard.version6`.
 
-GUID
+Globally Unique Identifiers (GUIDs)
     A globally unique identifier, or GUID, is often used as a synonym for UUID.
     A key difference is the order of the bytes. Any `RFC 4122`_ version UUID may
     be represented as a GUID. For more details, see :ref:`nonstandard.guid`.

docs/nonstandard/guid.rst

@@ -1,8 +1,8 @@
 .. _nonstandard.guid:
 
-=================================
-Globally Unique Identifier (GUID)
-=================================
+===================================
+Globally Unique Identifiers (GUIDs)
+===================================
 
 .. tip::
 

docs/nonstandard/other.rst

@@ -3,3 +3,47 @@
 =======================
 Other Nonstandard UUIDs
 =======================
+
+Sometimes, you might encounter a string that looks like a UUID but doesn't
+follow the `RFC 4122`_ specification. Take this string, for example:
+
+.. code-block:: text
+
+    d95959bc-2ff5-43eb-fccd-14883ba8f174
+
+At a glance, this looks like a valid UUID, but the variant bits don't match RFC
+4122. Instead of throwing a validation exception, ramsey/uuid will assume this
+is a UUID, since it fits the format and has 128 bits, but it will represent it
+as a :php:class:`Ramsey\\Uuid\\Nonstandard\\Uuid`.
+
+.. code-block:: php
+    :caption: Create an instance of Nonstandard\\Uuid from a non-RFC 4122 UUID
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::fromString('d95959bc-2ff5-43eb-fccd-14883ba8f174');
+
+    printf(
+        "Class: %s\nUUID: %s\nVersion: %d\nVariant: %s\n",
+        get_class($uuid),
+        $uuid->toString(),
+        $uuid->getFields()->getVersion(),
+        $uuid->getFields()->getVariant()
+    );
+
+This will create a Nonstandard\\Uuid from the given string and print out a few
+details about it. It will look something like this:
+
+.. code-block:: text
+
+    Class: Ramsey\Uuid\Nonstandard\Uuid
+    UUID: d95959bc-2ff5-43eb-fccd-14883ba8f174
+    Version: 0
+    Variant: 7
+
+Note that the version is 0. Since the variant is 7, and there is no
+formal specification for this variant of UUID, ramsey/uuid has no way of knowing
+what type of UUID this is.
+
+
+.. _RFC 4122: https://tools.ietf.org/html/rfc4122

docs/quickstart.rst

@@ -104,6 +104,8 @@ library.
     * - :php:meth:`Uuid::fromInteger() <Ramsey\\Uuid\\Uuid::fromInteger>`
       - Creates a UUID instance from a string integer.
     * - :php:meth:`Uuid::fromDateTime() <Ramsey\\Uuid\\Uuid::fromDateTime>`
-      - Creates a version 1 UUID instance from a PHP ``\DateTimeInterface``.
+      - Creates a version 1 UUID instance from a PHP `DateTimeInterface`_.
+
 
 .. _RFC 4122: https://tools.ietf.org/html/rfc4122
+.. _DateTimeInterface: https://www.php.net/datetimeinterface

docs/reference.rst

@@ -20,6 +20,9 @@ Reference
     reference/nonstandard-uuidv6
     reference/guid-fields
     reference/guid-guid
+    reference/nonstandard-fields
+    reference/nonstandard-uuid
+    reference/uuidfactoryinterface
     reference/types
     reference/exceptions
     reference/helper

docs/reference/exceptions.rst

@@ -8,33 +8,33 @@ Exceptions
 
 .. php:exception:: BuilderNotFoundException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that no suitable UUID builder could be found.
 
 .. php:exception:: DateTimeException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that the PHP DateTime extension encountered an
     exception or error.
 
 .. php:exception:: DceSecurityException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate an exception occurred while dealing with DCE Security
     (version 2) UUIDs
 
 .. php:exception:: InvalidArgumentException
 
-    Extends ``\InvalidArgumentException``.
+    Extends `InvalidArgumentException <https://www.php.net/invalidargumentexception>`_.
 
     Thrown to indicate that the argument received is not valid.
 
 .. php:exception:: InvalidBytesException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that the bytes being operated on are invalid in some way.
 
@@ -46,38 +46,38 @@ Exceptions
 
 .. php:exception:: NameException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that an error occurred while attempting to hash a
     namespace and name
 
 .. php:exception:: NodeException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that attempting to fetch or create a node ID encountered
     an error.
 
 .. php:exception:: RandomSourceException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that the source of random data encountered an error.
 
 .. php:exception:: TimeSourceException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate that the source of time encountered an error.
 
 .. php:exception:: UnableToBuildUuidException
 
-    Extends ``\RuntimeException``.
+    Extends `RuntimeException <https://www.php.net/runtimeexception>`_.
 
     Thrown to indicate a builder is unable to build a UUID.
 
 .. php:exception:: UnsupportedOperationException
 
-    Extends ``\LogicException``.
+    Extends `LogicException <https://www.php.net/logicexception>`_.
 
     Thrown to indicate that the requested operation is not supported.

docs/reference/guid-fields.rst

@@ -10,4 +10,4 @@ Guid\\Fields
 
     Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\FieldsInterface`.
 
-    ``Guid\Fields`` represents the fields of a GUID.
+    Guid\Fields represents the fields of a GUID.

docs/reference/nonstandard-fields.rst

@@ -0,0 +1,13 @@
+.. _reference.nonstandard.fields:
+
+===================
+Nonstandard\\Fields
+===================
+
+.. php:namespace:: Ramsey\Uuid\Nonstandard
+
+.. php:class:: Fields
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\FieldsInterface`.
+
+    Nonstandard\Fields represents the fields of a nonstandard UUID.

docs/reference/nonstandard-uuid.rst

@@ -0,0 +1,20 @@
+.. _reference.nonstandard.uuid:
+
+=================
+Nonstandard\\Uuid
+=================
+
+.. php:namespace:: Ramsey\Uuid\Nonstandard
+
+.. php:class:: Uuid
+
+    Implements :php:interface:`Ramsey\\Uuid\\UuidInterface`.
+
+    Nonstandard\Uuid represents :ref:`nonstandard.other`. In addition to
+    providing the methods defined on the interface, this class additionally
+    provides the following methods.
+
+    .. php:method:: getFields()
+
+        :returns: The fields that comprise this UUID
+        :returntype: Ramsey\\Uuid\\Nonstandard\\Fields

docs/reference/rfc4122-fieldsinterface.rst

@@ -10,7 +10,7 @@ Rfc4122\\FieldsInterface
 
     Implements :php:interface:`Ramsey\\Uuid\\Fields\\FieldsInterface`.
 
-    ``Rfc4122\FieldsInterface`` represents the fields of an RFC 4122 UUID.
+    Rfc4122\FieldsInterface represents the fields of an RFC 4122 UUID.
     In addition to the methods defined on the interface, this class additionally
     defines the following methods.
 

docs/reference/rfc4122-uuidinterface.rst

@@ -10,7 +10,7 @@ Rfc4122\\UuidInterface
 
     Implements :php:interface:`Ramsey\\Uuid\\UuidInterface`.
 
-    ``Rfc4122\UuidInterface`` represents an RFC 4122 UUID. In addition to the
+    Rfc4122\UuidInterface represents an RFC 4122 UUID. In addition to the
     methods defined on the interface, this interface additionally defines the
     following methods.
 

docs/reference/rfc4122-uuidv2.rst

@@ -16,8 +16,8 @@ Rfc4122\\UuidV2
 
     .. php:method:: getDateTime()
 
-        Returns a DateTimeInterface object representing the timestamp associated
-        with the UUID
+        Returns a `DateTimeInterface <https://www.php.net/datetimeinterface>`_
+        instance representing the timestamp associated with the UUID
 
         .. caution::
 

docs/reference/types.rst

@@ -8,7 +8,8 @@ Types
 
 .. php:class:: TypeInterface
 
-    Implements ``\JsonSerializable`` and ``\Serializable``.
+    Implements `JsonSerializable <https://www.php.net/jsonserializable>`_ and
+    `Serializable <https://www.php.net/serializable>`_.
 
     TypeInterface ensures consistency in typed values returned by ramsey/uuid.
 

docs/reference/uuid.rst

@@ -4,7 +4,7 @@
 Uuid
 ====
 
-``Ramsey\Uuid`` provides static methods for the most common functionality for
+Ramsey\Uuid\Uuid provides static methods for the most common functionality for
 generating and working with UUIDs. It also provides constants used throughout
 the ramsey/uuid library.
 
@@ -141,7 +141,7 @@ the ramsey/uuid library.
 
     .. php:staticmethod:: fromString($uuid)
 
-        Creates an instance of ``UuidInterface`` from the string standard
+        Creates an instance of UuidInterface from the string standard
         representation.
 
         :param string $uuid: The string standard representation of a UUID
@@ -149,21 +149,22 @@ the ramsey/uuid library.
 
     .. php:staticmethod:: fromBytes($bytes)
 
-        Creates an instance of ``UuidInterface`` from a 16-byte string.
+        Creates an instance of UuidInterface from a 16-byte string.
 
         :param string $bytes: A 16-byte binary string representation of a UUID
         :returntype: Ramsey\\Uuid\\UuidInterface
 
     .. php:staticmethod:: fromInteger($integer)
 
-        Creates an instance of ``UuidInterface`` from a 128-bit string integer.
+        Creates an instance of UuidInterface from a 128-bit string integer.
 
         :param string $integer: A 128-bit string integer representation of a UUID
         :returntype: Ramsey\\Uuid\\UuidInterface
 
     .. php:staticmethod:: fromDateTime($dateTime[, $node[, $clockSeq]])
 
-        Creates a version 1 UUID instance from a ``\DateTimeInterface`` instance.
+        Creates a version 1 UUID instance from a `DateTimeInterface
+        <https://www.php.net/datetimeinterface>`_ instance.
 
         :param DateTimeInterface $dateTime: The date from which to create the UUID instance
         :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
@@ -173,11 +174,18 @@ the ramsey/uuid library.
 
     .. php:staticmethod:: isValid($uuid)
 
-        Validates the string standard representation of a UUID
+        Validates the string standard representation of a UUID.
 
         :param string $uuid: The string standard representation of a UUID
         :returntype: ``bool``
 
+    .. php:staticmethod:: setFactory($factory)
+
+        Sets the factory used to create UUIDs.
+
+        :param Ramsey\\Uuid\\UuidFactoryInterface $factory: A UUID factory to use for all UUID generation
+        :returntype: void
+
 
 .. _ISO object identifier (OID): http://www.oid-info.com
 .. _X.500: https://en.wikipedia.org/wiki/X.500

docs/reference/uuidfactoryinterface.rst

@@ -0,0 +1,102 @@
+.. _reference.uuidfactoryinterface:
+
+====================
+UuidFactoryInterface
+====================
+
+.. php:namespace:: Ramsey\Uuid
+
+.. php:interface:: UuidFactoryInterface
+
+    Represents a UUID factory.
+
+    .. php:method:: getValidator()
+
+        :returntype: Ramsey\\Uuid\\Validator\\ValidatorInterface
+
+    .. php:method:: uuid1([$node[, $clockSeq]])
+
+        Generates a version 1, time-based UUID. See :ref:`rfc4122.version1`.
+
+        :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
+        :param int|null $clockSeq: An optional clock sequence to use
+        :returns: A version 1 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1
+
+    .. php:method:: uuid2($localDomain[, $localIdentifier[, $node[, $clockSeq]]])
+
+        Generates a version 2, DCE Security UUID. See :ref:`rfc4122.version2`.
+
+        :param int $localDomain: The local domain to use (one of :php:const:`Uuid::DCE_DOMAIN_PERSON`, :php:const:`Uuid::DCE_DOMAIN_GROUP`, or :php:const:`Uuid::DCE_DOMAIN_ORG`)
+        :param Ramsey\\Uuid\\Type\\Integer|null $localIdentifier: A local identifier for the domain (defaults to system UID or GID for *person* or *group*)
+        :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
+        :param int|null $clockSeq: An optional clock sequence to use
+        :returns: A version 2 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV2
+
+    .. php:method:: uuid3($ns, $name)
+
+        Generates a version 3, name-based (MD5) UUID. See :ref:`rfc4122.version3`.
+
+        :param Ramsey\\Uuid\\UuidInterface|string $ns: The namespace for this identifier
+        :param string $name: The name from which to generate an identifier
+        :returns: A version 3 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV3
+
+    .. php:method:: uuid4()
+
+        Generates a version 4, random UUID. See :ref:`rfc4122.version4`.
+
+        :returns: A version 4 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV4
+
+    .. php:method:: uuid5($ns, $name)
+
+        Generates a version 5, name-based (SHA-1) UUID. See :ref:`rfc4122.version5`.
+
+        :param Ramsey\\Uuid\\UuidInterface|string $ns: The namespace for this identifier
+        :param string $name: The name from which to generate an identifier
+        :returns: A version 5 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV5
+
+    .. php:method:: uuid6([$node[, $clockSeq]])
+
+        Generates a version 6, ordered-time UUID. See :ref:`nonstandard.version6`.
+
+        :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
+        :param int|null $clockSeq: An optional clock sequence to use
+        :returns: A version 6 UUID
+        :returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6
+
+    .. php:method:: fromString($uuid)
+
+        Creates an instance of UuidInterface from the string standard
+        representation.
+
+        :param string $uuid: The string standard representation of a UUID
+        :returntype: Ramsey\\Uuid\\UuidInterface
+
+    .. php:method:: fromBytes($bytes)
+
+        Creates an instance of UuidInterface from a 16-byte string.
+
+        :param string $bytes: A 16-byte binary string representation of a UUID
+        :returntype: Ramsey\\Uuid\\UuidInterface
+
+    .. php:method:: fromInteger($integer)
+
+        Creates an instance of UuidInterface from a 128-bit string integer.
+
+        :param string $integer: A 128-bit string integer representation of a UUID
+        :returntype: Ramsey\\Uuid\\UuidInterface
+
+    .. php:method:: fromDateTime($dateTime[, $node[, $clockSeq]])
+
+        Creates a version 1 UUID instance from a `DateTimeInterface
+        <https://www.php.net/datetimeinterface>`_ instance.
+
+        :param DateTimeInterface $dateTime: The date from which to create the UUID instance
+        :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
+        :param int|null $clockSeq: An optional clock sequence to use
+        :returns: A version 1 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1

docs/rfc4122/version2.rst

@@ -249,8 +249,8 @@ that represents a local identifier. Because of this, not only do version 2 UUIDs
 have :ref:`limited uniqueness <rfc4122.version2.uniqueness-problems>`, but they
 also lack time precision.
 
-When reconstructing the timestamp to return a ``\DateTimeInterface`` instance
-from :php:meth:`UuidV2::getDateTime() <Ramsey\\Uuid\\Rfc4122\\UuidV2::getDateTime>`,
+When reconstructing the timestamp to return a `DateTimeInterface`_ instance from
+:php:meth:`UuidV2::getDateTime() <Ramsey\\Uuid\\Rfc4122\\UuidV2::getDateTime>`,
 we replace the 32 lower bits of the timestamp with zeros, since the local
 identifier should not be part of the timestamp. This results in a loss of
 precision, causing the timestamp to be off by a range of 0 to 429.4967295
@@ -270,3 +270,4 @@ it could be off by about 7 minutes.
 
 .. _Distributed Computing Environment: https://en.wikipedia.org/wiki/Distributed_Computing_Environment
 .. _POSIX: https://en.wikipedia.org/wiki/POSIX
+.. _DateTimeInterface: https://www.php.net/datetimeinterface