From b31703e7c9752260ddc773c95110294fa9abc5ff Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Wed, 4 Mar 2020 22:50:39 -0600 Subject: [PATCH] Improve documentation --- docs/conf.py | 4 + docs/index.rst | 3 +- docs/introduction.rst | 13 +-- docs/quickstart.rst | 43 +++++++++- docs/reference.rst | 9 ++ docs/reference/fields-fieldsinterface.rst | 16 ++++ docs/reference/helper.rst | 18 ++-- docs/reference/nonstandard-uuidv6.rst | 38 +++++++++ docs/reference/references.rst | 25 ++++++ docs/reference/rfc4122-fieldsinterface.rst | 44 ++++++---- docs/reference/rfc4122-uuidinterface.rst | 38 ++------- docs/reference/rfc4122-uuidv1.rst | 3 +- docs/reference/rfc4122-uuidv2.rst | 53 ++++++++++++ docs/reference/rfc4122-uuidv3.rst | 13 +++ docs/reference/rfc4122-uuidv4.rst | 13 +++ docs/reference/rfc4122-uuidv5.rst | 13 +++ docs/reference/types.rst | 65 +++++++++++++++ docs/reference/uuid.rst | 29 ++++--- docs/reference/uuidinterface.rst | 48 +++++++++++ docs/requirements.txt | 4 +- docs/rfc4122.rst | 5 +- docs/rfc4122/version1.rst | 8 +- docs/rfc4122/version2.rst | 96 ++++++++++++++++++++++ docs/rfc4122/version3.rst | 10 +-- docs/rfc4122/version5.rst | 5 +- src/Rfc4122/UuidV2.php | 4 +- src/Uuid.php | 3 +- 27 files changed, 520 insertions(+), 103 deletions(-) create mode 100644 docs/reference/fields-fieldsinterface.rst create mode 100644 docs/reference/nonstandard-uuidv6.rst create mode 100644 docs/reference/references.rst create mode 100644 docs/reference/rfc4122-uuidv2.rst create mode 100644 docs/reference/rfc4122-uuidv3.rst create mode 100644 docs/reference/rfc4122-uuidv4.rst create mode 100644 docs/reference/rfc4122-uuidv5.rst create mode 100644 docs/reference/types.rst create mode 100644 docs/reference/uuidinterface.rst diff --git a/docs/conf.py b/docs/conf.py index a69c799..9976a6c 100644 --- a/docs/conf.py +++ b/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', ] diff --git a/docs/index.rst b/docs/index.rst index 0f2c4f6..632a9cd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,7 @@ ramsey/uuid Manual ================== -For ramsey/uuid |version|. Updated on |today|. +For `ramsey/uuid `_ |version|. Updated on |today|. This work is licensed under the `Creative Commons Attribution 4.0 International `_ license. @@ -14,7 +14,6 @@ This work is licensed under the `Creative Commons Attribution 4.0 International :caption: Contents introduction - installation quickstart rfc4122 nonstandard diff --git a/docs/introduction.rst b/docs/introduction.rst index c6e694c..174fde5 100644 --- a/docs/introduction.rst +++ b/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 diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 458b1c8..8b8b719 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -4,8 +4,47 @@ Getting Started =============== -After :ref:`installing ramsey/uuid `, 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 `_ + +The JSON extension is normally enabled by default, but it is possible to disable +it. Other required extensions include +`PCRE `_ +and `SPL `_. 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 `_ +* `ext-gmp `_ +* `ext-bcmath `_ + + +Install With Composer +##################### + +The only supported installation method for ramsey/uuid is +`Composer `_. 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 diff --git a/docs/reference.rst b/docs/reference.rst index 31b5489..062e727 100644 --- a/docs/reference.rst +++ b/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 diff --git a/docs/reference/fields-fieldsinterface.rst b/docs/reference/fields-fieldsinterface.rst new file mode 100644 index 0000000..091ee01 --- /dev/null +++ b/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`` diff --git a/docs/reference/helper.rst b/docs/reference/helper.rst index 046c1d8..9c410e1 100644 --- a/docs/reference/helper.rst +++ b/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 diff --git a/docs/reference/nonstandard-uuidv6.rst b/docs/reference/nonstandard-uuidv6.rst new file mode 100644 index 0000000..cc77067 --- /dev/null +++ b/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 + `. 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 diff --git a/docs/reference/references.rst b/docs/reference/references.rst new file mode 100644 index 0000000..4718b4e --- /dev/null +++ b/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 diff --git a/docs/reference/rfc4122-fieldsinterface.rst b/docs/reference/rfc4122-fieldsinterface.rst index 06273a1..d88770c 100644 --- a/docs/reference/rfc4122-fieldsinterface.rst +++ b/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`` diff --git a/docs/reference/rfc4122-uuidinterface.rst b/docs/reference/rfc4122-uuidinterface.rst index f81cd5a..dfe4403 100644 --- a/docs/reference/rfc4122-uuidinterface.rst +++ b/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 diff --git a/docs/reference/rfc4122-uuidv1.rst b/docs/reference/rfc4122-uuidv1.rst index 6c7649c..c28c27c 100644 --- a/docs/reference/rfc4122-uuidv1.rst +++ b/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`` diff --git a/docs/reference/rfc4122-uuidv2.rst b/docs/reference/rfc4122-uuidv2.rst new file mode 100644 index 0000000..4c69b6f --- /dev/null +++ b/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 `. + 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 diff --git a/docs/reference/rfc4122-uuidv3.rst b/docs/reference/rfc4122-uuidv3.rst new file mode 100644 index 0000000..506019b --- /dev/null +++ b/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 `. diff --git a/docs/reference/rfc4122-uuidv4.rst b/docs/reference/rfc4122-uuidv4.rst new file mode 100644 index 0000000..540ec25 --- /dev/null +++ b/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 `. diff --git a/docs/reference/rfc4122-uuidv5.rst b/docs/reference/rfc4122-uuidv5.rst new file mode 100644 index 0000000..833e234 --- /dev/null +++ b/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 `. diff --git a/docs/reference/types.rst b/docs/reference/types.rst new file mode 100644 index 0000000..0ee432b --- /dev/null +++ b/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. diff --git a/docs/reference/uuid.rst b/docs/reference/uuid.rst index cbee71e..baf5a73 100644 --- a/docs/reference/uuid.rst +++ b/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 diff --git a/docs/reference/uuidinterface.rst b/docs/reference/uuidinterface.rst new file mode 100644 index 0000000..b27d2bd --- /dev/null +++ b/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`` diff --git a/docs/requirements.txt b/docs/requirements.txt index 5b62d30..767ec4d 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/rfc4122.rst b/docs/rfc4122.rst index 78ed8a4..a27a11d 100644 --- a/docs/rfc4122.rst +++ b/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 diff --git a/docs/rfc4122/version1.rst b/docs/rfc4122/version1.rst index 53c3058..8c6da00 100644 --- a/docs/rfc4122/version1.rst +++ b/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 `_, + See [RFC4122]_, `section 4.5 `_, for more details. diff --git a/docs/rfc4122/version2.rst b/docs/rfc4122/version2.rst index 9849fb5..f10d58d 100644 --- a/docs/rfc4122/version2.rst +++ b/docs/rfc4122/version2.rst @@ -3,3 +3,99 @@ ======================= Version 2: DCE Security ======================= + +Like a :ref:`version 1 UUID `, 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. diff --git a/docs/rfc4122/version3.rst b/docs/rfc4122/version3.rst index 8d3505b..ed5d0db 100644 --- a/docs/rfc4122/version3.rst +++ b/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 ` 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) `. 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 diff --git a/docs/rfc4122/version5.rst b/docs/rfc4122/version5.rst index f568c59..32445e0 100644 --- a/docs/rfc4122/version5.rst +++ b/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 diff --git a/src/Rfc4122/UuidV2.php b/src/Rfc4122/UuidV2.php index d134d3b..67cf189 100644 --- a/src/Rfc4122/UuidV2.php +++ b/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). * diff --git a/src/Uuid.php b/src/Uuid.php index a373149..4f4045b 100644 --- a/src/Uuid.php +++ b/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