1. class
  2. Keruald
  3. \
  4. OmniTools
  5. \
  6. Identifiers
  7. \
  8. UUID

UUID

class UUID

Allow generating and representing UUID. This static class contains helper methods to generate, validate, format and convert UUID.

The UUID class implements both RFC 4122 and proposed extension to UUIDv6, UUIDv7 and UUIDv8.

A UUID is a universal identified with good local and global uniqueness on the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where x is hexadecimal.

To generate a random identified, you can use UUID::UUIDv4().

When you need a monotonic series of always growing identifiers, you can call UUID::UUIDv7(), time-dependent, with 74 bits of randomness, or UUID::batchOfUUIDv7(10), with at least 62 bits of randomness warranted.

Constants

UUID_REGEXP

A regular expression to detect if a lowercase string is a valid UUID.
private MAX_12

The maximal signed integer representable in 12 bits.
private MAX_48

The maximal signed integer representable in 48 bits.
private MAX_62

The maximal signed integer representable in 62 bits.
private UUIDV7_QUANTITY_PER_MS

The quantity of UUIDv7 in a batch allowed to share the same timestamp.
NIL

A null value for a UUID, as defined in RFC 4122.
MAX

The maximum value for a UUID.

Methods

static string
UUIDv1(string $mac = "", int $clk_seq_hi_res = 0, int $clk_seq_low = 0)

Generate a UUIDv1, as defined in RFC 4122.

static string
UUIDv1FromValues(UUIDv1TimeStamp $timestamp, int $clk_seq_hi_res, int $clk_seq_low, BitsVector $node)

Generate a UUIDv1, as defined in RFC 4122, from specified values.

static string
UUIDv4()

Generate a UUIDv4, as defined in RFC 4122.

static string
UUIDv4WithoutHyphens()

Generate a UUIDv4, as defined in RFC 4122, without hyphens.

static string
UUIDv6(string $mac = "", int $clk_seq_hi_res = 0, int $clk_seq_low = 0)

Generate a UUIDv6, as defined in draft-peabody-dispatch-new-uuid-format-03.

static string
UUIDv6FromValues(UUIDv1TimeStamp $timestamp, int $clk_seq_hi_res, int $clk_seq_low, BitsVector $node)

Generate a UUIDv6, as defined in draft-peabody-dispatch-new-uuid-format-03, from known values.

static string
UUIDv1ToUUIDv6(string $uuid)

Convert RFC 4122 UUIDv1 to proposed draft UUIDv6.

static string
UUIDv6ToUUIDv1(string $uuid)

Convert proposed draft UUIDv6 to RFC 4122 UUIDv1.

static string
UUIDv7()

Generate a UUIDv7, as defined in draft-peabody-dispatch-new-uuid-format-03.

static array
batchOfUUIDv7(int $count)

Generate in batch UUIDv7 with monotonicity warranty among them.

static string
UUIDv7FromBits(BitsVector $unixTimestampMs, int $randA, int $randB)

Generate a UUIDv7 for known timestamp and known random values.

static string
UUIDv7FromValues(int $unixTimestampMs, int $randA, int $randB)

Generate a UUIDv7 for known timestamp and known random values, with the timestamp expressed as a 48-bits signed integer.

static string
UUIDv8(int $a, int $b, int $c)

Generate a UUIDv8 for specified custom values.

static string
reformat(string $uuid)

Reformat a 32 or 36 hexadecimal string to a lowercase 36 uuid string.

static bool
isUUID($string)

Determine if the specified string is a valid UUID

static int
getVersion(string $uuid)

Determine the version of the specified UUID.

static int
getVariant(string $uuid)

Determine the variant of the specified UUID.

Details

at line 87
static string UUIDv1(string $mac = "", int $clk_seq_hi_res = 0, int $clk_seq_low = 0)

Generate a UUIDv1, as defined in RFC 4122.

Parameters

string $mac

The node information, normally the MAC address ; if omitted, a random value will be generated.
int $clk_seq_hi_res
int $clk_seq_low

Return Value

string

The UUID

Exceptions

Exception
InvalidArgumentException

at line 117
static string UUIDv1FromValues(UUIDv1TimeStamp $timestamp, int $clk_seq_hi_res, int $clk_seq_low, BitsVector $node)

Generate a UUIDv1, as defined in RFC 4122, from specified values.

That method can be used to reproduce a UUID from known parameters.

Parameters

UUIDv1TimeStamp $timestamp

A 60 bits timestamp
int $clk_seq_hi_res

A 6 bits signed integer
int $clk_seq_low

A 8 bits signed integer
BitsVector $node

A 48 bits vector

Return Value

string

The UUID

at line 152
static string UUIDv4()

Generate a UUIDv4, as defined in RFC 4122.

This UUID offers 122 bits of randomness, built from cryptographically secure pseudo-random integers.

Return Value

string

An RFC 4122 compliant v4 UUID

Exceptions

Exception

at line 187
static string UUIDv4WithoutHyphens()

Generate a UUIDv4, as defined in RFC 4122, without hyphens.

Return Value

string

Exceptions

Exception

See also

UUID::UUIDv4

at line 223
static string UUIDv6(string $mac = "", int $clk_seq_hi_res = 0, int $clk_seq_low = 0)

Generate a UUIDv6, as defined in draft-peabody-dispatch-new-uuid-format-03.

This format is similar to UUIDv1, with bits reordered to allow monotonicity. It is mainly designed to use when compatibility with UUIDv1 is required. For new systems, UUIDv7 use is recommended.

This UUID is deterministic, built from a 60 bits timestamp, a clock sequence and a node information. It doesn't contain any source of randomness, excepted if node information is replaced by 48 random bits, and as such, isn't suitable to be used to generate credentials, or an identified difficult to guess ; use UUIDv7 or UUIDv4 in such cases.

The RFC 4122 recommends the use of the MAC address when available, as a good way to ensure global uniqueness of the UUID. Such use will leak your MAC address, while the warranty of global uniqueness will be false if the MAC address is spoofed, or automatically generated for a VM. As such, proposed draft don't recommend to use MAC address anymore.

Parameters

string $mac

The node information, normally the MAC address ; if omitted, a random value will be generated.
int $clk_seq_hi_res
int $clk_seq_low

Return Value

string

The UUID

Exceptions

Exception
InvalidArgumentException

at line 256
static string UUIDv6FromValues(UUIDv1TimeStamp $timestamp, int $clk_seq_hi_res, int $clk_seq_low, BitsVector $node)

Generate a UUIDv6, as defined in draft-peabody-dispatch-new-uuid-format-03, from known values.

Parameters

UUIDv1TimeStamp $timestamp

A 60 bits precision timestamp
int $clk_seq_hi_res
int $clk_seq_low
BitsVector $node

A 48 bits vector to identify the node

Return Value

string

The UUID

Exceptions

Exception
InvalidArgumentException

See also

UUID::UUIDv6

at line 284
static string UUIDv1ToUUIDv6(string $uuid)

Convert RFC 4122 UUIDv1 to proposed draft UUIDv6.

Parameters

string $uuid

The UUIDv1 to convert

Return Value

string

A UUIDv6 with the same information as the UUIDv1.

at line 300
static string UUIDv6ToUUIDv1(string $uuid)

Convert proposed draft UUIDv6 to RFC 4122 UUIDv1.

Parameters

string $uuid

The UUIDv6 to convert

Return Value

string

A UUIDv1 with the same information as the UUIDv6.

at line 327
static string UUIDv7()

Generate a UUIDv7, as defined in draft-peabody-dispatch-new-uuid-format-03.

This UUID associates a 48 bits timestamp to 74 bits of randomness.

When called at 1 ms intervals, it gives a monotonicity warranty, ie each UUID generated will be greater than the previous one. When you need several UUIDv7 immediately, use UUID::batchOfUUIDv7($count) to get the same warranty.

Return Value

string

Exceptions

Exception

See also

UUID::batchOfUUIDv7 when you need a monotonic series of UUIDv7

at line 349
static array batchOfUUIDv7(int $count)

Generate in batch UUIDv7 with monotonicity warranty among them.

UUID in small batches share the same timestamp, but to maintain some bits of randomness and enough entropy, a new timestamp will be used every 64 timestamps.

When generating a very large batch (> 10000), this method will be slow, as 1 ms break is needed every 64 timestamps, and random_int() can also wait for a source of entropy.

Parameters

int $count

The number of UUIDv7 to generate

Return Value

array

An array of UUIDv7 with monotonic warranty.

at line 391
static string UUIDv7FromBits(BitsVector $unixTimestampMs, int $randA, int $randB)

Generate a UUIDv7 for known timestamp and known random values.

Parameters

BitsVector $unixTimestampMs

A 48 bits timestamp
int $randA

A 12 bits value for random A number
int $randB

A 62 bits value for random B number

Return Value

string

The UUIDv7

at line 420
static string UUIDv7FromValues(int $unixTimestampMs, int $randA, int $randB)

Generate a UUIDv7 for known timestamp and known random values, with the timestamp expressed as a 48-bits signed integer.

Parameters

int $unixTimestampMs

A 48 bits signed integer for timestamp
int $randA

A 12 bits value for random A number
int $randB

A 62 bits value for random B number

Return Value

string

The UUIDv7

at line 447
static string UUIDv8(int $a, int $b, int $c)

Generate a UUIDv8 for specified custom values.

According to proposed draft, the UUIDv8 lets the implementation decides of the bits' layout. Accordingly, this method give you the control of the data you want to use in the UUID. It will write specified values like big-endian signed numbers.

Parameters

int $a

A 48 bits integer for custom_a field
int $b

A 12 bits integer for custom_b field
int $c

A 62 bits integer for custom_c field

Return Value

string

The generated UUID

at line 481
static string reformat(string $uuid)

Reformat a 32 or 36 hexadecimal string to a lowercase 36 uuid string.

Parameters

string $uuid

a hexadecimal string with or without hyphens

Return Value

string

A formatted UUID.

at line 503
static bool isUUID($string)

Determine if the specified string is a valid UUID

Parameters

$string

Return Value

bool

at line 517
static int getVersion(string $uuid)

Determine the version of the specified UUID.

Normally, the proposed draft recommends treating UUID as an opaque value and refrain to inspect bits. However, where necessary, inspectors method for version and variants are allowed.

Parameters

string $uuid

Return Value

int

The UUID version

at line 534
static int getVariant(string $uuid)

Determine the variant of the specified UUID.

Normally, the proposed draft recommends treating UUID as an opaque value and refrain to inspect bits. However, where necessary, inspectors method for version and variants are allowed.

Parameters

string $uuid

Return Value

int

The UUID variant