Update documentation with references to RFC 9562

Author: ramsey

docs/LICENSE

@@ -1,7 +1,6 @@
 # ramsey/uuid Documentation
 
-Changes to the documentation are automatically built by [Read the Docs][] and
-viewable from <https://uuid.ramsey.dev>.
+Changes to the documentation are automatically built by [Read the Docs][] and viewable from <https://uuid.ramsey.dev>.
 
 ## Getting Started
 
@@ -17,8 +16,8 @@ pip install -r requirements.txt
 
 ## Building the Docs
 
-To build the docs, change to the `docs/` directory, and make sure you're working
-on the virtualenv environment created in the last step.
+To build the docs, change to the `docs/` directory, and make sure you're working on the virtualenv environment created
+in the last step.
 
 ``` bash
 cd docs/
@@ -32,5 +31,4 @@ Then, to view the docs after building them:
 open _build/html/index.html
 ```
 
-
 [read the docs]: https://readthedocs.org

docs/README.md

@@ -23,7 +23,7 @@ def get_version():
     if os.environ.get('READTHEDOCS') == 'True':
         return os.environ.get('READTHEDOCS_VERSION')
 
-    pipe = Popen('git branch | grep \*', stdout=PIPE, shell=True, universal_newlines=True)
+    pipe = Popen('git branch | grep \\*', stdout=PIPE, shell=True, universal_newlines=True)
     version = pipe.stdout.read()
 
     if version:

docs/conf.py

@@ -4,9 +4,19 @@
 Copyright
 =========
 
-Copyright © 2012-|current_year| Ben Ramsey <[email protected]>
+Copyright © 2012-|current_year| `Ben Ramsey <https://benramsey.com>`_ and
+`contributors <https://github.com/ramsey/uuid/contributors>`_.
 
-This work is licensed under the Creative Commons Attribution 4.0 International
-License. To view a copy of this license, visit
-http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative
-Commons, PO Box 1866, Mountain View, CA 94042, USA.
+Documentation for ramsey/uuid is licensed under the Creative Commons Attribution 4.0 International License. To view a
+copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box
+1866, Mountain View, CA 94042, USA.
+
+ramsey/uuid is open source software: you can distribute it and/or modify it under the terms of the MIT License (the
+"License"). You may not use ramsey/uuid except in compliance with the License.
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
+language governing permissions and limitations under the License.
+
+You should have received a copy of the MIT License along with this program. If not, see
+https://opensource.org/license/mit/.

docs/copyright.rst

@@ -14,38 +14,30 @@ Customization
     customize/validators
     customize/factory
 
-ramsey/uuid offers a variety of ways to modify the standard behavior of the
-library through dependency injection. Using `FeatureSet`_, `UuidFactory`_, and
-:php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory()>`, you are able
-to replace just about any `builder`_, `codec`_, `converter`_, `generator`_,
-`provider`_, and more.
-
-Ordered-time Codec
-    The ordered-time codec exists to rearrange the bytes of a version 1,
-    Gregorian time UUID so that the timestamp portion of the UUID is
-    monotonically increasing. To learn more, see :ref:`customize.ordered-time-codec`.
-
-Timestamp-first COMB Codec
-    The timestamp-first COMB codec replaces part of a version 4, random UUID
-    with a timestamp, so that the UUID becomes monotonically increasing. To
-    learn more, see :ref:`customize.timestamp-first-comb-codec`.
+ramsey/uuid offers a variety of ways to modify the standard behavior of the library through dependency injection. Using
+`FeatureSet`_, `UuidFactory`_, and :php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory()>`, you are able to
+replace just about any `builder`_, `codec`_, `converter`_, `generator`_, `provider`_, and more.
+
+Ordered-time Codec *(deprecated)*
+    The ordered-time codec exists to rearrange the bytes of a version 1, Gregorian time UUID so that the timestamp
+    portion of the UUID is monotonically increasing. To learn more, see :ref:`customize.ordered-time-codec`.
+
+Timestamp-first COMB Codec *(deprecated)*
+    The timestamp-first COMB codec replaces part of a version 4, random UUID with a timestamp, so that the UUID becomes
+    monotonically increasing. To learn more, see :ref:`customize.timestamp-first-comb-codec`.
 
 Using a Custom Calculator
-    It's possible to replace the default calculator ramsey/uuid uses. If your
-    requirements require a different solution for making calculations, see
-    :ref:`customize.calculators`.
+    It's possible to replace the default calculator ramsey/uuid uses. If your requirements require a different solution
+    for making calculations, see :ref:`customize.calculators`.
 
 Using a Custom Validator
-    If your requirements require a different level of validation or a different
-    UUID format, you may replace the default validator. See
-    :ref:`customize.validators`, to learn more.
+    If your requirements require a different level of validation or a different UUID format, you may replace the default
+    validator. See :ref:`customize.validators`, to learn more.
 
 Replace the Default Factory
-    Not only are you able to inject alternate builders, codecs, etc. into the
-    factory and use the factory to generate UUIDs, you may also replace the
-    global, static factory used by the static methods on the Uuid class. To find
-    out how, see :ref:`customize.factory`.
-
+    Not only are you able to inject alternate builders, codecs, etc. into the factory and use the factory to generate
+    UUIDs, you may also replace the global, static factory used by the static methods on the Uuid class. To find out
+    how, see :ref:`customize.factory`.
 
 .. _UuidFactory: https://github.com/ramsey/uuid/blob/4.x/src/UuidFactory.php
 .. _FeatureSet: https://github.com/ramsey/uuid/blob/4.x/src/FeatureSet.php

docs/customize.rst

@@ -4,13 +4,11 @@
 Using a Custom Calculator
 =========================
 
-By default, ramsey/uuid uses `brick/math`_  as its internal calculator. However,
-you may change the calculator, if your needs require something else.
+By default, ramsey/uuid uses `brick/math`_  as its internal calculator. However, you may change the calculator, if your
+needs require something else.
 
-To swap the default calculator with your custom one, first make an adapter that
-wraps your custom calculator and implements
-:php:interface:`Ramsey\\Uuid\\Math\\CalculatorInterface`. This might look
-something like this:
+To swap the default calculator with your custom one, first make an adapter that wraps your custom calculator and
+implements :php:interface:`Ramsey\\Uuid\\Math\\CalculatorInterface`. This might look something like this:
 
 .. code-block:: php
     :caption: Create a custom calculator wrapper that implements CalculatorInterface
@@ -47,10 +45,9 @@ something like this:
 
     }
 
-The easiest way to use your custom calculator wrapper is to instantiate a new
-FeatureSet, set the calculator on it, and pass the FeatureSet into a new
-UuidFactory. Using the factory, you may then generate and work with UUIDs, using
-your custom calculator.
+The easiest way to use your custom calculator wrapper is to instantiate a new FeatureSet, set the calculator on it, and
+pass the FeatureSet into a new UuidFactory. Using the factory, you may then generate and work with UUIDs, using your
+custom calculator.
 
 .. code-block:: php
     :caption: Use your custom calculator wrapper when working with UUIDs
@@ -71,5 +68,4 @@ your custom calculator.
 
     $uuid = $factory->uuid1();
 
-
 .. _brick/math: https://github.com/brick/math

docs/customize/calculators.rst

@@ -4,8 +4,8 @@
 Replace the Default Factory
 ===========================
 
-In many of the examples throughout this documentation, we've seen how to
-configure the factory and then use that factory to generate and work with UUIDs.
+In many of the examples throughout this documentation, we've seen how to configure the factory and then use that factory
+to generate and work with UUIDs.
 
 For example:
 
@@ -23,9 +23,8 @@ For example:
 
     $orderedTimeUuid = $factory->uuid1();
 
-When doing this, the default behavior of ramsey/uuid is left intact. If we call
-``Uuid::uuid1()`` to generate a version 1 UUID after configuring the factory as
-shown above, it won't use :ref:`OrderedTimeCodec <customize.ordered-time-codec>`
+When doing this, the default behavior of ramsey/uuid is left intact. If we call ``Uuid::uuid1()`` to generate a version
+1 UUID after configuring the factory as shown above, it won't use :ref:`OrderedTimeCodec <customize.ordered-time-codec>`
 to generate the UUID.
 
 .. code-block:: php
@@ -48,10 +47,9 @@ to generate the UUID.
         bin2hex($uuid->getBytes())
     );
 
-In this example, we print out details for two different UUIDs. The first was
-generated with the :ref:`OrderedTimeCodec <customize.ordered-time-codec>` using
-``$factory->uuid1()``. The second was generated using ``Uuid::uuid1()``. It
-looks something like this:
+In this example, we print out details for two different UUIDs. The first was generated with the :ref:`OrderedTimeCodec
+<customize.ordered-time-codec>` using ``$factory->uuid1()``. The second was generated using ``Uuid::uuid1()``. It looks
+something like this:
 
 .. code-block:: text
 
@@ -61,15 +59,13 @@ looks something like this:
     UUID: 2ff09730-6251-11ea-ba64-0242ac130003
     Bytes: 2ff09730625111eaba640242ac130003
 
-Notice the arrangement of the bytes. The first set of bytes has been rearranged,
-according to the ordered-time codec rules, but the second set of bytes remains
-in the same order as the UUID string.
+Notice the arrangement of the bytes. The first set of bytes has been rearranged, according to the ordered-time codec
+rules, but the second set of bytes remains in the same order as the UUID string.
 
 *Configuring the factory does not change the default behavior.*
 
-If we want to change the default behavior, we must *replace* the factory used
-by the Uuid static methods, and we can do this using the
-:php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory>` static method.
+If we want to change the default behavior, we must *replace* the factory used by the Uuid static methods, and we can do
+this using the :php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory>` static method.
 
 .. code-block:: php
     :caption: Replace the factory to globally affect Uuid behavior
@@ -79,15 +75,12 @@ by the Uuid static methods, and we can do this using the
 
     $uuid = Uuid::uuid1();
 
-Now, every time we call :php:meth:`Uuid::uuid() <Ramsey\\Uuid\\Uuid::uuid1>`,
-ramsey/uuid will use the factory configured with the :ref:`OrderedTimeCodec
-<customize.ordered-time-codec>` to generate version 1 UUIDs.
+Now, every time we call :php:meth:`Uuid::uuid() <Ramsey\\Uuid\\Uuid::uuid1>`, ramsey/uuid will use the factory configured
+with the :ref:`OrderedTimeCodec <customize.ordered-time-codec>` to generate version 1 UUIDs.
 
 .. warning::
 
-    Calling :php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory>` to
-    replace the factory will change the behavior of Uuid no matter where it is
-    used, so keep this in mind when replacing the factory. If you replace the
-    factory deep inside a method somewhere, any later code that calls a static
-    method on :php:class:`Ramsey\\Uuid\\Uuid` will use the new factory to
-    generate UUIDs.
+    Calling :php:meth:`Uuid::setFactory() <Ramsey\\Uuid\\Uuid::setFactory>` to replace the factory will change the
+    behavior of Uuid no matter where it is used, so keep this in mind when replacing the factory. If you replace the
+    factory deep inside a method somewhere, any later code that calls a static method on :php:class:`Ramsey\\Uuid\\Uuid`
+    will use the new factory to generate UUIDs.

docs/customize/factory.rst

@@ -6,25 +6,21 @@ Ordered-time Codec
 
 .. attention::
 
-    :ref:`Version 6, reordered time UUIDs <rfc4122.version6>` are a new version
-    of UUID that eliminate the need for the ordered-time codec. If you aren't
-    currently using the ordered-time codec, and you need time-based, sortable
-    UUIDs, consider using version 6 UUIDs.
-
-UUIDs arrange their bytes according to the standard recommended by `RFC 4122`_.
-Unfortunately, this means the bytes aren't in an arrangement that supports
-sorting by creation time or an otherwise incrementing value. The Percona
-article, "`Storing UUID Values in MySQL`_," explains at length the problems this
-can cause. It also recommends a solution: the *ordered-time UUID*.
-
-RFC 4122 version 1, Gregorian time UUIDs rearrange the bytes of the time fields
-so that the lowest bytes appear first, the middle bytes are next, and the
-highest bytes come last. Logical sorting is not possible with this arrangement.
-
-An ordered-time UUID is a version 1 UUID with the time fields arranged in
-logical order so that the UUIDs can be sorted by creation time. These UUIDs are
-*monotonically increasing*, each one coming after the previously-created one, in
-a proper sort order.
+    The :php:class:`Ramsey\\Uuid\\Codec\\OrderedTimeCodec` class is deprecated. Please migrate to
+    :ref:`version 6, reordered Gregorian time UUIDs <rfc4122.version6>`.
+
+UUIDs arrange their bytes according to the standard recommended by `RFC 9562`_ (formerly `RFC 4122`_). Unfortunately,
+this means the bytes aren't in an arrangement that supports sorting by creation time or an otherwise incrementing value.
+The Percona article, "`Storing UUID Values in MySQL`_," explains at length the problems this can cause. It also
+recommends a solution: the *ordered-time UUID*.
+
+`RFC 9562 version 1, Gregorian time UUIDs <https://www.rfc-editor.org/rfc/rfc9562#section-5.1>`_ rearrange the bytes of
+the time fields so that the lowest bytes appear first, the middle bytes are next, and the highest bytes come last.
+Logical sorting is not possible with this arrangement.
+
+An ordered-time UUID is a version 1 UUID with the time fields arranged in logical order so that the UUIDs can be sorted
+by creation time. These UUIDs are *monotonically increasing*, each one coming after the previously-created one, in a
+proper sort order.
 
 .. code-block:: php
     :caption: Use the ordered-time codec to generate a version 1 UUID
@@ -49,8 +45,7 @@ a proper sort order.
         bin2hex($orderedTimeUuid->getBytes())
     );
 
-This will use the ordered-time codec to generate a version 1 UUID and will print
-out details about the UUID similar to these:
+This will use the ordered-time codec to generate a version 1 UUID and will print out details about the UUID similar to these:
 
 .. code-block:: text
 
@@ -62,25 +57,22 @@ out details about the UUID similar to these:
 
 .. attention::
 
-    Only the byte representation is rearranged. The string representation
-    follows the format of a standard version 1 UUID. This means only the byte
-    representation of an ordered-time codec encoded UUID may be used for
-    sorting, such as with database results.
+    Only the byte representation is rearranged. The string representation follows the format of a standard version 1
+    UUID. This means only the byte representation of an ordered-time codec encoded UUID may be used for sorting, such as
+    with database results.
 
-    To store the byte representation to a database field, see
-    :ref:`database.bytes`.
+    To store the byte representation to a database field, see :ref:`database.bytes`.
 
 .. hint::
 
-    If you use this codec and store the bytes of the UUID to the database, as
-    recommended above, you will need to use this codec to decode the bytes, as
-    well. Otherwise, the UUID string value will be incorrect.
+    If you use this codec and store the bytes of the UUID to the database, as recommended above, you will need to use
+    this codec to decode the bytes, as well. Otherwise, the UUID string value will be incorrect.
 
     .. code-block:: php
 
         // Using a factory configured with the OrderedTimeCodec, as shown above.
         $orderedTimeUuid = $factory->fromBytes($bytes);
 
-
-.. _RFC 4122: https://tools.ietf.org/html/rfc4122
-.. _Storing UUID Values in MySQL: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/
+.. _RFC 4122: https://www.rfc-editor.org/rfc/rfc4122
+.. _RFC 9562: https://www.rfc-editor.org/rfc/rfc9562
+.. _Storing UUID Values in MySQL: https://www.percona.com/blog/store-uuid-optimized-way/

docs/customize/ordered-time-codec.rst

@@ -6,24 +6,19 @@ Timestamp-first COMB Codec
 
 .. attention::
 
-    :ref:`Version 7, Unix Epoch time UUIDs <rfc4122.version7>` are a new version
-    of UUID that eliminate the need for the timestamp-first COMB codec. If you
-    aren't currently using the timestamp-first COMB codec, and you need
-    time-based, sortable UUIDs, consider using version 7 UUIDs.
-
-:ref:`Version 4, random UUIDs <rfc4122.version4>` are doubly problematic when it
-comes to sorting and storing to databases (see :ref:`database.order`), since
-their values are random, and there is no timestamp associated with them that may
-be rearranged, like with the :ref:`ordered-time codec
-<customize.ordered-time-codec>`. In 2002, Jimmy Nilsson recognized this problem
-with random UUIDs and proposed a solution he called "COMBs" (see "`The Cost of
-GUIDs as Primary Keys`_").
-
-So-called because they *combine* random bytes with a timestamp, the
-timestamp-first COMB codec replaces the first 48 bits of a version 4, random
-UUID with a Unix timestamp and microseconds, creating an identifier that can be
-sorted by creation time. These UUIDs are *monotonically increasing*, each one
-coming after the previously-created one, in a proper sort order.
+    The :php:class:`Ramsey\\Uuid\\Codec\\TimestampFirstCombCodec` class is deprecated. Please migrate to
+    :ref:`version 7, Unix Epoch time UUIDs <rfc4122.version7>`.
+
+:ref:`Version 4, random UUIDs <rfc4122.version4>` are doubly problematic when it comes to sorting and storing to
+databases (see :ref:`database.order`), since their values are random, and there is no timestamp associated with them
+that may be rearranged, like with the :ref:`ordered-time codec <customize.ordered-time-codec>`. In 2002, Jimmy Nilsson
+recognized this problem with random UUIDs and proposed a solution he called "COMBs" (see "`The Cost of GUIDs as Primary
+Keys`_").
+
+So-called because they *combine* random bytes with a timestamp, the timestamp-first COMB codec replaces the first 48
+bits of a version 4, random UUID with a Unix timestamp and microseconds, creating an identifier that can be sorted by
+creation time. These UUIDs are *monotonically increasing*, each one coming after the previously-created one, in a proper
+sort order.
 
 .. code-block:: php
     :caption: Use the timestamp-first COMB codec to generate a version 4 UUID
@@ -52,21 +47,18 @@ coming after the previously-created one, in a proper sort order.
         bin2hex($timestampFirstComb->getBytes())
     );
 
-This will use the timestamp-first COMB codec to generate a version 4 UUID with
-the timestamp replacing the first 48 bits and will print out details about the
-UUID similar to these:
+This will use the timestamp-first COMB codec to generate a version 4 UUID with the timestamp replacing the first 48 bits
+and will print out details about the UUID similar to these:
 
 .. code-block:: text
 
     UUID: 9009ebcc-cd99-4b5f-90cf-9155607d2de9
     Version: 4
     Bytes: 9009ebcccd994b5f90cf9155607d2de9
 
-Note that the bytes are in the same order as the string representation. Unlike
-the :ref:`ordered-time codec <customize.ordered-time-codec>`, the
-timestamp-first COMB codec affects both the string representation and the byte
-representation. This means either the string UUID or the bytes may be stored to
-a datastore and sorted. To learn more, see :ref:`database`.
-
+Note that the bytes are in the same order as the string representation. Unlike the :ref:`ordered-time codec
+<customize.ordered-time-codec>`, the timestamp-first COMB codec affects both the string representation and the byte
+representation. This means either the string UUID or the bytes may be stored to a datastore and sorted. To learn more,
+see :ref:`database`.
 
-.. _The Cost of GUIDs as Primary Keys: https://www.informit.com/articles/printerfriendly/25862
+.. _The Cost of GUIDs as Primary Keys: https://web.archive.org/web/20240118030355/https://www.informit.com/articles/printerfriendly/25862