[ci skip] Update documentation

.gitattributes

@@ -1,6 +1,7 @@
 .gitattributes     export-ignore
 .github/           export-ignore
 .gitignore         export-ignore
+.readthedocs.yml   export-ignore
 .travis.yml        export-ignore
 docs/              export-ignore
 phpcs.xml.dist     export-ignore

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+formats: all
+
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -53,7 +53,6 @@ information.
 [javauuid]: http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html
 [pyuuid]: http://docs.python.org/3/library/uuid.html
 [composer]: http://getcomposer.org/
-[wiki-cookbook]: https://github.com/ramsey/uuid/wiki/Ramsey%5CUuid-Cookbook
 [contributing.md]: https://github.com/ramsey/uuid/blob/master/.github/CONTRIBUTING.md
 
 [badge-source]: https://img.shields.io/badge/source-ramsey/uuid-blue.svg?style=flat-square

docs/conf.py

@@ -55,6 +55,7 @@ lexers['php-annotations'] = PhpLexer(startinline=True)
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinxcontrib.phpdomain',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -20,4 +20,5 @@ This work is licensed under the `Creative Commons Attribution 4.0 International
     nonstandard
     upgrading
     FAQs <faq>
+    reference
     copyright

docs/installation.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 ======================
 Installing ramsey/uuid
 ======================

docs/nonstandard/comb.rst

@@ -1,3 +1,5 @@
+.. _nonstandard.codec.comb:
+
 =====
 COMBs
 =====

docs/nonstandard/guid.rst

@@ -1,3 +1,5 @@
+.. _nonstandard.codec.guid:
+
 =====
 GUIDs
 =====

docs/nonstandard/ordered-time.rst

@@ -1,3 +1,5 @@
+.. _nonstandard.codec.ordered-time:
+
 ============
 Ordered Time
 ============

docs/nonstandard/version6.rst

@@ -1,3 +1,5 @@
+.. _nonstandard.version6:
+
 =======================
 Version 6: Ordered Time
 =======================

docs/quickstart.rst

@@ -1,4 +1,70 @@
+.. _quickstart:
+
 ===============
 Getting Started
 ===============
 
+After :ref:`installing ramsey/uuid <installation>`, the quickest way to get
+up-and-running is to use the static generation methods.
+
+.. code-block:: php
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid4();
+
+    printf(
+        "UUID: %s\nVersion: %d\n",
+        $uuid->toString(),
+        $uuid->getFields()->getVersion()
+    );
+
+This will return an instance of ``Ramsey\Uuid\Rfc4122\UuidV4``.
+
+.. tip::
+    .. rubric:: Use the Interfaces
+
+    Feel free to use ``instanceof`` to check the specific instance types of
+    UUIDs. However, when using type hints, it's best to use the interfaces.
+
+    The most lenient interface is ``Ramsey\Uuid\UuidInterface``, while
+    ``Ramsey\Uuid\Rfc4122\UuidInterface`` ensures the UUIDs you're using conform
+    to the `RFC 4122`_ standard. If you're not sure which one to use, start with
+    the stricter ``Ramsey\Uuid\Rfc4122\UuidInterface``.
+
+ramsey/uuid provides a number of helpful static methods that help you work with
+and generate most types of UUIDs, without any special customization of the
+library.
+
+.. list-table::
+    :widths: 25 75
+    :width: 100%
+    :align: center
+    :header-rows: 1
+
+    * - Method
+      - Description
+    * - :php:meth:`Uuid::uuid1() <Ramsey\\Uuid\\Uuid::uuid1>`
+      - This generates a :ref:`rfc4122.version1` UUID.
+    * - :php:meth:`Uuid::uuid2() <Ramsey\\Uuid\\Uuid::uuid2>`
+      - This generates a :ref:`rfc4122.version2` UUID.
+    * - :php:meth:`Uuid::uuid3() <Ramsey\\Uuid\\Uuid::uuid3>`
+      - This generates a :ref:`rfc4122.version3` UUID.
+    * - :php:meth:`Uuid::uuid4() <Ramsey\\Uuid\\Uuid::uuid4>`
+      - This generates a :ref:`rfc4122.version4` UUID.
+    * - :php:meth:`Uuid::uuid5() <Ramsey\\Uuid\\Uuid::uuid5>`
+      - This generates a :ref:`rfc4122.version5` UUID.
+    * - :php:meth:`Uuid::uuid6() <Ramsey\\Uuid\\Uuid::uuid6>`
+      - This generates a :ref:`nonstandard.version6` UUID.
+    * - :php:meth:`Uuid::isValid() <Ramsey\\Uuid\\Uuid::isValid>`
+      - Checks whether a string is a valid UUID.
+    * - :php:meth:`Uuid::fromString() <Ramsey\\Uuid\\Uuid::fromString>`
+      - Creates a UUID instance from a string UUID.
+    * - :php:meth:`Uuid::fromBytes() <Ramsey\\Uuid\\Uuid::fromBytes>`
+      - Creates a UUID instance from a 16-byte string.
+    * - :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``.
+
+.. _RFC 4122: https://tools.ietf.org/html/rfc4122

docs/reference.rst

@@ -0,0 +1,14 @@
+.. _reference:
+
+=========
+Reference
+=========
+
+.. toctree::
+    :titlesonly:
+
+    reference/uuid
+    reference/rfc4122-uuidinterface
+    reference/rfc4122-fieldsinterface
+    reference/helper
+    reference/name-based-namespaces

docs/reference/helper.rst

@@ -0,0 +1,56 @@
+.. _reference.helper:
+
+================
+Helper Functions
+================
+
+ramsey/uuid additionally provides the following helper functions, which return
+only the string standard representation of a UUID.
+
+.. php:function:: Ramsey\\Uuid\\v1([$node[, $clockSeq]])
+
+    Generates a string standard representation of a version 1, time-based UUID.
+
+    :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
+    :param int|null $clockSeq: An optional clock sequence to use
+    :returns: (*string*) A string standard representation of a version 1 UUID
+
+.. php:function:: Ramsey\\Uuid\\v2($localDomain[, $localIdentifier[, $node[, $clockSeq]]])
+
+    Generates a string standard representation of a version 2, DCE Security UUID.
+
+    :param int $localDomain: The local domain to use (one of ``Uuid::DCE_DOMAIN_PERSON``, ``Uuid::DCE_DOMAIN_GROUP``, or ``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: (*string*) A string standard representation of a version 2 UUID
+
+.. php:function:: Ramsey\\Uuid\\v3($ns, $name)
+
+    Generates a string standard representation of a version 3, name-based (MD5) UUID.
+
+    :param Ramsey\\Uuid\\UuidInterface|string $ns: The namespace for this identifier
+    :param string $name: The name from which to generate an identifier
+    :returns: (*string*) A string standard representation of a version 3 UUID
+
+.. php:function:: Ramsey\\Uuid\\v4()
+
+    Generates a string standard representation of a version 4, random UUID.
+
+    :returns: (*string*) A string standard representation of a version 4 UUID
+
+.. php:function:: Ramsey\\Uuid\\v5($ns, $name)
+
+    Generates a string standard representation of a version 5, name-based (SHA-1) UUID.
+
+    :param Ramsey\\Uuid\\UuidInterface|string $ns: The namespace for this identifier
+    :param string $name: The name from which to generate an identifier
+    :returns: (*string*) A string standard representation of a version 5 UUID
+
+.. php:function:: Ramsey\\Uuid\\v6([$node[, $clockSeq]])
+
+    Generates a string standard representation of a version 6, ordered-time UUID.
+
+    :param Ramsey\\Uuid\\Type\\Hexadecimal|null $node: An optional hexadecimal node to use
+    :param int|null $clockSeq: An optional clock sequence to use
+    :returns: (*string*) A string standard representation of a version 6 UUID

docs/reference/name-based-namespaces.rst

@@ -0,0 +1,32 @@
+.. _reference.name-based-namespaces:
+
+=====================
+Predefined Namespaces
+=====================
+
+`RFC 4122`_ defines a handful of UUIDs to use with "for some potentially
+interesting name spaces."
+
+.. list-table::
+    :widths: 30 70
+    :width: 100%
+    :align: center
+    :header-rows: 1
+
+    * - Constant
+      - Description
+    * - :php:const:`Uuid::NAMESPACE_DNS <Ramsey\\Uuid\\Uuid::NAMESPACE_DNS>`
+      - The name string is a fully-qualified domain name.
+    * - :php:const:`Uuid::NAMESPACE_URL <Ramsey\\Uuid\\Uuid::NAMESPACE_URL>`
+      - The name string is URL.
+    * - :php:const:`Uuid::NAMESPACE_OID <Ramsey\\Uuid\\Uuid::NAMESPACE_OID>`
+      - The name string is an `ISO object identifier (OID)`_.
+    * - :php:const:`Uuid::NAMESPACE_X500 <Ramsey\\Uuid\\Uuid::NAMESPACE_X500>`
+      - The name string is an `X.500`_ `DN`_ in `DER`_ or a text output format.
+
+
+.. _RFC 4122: https://tools.ietf.org/html/rfc4122
+.. _ISO object identifier (OID): http://www.oid-info.com
+.. _X.500: https://en.wikipedia.org/wiki/X.500
+.. _DN: https://en.wikipedia.org/wiki/Distinguished_Name
+.. _DER: https://www.itu.int/rec/T-REC-X.690/

docs/reference/rfc4122-fieldsinterface.rst

@@ -0,0 +1,69 @@
+.. _reference.rfc4122.fieldsinterface:
+
+========================
+Rfc4122\\FieldsInterface
+========================
+
+All RFC 4122 UUID instances in ramsey/uuid implement a ``getFields()`` method
+that returns an instance of ``Rfc4122\FieldsInterface``.
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:interface:: FieldsInterface
+
+    Represents the fields of an RFC 4122 UUID.
+
+    .. php:method:: getBytes()
+
+        :returns: (*string*) The bytes that comprise these fields.
+
+    .. php:method:: getClockSeq()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The full 16-bit clock sequence, with the variant bits (two most significant bits) masked out.
+
+    .. php:method:: getClockSeqHiAndReserved()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The high field of the clock sequence multiplexed with the variant.
+
+    .. php:method:: getClockSeqLow()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The low field of the clock sequence.
+
+    .. php:method:: getNode()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The node field.
+
+    .. php:method:: getTimeHiAndVersion()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The high field of the timestamp multiplexed with the version.
+
+    .. php:method:: getTimeLow()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The low field of the timestamp.
+
+    .. php:method:: getTimeMid()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The middle field of the timestamp.
+
+    .. php:method:: getTimestamp()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The full 60-bit timestamp, without the version.
+
+    .. php:method:: getVariant()
+
+        Returns the variant, which, for RFC 4122 variant UUIDs, should always be
+        the value ``2``.
+
+        :returns: (*int*) The UUID variant.
+
+    .. php:method:: getVersion()
+
+        :returns: (*int*) The UUID version.
+
+    .. php:method:: isNil()
+
+        A *nil* UUID is a special type of UUID with all 128 bits set to zero.
+        Its string standard representation is always
+        ``00000000-0000-0000-0000-000000000000``.
+
+        :returns: (*bool*) True if this UUID represents a nil UUID.

docs/reference/rfc4122-uuidinterface.rst

@@ -0,0 +1,50 @@
+.. _reference.rfc4122.uuidinterface:
+
+======================
+Rfc4122\\UuidInterface
+======================
+
+All RFC 4122 UUID instances in ramsey/uuid implement the following interface.
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:interface:: UuidInterface
+
+    Represents an RFC 4122 UUID.
+
+    .. php:method:: compareTo($other)
+
+        :param Ramsey\\Uuid\\UuidInterface $other: The UUID to compare
+        :returns: (*int*) Returns ``-1``, ``0``, or ``1`` if the UUID is less than, equal to, or greater than the other UUID.
+
+    .. php:method:: equals($other)
+
+        :param object|null $other: An object to test for equality with this UUID.
+        :returns: (*bool*) Returns true if the UUID is equal to the provided object.
+
+    .. php:method:: getBytes()
+
+        :returns: (*string*) A binary string representation of the UUID.
+
+    .. php:method:: getFields()
+
+        :returns: (:php:interface:`Ramsey\\Uuid\\Rfc4122\\FieldsInterface`) The fields that comprise this UUID.
+
+    .. php:method:: getHex()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The hexadecimal representation of the UUID.
+
+    .. php:method:: getInteger()
+
+        :returns: (*Ramsey\\Uuid\\Type\\Integer*) The integer representation of the UUID.
+
+    .. php:method:: toString()
+
+        :returns: (*string*) The string standard representation of the UUID.
+
+    .. php:method:: getUrn()
+
+        :returns: (*string*) The string standard representation of the UUID as a `URN`_.
+
+
+.. _URN: https://tools.ietf.org/html/rfc8141

docs/reference/uuid.rst

@@ -0,0 +1,115 @@
+.. _reference.uuid:
+
+====
+Uuid
+====
+
+``Ramsey\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.
+
+.. php:namespace:: Ramsey\Uuid
+
+.. php:class:: Uuid
+
+    .. php:staticmethod:: 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: (*Ramsey\\Uuid\\Rfc4122\\UuidV1*) A version 1 UUID
+
+    .. php:staticmethod:: 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 ``Uuid::DCE_DOMAIN_PERSON``, ``Uuid::DCE_DOMAIN_GROUP``, or ``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: (*Ramsey\\Uuid\\Rfc4122\\UuidV2*) A version 2 UUID
+
+    .. php:staticmethod:: 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: (*Ramsey\\Uuid\\Rfc4122\\UuidV3*) A version 3 UUID
+
+    .. php:staticmethod:: uuid4()
+
+        Generates a version 4, random UUID. See :ref:`rfc4122.version4`.
+
+        :returns: (*Ramsey\\Uuid\\Rfc4122\\UuidV4*) A version 4 UUID
+
+    .. php:staticmethod:: 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: (*Ramsey\\Uuid\\Rfc4122\\UuidV5*) A version 5 UUID
+
+    .. php:staticmethod:: 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: (*Ramsey\\Uuid\\Nonstandard\\UuidV6*) A version 6 UUID
+
+    .. php:staticmethod:: fromString($uuid)
+
+        Creates an instance of ``UuidInterface`` from the string standard
+        representation.
+
+        :param string $uuid: The string standard representation of a UUID
+        :returns: (*Ramsey\\Uuid\\UuidInterface*) An instance of ``UuidInterface``
+
+    .. php:staticmethod:: fromBytes($bytes)
+
+        Creates an instance of ``UuidInterface`` from a 16-byte string.
+
+        :param string $bytes: A 16-byte binary string representation of a UUID
+        :returns: (*Ramsey\\Uuid\\UuidInterface*) An instance of ``UuidInterface``
+
+    .. php:staticmethod:: 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
+        :returns: (*Ramsey\\Uuid\\UuidInterface*) An instance of ``UuidInterface``
+
+    .. php:staticmethod:: fromDateTime($dateTime[, $node[, $clockSeq]])
+
+        Creates a version 1 UUID instance from a ``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: (*Ramsey\\Uuid\\Rfc4122\\UuidV1*) A version 1 UUID
+
+    .. php:staticmethod:: isValid($uuid)
+
+        Validates the string standard representation of a UUID
+
+        :param string $uuid: The string standard representation of a UUID
+        :returns: True if the string UUID is valid, false otherwise
+
+    .. php:const:: NAMESPACE_DNS
+
+        6ba7b810-9dad-11d1-80b4-00c04fd430c8
+
+    .. php:const:: NAMESPACE_URL
+
+        6ba7b811-9dad-11d1-80b4-00c04fd430c8
+
+    .. php:const:: NAMESPACE_OID
+
+        6ba7b812-9dad-11d1-80b4-00c04fd430c8
+
+    .. php:const:: NAMESPACE_X500
+
+        6ba7b814-9dad-11d1-80b4-00c04fd430c8

docs/requirements.txt

@@ -1,2 +1,3 @@
-Sphinx==2.4.3
+Sphinx==2.2.2
 sphinx-rtd-theme==0.4.3
+sphinxcontrib-phpdomain==0.6.3

docs/rfc4122.rst

@@ -1,3 +1,5 @@
+.. _rfc4122:
+
 ==============
 RFC 4122 UUIDs
 ==============

docs/rfc4122/version1.rst

@@ -1,3 +1,5 @@
+.. _rfc4122.version1:
+
 =====================
 Version 1: Time-based
 =====================
@@ -33,9 +35,13 @@ will generate a random node.
 
     $uuid = Uuid::uuid1();
 
-    echo $uuid->toString() . "\n";
-    echo $uuid->getDateTime()->format('r') . "\n";
-    echo $uuid->getFields()->getNode()->toString() . "\n";
+    printf(
+        "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\n",
+        $uuid->toString(),
+        $uuid->getFields()->getVersion(),
+        $uuid->getDateTime()->format('r'),
+        $uuid->getFields()->getNode()->toString()
+    );
 
 This will generate a version 1 UUID and print out its string representation, the
 time the UUID was created, and the node used to create the UUID.
@@ -44,9 +50,35 @@ It will look something like this:
 
 .. code-block:: text
 
-    ba1fe680-5b3b-11ea-8009-acde48001122
-    Sat, 29 Feb 2020 21:37:47 +0000
-    acde48001122
+    UUID: e22e1622-5c14-11ea-b2f3-acde48001122
+    Version: 1
+    Date: Sun, 01 Mar 2020 23:32:15 +0000
+    Node: acde48001122
+
+After creating a ``UuidInterface`` object from a string (or bytes), you can
+check to see if it's a version 1 UUID by checking its instance type.
+
+.. code-block:: php
+
+    use Ramsey\Uuid\Rfc4122\UuidV1;
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::fromString('200e43fa-5c14-11ea-bc55-0242ac130003');
+
+    if ($uuid instanceof UuidV1) {
+        printf(
+            "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\n",
+            $uuid->toString(),
+            $uuid->getFields()->getVersion(),
+            $uuid->getDateTime()->format('r'),
+            $uuid->getFields()->getNode()->toString()
+        );
+    }
+
+.. tip::
+    Check out the :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface` API
+    documentation to learn more about what you can do with a ``UuidV1``
+    instance.
 
 
 Random or Custom Node

docs/rfc4122/version2.rst

@@ -1,3 +1,5 @@
+.. _rfc4122.version2:
+
 =======================
 Version 2: DCE Security
 =======================

docs/rfc4122/version3.rst

@@ -1,3 +1,78 @@
+.. _rfc4122.version3:
+
 ===========================
 Version 3: Name-based (MD5)
 ===========================
+
+The first thing that comes to mind with most people think of a UUID is a
+*random* identifier, but name-based UUIDs aren't random at all. In fact, they're
+deterministic. For any given identical namespace and name, you will always
+generate the same UUID.
+
+Name-based UUIDs are useful when you need an identifier that's based on
+something's name and will always be the same for that name.
+
+For example, let's say I want to create an identifier for a URL. I could use
+a :ref:`version 1 <rfc4122.version1>` or :ref:`version 4 <rfc4122.version4>`
+UUID to create an identifier for the URL, but what if I'm working with a
+distributed system, and I want to ensure that every client in this system can
+always generate the same identifier for any given URL in the system?
+
+This is where a name-based UUID comes in handy.
+
+Name-based UUIDs combine a namespace with a name. This way, the UUIDs are unique
+to the namespace they're created in. RFC 4122 defines some
+:ref:`predefined namespaces <reference.name-based-namespaces>`, one of which is
+for URLs.
+
+.. code-block:: php
+    :caption: Generate a name-based UUID for a URL
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid3(Uuid::NAMESPACE_URL, 'https://www.php.net');
+
+The UUID generated will always be the same, as long as the namespace and name
+are the same.
+
+.. hint::
+    The version 3 UUID for "https://www.php.net" in the URL namespace will
+    always be ``3f703955-aaba-3e70-a3cb-baff6aa3b28f``. See for yourself. Run
+    the code above, and you'll see it always generates the same UUID.
+
+
+.. _rfc4122.version3.custom-namespaces:
+
+Custom Namespaces
+#################
+
+If you're working with name-based UUIDs for names that don't fit into any of
+the :ref:`predefined namespaces <reference.name-based-namespaces>`, or you don't
+want to use any of the predefined namespaces, you can create your own namespace.
+
+The best way to do this is to generate a :ref:`version 1 <rfc4122.version1>` or
+:ref:`version 4 <rfc4122.version4>` UUID and save this UUID as your namespace.
+
+.. code-block:: php
+    :caption: Generate a custom namespace UUID
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid4();
+
+    printf("My namespace UUID is %s\n", $uuid->toString());
+
+This will generate a random UUID, which we'll store to a constant so we can
+reuse it as our own custom namespace.
+
+.. code-block:: php
+    :caption: Use a custom namespace to create name-based UUIDs
+
+    use Ramsey\Uuid\Uuid;
+
+    const MY_NAMESPACE = '9a494836-ef67-4c63-a27b-15bc5a17e0ed';
+
+    $uuid = Uuid::uuid3(MY_NAMESPACE, 'widget/1234567890');
+
+With this custom namespace, the version 3 UUID for the name "widget/1234567890"
+will always be ``f8e9b8cf-43a2-378b-9de0-aa714f6e989b``.

docs/rfc4122/version4.rst

@@ -1,3 +1,43 @@
+.. _rfc4122.version4:
+
 =================
 Version 4: Random
 =================
+
+Version 4 UUIDs are perhaps the most popular form of UUID. They are
+randomly-generated and do not contain any information about the time they are
+created or the machine that generated them. If you don't care about this
+information, then a version 4 UUID might be perfect for your needs.
+
+To generate a version 4 UUID, you may use the ``Uuid::uuid4()`` static method.
+
+.. code-block:: php
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid4();
+
+    printf(
+        "UUID: %s\nVersion: %d\n",
+        $uuid->toString(),
+        $uuid->getFields()->getVersion()
+    );
+
+After creating a ``UuidInterface`` object from a string (or bytes), you can
+check to see if it's a version 4 UUID by checking its instance type.
+
+.. code-block:: php
+
+    use Ramsey\Uuid\Rfc4122\UuidV4;
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::fromString('6b8d3b65-a527-49d5-b6dc-cf195877feef');
+
+    if ($uuid instanceof UuidV4) {
+        printf("%s is a version 4 UUID!\n", $uuid->toString());
+    }
+
+.. tip::
+    Check out the :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface` API
+    documentation to learn more about what you can do with a ``UuidV4``
+    instance.

docs/rfc4122/version5.rst

@@ -1,3 +1,5 @@
+.. _rfc4122.version5:
+
 =============================
 Version 5: Name-based (SHA-1)
 =============================

docs/test.php

@@ -2,23 +2,10 @@
 
 require_once '../vendor/autoload.php';
 
-use Ramsey\Uuid\FeatureSet;
-use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
-use Ramsey\Uuid\Type\Hexadecimal;
 use Ramsey\Uuid\Uuid;
-use Ramsey\Uuid\UuidFactory;
 
-$nodeProvider = new StaticNodeProvider(new Hexadecimal('1234567890ab'));
+const MY_NAMESPACE = '9a494836-ef67-4c63-a27b-15bc5a17e0ed';
 
-$featureSet = new FeatureSet();
-$featureSet->setNodeProvider($nodeProvider);
+$uuid = Uuid::uuid3(MY_NAMESPACE, 'widget/1234567890');
 
-$factory = new UuidFactory($featureSet);
-
-Uuid::setFactory($factory);
-
-$uuid = Uuid::uuid1();
-
-echo $uuid->toString() . "\n";
-echo $uuid->getDateTime()->format('r') . "\n";
-echo $uuid->getFields()->getNode()->toString() . "\n";
+printf("UUID: %s\n", $uuid->toString());

docs/upgrading.rst

@@ -1,9 +1,11 @@
+.. _upgrading:
+
 =====================
 Upgrading ramsey/uuid
 =====================
 
 .. toctree::
-   :titlesonly:
+    :titlesonly:
 
-   upgrading/3-to-4
-   upgrading/2-to-3
+    upgrading/3-to-4
+    upgrading/2-to-3

src/Rfc4122/UuidInterface.php

@@ -27,7 +27,7 @@ use Ramsey\Uuid\UuidInterface as BaseUuidInterface;
 interface UuidInterface extends BaseUuidInterface
 {
     /**
-     * Returns the string representation of the UUID as a URN
+     * Returns the string standard representation of the UUID as a URN
      *
      * @link http://en.wikipedia.org/wiki/Uniform_Resource_Name Uniform Resource Name
      * @link https://tools.ietf.org/html/rfc4122#section-3 RFC 4122, § 3: Namespace Registration Template

src/Uuid.php

@@ -27,17 +27,7 @@ use function str_replace;
 use function strcmp;
 
 /**
- * Represents a RFC 4122 universally unique identifier (UUID)
- *
- * This class provides immutable UUID objects (the Uuid class) and the static
- * methods `uuid1()`, `uuid3()`, `uuid4()`, and `uuid5()` for generating version
- * 1, 3, 4, and 5 UUIDs as specified in RFC 4122.
- *
- * If all you want is a unique ID, you should probably call `uuid1()` or `uuid4()`.
- * Note that `uuid1()` may compromise privacy since it creates a UUID containing
- * the computer’s network address. `uuid4()` creates a random UUID.
- *
- * @link http://tools.ietf.org/html/rfc4122 RFC 4122
+ * Uuid provides constants and static methods for working with and generating UUIDs
  *
  * @psalm-immutable
  */

src/UuidInterface.php

@@ -74,24 +74,24 @@ interface UuidInterface extends
     public function getFields(): FieldsInterface;
 
     /**
-     * Returns the hexadecimal string representation of the UUID
+     * Returns the hexadecimal representation of the UUID
      */
     public function getHex(): Hexadecimal;
 
     /**
-     * Returns the integer value of the UUID as a string
+     * Returns the integer representation of the UUID
      */
     public function getInteger(): IntegerObject;
 
     /**
-     * Returns a string representation of the UUID
+     * Returns the string standard representation of the UUID
      *
      * @psalm-return non-empty-string
      */
     public function toString(): string;
 
     /**
-     * Casts the UUID to a string representation
+     * Casts the UUID to the string standard representation
      *
      * @psalm-return non-empty-string
      */