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.

link http://tools.ietf.org/html/rfc4122
link http://en.wikipedia.org/wiki/Universally_unique_identifier
link http://docs.python.org/3/library/uuid.html
link http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html

 Methods

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

__toString() : string

Compares this UUID with the specified UUID.

compareTo(\Rhumsaa\Uuid\Uuid $uuid) : 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.

Parameters

$uuid

\Rhumsaa\Uuid\Uuid

UUID to which this UUID is to be compared

Returns

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

Compares this object to the specified object.

equals(object $obj) : 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

$obj

object

Returns

boolTrue if $obj is equal to this UUID

Creates a UUID from a byte string.

fromBytes(string $bytes) : \Rhumsaa\Uuid\Uuid
Static

Parameters

$bytes

string

Exceptions

\InvalidArgumentException If the $bytes string does not contain 16 characters

Returns

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

fromString(string $name) : \Rhumsaa\Uuid\Uuid
Static

Parameters

$name

string

A string that specifies a UUID

Exceptions

\InvalidArgumentException If the $name isn't a valid UUID

Returns

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

getBytes() : string

Returns

string

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

getClockSeqHiAndReserved() : int

Returns

intUnsigned 8-bit integer value of clock_seq_hi_and_reserved

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

getClockSeqHiAndReservedHex() : string

Returns

stringHexadecimal value of clock_seq_hi_and_reserved

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

getClockSeqLow() : int

Returns

intUnsigned 8-bit integer value of clock_seq_low

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

getClockSeqLowHex() : string

Returns

stringHexadecimal value of clock_seq_low

Returns the clock sequence value associated with this UUID.

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.

link http://tools.ietf.org/html/rfc4122#section-4.1.5

Returns

intUnsigned 14-bit integer value of clock sequence

Returns the clock sequence value associated with this UUID.

getClockSequenceHex() : string

Returns

stringHexadecimal value of clock sequence

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

getDateTime() : \DateTime

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.

Exceptions

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

Returns

\DateTimeA PHP DateTime representation of the date

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

getFields() : array
  • 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
link http://tools.ietf.org/html/rfc4122#section-4.1.2

Exceptions

\Rhumsaa\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system

Returns

arrayThe UUID fields represented as integer values

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

getFieldsHex() : array
  • 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

Returns

arrayThe UUID fields represented as hexadecimal values

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

getLeastSignificantBits() : \Moontoast\Math\BigNumber

Exceptions

\Rhumsaa\Uuid\Exception\UnsatisfiedDependencyException if Moontoast\Math\BigNumber is not present

Returns

\Moontoast\Math\BigNumberBigNumber representation of the unsigned 64-bit integer value

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

getLeastSignificantBitsHex() : string

Returns

stringHexadecimal value of least significant bits

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

getMostSignificantBits() : \Moontoast\Math\BigNumber

Exceptions

\Rhumsaa\Uuid\Exception\UnsatisfiedDependencyException if Moontoast\Math\BigNumber is not present

Returns

\Moontoast\Math\BigNumberBigNumber representation of the unsigned 64-bit integer value

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

getMostSignificantBitsHex() : string

Returns

stringHexadecimal value of most significant bits

Returns the node value associated with this UUID

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.

link http://tools.ietf.org/html/rfc4122#section-4.1.6

Exceptions

\Rhumsaa\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system

Returns

intUnsigned 48-bit integer value of node

Returns the node value associated with this UUID

getNodeHex() : string

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.

link http://tools.ietf.org/html/rfc4122#section-4.1.6

Returns

stringHexadecimal value of node

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

getTimeHiAndVersion() : int

Returns

intUnsigned 16-bit integer value of time_hi_and_version

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

getTimeHiAndVersionHex() : string

Returns

stringHexadecimal value of time_hi_and_version

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

getTimeLow() : int

Exceptions

\Rhumsaa\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system

Returns

intUnsigned 32-bit integer value of time_low

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

getTimeLowHex() : string

Returns

stringHexadecimal value of time_low

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

getTimeMid() : int

Returns

intUnsigned 16-bit integer value of time_mid

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

getTimeMidHex() : string

Returns

stringHexadecimal value of time_mid

The timestamp value associated with this UUID

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.

link http://tools.ietf.org/html/rfc4122#section-4.1.4

Exceptions

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

Returns

intUnsigned 60-bit integer value of the timestamp

The timestamp value associated with this UUID

getTimestampHex() : string

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.

link http://tools.ietf.org/html/rfc4122#section-4.1.4

Exceptions

\Rhumsaa\Uuid\Exception\UnsupportedOperationException If this UUID is not a version 1 UUID

Returns

stringHexadecimal value of the timestamp

Returns the string representation of the UUID as a URN.

getUrn() : string

Returns the variant number associated with this UUID.

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
link http://tools.ietf.org/html/rfc4122#section-4.1.1

Returns

int

The version number associated with this UUID.

getVersion() : int

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
link http://tools.ietf.org/html/rfc4122#section-4.1.3

Returns

int

Check if a string is a valid uuid

isValid(string $uuid) : boolean
Static

Parameters

$uuid

string

The uuid to test

Returns

boolean

Converts this UUID into a string representation

toString() : string

Returns

string

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

uuid1(int | string $node, int $clockSeq) : \Rhumsaa\Uuid\Uuid
Static

If $node is not given, getMacAddress() is used to obtain the hardware address. If $clockSeq is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen.

Parameters

$node

intstring

A 48-bit number representing the hardware address. This number may be represented as an integer or a hexadecimal string.

$clockSeq

int

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.

Exceptions

\InvalidArgumentException if the $node is invalid

Returns

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

uuid3(\Rhumsaa\Uuid\Uuid | string $ns, string $name) : \Rhumsaa\Uuid\Uuid
Static

Parameters

$ns

\Rhumsaa\Uuid\Uuidstring

The UUID namespace in which to create the named UUID

$name

string

The name to create a UUID for

Returns

Generate a version 4 (random) UUID.

uuid4() : \Rhumsaa\Uuid\Uuid
Static

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

uuid5(\Rhumsaa\Uuid\Uuid | string $ns, string $name) : \Rhumsaa\Uuid\Uuid
Static

Parameters

$ns

\Rhumsaa\Uuid\Uuidstring

The UUID namespace in which to create the named UUID

$name

string

The name to create a UUID for

Returns

Creates a universally unique identifier (UUID) from the most significant bits and least significant bits.

__construct(array $fields) 

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

Parameters

$fields

array

Calculates the UUID time fields from a UNIX timestamp

calculateUuidTime(int $sec, int $usec) : array
Static

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

Parameters

$sec

int

Seconds since the Unix Epoch

$usec

int

Microseconds

Exceptions

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

Returns

array

Get the hardware address as a 48-bit positive integer.

getNodeFromSystem() : string
Static

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.

todo Needs evaluation and possibly modification to ensure this works well across multiple platforms.

Returns

string

Returns true if the system has Moontoast\Math\BigNumber

hasBigNumber() : bool
Static

Returns

bool

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

is64BitSystem() : bool
Static

Returns

bool

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)

uuidFromHashedName(string $hash, int $version) : \Rhumsaa\Uuid\Uuid
Static

Parameters

$hash

string

The hash to use when creating the UUID

$version

int

The UUID version to be generated

Returns

 Properties

 

For testing, 64-bit system override; if true, treat the system as 32-bit

$force32Bit : bool
 

For testing, Moontoast\Math\BigNumber override; if true, treat as if BigNumber is not available

$forceNoBigNumber : bool
 

For testing, system override to ignore generating node from hardware

$ignoreSystemNode : bool
 

For testing, sets time of day to a static, known value

$timeOfDayTest : array
 

The fields that make up this UUID

$fields : array

This is initialized to the nil value.

see \Rhumsaa\Uuid\Uuid::getFields

 Constants

 

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

NAMESPACE_DNS 
 

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

NAMESPACE_OID 
 

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

NAMESPACE_URL 
 

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

NAMESPACE_X500 
 

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

NIL 
 

Reserved for future definition.

RESERVED_FUTURE 
 

Reserved for Microsoft compatibility.

RESERVED_MICROSOFT 
 

Reserved for NCS compatibility.

RESERVED_NCS 
 

Specifies the UUID layout given in RFC 4122.

RFC_4122