php-uuid/docs/reference/uuid.rst

.. _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:const:: UUID_TYPE_TIME

        :ref:`rfc4122.version1` UUID.

    .. php:const:: UUID_TYPE_DCE_SECURITY

        :ref:`rfc4122.version2` UUID.

    .. php:const:: UUID_TYPE_HASH_MD5

        :ref:`rfc4122.version3` UUID.

    .. php:const:: UUID_TYPE_RANDOM

        :ref:`rfc4122.version4` UUID.

    .. php:const:: UUID_TYPE_HASH_SHA1

        :ref:`rfc4122.version5` UUID.

    .. php:const:: UUID_TYPE_PEABODY

        :ref:`nonstandard.version6` UUID.

    .. php:const:: NAMESPACE_DNS

        The name string is a fully-qualified domain name.

    .. php:const:: NAMESPACE_URL

        The name string is a URL.

    .. php:const:: NAMESPACE_OID

        The name string is an `ISO object identifier (OID)`_.

    .. php:const:: NAMESPACE_X500

        The name string is an `X.500`_ `DN`_ in `DER`_ or a text output format.

    .. php:const:: NIL

        The nil UUID is a special form of UUID that is specified to have all 128
        bits set to zero.

    .. php:const:: DCE_DOMAIN_PERSON

        DCE Security principal (person) domain.

    .. php:const:: DCE_DOMAIN_GROUP

        DCE Security group domain.

    .. php:const:: DCE_DOMAIN_ORG

        DCE Security organization domain.

    .. php:const:: RESERVED_NCS

        Variant identifier: reserved, NCS backward compatibility.

    .. php:const:: RFC_4122

        Variant identifier: the UUID layout specified in RFC 4122.

    .. php:const:: RESERVED_MICROSOFT

        Variant identifier: reserved, Microsoft Corporation backward compatibility.

    .. php:const:: RESERVED_FUTURE

        Variant identifier: reserved for future definition.

    .. 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: A version 1 UUID
        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV1

    .. 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 :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: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: A version 3 UUID
        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV3

    .. php:staticmethod:: uuid4()

        Generates a version 4, random UUID. See :ref:`rfc4122.version4`.

        :returns: A version 4 UUID
        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV4

    .. 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: A version 5 UUID
        :returntype: Ramsey\\Uuid\\Rfc4122\\UuidV5

    .. 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: A version 6 UUID
        :returntype: Ramsey\\Uuid\\Nonstandard\\UuidV6

    .. php:staticmethod:: 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: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
        :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
        :returntype: Ramsey\\Uuid\\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: 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
        :returntype: ``bool``


.. _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/