From cbd6a45a6a1a9cb41e8c1a1a40cc0764df947fa3 Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sun, 1 Mar 2020 23:59:58 -0600 Subject: [PATCH] [ci skip] Update documentation --- .gitattributes | 1 + .readthedocs.yml | 11 ++ README.md | 1 - docs/conf.py | 1 + docs/index.rst | 1 + docs/installation.rst | 2 + docs/nonstandard/comb.rst | 2 + docs/nonstandard/guid.rst | 2 + docs/nonstandard/ordered-time.rst | 2 + docs/nonstandard/version6.rst | 2 + docs/quickstart.rst | 66 ++++++++++++ docs/reference.rst | 14 +++ docs/reference/helper.rst | 56 ++++++++++ docs/reference/name-based-namespaces.rst | 32 ++++++ docs/reference/rfc4122-fieldsinterface.rst | 69 +++++++++++++ docs/reference/rfc4122-uuidinterface.rst | 50 +++++++++ docs/reference/uuid.rst | 115 +++++++++++++++++++++ docs/requirements.txt | 3 +- docs/rfc4122.rst | 2 + docs/rfc4122/version1.rst | 44 ++++++-- docs/rfc4122/version2.rst | 2 + docs/rfc4122/version3.rst | 75 ++++++++++++++ docs/rfc4122/version4.rst | 40 +++++++ docs/rfc4122/version5.rst | 2 + docs/test.php | 19 +--- docs/upgrading.rst | 8 +- src/Rfc4122/UuidInterface.php | 2 +- src/Uuid.php | 12 +-- src/UuidInterface.php | 8 +- 29 files changed, 601 insertions(+), 43 deletions(-) create mode 100644 .readthedocs.yml create mode 100644 docs/reference.rst create mode 100644 docs/reference/helper.rst create mode 100644 docs/reference/name-based-namespaces.rst create mode 100644 docs/reference/rfc4122-fieldsinterface.rst create mode 100644 docs/reference/rfc4122-uuidinterface.rst create mode 100644 docs/reference/uuid.rst diff --git a/.gitattributes b/.gitattributes index 65f4080..5d184e3 100644 --- a/.gitattributes +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..bc50e91 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,11 @@ +version: 2 + +sphinx: + configuration: docs/conf.py + +formats: all + +python: + version: 3.7 + install: + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index 752ad8a..8fe3ebb 100644 --- a/README.md +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 8602aa4..a69c799 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 63e87a8..0f2c4f6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,4 +20,5 @@ This work is licensed under the `Creative Commons Attribution 4.0 International nonstandard upgrading FAQs + reference copyright diff --git a/docs/installation.rst b/docs/installation.rst index 955ca37..886f092 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,3 +1,5 @@ +.. _installation: + ====================== Installing ramsey/uuid ====================== diff --git a/docs/nonstandard/comb.rst b/docs/nonstandard/comb.rst index d30a850..06c7c31 100644 --- a/docs/nonstandard/comb.rst +++ b/docs/nonstandard/comb.rst @@ -1,3 +1,5 @@ +.. _nonstandard.codec.comb: + ===== COMBs ===== diff --git a/docs/nonstandard/guid.rst b/docs/nonstandard/guid.rst index d649e06..631e427 100644 --- a/docs/nonstandard/guid.rst +++ b/docs/nonstandard/guid.rst @@ -1,3 +1,5 @@ +.. _nonstandard.codec.guid: + ===== GUIDs ===== diff --git a/docs/nonstandard/ordered-time.rst b/docs/nonstandard/ordered-time.rst index bfd4d26..bf67dde 100644 --- a/docs/nonstandard/ordered-time.rst +++ b/docs/nonstandard/ordered-time.rst @@ -1,3 +1,5 @@ +.. _nonstandard.codec.ordered-time: + ============ Ordered Time ============ diff --git a/docs/nonstandard/version6.rst b/docs/nonstandard/version6.rst index fdf5b93..f75a7af 100644 --- a/docs/nonstandard/version6.rst +++ b/docs/nonstandard/version6.rst @@ -1,3 +1,5 @@ +.. _nonstandard.version6: + ======================= Version 6: Ordered Time ======================= diff --git a/docs/quickstart.rst b/docs/quickstart.rst index be11378..81a0a5c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,4 +1,70 @@ +.. _quickstart: + =============== Getting Started =============== +After :ref:`installing ramsey/uuid `, 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() ` + - This generates a :ref:`rfc4122.version1` UUID. + * - :php:meth:`Uuid::uuid2() ` + - This generates a :ref:`rfc4122.version2` UUID. + * - :php:meth:`Uuid::uuid3() ` + - This generates a :ref:`rfc4122.version3` UUID. + * - :php:meth:`Uuid::uuid4() ` + - This generates a :ref:`rfc4122.version4` UUID. + * - :php:meth:`Uuid::uuid5() ` + - This generates a :ref:`rfc4122.version5` UUID. + * - :php:meth:`Uuid::uuid6() ` + - This generates a :ref:`nonstandard.version6` UUID. + * - :php:meth:`Uuid::isValid() ` + - Checks whether a string is a valid UUID. + * - :php:meth:`Uuid::fromString() ` + - Creates a UUID instance from a string UUID. + * - :php:meth:`Uuid::fromBytes() ` + - Creates a UUID instance from a 16-byte string. + * - :php:meth:`Uuid::fromInteger() ` + - Creates a UUID instance from a string integer. + * - :php:meth:`Uuid::fromDateTime() ` + - Creates a version 1 UUID instance from a PHP ``DateTimeInterface``. + +.. _RFC 4122: https://tools.ietf.org/html/rfc4122 diff --git a/docs/reference.rst b/docs/reference.rst new file mode 100644 index 0000000..3bf58b0 --- /dev/null +++ b/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 diff --git a/docs/reference/helper.rst b/docs/reference/helper.rst new file mode 100644 index 0000000..046c1d8 --- /dev/null +++ b/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 diff --git a/docs/reference/name-based-namespaces.rst b/docs/reference/name-based-namespaces.rst new file mode 100644 index 0000000..a1cf36e --- /dev/null +++ b/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 ` + - The name string is a fully-qualified domain name. + * - :php:const:`Uuid::NAMESPACE_URL ` + - The name string is URL. + * - :php:const:`Uuid::NAMESPACE_OID ` + - The name string is an `ISO object identifier (OID)`_. + * - :php:const:`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/ diff --git a/docs/reference/rfc4122-fieldsinterface.rst b/docs/reference/rfc4122-fieldsinterface.rst new file mode 100644 index 0000000..06273a1 --- /dev/null +++ b/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. diff --git a/docs/reference/rfc4122-uuidinterface.rst b/docs/reference/rfc4122-uuidinterface.rst new file mode 100644 index 0000000..f81cd5a --- /dev/null +++ b/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 diff --git a/docs/reference/uuid.rst b/docs/reference/uuid.rst new file mode 100644 index 0000000..5b3fc9e --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index b0fa6d3..5b62d30 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/rfc4122.rst b/docs/rfc4122.rst index 52313a7..78ed8a4 100644 --- a/docs/rfc4122.rst +++ b/docs/rfc4122.rst @@ -1,3 +1,5 @@ +.. _rfc4122: + ============== RFC 4122 UUIDs ============== diff --git a/docs/rfc4122/version1.rst b/docs/rfc4122/version1.rst index 8b7f300..8d953a7 100644 --- a/docs/rfc4122/version1.rst +++ b/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 diff --git a/docs/rfc4122/version2.rst b/docs/rfc4122/version2.rst index e7f7478..9849fb5 100644 --- a/docs/rfc4122/version2.rst +++ b/docs/rfc4122/version2.rst @@ -1,3 +1,5 @@ +.. _rfc4122.version2: + ======================= Version 2: DCE Security ======================= diff --git a/docs/rfc4122/version3.rst b/docs/rfc4122/version3.rst index d77964e..ef92446 100644 --- a/docs/rfc4122/version3.rst +++ b/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 ` or :ref:`version 4 ` +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 `, 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 `, 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 ` or +:ref:`version 4 ` 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``. diff --git a/docs/rfc4122/version4.rst b/docs/rfc4122/version4.rst index fc8f992..948db14 100644 --- a/docs/rfc4122/version4.rst +++ b/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. diff --git a/docs/rfc4122/version5.rst b/docs/rfc4122/version5.rst index 6763c45..e916811 100644 --- a/docs/rfc4122/version5.rst +++ b/docs/rfc4122/version5.rst @@ -1,3 +1,5 @@ +.. _rfc4122.version5: + ============================= Version 5: Name-based (SHA-1) ============================= diff --git a/docs/test.php b/docs/test.php index 8026137..3f65423 100644 --- a/docs/test.php +++ b/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()); diff --git a/docs/upgrading.rst b/docs/upgrading.rst index d9f0b4d..31e3e53 100644 --- a/docs/upgrading.rst +++ b/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 diff --git a/src/Rfc4122/UuidInterface.php b/src/Rfc4122/UuidInterface.php index 3b86dc1..3e4d9fa 100644 --- a/src/Rfc4122/UuidInterface.php +++ b/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 diff --git a/src/Uuid.php b/src/Uuid.php index 71f0067..a373149 100644 --- a/src/Uuid.php +++ b/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 */ diff --git a/src/UuidInterface.php b/src/UuidInterface.php index 16665ba..f22eb0f 100644 --- a/src/UuidInterface.php +++ b/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 */