diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9d4c94e..cd34a42 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -16,7 +16,6 @@ this project and its community, you are expected to uphold this code. You can find help and discussion in the following places: * GitHub Issues: -* GitHub Wiki: ## Reporting Bugs diff --git a/composer.json b/composer.json index 9ef6f3e..2c9a08c 100644 --- a/composer.json +++ b/composer.json @@ -92,7 +92,6 @@ "support": { "issues": "https://github.com/ramsey/uuid/issues", "rss": "https://github.com/ramsey/uuid/releases.atom", - "source": "https://github.com/ramsey/uuid", - "wiki": "https://github.com/ramsey/uuid/wiki" + "source": "https://github.com/ramsey/uuid" } } diff --git a/docs/customize.rst b/docs/customize.rst index cafd884..637c3c9 100644 --- a/docs/customize.rst +++ b/docs/customize.rst @@ -6,6 +6,32 @@ Customization .. toctree:: :titlesonly: + :hidden: customize/ordered-time-codec customize/timestamp-first-comb-codec + +ramsey/uuid offers a variety of ways to modify the standard behavior of the +library through dependency injection. Using `UuidFactory`_, `FeatureSet`_, and +:php:meth:`Uuid::setFactory() `, you are able +to replace just about any `codec`_, `builder`_, `converter`_, `provider`_, +`generator`_, and more. + +Ordered-time Codec + The ordered-time codec exists to rearrange the bytes of a version 1, + time-based 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`. + + +.. _UuidFactory: https://github.com/ramsey/uuid/blob/master/src/UuidFactory.php +.. _FeatureSet: https://github.com/ramsey/uuid/blob/master/src/FeatureSet.php +.. _codec: https://github.com/ramsey/uuid/tree/master/src/Codec +.. _builder: https://github.com/ramsey/uuid/tree/master/src/Builder +.. _converter: https://github.com/ramsey/uuid/tree/master/src/Converter +.. _provider: https://github.com/ramsey/uuid/tree/master/src/Provider +.. _generator: https://github.com/ramsey/uuid/tree/master/src/Generator diff --git a/docs/customize/ordered-time-codec.rst b/docs/customize/ordered-time-codec.rst index ce3a75d..bad166f 100644 --- a/docs/customize/ordered-time-codec.rst +++ b/docs/customize/ordered-time-codec.rst @@ -3,3 +3,82 @@ ================== Ordered-time Codec ================== + +.. hint:: + + :ref:`Version 6, ordered-time UUIDs ` are a proposed + new version of UUID that take the place of ordered time 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, time-based 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. + +.. code-block:: php + :caption: Use the ordered-time codec to generate a version 1 UUID + :name: customize.ordered-time-codec-example + + use Ramsey\Uuid\Codec\OrderedTimeCodec; + use Ramsey\Uuid\UuidFactory; + + $factory = new UuidFactory(); + $codec = new OrderedTimeCodec($factory->getUuidBuilder()); + + $factory->setCodec($codec); + + $orderedTimeUuid = $factory->uuid1(); + + printf( + "UUID: %s\nVersion: %d\nDate: %s\nNode: %s\nBytes: %s\n", + $orderedTimeUuid->toString(), + $orderedTimeUuid->getFields()->getVersion(), + $orderedTimeUuid->getDateTime()->format('r'), + $orderedTimeUuid->getFields()->getNode()->toString(), + 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: + +.. code-block:: text + + UUID: 593200aa-61ae-11ea-bbf2-0242ac130003 + Version: 1 + Date: Mon, 09 Mar 2020 02:33:23 +0000 + Node: 0242ac130003 + Bytes: 11ea61ae593200aabbf20242ac130003 + +.. 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. + + 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. + + .. 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/ diff --git a/docs/customize/timestamp-first-comb-codec.rst b/docs/customize/timestamp-first-comb-codec.rst index 909395d..00f3377 100644 --- a/docs/customize/timestamp-first-comb-codec.rst +++ b/docs/customize/timestamp-first-comb-codec.rst @@ -3,3 +3,63 @@ ========================== Timestamp-first COMB Codec ========================== + +:ref:`Version 4, random UUIDs ` 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 +`. 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 + :name: customize.timestamp-first-comb-codec-example + + use Ramsey\Uuid\Codec\TimestampFirstCombCodec; + use Ramsey\Uuid\Generator\CombGenerator; + use Ramsey\Uuid\UuidFactory; + + $factory = new UuidFactory(); + $codec = new TimestampFirstCombCodec($factory->getUuidBuilder()); + + $factory->setCodec($codec); + + $factory->setRandomGenerator(new CombGenerator( + $factory->getRandomGenerator(), + $factory->getNumberConverter() + )); + + $timestampFirstComb = $factory->uuid4(); + + printf( + "UUID: %s\nVersion: %d\nBytes: %s\n", + $timestampFirstComb->toString(), + $timestampFirstComb->getFields()->getVersion(), + 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: + +.. 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 `, 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 diff --git a/docs/database.rst b/docs/database.rst new file mode 100644 index 0000000..d939be5 --- /dev/null +++ b/docs/database.rst @@ -0,0 +1,256 @@ +.. _database: + +=================== +Using In a Database +=================== + +.. tip:: + + `ramsey/uuid-doctrine`_ allows the use of ramsey/uuid as a `Doctrine field + type`_. If you use Doctrine, it's a great option for working with UUIDs and + databases. + +There are several strategies to consider when working with UUIDs in a database. +Among these are whether to store the string representation or bytes and whether +the UUID column should be treated as a primary key. We'll discuss a few of these +approaches here, but the final decision on how to use UUIDs in a database is up +to you, since your needs will be different from those of others. + +.. note:: + + All database code examples in this section assume the use of `MariaDB`_ and + `PHP Data Objects (PDO)`_. If using a different database engine or + connection library, your code will differ, but the general concepts should + remain the same. + + +.. _database.string: + +Storing As a String +################### + +Perhaps the easiest way to store a UUID to a database is to create a ``char(36)`` +column and store the UUID as a string. When stored as a string, UUIDs require +no special treatment in SQL statements or when displaying them. + +The primary drawback is the size. At 36 characters, UUIDs can take up a lot of +space, and when handling a lot of data, this can add up. + +.. code-block:: sql + :caption: Create a table with a column for UUIDs + :name: database.uuid-column-example + + CREATE TABLE `notes` ( + `uuid` char(36) NOT NULL, + `notes` text NOT NULL + ) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +Using this database table, we can store the string UUID using code similar to +this (assume some of the variables in this example have been set beforehand): + +.. code-block:: php + :caption: Store a string UUID to the uuid column + :name: database.uuid-column-store-example + + use Ramsey\Uuid\Uuid; + + $uuid = Uuid::uuid4(); + + $dbh = new PDO($dsn, $username, $password); + + $sth = $dbh->prepare(' + INSERT INTO notes ( + uuid, + notes + ) VALUES ( + :uuid, + :notes + ) + '); + + $sth->execute([ + ':uuid' => $uuid->toString(), + ':notes' => $notes, + ]); + + +.. _database.bytes: + +Storing As Bytes +################ + +In :ref:`the previous example `, we saw how +to store the string representation of a UUID to a ``char(36)`` column. As +discussed, the primary drawback is the size. However, if we store the UUID in +byte form, we only need a ``char(16)`` column, saving over half the space. + +The primary drawback with this approach is ease-of-use. Since the UUID bytes are +stored in the database, querying and selecting data becomes more difficult. + +.. code-block:: sql + :caption: Create a table with a column for UUID bytes + :name: database.uuid-bytes-example + + CREATE TABLE `notes` ( + `uuid` char(16) NOT NULL, + `notes` text NOT NULL + ) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +Using this database table, we can store the UUID bytes using code similar to +this (again, assume some of the variables in this example have been set +beforehand): + +.. code-block:: php + :caption: Store a string UUID to the uuid column + :name: database.uuid-bytes-store-example + + $sth->execute([ + ':uuid' => $uuid->getBytes(), + ':notes' => $notes, + ]); + +Now, when we ``SELECT`` the records from the database, we will need to convert +the ``notes.uuid`` column to a ramsey/uuid object, so that we are able to use +it. + +.. code-block:: php + :caption: Covert database UUID bytes to UuidInterface instance + :name: database.uuid-bytes-convert-example + + use Ramsey\Uuid\Uuid; + + $uuid = Uuid::uuid4(); + + $dbh = new PDO($dsn, $username, $password); + + $sth = $dbh->prepare('SELECT uuid, notes FROM notes'); + $sth->execute(); + + foreach ($sth->fetchAll() as $record) { + $uuid = Uuid::fromBytes($record['uuid']); + + printf( + "UUID: %s\nNotes: %s\n\n", + $uuid->toString(), + $record['notes'] + ); + } + +We'll also need to query the database using the bytes. + +.. code-block:: php + :caption: Look-up the record from the database, using the UUID bytes + :name: database.uuid-bytes-select-example + + use Ramsey\Uuid\Uuid; + + $uuid = Uuid::fromString('278198d3-fa96-4833-abab-82f9e67f4712'); + + $dbh = new PDO($dsn, $username, $password); + + $sth = $dbh->prepare(' + SELECT uuid, notes + FROM notes + WHERE uuid = :uuid + '); + + $sth->execute([ + ':uuid' => $uuid->getBytes(), + ]); + + $record = $sth->fetch(); + + if ($record) { + $uuid = Uuid::fromBytes($record['uuid']); + + printf( + "UUID: %s\nNotes: %s\n\n", + $uuid->toString(), + $record['notes'] + ); + } + + +.. _database.pk: + +Using As a Primary Key +###################### + +In the previous examples, we didn't use the UUID as a primary key, but it's +logical to use the ``notes.uuid`` field as a primary key. There's nothing wrong +with this approach, but there are a couple points to consider: + +* InnoDB stores data in the primary key order +* All the secondary keys also contain the primary key (in InnoDB) + +We'll deal with the first point in the section, :ref:`database.order`. For the +second point, if you are using the string version of the UUID (i.e., +``char(36)``), then not only will the primary key be large and take up a lot of +space, but every secondary key that uses that primary key will also be must +larger. + +For this reason, if you choose to use UUIDs as primary keys, it might be worth +the drawbacks to use UUID bytes (i.e., ``char(16)``) instead of the string +representation (see :ref:`database.bytes`). + + +.. _database.uk: + +Using As a Unique Key +##################### + +Instead of :ref:`using UUIDs as a primary key `, you may choose to +use an ``AUTO_INCREMENT`` column with the ``int unsigned`` data type as a +primary key, while using a ``char(36)`` for UUIDs and setting a ``UNIQUE KEY`` +on this column. This will aid in lookups, while helping keep your secondary keys +small. + +.. code-block:: sql + :caption: Use auto-incrementing column as primary key, with UUID as unique key + :name: database.id-auto-increment-uuid-unique-key + + CREATE TABLE `notes` ( + `id` int(11) unsigned NOT NULL AUTO_INCREMENT, + `uuid` char(36) NOT NULL, + `notes` text NOT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `notes_uuid_uk` (`uuid`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8; + + +.. _database.order: + +Insertion Order and Sorting +########################### + +UUIDs are not *monotonically increasing*. Even time-based UUIDs are not. If +using UUIDs as primary keys, the inserts will be random, and the data will be +scattered on disk. Over time, as the database size grows, lookups will become +slower and slower. + +.. note:: + + See Percona's "`Storing UUID Values in MySQL`_" post, for more details on + performance of UUIDs as primary keys. + +To minimize these problems, two solutions have been devised: + +1. Timestamp first COMBs +2. Ordered Time UUIDs + +:ref:`customize.timestamp-first-comb-codec` explains the first solution and how +to use ramsey/uuid to implement it, while :ref:`customize.ordered-time-codec` +explains how to use ramsey/uuid to implement the second solution. + +.. hint:: + + :ref:`Version 6, ordered-time UUIDs ` are a proposed + new version of UUID that take the place of ordered time UUIDs. + + +.. _ramsey/uuid-doctrine: https://github.com/ramsey/uuid-doctrine +.. _Doctrine field type: https://www.doctrine-project.org/projects/doctrine-dbal/en/2.10/reference/types.html +.. _MariaDB: https://mariadb.org +.. _PHP Data Objects (PDO): https://www.php.net/pdo +.. _Storing UUID Values in MySQL: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/ +.. _Version 6, ordered-time UUIDs: nonstandard.version6 diff --git a/docs/index.rst b/docs/index.rst index 9e769e5..b5a4aa8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Contents quickstart rfc4122 nonstandard + database customize upgrading FAQs diff --git a/docs/nonstandard.rst b/docs/nonstandard.rst index aa0eb5f..9bae3e2 100644 --- a/docs/nonstandard.rst +++ b/docs/nonstandard.rst @@ -25,7 +25,7 @@ Version 6: Ordered-time :ref:`version 1 UUID ` with a *monotonically increasing* UUID. For more details, see :ref:`nonstandard.version6`. -GUID +Globally Unique Identifiers (GUIDs) A globally unique identifier, or GUID, is often used as a synonym for UUID. A key difference is the order of the bytes. Any `RFC 4122`_ version UUID may be represented as a GUID. For more details, see :ref:`nonstandard.guid`. diff --git a/docs/nonstandard/guid.rst b/docs/nonstandard/guid.rst index db99d90..3c9613f 100644 --- a/docs/nonstandard/guid.rst +++ b/docs/nonstandard/guid.rst @@ -1,8 +1,8 @@ .. _nonstandard.guid: -================================= -Globally Unique Identifier (GUID) -================================= +=================================== +Globally Unique Identifiers (GUIDs) +=================================== .. tip:: diff --git a/docs/nonstandard/other.rst b/docs/nonstandard/other.rst index ac86400..f7e5a41 100644 --- a/docs/nonstandard/other.rst +++ b/docs/nonstandard/other.rst @@ -3,3 +3,47 @@ ======================= Other Nonstandard UUIDs ======================= + +Sometimes, you might encounter a string that looks like a UUID but doesn't +follow the `RFC 4122`_ specification. Take this string, for example: + +.. code-block:: text + + d95959bc-2ff5-43eb-fccd-14883ba8f174 + +At a glance, this looks like a valid UUID, but the variant bits don't match RFC +4122. Instead of throwing a validation exception, ramsey/uuid will assume this +is a UUID, since it fits the format and has 128 bits, but it will represent it +as a :php:class:`Ramsey\\Uuid\\Nonstandard\\Uuid`. + +.. code-block:: php + :caption: Create an instance of Nonstandard\\Uuid from a non-RFC 4122 UUID + + use Ramsey\Uuid\Uuid; + + $uuid = Uuid::fromString('d95959bc-2ff5-43eb-fccd-14883ba8f174'); + + printf( + "Class: %s\nUUID: %s\nVersion: %d\nVariant: %s\n", + get_class($uuid), + $uuid->toString(), + $uuid->getFields()->getVersion(), + $uuid->getFields()->getVariant() + ); + +This will create a Nonstandard\\Uuid from the given string and print out a few +details about it. It will look something like this: + +.. code-block:: text + + Class: Ramsey\Uuid\Nonstandard\Uuid + UUID: d95959bc-2ff5-43eb-fccd-14883ba8f174 + Version: 0 + Variant: 7 + +Note that the version is 0. Since the variant is 7, and there is no +formal specification for this variant of UUID, ramsey/uuid has no way of knowing +what type of UUID this is. + + +.. _RFC 4122: https://tools.ietf.org/html/rfc4122 diff --git a/docs/quickstart.rst b/docs/quickstart.rst index e53fc1d..d964a73 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -104,6 +104,8 @@ library. * - :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``. + - Creates a version 1 UUID instance from a PHP `DateTimeInterface`_. + .. _RFC 4122: https://tools.ietf.org/html/rfc4122 +.. _DateTimeInterface: https://www.php.net/datetimeinterface diff --git a/docs/reference.rst b/docs/reference.rst index 1f8e587..fc02b7b 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -20,6 +20,9 @@ Reference reference/nonstandard-uuidv6 reference/guid-fields reference/guid-guid + reference/nonstandard-fields + reference/nonstandard-uuid + reference/uuidfactoryinterface reference/types reference/exceptions reference/helper diff --git a/docs/reference/exceptions.rst b/docs/reference/exceptions.rst index 7790053..29c3eaf 100644 --- a/docs/reference/exceptions.rst +++ b/docs/reference/exceptions.rst @@ -8,33 +8,33 @@ Exceptions .. php:exception:: BuilderNotFoundException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that no suitable UUID builder could be found. .. php:exception:: DateTimeException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that the PHP DateTime extension encountered an exception or error. .. php:exception:: DceSecurityException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate an exception occurred while dealing with DCE Security (version 2) UUIDs .. php:exception:: InvalidArgumentException - Extends ``\InvalidArgumentException``. + Extends `InvalidArgumentException `_. Thrown to indicate that the argument received is not valid. .. php:exception:: InvalidBytesException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that the bytes being operated on are invalid in some way. @@ -46,38 +46,38 @@ Exceptions .. php:exception:: NameException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that an error occurred while attempting to hash a namespace and name .. php:exception:: NodeException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that attempting to fetch or create a node ID encountered an error. .. php:exception:: RandomSourceException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that the source of random data encountered an error. .. php:exception:: TimeSourceException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate that the source of time encountered an error. .. php:exception:: UnableToBuildUuidException - Extends ``\RuntimeException``. + Extends `RuntimeException `_. Thrown to indicate a builder is unable to build a UUID. .. php:exception:: UnsupportedOperationException - Extends ``\LogicException``. + Extends `LogicException `_. Thrown to indicate that the requested operation is not supported. diff --git a/docs/reference/guid-fields.rst b/docs/reference/guid-fields.rst index 9b4b407..73ace97 100644 --- a/docs/reference/guid-fields.rst +++ b/docs/reference/guid-fields.rst @@ -10,4 +10,4 @@ Guid\\Fields Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\FieldsInterface`. - ``Guid\Fields`` represents the fields of a GUID. + Guid\Fields represents the fields of a GUID. diff --git a/docs/reference/nonstandard-fields.rst b/docs/reference/nonstandard-fields.rst new file mode 100644 index 0000000..b4196c9 --- /dev/null +++ b/docs/reference/nonstandard-fields.rst @@ -0,0 +1,13 @@ +.. _reference.nonstandard.fields: + +=================== +Nonstandard\\Fields +=================== + +.. php:namespace:: Ramsey\Uuid\Nonstandard + +.. php:class:: Fields + + Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\FieldsInterface`. + + Nonstandard\Fields represents the fields of a nonstandard UUID. diff --git a/docs/reference/nonstandard-uuid.rst b/docs/reference/nonstandard-uuid.rst new file mode 100644 index 0000000..152169f --- /dev/null +++ b/docs/reference/nonstandard-uuid.rst @@ -0,0 +1,20 @@ +.. _reference.nonstandard.uuid: + +================= +Nonstandard\\Uuid +================= + +.. php:namespace:: Ramsey\Uuid\Nonstandard + +.. php:class:: Uuid + + Implements :php:interface:`Ramsey\\Uuid\\UuidInterface`. + + Nonstandard\Uuid represents :ref:`nonstandard.other`. In addition to + providing the methods defined on the interface, this class additionally + provides the following methods. + + .. php:method:: getFields() + + :returns: The fields that comprise this UUID + :returntype: Ramsey\\Uuid\\Nonstandard\\Fields diff --git a/docs/reference/rfc4122-fieldsinterface.rst b/docs/reference/rfc4122-fieldsinterface.rst index d5f34c9..44ec64d 100644 --- a/docs/reference/rfc4122-fieldsinterface.rst +++ b/docs/reference/rfc4122-fieldsinterface.rst @@ -10,7 +10,7 @@ Rfc4122\\FieldsInterface Implements :php:interface:`Ramsey\\Uuid\\Fields\\FieldsInterface`. - ``Rfc4122\FieldsInterface`` represents the fields of an RFC 4122 UUID. + Rfc4122\FieldsInterface represents the fields of an RFC 4122 UUID. In addition to the methods defined on the interface, this class additionally defines the following methods. diff --git a/docs/reference/rfc4122-uuidinterface.rst b/docs/reference/rfc4122-uuidinterface.rst index 5eb07bd..543d445 100644 --- a/docs/reference/rfc4122-uuidinterface.rst +++ b/docs/reference/rfc4122-uuidinterface.rst @@ -10,7 +10,7 @@ Rfc4122\\UuidInterface Implements :php:interface:`Ramsey\\Uuid\\UuidInterface`. - ``Rfc4122\UuidInterface`` represents an RFC 4122 UUID. In addition to the + Rfc4122\UuidInterface represents an RFC 4122 UUID. In addition to the methods defined on the interface, this interface additionally defines the following methods. diff --git a/docs/reference/rfc4122-uuidv2.rst b/docs/reference/rfc4122-uuidv2.rst index 2745de2..026cd62 100644 --- a/docs/reference/rfc4122-uuidv2.rst +++ b/docs/reference/rfc4122-uuidv2.rst @@ -16,8 +16,8 @@ Rfc4122\\UuidV2 .. php:method:: getDateTime() - Returns a DateTimeInterface object representing the timestamp associated - with the UUID + Returns a `DateTimeInterface `_ + instance representing the timestamp associated with the UUID .. caution:: diff --git a/docs/reference/types.rst b/docs/reference/types.rst index 2556ffc..a74dc6d 100644 --- a/docs/reference/types.rst +++ b/docs/reference/types.rst @@ -8,7 +8,8 @@ Types .. php:class:: TypeInterface - Implements ``\JsonSerializable`` and ``\Serializable``. + Implements `JsonSerializable `_ and + `Serializable `_. TypeInterface ensures consistency in typed values returned by ramsey/uuid. diff --git a/docs/reference/uuid.rst b/docs/reference/uuid.rst index baf5a73..f3c2f32 100644 --- a/docs/reference/uuid.rst +++ b/docs/reference/uuid.rst @@ -4,7 +4,7 @@ Uuid ==== -``Ramsey\Uuid`` provides static methods for the most common functionality for +Ramsey\Uuid\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. @@ -141,7 +141,7 @@ the ramsey/uuid library. .. php:staticmethod:: fromString($uuid) - Creates an instance of ``UuidInterface`` from the string standard + Creates an instance of UuidInterface from the string standard representation. :param string $uuid: The string standard representation of a UUID @@ -149,21 +149,22 @@ the ramsey/uuid library. .. php:staticmethod:: fromBytes($bytes) - Creates an instance of ``UuidInterface`` from a 16-byte string. + Creates an instance of UuidInterface from a 16-byte string. :param string $bytes: A 16-byte binary string representation of a UUID :returntype: Ramsey\\Uuid\\UuidInterface .. php:staticmethod:: fromInteger($integer) - Creates an instance of ``UuidInterface`` from a 128-bit string integer. + Creates an instance of UuidInterface from a 128-bit string integer. :param string $integer: A 128-bit string integer representation of a UUID :returntype: Ramsey\\Uuid\\UuidInterface .. php:staticmethod:: fromDateTime($dateTime[, $node[, $clockSeq]]) - Creates a version 1 UUID instance from a ``\DateTimeInterface`` instance. + 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 @@ -173,11 +174,18 @@ the ramsey/uuid library. .. php:staticmethod:: isValid($uuid) - Validates the string standard representation of a UUID + Validates the string standard representation of a UUID. :param string $uuid: The string standard representation of a UUID :returntype: ``bool`` + .. php:staticmethod:: setFactory($factory) + + Sets the factory used to create UUIDs. + + :param Ramsey\\Uuid\\UuidFactoryInterface $factory: A UUID factory to use for all UUID generation + :returntype: void + .. _ISO object identifier (OID): http://www.oid-info.com .. _X.500: https://en.wikipedia.org/wiki/X.500 diff --git a/docs/reference/uuidfactoryinterface.rst b/docs/reference/uuidfactoryinterface.rst new file mode 100644 index 0000000..842f71d --- /dev/null +++ b/docs/reference/uuidfactoryinterface.rst @@ -0,0 +1,102 @@ +.. _reference.uuidfactoryinterface: + +==================== +UuidFactoryInterface +==================== + +.. php:namespace:: Ramsey\Uuid + +.. php:interface:: UuidFactoryInterface + + Represents a UUID factory. + + .. php:method:: getValidator() + + :returntype: Ramsey\\Uuid\\Validator\\ValidatorInterface + + .. php:method:: 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: A version 1 UUID + :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1 + + .. php:method:: 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 :php:const:`Uuid::DCE_DOMAIN_PERSON`, :php:const:`Uuid::DCE_DOMAIN_GROUP`, or :php:const:`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: A version 2 UUID + :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV2 + + .. php:method:: 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: A version 3 UUID + :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV3 + + .. php:method:: uuid4() + + Generates a version 4, random UUID. See :ref:`rfc4122.version4`. + + :returns: A version 4 UUID + :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV4 + + .. php:method:: 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: A version 5 UUID + :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV5 + + .. php:method:: 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: A version 6 UUID + :returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6 + + .. php:method:: fromString($uuid) + + Creates an instance of UuidInterface from the string standard + representation. + + :param string $uuid: The string standard representation of a UUID + :returntype: Ramsey\\Uuid\\UuidInterface + + .. php:method:: fromBytes($bytes) + + Creates an instance of UuidInterface from a 16-byte string. + + :param string $bytes: A 16-byte binary string representation of a UUID + :returntype: Ramsey\\Uuid\\UuidInterface + + .. php:method:: 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 + :returntype: Ramsey\\Uuid\\UuidInterface + + .. php:method:: 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: A version 1 UUID + :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1 diff --git a/docs/rfc4122/version2.rst b/docs/rfc4122/version2.rst index e1a1ca4..49e6612 100644 --- a/docs/rfc4122/version2.rst +++ b/docs/rfc4122/version2.rst @@ -249,8 +249,8 @@ that represents a local identifier. Because of this, not only do version 2 UUIDs have :ref:`limited uniqueness `, but they also lack time precision. -When reconstructing the timestamp to return a ``\DateTimeInterface`` instance -from :php:meth:`UuidV2::getDateTime() `, +When reconstructing the timestamp to return a `DateTimeInterface`_ instance from +:php:meth:`UuidV2::getDateTime() `, we replace the 32 lower bits of the timestamp with zeros, since the local identifier should not be part of the timestamp. This results in a loss of precision, causing the timestamp to be off by a range of 0 to 429.4967295 @@ -270,3 +270,4 @@ it could be off by about 7 minutes. .. _Distributed Computing Environment: https://en.wikipedia.org/wiki/Distributed_Computing_Environment .. _POSIX: https://en.wikipedia.org/wiki/POSIX +.. _DateTimeInterface: https://www.php.net/datetimeinterface