Improve documentation

docs/conf.py

@@ -13,6 +13,7 @@
 import os
 import sphinx_rtd_theme
 import sys
+import datetime
 
 from pygments.lexers.web import PhpLexer
 from sphinx.highlighting import lexers
@@ -40,6 +41,8 @@ author = 'Ben Ramsey'
 version = get_version().strip()
 release = version
 
+today = datetime.date.today().strftime('%Y-%m-%d')
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -55,6 +58,7 @@ lexers['php-annotations'] = PhpLexer(startinline=True)
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
     'sphinxcontrib.phpdomain',
 ]
 

docs/index.rst

@@ -2,7 +2,7 @@
 ramsey/uuid Manual
 ==================
 
-For ramsey/uuid |version|. Updated on |today|.
+For `ramsey/uuid <https://github.com/ramsey/uuid>`_ |version|. Updated on |today|.
 
 This work is licensed under the `Creative Commons Attribution 4.0 International
 <https://creativecommons.org/licenses/by/4.0/>`_ license.
@@ -14,7 +14,6 @@ This work is licensed under the `Creative Commons Attribution 4.0 International
     :caption: Contents
 
     introduction
-    installation
     quickstart
     rfc4122
     nonstandard

docs/introduction.rst

@@ -2,17 +2,17 @@
 Introduction
 ============
 
-ramsey/uuid is a PHP library for generating and working with `RFC 4122`_ version
+ramsey/uuid is a PHP library for generating and working with [RFC4122]_ version
 1, 2, 3, 4, and 5 universally unique identifiers (UUID). ramsey/uuid also
-supports optional and non-standard features, such as `version 6 UUIDs`_,
-`GUIDs`_, and other approaches for encoding/decoding UUIDs.
+supports optional and non-standard features, such as version 6 UUIDs [UUIDV6]_,
+GUIDs, and other approaches for encoding/decoding UUIDs.
 
 What Is a UUID?
 ###############
 
 A universally unique identifier, or UUID, is a 128-bit unsigned integer, usually
 represented as a hexadecimal string split into five groups with dashes. The most
-widely-known and used types of UUIDs are defined by `RFC 4122`_.
+widely-known and used types of UUIDs are defined by [RFC4122]_.
 
 A UUID, when encoded in hexadecimal string format, looks like:
 
@@ -24,8 +24,3 @@ The probability of duplicating a UUID is close to zero, so they are a great
 choice for generating unique identifiers in distributed systems.
 
 UUIDs can also be stored in binary format, as a string of 16 bytes.
-
-
-.. _RFC 4122: https://tools.ietf.org/html/rfc4122
-.. _version 6 UUIDs: http://gh.peabody.io/uuidv6/
-.. _GUIDs: https://docs.microsoft.com/en-us/dotnet/api/system.guid

docs/quickstart.rst

@@ -4,8 +4,47 @@
 Getting Started
 ===============
 
-After :ref:`installing ramsey/uuid <installation>`, the quickest way to get
-up-and-running is to use the static generation methods.
+
+Requirements
+############
+
+ramsey/uuid |version| requires the following:
+
+* PHP 7.2+
+* `ext-json <https://www.php.net/manual/en/book.json.php>`_
+
+The JSON extension is normally enabled by default, but it is possible to disable
+it. Other required extensions include
+`PCRE <https://www.php.net/manual/en/book.pcre.php>`_
+and `SPL <https://www.php.net/manual/en/book.spl.php>`_. These standard
+extensions cannot be disabled without patching PHP's build system and/or C
+sources.
+
+ramsey/uuid recommends installing/enabling the following extensions. While not
+required, these extensions improve the performance of ramsey/uuid.
+
+* `ext-ctype <https://www.php.net/manual/en/book.ctype.php>`_
+* `ext-gmp <https://www.php.net/manual/en/book.gmp.php>`_
+* `ext-bcmath <https://www.php.net/manual/en/book.bc.php>`_
+
+
+Install With Composer
+#####################
+
+The only supported installation method for ramsey/uuid is
+`Composer <https://getcomposer.org>`_. Use the following command to add
+ramsey/uuid to your project dependencies:
+
+.. code-block:: bash
+
+    composer require ramsey/uuid
+
+
+Using ramsey/uuid
+#################
+
+After installing ramsey/uuid, the quickest way to get up-and-running is to use
+the static generation methods.
 
 .. code-block:: php
 

docs/reference.rst

@@ -8,9 +8,18 @@ Reference
     :titlesonly:
 
     reference/uuid
+    reference/uuidinterface
+    reference/fields-fieldsinterface
     reference/rfc4122-uuidinterface
     reference/rfc4122-fieldsinterface
     reference/rfc4122-uuidv1
+    reference/rfc4122-uuidv2
+    reference/rfc4122-uuidv3
+    reference/rfc4122-uuidv4
+    reference/rfc4122-uuidv5
+    reference/nonstandard-uuidv6
+    reference/types
     reference/exceptions
     reference/helper
     reference/name-based-namespaces
+    reference/references

docs/reference/fields-fieldsinterface.rst

@@ -0,0 +1,16 @@
+.. _reference.fields.fieldsinterface:
+
+========================
+Fields\\FieldsInterface
+========================
+
+.. php:namespace:: Ramsey\Uuid\Fields
+
+.. php:interface:: FieldsInterface
+
+    Represents the fields of a UUID.
+
+    .. php:method:: getBytes()
+
+        :returns: The bytes that comprise these fields.
+        :returntype: ``string``

docs/reference/helper.rst

@@ -13,7 +13,8 @@ only the string standard representation of a 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
+    :returns: A string standard representation of a version 1 UUID
+    :returntype: string
 
 .. php:function:: Ramsey\\Uuid\\v2($localDomain[, $localIdentifier[, $node[, $clockSeq]]])
 
@@ -23,7 +24,8 @@ only the string standard representation of a UUID.
     :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
+    :returns: A string standard representation of a version 2 UUID
+    :returntype: string
 
 .. php:function:: Ramsey\\Uuid\\v3($ns, $name)
 
@@ -31,13 +33,15 @@ only the string standard representation of a 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
+    :returns: A string standard representation of a version 3 UUID
+    :returntype: string
 
 .. 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
+    :returns: A string standard representation of a version 4 UUID
+    :returntype: string
 
 .. php:function:: Ramsey\\Uuid\\v5($ns, $name)
 
@@ -45,7 +49,8 @@ only the string standard representation of a 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
+    :returns: A string standard representation of a version 5 UUID
+    :returntype: string
 
 .. php:function:: Ramsey\\Uuid\\v6([$node[, $clockSeq]])
 
@@ -53,4 +58,5 @@ only the string standard representation of a 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
+    :returns: A string standard representation of a version 6 UUID
+    :returntype: string

docs/reference/nonstandard-uuidv6.rst

@@ -0,0 +1,38 @@
+.. _reference.nonstandard.uuidv6:
+
+===================
+Nonstandard\\UuidV6
+===================
+
+.. php:namespace:: Ramsey\Uuid\Nonstandard
+
+.. php:class:: UuidV6
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
+
+    While in the Nonstandard sub-namespace, UuidV6 implements the same interface
+    as the RFC 4122 UUIDs. This is because the definition for version 6 UUIDs is
+    `currently in draft form`_, with the intent to update RFC 4122.
+
+    UuidV6 represents a :ref:`version 6, ordered-time UUID
+    <nonstandard.version6>`. In addition to providing the methods defined on the
+    interface, this class additionally provides the following methods.
+
+    .. php:method:: getDateTime()
+
+        :returns: A date object representing the timestamp associated with the UUID
+        :returntype: ``\DateTimeInterface``
+
+    .. php:method:: toUuidV1()
+
+        :returns: A version 1 UUID, converted from this version 6 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1
+
+    .. php:staticmethod:: fromUuidV1()
+
+        :param Ramsey\\Uuid\\Rfc4122\\UuidV1 $uuidV1: A version 1 UUID
+        :returns: A version 6 UUID, converted from the given version 1 UUID
+        :returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6
+
+
+.. _currently in draft form: https://tools.ietf.org/html/draft-peabody-dispatch-new-uuid-format-00

docs/reference/references.rst

@@ -0,0 +1,25 @@
+.. _reference.references:
+
+==========
+References
+==========
+
+.. [DCE11SEC] Open Group. (1997). *DCE 1.1: Authentication and Security Services*
+    (Document No. C311). Retrieved from https://publications.opengroup.org/c311
+
+.. [RFC4122] Leach, P., Mealling, M., & Salz, R. (2005, July). A universally
+    unique identifier (UUID) URN namespace. *Internet Requests for Comments*
+    (RFC 4122). RFC Editor. Retrieved from https://www.rfc-editor.org/rfc/rfc4122.html
+
+.. [UUIDV6] Peabody, B. (2020, February 24). UUID format update. *Internet
+    Drafts* (draft-peabody-dispatch-new-uuid-format-00). Working Draft, IETF
+    Secretariat. Retrieved from
+    https://tools.ietf.org/html/draft-peabody-dispatch-new-uuid-format-00
+
+.. [RFC1321] Rivest, R. (1992, April). The MD5 message-digest algorithm.
+    *Internet Requests for Comments* (RFC 1321). RFC Editor. Retrieved from
+    https://www.rfc-editor.org/rfc/rfc1321.html
+
+.. [SHA1] U.S. Department of Commerce, National Institute of Standards and
+    Technology. (2015). *Secure Hash Standard (SHS)* (FIPS PUB 180-4). Retrieved
+    from http://dx.doi.org/10.6028/NIST.FIPS.180-4

docs/reference/rfc4122-fieldsinterface.rst

@@ -4,61 +4,68 @@
 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.
+    Implements :php:interface:`Ramsey\\Uuid\\Fields\\FieldsInterface`.
 
-    .. php:method:: getBytes()
-
-        :returns: (*string*) The bytes that comprise these fields.
+    ``Rfc4122\FieldsInterface`` represents the fields of an RFC 4122 UUID.
+    In addition to providing the methods defined on the interface, this class
+    additionally provides the following methods.
 
     .. php:method:: getClockSeq()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The full 16-bit clock sequence, with the variant bits (two most significant bits) masked out.
+        :returns: The full 16-bit clock sequence, with the variant bits (two most significant bits) masked out.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getClockSeqHiAndReserved()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The high field of the clock sequence multiplexed with the variant.
+        :returns: The high field of the clock sequence multiplexed with the variant.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getClockSeqLow()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The low field of the clock sequence.
+        :returns: The low field of the clock sequence.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getNode()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The node field.
+        :returns: The node field.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getTimeHiAndVersion()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The high field of the timestamp multiplexed with the version.
+        :returns: The high field of the timestamp multiplexed with the version.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getTimeLow()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The low field of the timestamp.
+        :returns: The low field of the timestamp.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getTimeMid()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The middle field of the timestamp.
+        :returns: The middle field of the timestamp.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getTimestamp()
 
-        :returns: (*Ramsey\\Uuid\\Type\\Hexadecimal*) The full 60-bit timestamp, without the version.
+        :returns: The full 60-bit timestamp, without the version.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
 
     .. php:method:: getVariant()
 
         Returns the variant, which, for RFC 4122 variant UUIDs, should always be
         the value ``2``.
 
-        :returns: (*int*) The UUID variant.
+        :returns: The UUID variant.
+        :returntype: ``int``
 
     .. php:method:: getVersion()
 
-        :returns: (*int*) The UUID version.
+        :returns: The UUID version.
+        :returntype: ``int``
 
     .. php:method:: isNil()
 
@@ -66,4 +73,5 @@ that returns an instance of ``Rfc4122\FieldsInterface``.
         Its string standard representation is always
         ``00000000-0000-0000-0000-000000000000``.
 
-        :returns: (*bool*) True if this UUID represents a nil UUID.
+        :returns: True if this UUID represents a nil UUID.
+        :returntype: ``bool``

docs/reference/rfc4122-uuidinterface.rst

@@ -4,47 +4,25 @@
 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.
+    Implements :php:interface:`Ramsey\\Uuid\\UuidInterface`.
 
-    .. 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.
+    ``Rfc4122\UuidInterface`` represents an RFC 4122 UUID.
+    In addition to providing the methods defined on the interface, this class
+    additionally provides the following methods.
 
     .. 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.
+        :returns: The fields that comprise this UUID.
+        :returntype: Ramsey\\Uuid\\Rfc4122\\FieldsInterface
 
     .. php:method:: getUrn()
 
-        :returns: (*string*) The string standard representation of the UUID as a `URN`_.
+        :returns: The string standard representation of the UUID as a `URN`_.
+        :returntype: ``string``
 
 
 .. _URN: https://tools.ietf.org/html/rfc8141

docs/reference/rfc4122-uuidv1.rst

@@ -16,4 +16,5 @@ Rfc4122\\UuidV1
 
     .. php:method:: getDateTime()
 
-        :returns: (*\\DateTimeInterface*) A date object representing the timestamp associated with the UUID.
+        :returns: A date object representing the timestamp associated with the UUID.
+        :returntype: ``\DateTimeInterface``

docs/reference/rfc4122-uuidv2.rst

@@ -0,0 +1,53 @@
+.. _reference.rfc4122.uuidv2:
+
+===============
+Rfc4122\\UuidV2
+===============
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:class:: UuidV2
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
+
+    UuidV2 represents a :ref:`version 2, DCE Security UUID <rfc4122.version2>`.
+    In addition to providing the methods defined on the interface, this class
+    additionally provides the following methods.
+
+    .. php:method:: getDateTime()
+
+        Returns a DateTimeInterface object representing the timestamp associated
+        with the UUID
+
+        .. caution::
+
+            It is important to note that a version 2 UUID suffers from some loss of
+            fidelity of the timestamp, due to replacing the ``time_low`` field with
+            the local identifier. When constructing the timestamp value for date
+            purposes, we replace the local identifier bits with zeros. As a result,
+            the timestamp can be off by a range of 0 to 429.4967295 seconds (or
+            about 7 minutes, 9 seconds, and 496730 microseconds).
+
+            Astute observers might note this value directly corresponds to
+            2\ :sup:`32` -- 1, or ``0xffffffff``. The local identifier is 32-bits,
+            and we have set each of these bits to 0, so the maximum range of
+            timestamp drift is ``0x00000000`` to ``0xffffffff`` (counted in
+            100-nanosecond intervals).
+
+        :returns: A date object representing the timestamp associated with the UUID
+        :returntype: ``\DateTimeInterface``
+
+    .. php:method:: getLocalDomain()
+
+        :returns: The local domain identifier for this UUID, which is one of :php:const:`Ramsey\\Uuid\\Uuid::DCE_DOMAIN_PERSON`, :php:const:`Ramsey\\Uuid\\Uuid::DCE_DOMAIN_GROUP`, or :php:const:`Ramsey\\Uuid\\Uuid::DCE_DOMAIN_ORG`
+        :returntype: ``int``
+
+    .. php:method:: getLocalDomainName()
+
+        :returns: A string name associated with the local domain identifier (one of "person," "group," or "org")
+        :returntype: ``string``
+
+    .. php:method:: getLocalIdentifier()
+
+        :returns: The local identifier used when creating this UUID
+        :returntype: Ramsey\\Uuid\\Type\\Integer

docs/reference/rfc4122-uuidv3.rst

@@ -0,0 +1,13 @@
+.. _reference.rfc4122.uuidv3:
+
+===============
+Rfc4122\\UuidV3
+===============
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:class:: UuidV3
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
+
+    UuidV3 represents a :ref:`version 3, name-based (MD5) UUID <rfc4122.version3>`.

docs/reference/rfc4122-uuidv4.rst

@@ -0,0 +1,13 @@
+.. _reference.rfc4122.uuidv4:
+
+===============
+Rfc4122\\UuidV4
+===============
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:class:: UuidV4
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
+
+    UuidV4 represents a :ref:`version 4, random UUID <rfc4122.version4>`.

docs/reference/rfc4122-uuidv5.rst

@@ -0,0 +1,13 @@
+.. _reference.rfc4122.uuidv5:
+
+===============
+Rfc4122\\UuidV5
+===============
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:class:: UuidV5
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface`.
+
+    UuidV5 represents a :ref:`version 5, name-based (SHA-1) UUID <rfc4122.version5>`.

docs/reference/types.rst

@@ -0,0 +1,65 @@
+.. _reference.types:
+
+=====
+Types
+=====
+
+.. php:namespace:: Ramsey\Uuid\Type
+
+.. php:class:: TypeInterface
+
+    Implements ``\JsonSerializable`` and ``\Serializable``.
+
+    TypeInterface ensures consistency in typed values returned by ramsey/uuid.
+
+    .. php:method:: toString()
+
+        :returntype: ``string``
+
+    .. php:method:: __toString()
+
+        :returntype: ``string``
+
+.. php:class:: NumberInterface
+
+    Implements :php:interface:`Ramsey\\Uuid\\Type\\TypeInterface`.
+
+    NumberInterface ensures consistency in numeric values returned by ramsey/uuid.
+
+.. php:class:: Decimal
+
+    Implements :php:interface:`Ramsey\\Uuid\\Type\\NumberInterface`.
+
+    A value object representing a decimal, for type-safety purposes, to ensure
+    that decimals returned from ramsey/uuid methods as strings are truly
+    decimals and not some other kind of string.
+
+    To support values as true decimals and not as floats or doubles, we store
+    the decimals as strings.
+
+.. php:class:: Hexadecimal
+
+    Implements :php:interface:`Ramsey\\Uuid\\Type\\TypeInterface`.
+
+    A value object representing a hexadecimal number, for type-safety purposes,
+    to ensure that hexadecimal numbers returned from ramsey/uuid methods as
+    strings are truly hexadecimal and not some other kind of string.
+
+.. php:class:: Integer
+
+    Implements :php:interface:`Ramsey\\Uuid\\Type\\NumberInterface`.
+
+    A value object representing an integer, for type-safety purposes, to ensure
+    that integers returned from ramsey/uuid methods as strings are truly
+    integers and not some other kind of string.
+
+    To support large integers beyond ``PHP_INT_MAX`` and ``PHP_INT_MIN`` on both
+    64-bit and 32-bit systems, we store the integers as strings.
+
+.. php:class:: Time
+
+    Implements :php:interface:`Ramsey\\Uuid\\Type\\TypeInterface`.
+
+    A value object representing a timestamp, for type-safety purposes, to ensure
+    that timestamps used by ramsey/uuid are truly timestamp integers and not
+    some other kind of string or integer.

docs/reference/uuid.rst

@@ -91,7 +91,8 @@ the ramsey/uuid library.
 
         :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
+        :returns: A version 1 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1
 
     .. php:staticmethod:: uuid2($localDomain[, $localIdentifier[, $node[, $clockSeq]]])
 
@@ -101,7 +102,8 @@ the ramsey/uuid library.
         :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
+        :returns: A version 2 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV2
 
     .. php:staticmethod:: uuid3($ns, $name)
 
@@ -109,13 +111,15 @@ the ramsey/uuid library.
 
         :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
+        :returns: A version 3 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV3
 
     .. php:staticmethod:: uuid4()
 
         Generates a version 4, random UUID. See :ref:`rfc4122.version4`.
 
-        :returns: (*Ramsey\\Uuid\\Rfc4122\\UuidV4*) A version 4 UUID
+        :returns: A version 4 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV4
 
     .. php:staticmethod:: uuid5($ns, $name)
 
@@ -123,7 +127,8 @@ the ramsey/uuid library.
 
         :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
+        :returns: A version 5 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV5
 
     .. php:staticmethod:: uuid6([$node[, $clockSeq]])
 
@@ -131,7 +136,8 @@ the ramsey/uuid library.
 
         :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
+        :returns: A version 6 UUID
+        :returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6
 
     .. php:staticmethod:: fromString($uuid)
 
@@ -139,21 +145,21 @@ the ramsey/uuid library.
         representation.
 
         :param string $uuid: The string standard representation of a UUID
-        :returns: (*Ramsey\\Uuid\\UuidInterface*) An instance of ``UuidInterface``
+        :returntype: Ramsey\\Uuid\\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``
+        :returntype: Ramsey\\Uuid\\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``
+        :returntype: Ramsey\\Uuid\\UuidInterface
 
     .. php:staticmethod:: fromDateTime($dateTime[, $node[, $clockSeq]])
 
@@ -162,14 +168,15 @@ the ramsey/uuid library.
         :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
+        :returns: A version 1 UUID
+        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1
 
     .. 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
+        :returntype: ``bool``
 
 
 .. _ISO object identifier (OID): http://www.oid-info.com

docs/reference/uuidinterface.rst

@@ -0,0 +1,48 @@
+.. _reference.uuidinterface:
+
+=============
+UuidInterface
+=============
+
+.. php:namespace:: Ramsey\Uuid
+
+.. php:interface:: UuidInterface
+
+    Represents a UUID.
+
+    .. php:method:: compareTo($other)
+
+        :param Ramsey\\Uuid\\UuidInterface $other: The UUID to compare
+        :returns: Returns ``-1``, ``0``, or ``1`` if the UUID is less than, equal to, or greater than the other UUID.
+        :returntype: ``int``
+
+    .. php:method:: equals($other)
+
+        :param object|null $other: An object to test for equality with this UUID.
+        :returns: Returns true if the UUID is equal to the provided object.
+        :returntype: ``bool``
+
+    .. php:method:: getBytes()
+
+        :returns: A binary string representation of the UUID.
+        :returntype: ``string``
+
+    .. php:method:: getFields()
+
+        :returns: The fields that comprise this UUID.
+        :returntype: Ramsey\\Uuid\\Fields\\FieldsInterface
+
+    .. php:method:: getHex()
+
+        :returns: The hexadecimal representation of the UUID.
+        :returntype: Ramsey\\Uuid\\Type\\Hexadecimal
+
+    .. php:method:: getInteger()
+
+        :returns: The integer representation of the UUID.
+        :returntype: Ramsey\\Uuid\\Type\\Integer
+
+    .. php:method:: toString()
+
+        :returns: The string standard representation of the UUID.
+        :returntype: ``string``

docs/requirements.txt

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

docs/rfc4122.rst

@@ -14,7 +14,7 @@ RFC 4122 UUIDs
     rfc4122/version4
     rfc4122/version5
 
-`RFC 4122`_ defines five versions of UUID. Each version has different generation
+[RFC4122]_ defines five versions of UUID. Each version has different generation
 algorithms and properties. Which one you choose to use depends on your use-case.
 You can find out more about their applications on the specific page for that
 version.
@@ -43,6 +43,3 @@ Version 5: Named-based (SHA-1)
     This version of UUID hashes together a namespace and a name to create a
     deterministic UUID. The hashing algorithm used is SHA-1. For more details,
     see :doc:`rfc4122/version5`.
-
-
-.. _RFC 4122: https://tools.ietf.org/html/rfc4122

docs/rfc4122/version1.rst

@@ -50,10 +50,10 @@ It will look something like this:
 
 .. code-block:: text
 
-    UUID: e22e1622-5c14-11ea-b2f3-acde48001122
+    UUID: e22e1622-5c14-11ea-b2f3-0242ac130003
     Version: 1
     Date: Sun, 01 Mar 2020 23:32:15 +0000
-    Node: acde48001122
+    Node: 0242ac130003
 
 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.
@@ -114,7 +114,7 @@ You may also set the node value of your choice. In this example, we use
     $uuid = Uuid::uuid1($nodeProvider->getNode());
 
 .. attention::
-    According to RFC 4122, nodes that do not identify the host should set the
+    According to [RFC4122]_, nodes that do not identify the host should set the
     unicast/multicast bit to one (``1``). This bit will never be set in IEEE 802
     addresses obtained from network cards, so it helps to distinguish it from a
     hardware MAC address.
@@ -123,7 +123,7 @@ You may also set the node value of your choice. In this example, we use
     bit for you, so they’re the easiest to use, but if you use a custom node
     provider, be sure to set this bit.
 
-    See `RFC 4122, section 4.5 <https://tools.ietf.org/html/rfc4122#section-4.5>`_,
+    See [RFC4122]_, `section 4.5 <https://tools.ietf.org/html/rfc4122#section-4.5>`_,
     for more details.
 
 

docs/rfc4122/version2.rst

@@ -3,3 +3,99 @@
 =======================
 Version 2: DCE Security
 =======================
+
+Like a :ref:`version 1 UUID <rfc4122.version1>`, a version 2 UUID uses the
+current time, along with the MAC address (or *node*) for a network interface on
+the local machine. Additionally, a version 2 UUID replaces the low part of the
+time field with a local identifier such as the user ID or group ID of the local
+account that created the UUID. This serves three purposes:
+
+1. You can know *when* the identifier was created (see :ref:`rfc4122.version2.caveats`).
+2. You can know *where* the identifier was created.
+3. You can know *who* created the identifier.
+
+In a distributed system, these three pieces of information can be valuable. Not
+only is there no need for a central authority to generate identifiers, but you
+can determine what nodes in your infrastructure created the UUIDs, at what time
+they were created, and the account on the machine that created them.
+
+.. code-block::
+    :caption: Use a domain to generate a version 2, DCE Security UUID
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON);
+
+    printf(
+        "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\nDomain: %s\nID: %s\n",
+        $uuid->toString(),
+        $uuid->getFields()->getVersion(),
+        $uuid->getDateTime()->format('r'),
+        $uuid->getFields()->getNode()->toString(),
+        $uuid->getLocalDomainName(),
+        $uuid->getLocalIdentifier()->toString()
+    );
+
+This will generate a version 2 UUID and print out its string representation, the
+time the UUID was created, and the node used to create it, as well as the name
+of the local domain specified and the local domain identifier (in this case, a
+POSIX UID, automatically obtained from the local machine).
+
+It will look something like this:
+
+.. code-block:: text
+
+    UUID: 000001f5-5e9a-21ea-9e00-0242ac130003
+    Version: 2
+    Date: Thu, 05 Mar 2020 04:30:10 +0000
+    Node: 0242ac130003
+    Domain: person
+    ID: 501
+
+.. todo::
+
+    Needs discussion on domains (list the domains), ability to specify the node
+    and clock sequence (though the lower 8 bits of the clock sequence, originally
+    a 14-bit integer, are replaced with the domain). In theory, 2^8-1 domains
+    could be defined, but only 3 are registered by the DCE specification.
+    Discuss ability to pass the local identifier.
+
+    .. epigraph::
+
+        Note that the [domain] can potentially hold values outside the range
+        [0, 2\ :sup:`8` -- 1]; however, the only values currently registered are in
+        the range [0, 2]… [DCE11SEC]_
+
+
+.. _rfc4122.version2.caveats:
+
+Problems With Version 2 UUIDs
+#############################
+
+Version 2 UUIDs can be useful for the data they contain. However, there are
+trade-offs in choosing to use them.
+
+Lossy Timestamps
+----------------
+
+Version 2 UUIDs are first generated in the same way as version 1 UUIDs, but then
+the low part of the timestamp (the ``time_low`` field) is replaced by a 32-bit
+integer that represents a local identifier, which refers to
+
+It is important to note that a version 2 UUID suffers from some loss of
+fidelity of the timestamp, due to replacing the time_low field with the
+local identifier. When constructing the timestamp value for date
+purposes, we replace the local identifier bits with zeros. As a result,
+the timestamp can be off by a range of 0 to 429.4967295 seconds (or 7
+minutes, 9 seconds, and 496730 microseconds).
+
+Astute observers might note this value directly corresponds to
+2\ :sup:`32` -- 1, or ``0xffffffff``. The local identifier is 32-bits, and we
+have set each of these bits to 0, so the maximum range of timestamp drift is
+``0x00000000`` to ``0xffffffff`` (counted in 100-nanosecond intervals).
+
+Limited Unique UUIDs
+--------------------
+
+With the inclusion of the local identifier comes a serious limitation in the
+amount of unique UUIDs that may be created.

docs/rfc4122/version3.rst

@@ -6,7 +6,7 @@ Version 3: Name-based (MD5)
 
 .. attention::
 
-    `RFC 4122`_ states, "If backward compatibility is not an issue, SHA-1 is
+    [RFC4122]_ states, "If backward compatibility is not an issue, SHA-1 is
     preferred." As a result, the use of :ref:`version 5 UUIDs
     <rfc4122.version5>` is preferred over version 3 UUIDs, unless you have a
     specific use-case for version 3 UUIDs.
@@ -18,8 +18,8 @@ Version 3: Name-based (MD5)
     <rfc4122.version5>`. The only difference is the hashing algorithm used to
     generate the UUID.
 
-    Version 3 UUIDs use `MD5`_ as the hashing algorithm for combining the
-    namespace and the name.
+    Version 3 UUIDs use MD5 [RFC1321]_ as the hashing algorithm for combining
+    the namespace and the name.
 
 Due to the use of a different hashing algorithm, version 3 UUIDs generated with
 any given namespace and name will differ from version 5 UUIDs generated using
@@ -62,7 +62,3 @@ will always be ``53564aa3-4154-3ca5-ac90-dba59dc7d3cb``.
     ``Ramsey\Uuid\Rfc4122\UuidV3``. Check out the
     :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface` API documentation to
     learn more about what you can do with a ``UuidV3`` instance.
-
-
-.. _RFC 4122: https://tools.ietf.org/html/rfc4122
-.. _MD5: https://tools.ietf.org/html/rfc1321

docs/rfc4122/version5.rst

@@ -36,7 +36,7 @@ to the namespace they're created in. RFC 4122 defines some
 for URLs.
 
 .. note::
-    Version 5 UUIDs use `SHA-1`_ as the hashing algorithm for combining the
+    Version 5 UUIDs use [SHA1]_ as the hashing algorithm for combining the
     namespace and the name.
 
 .. code-block:: php
@@ -100,6 +100,3 @@ will always be ``a35477ae-bfb1-5f2e-b5a4-4711594d855f``.
 We can publish this namespace, allowing others to use it to generate identifiers
 for widgets. When two or more systems try to reference the same widget, they'll
 end up generating the same identifier for it, which is exactly what we want.
-
-
-.. _SHA-1: http://dx.doi.org/10.6028/NIST.FIPS.180-4

src/Rfc4122/UuidV2.php

@@ -83,8 +83,8 @@ final class UuidV2 extends Uuid implements UuidInterface
      * the timestamp can be off by a range of 0 to 429.4967295 seconds (or 7
      * minutes, 9 seconds, and 496730 microseconds).
      *
-     * Astute observers might note this value directly corresponds to 2^32, or
-     * 0xffffffff. The local identifier is 32-bits, and we have set each of
+     * Astute observers might note this value directly corresponds to 2^32 - 1,
+     * or 0xffffffff. The local identifier is 32-bits, and we have set each of
      * these bits to 0, so the maximum range of timestamp drift is 0x00000000
      * to 0xffffffff (counted in 100-nanosecond intervals).
      *

src/Uuid.php

@@ -488,7 +488,8 @@ class Uuid implements UuidInterface
      *     address
      * @param int|null $clockSeq A 14-bit number used to help avoid duplicates
      *     that could arise when the clock is set backwards in time or if the
-     *     node ID changes
+     *     node ID changes (in a version 2 UUID, the lower 8 bits of this number
+     *     are replaced with the domain).
      *
      * @return UuidInterface A UuidInterface instance that represents a
      *     version 2 UUID