Documentation

Ramsey
Uuid

Uuid
in package

Application

implements UuidInterface

Represents a universally unique identifier (UUID), according to RFC 4122.

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.

Interfaces, Classes and Traits

UuidInterface: UuidInterface defines common functionality for all universally unique identifiers (UUIDs)

NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8': When this namespace is specified, the name string is a fully-qualified domain name.
NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8': When this namespace is specified, the name string is an ISO OID.
NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8': When this namespace is specified, the name string is a URL.
NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8': When this namespace is specified, the name string is an X.500 DN in DER or a text output format.
NIL = '00000000-0000-0000-0000-000000000000': The nil UUID is special form of UUID that is specified to have all 128 bits set to zero.
RESERVED_FUTURE = 7: Reserved for future definition.
RESERVED_MICROSOFT = 6: Reserved for Microsoft compatibility.
RESERVED_NCS = 0: Reserved for NCS compatibility.
RFC_4122 = 2: Specifies the UUID layout given in RFC 4122.
UUID_TYPE_HASH_MD5 = 3: Version 3 (name-based and hashed with MD5) UUID object constant identifier
UUID_TYPE_HASH_SHA1 = 5: Version 5 (name-based and hashed with SHA1) UUID object constant identifier
UUID_TYPE_IDENTIFIER = 2: Version 2 (identifier-based) UUID object constant identifier
UUID_TYPE_RANDOM = 4: Version 4 (random) UUID object constant identifier
UUID_TYPE_TIME = 1: Version 1 (time-based) UUID object constant identifier
VALID_PATTERN = '^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$': Regular expression pattern for matching a valid UUID of any variant.
$codec : CodecInterface: The codec to use when encoding or decoding UUID strings.
$converter : NumberConverterInterface: The number converter to use for converting hex values to/from integers.
$fields : array<string|int, mixed>: The fields that make up this UUID.
$factory : UuidFactoryInterface: The factory to use when creating UUIDs.
__construct() : mixed: Creates a universally unique identifier (UUID) from an array of fields.
__toString() : string: Converts this UUID object to a string when the object is used in any string context.
compareTo() : int: Compares this UUID to the specified UUID.
equals() : bool: Compares this object to the specified object.
fromBytes() : UuidInterface: Creates a UUID from a byte string.
fromInteger() : UuidInterface: Creates a UUID from a 128-bit integer string.
fromString() : UuidInterface: Creates a UUID from the string standard representation.
getBytes() : string: Returns the UUID as a 16-byte string (containing the six integer fields in big-endian byte order).
getClockSeqHiAndReserved() : int: Returns the high field of the clock sequence multiplexed with the variant (bits 65-72 of the UUID).
getClockSeqHiAndReservedHex() : string: Returns the high field of the clock sequence multiplexed with the variant (bits 65-72 of the UUID).
getClockSeqLow() : int: Returns the low field of the clock sequence (bits 73-80 of the UUID).
getClockSeqLowHex() : string: Returns the low field of the clock sequence (bits 73-80 of the UUID).
getClockSequence() : int: Returns the clock sequence value associated with this UUID.
getClockSequenceHex() : string: Returns the clock sequence value associated with this UUID.
getDateTime() : DateTime: Returns a PHP `DateTime` object representing the timestamp associated with this UUID.
getFactory() : UuidFactoryInterface: Returns the currently set factory used to create UUIDs.
getFields() : array<string|int, mixed>: Returns an array of the fields of this UUID, with keys named according to the RFC 4122 names for the fields.
getFieldsHex() : array<string|int, mixed>: Returns an array of the fields of this UUID, with keys named according to the RFC 4122 names for the fields.
getHex() : string: Returns the hexadecimal value of the UUID.
getInteger() : mixed: Returns the integer value of the UUID, converted to an appropriate number representation.
getLeastSignificantBits() : mixed: Returns the least significant 64 bits of this UUID's 128 bit value.
getLeastSignificantBitsHex() : string: Returns the least significant 64 bits of this UUID's 128 bit value.
getMostSignificantBits() : mixed: Returns the most significant 64 bits of this UUID's 128 bit value.
getMostSignificantBitsHex() : string: Returns the most significant 64 bits of this UUID's 128 bit value.
getNode() : int: Returns the node value associated with this UUID
getNodeHex() : string: Returns the node value associated with this UUID
getNumberConverter() : NumberConverterInterface: Returns the number converter to use for converting hex values to/from integers.
getTimeHiAndVersion() : int: Returns the high field of the timestamp multiplexed with the version number (bits 49-64 of the UUID).
getTimeHiAndVersionHex() : string: Returns the high field of the timestamp multiplexed with the version number (bits 49-64 of the UUID).
getTimeLow() : int: Returns the low field of the timestamp (the first 32 bits of the UUID).
getTimeLowHex() : string: Returns the low field of the timestamp (the first 32 bits of the UUID).
getTimeMid() : int: Returns the middle field of the timestamp (bits 33-48 of the UUID).
getTimeMidHex() : string: Returns the middle field of the timestamp (bits 33-48 of the UUID).
getTimestamp() : int: Returns the timestamp value associated with this UUID.
getTimestampHex() : string: Returns the timestamp value associated with this UUID.
getUrn() : string: Returns the string representation of the UUID as a URN.
getVariant() : int: Returns the variant number associated with this UUID.
getVersion() : int|null: Returns the version number associated with this UUID.
isValid() : bool: Check if a string is a valid UUID.
jsonSerialize() : string: Converts this UUID object to a string when the object is serialized with `json_encode()`
serialize() : string: Converts this UUID object to a string when the object is serialized with `serialize()`
setFactory() : mixed: Sets the factory used to create UUIDs.
toString() : string: Converts this UUID into a string representation.
unserialize() : mixed: Re-constructs the object from its serialized form.
uuid1() : UuidInterface: Generate a version 1 UUID from a host ID, sequence number, and the current time.
uuid3() : UuidInterface: Generate a version 3 UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a string).
uuid4() : UuidInterface: Generate a version 4 (random) UUID.
uuid5() : UuidInterface: Generate a version 5 UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a string).

NAMESPACE_DNS

When this namespace is specified, the name string is a fully-qualified domain name.


    public
    mixed
    NAMESPACE_DNS
    = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'

NAMESPACE_OID

When this namespace is specified, the name string is an ISO OID.


    public
    mixed
    NAMESPACE_OID
    = '6ba7b812-9dad-11d1-80b4-00c04fd430c8'

NAMESPACE_URL

When this namespace is specified, the name string is a URL.


    public
    mixed
    NAMESPACE_URL
    = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'

NAMESPACE_X500

When this namespace is specified, the name string is an X.500 DN in DER or a text output format.


    public
    mixed
    NAMESPACE_X500
    = '6ba7b814-9dad-11d1-80b4-00c04fd430c8'

NIL

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


    public
    mixed
    NIL
    = '00000000-0000-0000-0000-000000000000'

RESERVED_FUTURE

Reserved for future definition.


    public
    mixed
    RESERVED_FUTURE
    = 7

RESERVED_MICROSOFT

Reserved for Microsoft compatibility.


    public
    mixed
    RESERVED_MICROSOFT
    = 6

RESERVED_NCS

Reserved for NCS compatibility.


    public
    mixed
    RESERVED_NCS
    = 0

RFC_4122

Specifies the UUID layout given in RFC 4122.


    public
    mixed
    RFC_4122
    = 2

UUID_TYPE_HASH_MD5

Version 3 (name-based and hashed with MD5) UUID object constant identifier


    public
    mixed
    UUID_TYPE_HASH_MD5
    = 3

UUID_TYPE_HASH_SHA1

Version 5 (name-based and hashed with SHA1) UUID object constant identifier


    public
    mixed
    UUID_TYPE_HASH_SHA1
    = 5

UUID_TYPE_IDENTIFIER

Version 2 (identifier-based) UUID object constant identifier


    public
    mixed
    UUID_TYPE_IDENTIFIER
    = 2

UUID_TYPE_RANDOM

Version 4 (random) UUID object constant identifier


    public
    mixed
    UUID_TYPE_RANDOM
    = 4

UUID_TYPE_TIME

Version 1 (time-based) UUID object constant identifier


    public
    mixed
    UUID_TYPE_TIME
    = 1

VALID_PATTERN

Regular expression pattern for matching a valid UUID of any variant.


    public
    mixed
    VALID_PATTERN
    = '^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$'

$codec

The codec to use when encoding or decoding UUID strings.


    protected
        CodecInterface
    $codec

$converter

The number converter to use for converting hex values to/from integers.


    protected
        NumberConverterInterface
    $converter

$fields

The fields that make up this UUID.


    protected
        array<string|int, mixed>
    $fields
     = ['time_low' => '00000000', 'time_mid' => '0000', 'time_hi_and_version' => '0000', 'clock_seq_hi_and_reserved' => '00', 'clock_seq_low' => '00', 'node' => '000000000000']

This is initialized to the nil value.

$factory

The factory to use when creating UUIDs.


    private
    static    UuidFactoryInterface
    $factory
     = null

__construct()

Creates a universally unique identifier (UUID) from an array of fields.


    public
                __construct(array<string|int, mixed> $fields, NumberConverterInterface $converter, CodecInterface $codec) : mixed

Unless you're making advanced use of this library to generate identifiers that deviate from RFC 4122, you probably do not want to instantiate a UUID directly. Use the static methods, instead:

use Ramsey\Uuid\Uuid;

$timeBasedUuid     = Uuid::uuid1();
$namespaceMd5Uuid  = Uuid::uuid3(Uuid::NAMESPACE_URL, 'http://php.net/');
$randomUuid        = Uuid::uuid4();
$namespaceSha1Uuid = Uuid::uuid5(Uuid::NAMESPACE_URL, 'http://php.net/');

Parameters

$fields : array<string|int, mixed>: An array of fields from which to construct a UUID; see UuidInterface::getFieldsHex() for array structure.
$converter : NumberConverterInterface: The number converter to use for converting hex values to/from integers.
$codec : CodecInterface: The codec to use when encoding or decoding UUID strings.

Return values

mixed —

__toString()

Converts this UUID object to a string when the object is used in any string context.


    public
                __toString() : string

Return values

string —

compareTo()

Compares this UUID to the specified UUID.


    public
                compareTo(UuidInterface $other) : int

The first of two UUIDs is greater than the second if the most significant field in which the UUIDs differ is greater for the first UUID.

Q. What's the value of being able to sort UUIDs?
A. Use them as keys in a B-Tree or similar mapping.

Parameters

$other : UuidInterface: UUID to which this UUID is compared

Return values

int —

-1, 0 or 1 as this UUID is less than, equal to, or greater than $uuid

equals()

Compares this object to the specified object.


    public
                equals(mixed $other) : bool

The result is true if and only if the argument is not null, is a UUID object, has the same variant, and contains the same value, bit for bit, as this UUID.

Parameters

$other : mixed

Return values

bool —

True if $other is equal to this UUID

fromBytes()

Creates a UUID from a byte string.


    public
            static    fromBytes(string $bytes) : UuidInterface

Parameters

$bytes : string

Return values

UuidInterface —

fromInteger()

Creates a UUID from a 128-bit integer string.


    public
            static    fromInteger(string $integer) : UuidInterface

Parameters

$integer : string: String representation of 128-bit integer

Return values

UuidInterface —

fromString()

Creates a UUID from the string standard representation.


    public
            static    fromString(string $name) : UuidInterface

Parameters

$name : string: A string that specifies a UUID

Return values

UuidInterface —

getBytes()

Returns the UUID as a 16-byte string (containing the six integer fields in big-endian byte order).


    public
                getBytes() : string

Return values

string —

getClockSeqHiAndReserved()

Returns the high field of the clock sequence multiplexed with the variant (bits 65-72 of the UUID).


    public
                getClockSeqHiAndReserved() : int

Return values

int —

Unsigned 8-bit integer value of clock_seq_hi_and_reserved

getClockSeqHiAndReservedHex()

Returns the high field of the clock sequence multiplexed with the variant (bits 65-72 of the UUID).


    public
                getClockSeqHiAndReservedHex() : string

Return values

string —

Hexadecimal value of clock_seq_hi_and_reserved

getClockSeqLow()

Returns the low field of the clock sequence (bits 73-80 of the UUID).


    public
                getClockSeqLow() : int

Return values

int —

Unsigned 8-bit integer value of clock_seq_low

getClockSeqLowHex()

Returns the low field of the clock sequence (bits 73-80 of the UUID).


    public
                getClockSeqLowHex() : string

Return values

string —

Hexadecimal value of clock_seq_low

getClockSequence()

Returns the clock sequence value associated with this UUID.


    public
                getClockSequence() : int

For UUID version 1, the clock sequence is used to help avoid duplicates that could arise when the clock is set backwards in time or if the node ID changes.

For UUID version 3 or 5, the clock sequence is a 14-bit value constructed from a name as described in RFC 4122, Section 4.3.

For UUID version 4, clock sequence is a randomly or pseudo-randomly generated 14-bit value as described in RFC 4122, Section 4.4.

Return values

int —

Unsigned 14-bit integer value of clock sequence

getClockSequenceHex()

Returns the clock sequence value associated with this UUID.


    public
                getClockSequenceHex() : string

Return values

string —

Hexadecimal value of clock sequence

getDateTime()

Returns a PHP `DateTime` object representing the timestamp associated with this UUID.


    public
                getDateTime() : DateTime

Return values

DateTime —

A PHP DateTime representation of the date

getFactory()

Returns the currently set factory used to create UUIDs.


    public
            static    getFactory() : UuidFactoryInterface

Return values

UuidFactoryInterface —

getFields()

Returns an array of the fields of this UUID, with keys named according to the RFC 4122 names for the fields.


    public
                getFields() : array<string|int, mixed>

time_low: The low field of the timestamp, an unsigned 32-bit integer
time_mid: The middle field of the timestamp, an unsigned 16-bit integer
time_hi_and_version: The high field of the timestamp multiplexed with the version number, an unsigned 16-bit integer
clock_seq_hi_and_reserved: The high field of the clock sequence multiplexed with the variant, an unsigned 8-bit integer
clock_seq_low: The low field of the clock sequence, an unsigned 8-bit integer
node: The spatially unique node identifier, an unsigned 48-bit integer

Return values

array<string|int, mixed> —

The UUID fields represented as integer values

getFieldsHex()

Returns an array of the fields of this UUID, with keys named according to the RFC 4122 names for the fields.


    public
                getFieldsHex() : array<string|int, mixed>

time_low: The low field of the timestamp, an unsigned 32-bit integer
time_mid: The middle field of the timestamp, an unsigned 16-bit integer
time_hi_and_version: The high field of the timestamp multiplexed with the version number, an unsigned 16-bit integer
clock_seq_hi_and_reserved: The high field of the clock sequence multiplexed with the variant, an unsigned 8-bit integer
clock_seq_low: The low field of the clock sequence, an unsigned 8-bit integer
node: The spatially unique node identifier, an unsigned 48-bit integer

Return values

array<string|int, mixed> —

The UUID fields represented as hexadecimal values

getHex()

Returns the hexadecimal value of the UUID.


    public
                getHex() : string

Return values

string —

getInteger()

Returns the integer value of the UUID, converted to an appropriate number representation.


    public
                getInteger() : mixed

Return values

mixed —

Converted representation of the unsigned 128-bit integer value

getLeastSignificantBits()

Returns the least significant 64 bits of this UUID's 128 bit value.


    public
                getLeastSignificantBits() : mixed

Return values

mixed —

Converted representation of the unsigned 64-bit integer value

getLeastSignificantBitsHex()

Returns the least significant 64 bits of this UUID's 128 bit value.


    public
                getLeastSignificantBitsHex() : string

Return values

string —

Hexadecimal value of least significant bits

getMostSignificantBits()

Returns the most significant 64 bits of this UUID's 128 bit value.


    public
                getMostSignificantBits() : mixed

Return values

mixed —

Converted representation of the unsigned 64-bit integer value

getMostSignificantBitsHex()

Returns the most significant 64 bits of this UUID's 128 bit value.


    public
                getMostSignificantBitsHex() : string

Return values

string —

Hexadecimal value of most significant bits

getNode()

Returns the node value associated with this UUID


    public
                getNode() : int

For UUID version 1, the node field consists of an IEEE 802 MAC address, usually the host address. For systems with multiple IEEE 802 addresses, any available one can be used. The lowest addressed octet (octet number 10) contains the global/local bit and the unicast/multicast bit, and is the first octet of the address transmitted on an 802.3 LAN.

For systems with no IEEE address, a randomly or pseudo-randomly generated value may be used; see RFC 4122, Section 4.5. The multicast bit must be set in such addresses, in order that they will never conflict with addresses obtained from network cards.

For UUID version 3 or 5, the node field is a 48-bit value constructed from a name as described in RFC 4122, Section 4.3.

For UUID version 4, the node field is a randomly or pseudo-randomly generated 48-bit value as described in RFC 4122, Section 4.4.

Return values

int —

Unsigned 48-bit integer value of node

getNodeHex()

Returns the node value associated with this UUID


    public
                getNodeHex() : string

For UUID version 3 or 5, the node field is a 48-bit value constructed from a name as described in RFC 4122, Section 4.3.

For UUID version 4, the node field is a randomly or pseudo-randomly generated 48-bit value as described in RFC 4122, Section 4.4.

Return values

string —

Hexadecimal value of node

getNumberConverter()

Returns the number converter to use for converting hex values to/from integers.


    public
                getNumberConverter() : NumberConverterInterface

Return values

NumberConverterInterface —

getTimeHiAndVersion()

Returns the high field of the timestamp multiplexed with the version number (bits 49-64 of the UUID).


    public
                getTimeHiAndVersion() : int

Return values

int —

Unsigned 16-bit integer value of time_hi_and_version

getTimeHiAndVersionHex()

Returns the high field of the timestamp multiplexed with the version number (bits 49-64 of the UUID).


    public
                getTimeHiAndVersionHex() : string

Return values

string —

Hexadecimal value of time_hi_and_version

getTimeLow()

Returns the low field of the timestamp (the first 32 bits of the UUID).


    public
                getTimeLow() : int

Return values

int —

Unsigned 32-bit integer value of time_low

getTimeLowHex()

Returns the low field of the timestamp (the first 32 bits of the UUID).


    public
                getTimeLowHex() : string

Return values

string —

Hexadecimal value of time_low

getTimeMid()

Returns the middle field of the timestamp (bits 33-48 of the UUID).


    public
                getTimeMid() : int

Return values

int —

Unsigned 16-bit integer value of time_mid

getTimeMidHex()

Returns the middle field of the timestamp (bits 33-48 of the UUID).


    public
                getTimeMidHex() : string

Return values

string —

Hexadecimal value of time_mid

getTimestamp()

Returns the timestamp value associated with this UUID.


    public
                getTimestamp() : int

The 60 bit timestamp value is constructed from the time_low, time_mid, and time_hi fields of this UUID. The resulting timestamp is measured in 100-nanosecond units since midnight, October 15, 1582 UTC.

The timestamp value is only meaningful in a time-based UUID, which has version type 1. If this UUID is not a time-based UUID then this method throws UnsupportedOperationException.

Return values

int —

Unsigned 60-bit integer value of the timestamp

getTimestampHex()

Returns the timestamp value associated with this UUID.


    public
                getTimestampHex() : string

Return values

string —

Hexadecimal value of the timestamp

getUrn()

Returns the string representation of the UUID as a URN.


    public
                getUrn() : string

Return values

string —

getVariant()

Returns the variant number associated with this UUID.


    public
                getVariant() : int

The variant number describes the layout of the UUID. The variant number has the following meaning:

0 - Reserved for NCS backward compatibility
2 - The RFC 4122 variant (used by this class)
6 - Reserved, Microsoft Corporation backward compatibility
7 - Reserved for future definition

Return values

int —

getVersion()

Returns the version number associated with this UUID.


    public
                getVersion() : int|null

The version number describes how this UUID was generated and has the following meaning:

1 - Time-based UUID
2 - DCE security UUID
3 - Name-based UUID hashed with MD5
4 - Randomly generated UUID
5 - Name-based UUID hashed with SHA-1

Returns null if this UUID is not an RFC 4122 variant, since version is only meaningful for this variant.

Return values

int|null —

isValid()

Check if a string is a valid UUID.


    public
            static    isValid(string $uuid) : bool

Parameters

$uuid : string: The string UUID to test

Return values

bool —

jsonSerialize()

Converts this UUID object to a string when the object is serialized with `json_encode()`


    public
                jsonSerialize() : string

Return values

string —

serialize()

Converts this UUID object to a string when the object is serialized with `serialize()`


    public
                serialize() : string

Return values

string —

setFactory()

Sets the factory used to create UUIDs.


    public
            static    setFactory(UuidFactoryInterface $factory) : mixed

Parameters

$factory : UuidFactoryInterface

Return values

mixed —

toString()

Converts this UUID into a string representation.


    public
                toString() : string

Return values

string —

unserialize()

Re-constructs the object from its serialized form.


    public
                unserialize(string $serialized) : mixed

Parameters

$serialized : string

Return values

mixed —

uuid1()

Generate a version 1 UUID from a host ID, sequence number, and the current time.


    public
            static    uuid1([int|string $node = null ][, int $clockSeq = null ]) : UuidInterface

Parameters

$node : int|string = null: A 48-bit number representing the hardware address This number may be represented as an integer or a hexadecimal string.
$clockSeq : int = null: 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.

Return values

UuidInterface —

uuid3()

Generate a version 3 UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a string).


    public
            static    uuid3(string|UuidInterface $ns, string $name) : UuidInterface

Parameters

$ns : string|UuidInterface: The UUID namespace in which to create the named UUID
$name : string: The name to create a UUID for

Return values

UuidInterface —

uuid4()

Generate a version 4 (random) UUID.


    public
            static    uuid4() : UuidInterface

Return values

UuidInterface —

uuid5()

Generate a version 5 UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a string).


    public
            static    uuid5(string|UuidInterface $ns, string $name) : UuidInterface

Parameters

$ns : string|UuidInterface: The UUID namespace in which to create the named UUID
$name : string: The name to create a UUID for

Return values

UuidInterface —