1. class
  2. Rhumsaa
  3. \
  4. Uuid
  5. \
  6. Uuid

Uuid

class Uuid (View source)

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.

Constants

NAMESPACE_DNS

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

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

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

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

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

Reserved for NCS compatibility.
RFC_4122

Specifies the UUID layout given in RFC 4122.
RESERVED_MICROSOFT

Reserved for Microsoft compatibility.
RESERVED_FUTURE

Reserved for future definition.
VALID_PATTERN

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

Version of the Rhumsaa\Uuid package

Properties

static bool $force32Bit For testing, 64-bit system override; if true, treat the system as 32-bit
static bool $forceNoBigNumber For testing, Moontoast\Math\BigNumber override; if true, treat as if BigNumber is not available
static bool $forceNoOpensslRandomPseudoBytes For testing, openssl_random_pseudo_bytes() override; if true, treat as if openssl_random_pseudo_bytes() is not available
static array $timeOfDayTest For testing, sets time of day to a static, known value
static bool $ignoreSystemNode For testing, system override to ignore generating node from hardware
protected array $fields The fields that make up this UUID

Methods

__construct(array $fields)

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

string
__toString()

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

int
compareTo(Uuid $uuid)

Compares this UUID with the specified UUID.

bool
equals(object $obj)

Compares this object to the specified object.

string
getBytes()

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

int
getClockSeqHiAndReserved()

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

string
getClockSeqHiAndReservedHex()

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

int
getClockSeqLow()

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

string
getClockSeqLowHex()

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

int
getClockSequence()

Returns the clock sequence value associated with this UUID.

string
getClockSequenceHex()

Returns the clock sequence value associated with this UUID.

DateTime
getDateTime()

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

array
getFields()

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

array
getFieldsHex()

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

string
getHex()

Returns the hexadecimal value of the UUID

BigNumber
getInteger()

Returns the integer value of the UUID, represented as a BigNumber

BigNumber
getLeastSignificantBits()

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

string
getLeastSignificantBitsHex()

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

BigNumber
getMostSignificantBits()

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

string
getMostSignificantBitsHex()

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

int
getNode()

Returns the node value associated with this UUID

string
getNodeHex()

Returns the node value associated with this UUID

int
getTimeHiAndVersion()

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

string
getTimeHiAndVersionHex()

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

int
getTimeLow()

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

string
getTimeLowHex()

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

int
getTimeMid()

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

string
getTimeMidHex()

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

int
getTimestamp()

The timestamp value associated with this UUID

string
getTimestampHex()

The timestamp value associated with this UUID

string
getUrn()

Returns the string representation of the UUID as a URN.

int
getVariant()

Returns the variant number associated with this UUID.

int|null
getVersion()

The version number associated with this UUID. The version number describes how this UUID was generated.

string
toString()

Converts this UUID into a string representation

static Uuid
fromBytes(string $bytes)

Creates a UUID from a byte string.

static Uuid
fromString(string $name)

Creates a UUID from the string standard representation as described in the toString() method.

static Uuid
fromInteger(string|BigNumber $integer)

Creates a UUID from either the UUID as a 128-bit integer string or a Moontoast\Math\BigNumber object.

static boolean
isValid(string $uuid)

Check if a string is a valid uuid

static Uuid
uuid1(int|string $node = null, int $clockSeq = null)

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

static Uuid
uuid3(Uuid|string $ns, string $name)

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).

static Uuid
uuid4()

Generate a version 4 (random) UUID.

static Uuid
uuid5(Uuid|string $ns, string $name)

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).

static array
calculateUuidTime(int $sec, int $usec)

Calculates the UUID time fields from a UNIX timestamp

static 
getIfconfig()

Returns the network interface configuration for the system

static string
getNodeFromSystem()

Get the hardware address as a 48-bit positive integer. If all attempts to obtain the hardware address fail, we choose a random 48-bit number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware address" means the MAC address of a network interface, and on a machine with multiple network interfaces the MAC address of any one of them may be returned.

static bool
hasBigNumber()

Returns true if the system has Moontoast\Math\BigNumber

static bool
hasOpensslRandomPseudoBytes()

Returns true if the system has openssl_random_pseudo_bytes()

static bool
is64BitSystem()

Returns true if the system is 64-bit, false otherwise

static Uuid
uuidFromHashedName(string $hash, int $version)

Returns a version 3 or 5 UUID based on the hash (md5 or sha1) of a namespace identifier (which is a UUID) and a name (which is a string)

Details

at line 161
protected __construct(array $fields)

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

Protected to prevent direct instantiation. Use static methods to create UUIDs.

Parameters

array $fields

at line 173
string __toString()

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

Return Value

string

at line 191
int compareTo(Uuid $uuid)

Compares this UUID with the specified UUID.

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

Uuid $uuid UUID to which this UUID is to be compared

Return Value

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

at line 220
bool equals(object $obj)

Compares this object to the specified object.

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

object $obj

Return Value

bool True if $obj is equal to this UUID

at line 235
string getBytes()

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

Return Value

string

at line 252
int getClockSeqHiAndReserved()

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

Return Value

int Unsigned 8-bit integer value of clock_seq_hi_and_reserved

at line 263
string getClockSeqHiAndReservedHex()

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

Return Value

string Hexadecimal value of clock_seq_hi_and_reserved

at line 273
int getClockSeqLow()

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

Return Value

int Unsigned 8-bit integer value of clock_seq_low

at line 283
string getClockSeqLowHex()

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

Return Value

string Hexadecimal value of clock_seq_low

at line 304
int getClockSequence()

Returns the clock sequence value associated with this UUID.

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 Value

int Unsigned 14-bit integer value of clock sequence

at line 315
string getClockSequenceHex()

Returns the clock sequence value associated with this UUID.

Return Value

string Hexadecimal value of clock sequence

at line 332
DateTime getDateTime()

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

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 Value

DateTime A PHP DateTime representation of the date

Exceptions

UnsupportedOperationException If this UUID is not a version 1 UUID
UnsatisfiedDependencyException if called on a 32-bit system and Moontoast\Math\BigNumber is not present

at line 386
array getFields()

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

  • 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 Value

array The UUID fields represented as integer values

Exceptions

UnsatisfiedDependencyException if called on a 32-bit system

at line 423
array getFieldsHex()

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

  • 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 Value

array The UUID fields represented as hexadecimal values

at line 433
string getHex()

Returns the hexadecimal value of the UUID

Return Value

string

at line 444
BigNumber getInteger()

Returns the integer value of the UUID, represented as a BigNumber

Return Value

BigNumber BigNumber representation of the unsigned 128-bit integer value

Exceptions

UnsatisfiedDependencyException if Moontoast\Math\BigNumber is not present

at line 470
BigNumber getLeastSignificantBits()

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

Return Value

BigNumber BigNumber representation of the unsigned 64-bit integer value

Exceptions

UnsatisfiedDependencyException if Moontoast\Math\BigNumber is not present

at line 495
string getLeastSignificantBitsHex()

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

Return Value

string Hexadecimal value of least significant bits

at line 511
BigNumber getMostSignificantBits()

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

Return Value

BigNumber BigNumber representation of the unsigned 64-bit integer value

Exceptions

UnsatisfiedDependencyException if Moontoast\Math\BigNumber is not present

at line 536
string getMostSignificantBitsHex()

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

Return Value

string Hexadecimal value of most significant bits

at line 571
int getNode()

Returns the node value associated with this UUID

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 Value

int Unsigned 48-bit integer value of node

Exceptions

UnsatisfiedDependencyException if called on a 32-bit system

at line 609
string getNodeHex()

Returns the node value associated with this UUID

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 Value

string Hexadecimal value of node

at line 620
int getTimeHiAndVersion()

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

Return Value

int Unsigned 16-bit integer value of time_hi_and_version

at line 631
string getTimeHiAndVersionHex()

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

Return Value

string Hexadecimal value of time_hi_and_version

at line 642
int getTimeLow()

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

Return Value

int Unsigned 32-bit integer value of time_low

Exceptions

UnsatisfiedDependencyException if called on a 32-bit system

at line 661
string getTimeLowHex()

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

Return Value

string Hexadecimal value of time_low

at line 671
int getTimeMid()

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

Return Value

int Unsigned 16-bit integer value of time_mid

at line 681
string getTimeMidHex()

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

Return Value

string Hexadecimal value of time_mid

at line 703
int getTimestamp()

The timestamp value associated with this UUID

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 Value

int Unsigned 60-bit integer value of the timestamp

Exceptions

UnsupportedOperationException If this UUID is not a version 1 UUID
UnsatisfiedDependencyException if called on a 32-bit system

at line 737
string getTimestampHex()

The timestamp value associated with this UUID

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 Value

string Hexadecimal value of the timestamp

Exceptions

UnsupportedOperationException If this UUID is not a version 1 UUID

at line 757
string getUrn()

Returns the string representation of the UUID as a URN.

Return Value

string

at line 776
int getVariant()

Returns the variant number associated with this UUID.

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 Value

int

at line 810
int|null getVersion()

The version number associated with this UUID. The version number describes how this UUID was generated.

The version number 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 Value

int|null

at line 824
string toString()

Converts this UUID into a string representation

Return Value

string

at line 839
static Uuid fromBytes(string $bytes)

Creates a UUID from a byte string.

Parameters

string $bytes

Return Value

Uuid

Exceptions

InvalidArgumentException If the $bytes string does not contain 16 characters

at line 865
static Uuid fromString(string $name)

Creates a UUID from the string standard representation as described in the toString() method.

Parameters

string $name A string that specifies a UUID

Return Value

Uuid

Exceptions

InvalidArgumentException If the $name isn't a valid UUID

at line 904
static Uuid fromInteger(string|BigNumber $integer)

Creates a UUID from either the UUID as a 128-bit integer string or a Moontoast\Math\BigNumber object.

Parameters

string|BigNumber $integer String/BigNumber representation of UUID integer

Return Value

Uuid

Exceptions

UnsatisfiedDependencyException If Moontoast\Math\BigNumber is not present

at line 930
static boolean isValid(string $uuid)

Check if a string is a valid uuid

Parameters

string $uuid The uuid to test

Return Value

boolean

at line 959
static Uuid uuid1(int|string $node = null, int $clockSeq = null)

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

If $node is not given, we will attempt to obtain the local hardware address. If $clockSeq is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen.

Parameters

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

Uuid

Exceptions

InvalidArgumentException if the $node is invalid

at line 1026
static Uuid uuid3(Uuid|string $ns, string $name)

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).

Parameters

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

Return Value

Uuid

at line 1042
static Uuid uuid4()

Generate a version 4 (random) UUID.

Return Value

Uuid

at line 1061
static Uuid uuid5(Uuid|string $ns, string $name)

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).

Parameters

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

Return Value

Uuid

at line 1083
static protected array calculateUuidTime(int $sec, int $usec)

Calculates the UUID time fields from a UNIX timestamp

UUID time is a 60-bit time value as a count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582.

Parameters

int $sec Seconds since the Unix Epoch
int $usec Microseconds

Return Value

array

Exceptions

UnsatisfiedDependencyException if called on a 32-bit system and Moontoast\Math\BigNumber is not present

at line 1135
static protected getIfconfig()

Returns the network interface configuration for the system

at line 1163
static protected string getNodeFromSystem()

Get the hardware address as a 48-bit positive integer. If all attempts to obtain the hardware address fail, we choose a random 48-bit number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware address" means the MAC address of a network interface, and on a machine with multiple network interfaces the MAC address of any one of them may be returned.

Return Value

string

at line 1185
static protected bool hasBigNumber()

Returns true if the system has Moontoast\Math\BigNumber

Return Value

bool

at line 1195
static protected bool hasOpensslRandomPseudoBytes()

Returns true if the system has openssl_random_pseudo_bytes()

Return Value

bool

at line 1205
static protected bool is64BitSystem()

Returns true if the system is 64-bit, false otherwise

Return Value

bool

at line 1218
static protected Uuid uuidFromHashedName(string $hash, int $version)

Returns a version 3 or 5 UUID based on the hash (md5 or sha1) of a namespace identifier (which is a UUID) and a name (which is a string)

Parameters

string $hash The hash to use when creating the UUID
int $version The UUID version to be generated

Return Value

Uuid