Documentation

Guid extends Uuid
in package

Guid represents a UUID with "native" (little-endian) byte order

From Wikipedia:

The first three fields are unsigned 32- and 16-bit integers and are subject to swapping, while the last two fields consist of uninterpreted bytes, not subject to swapping. This byte swapping applies even for versions 3, 4, and 5, where the canonical fields do not correspond to the content of the UUID.

The first three fields of a GUID are encoded in little-endian byte order, while the last three fields are in network (big-endian) byte order. This is according to the history of the Microsoft definition of a GUID.

According to the .NET Guid.ToByteArray method documentation:

Note that the order of bytes in the returned byte array is different from the string representation of a Guid value. The order of the beginning four-byte group and the next two two-byte groups is reversed, whereas the order of the last two-byte group and the closing six-byte group is the same.

Tags
link

UUID Variants on Wikipedia
link

Windows GUID structure
link

.NET Guid Struct
link

.NET Guid.ToByteArray Method
psalm-immutable

Table of Contents

DCE_DOMAIN_GROUP  = 1
DCE Security group domain
DCE_DOMAIN_NAMES  = [self::DCE_DOMAIN_PERSON => 'person', self::DCE_DOMAIN_GROUP => 'group', self::DCE_DOMAIN_ORG => 'org']
DCE Security domain string names
DCE_DOMAIN_ORG  = 2
DCE Security organization domain
DCE_DOMAIN_PERSON  = 0
DCE Security principal domain
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 a special form of UUID that is specified to have all 128 bits set to zero
RESERVED_FUTURE  = 7
Variant: reserved for future definition
RESERVED_MICROSOFT  = 6
Variant: reserved, Microsoft Corporation backward compatibility
RESERVED_NCS  = 0
Variant: reserved, NCS backward compatibility
RFC_4122  = 2
Variant: the UUID layout specified in RFC 4122
UUID_TYPE_DCE_SECURITY  = 2
Version 2 (DCE Security) UUID
UUID_TYPE_HASH_MD5  = 3
Version 3 (name-based and hashed with MD5) UUID
UUID_TYPE_HASH_SHA1  = 5
Version 5 (name-based and hashed with SHA1) UUID
UUID_TYPE_IDENTIFIER  = 2
UUID_TYPE_PEABODY  = 6
Version 6 (ordered-time) UUID
UUID_TYPE_RANDOM  = 4
Version 4 (random) UUID
UUID_TYPE_TIME  = 1
Version 1 (time-based) UUID
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  : CodecInterface
$fields  : FieldsInterface
$numberConverter  : NumberConverterInterface
$timeConverter  : TimeConverterInterface
$factory  : UuidFactoryInterface|null
$factoryReplaced  : bool
__construct()  : mixed
Creates a universally unique identifier (UUID) from an array of fields
__serialize()  : array<string|int, mixed>
__toString()  : string
Casts the UUID to the string standard representation
__unserialize()  : void
compareTo()  : int
Returns -1, 0, or 1 if the UUID is less than, equal to, or greater than the other UUID
equals()  : bool
Returns true if the UUID is equal to the provided object
fromBytes()  : UuidInterface
Creates a UUID from a byte string
fromDateTime()  : UuidInterface
Creates a UUID from a DateTimeInterface instance
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 binary string representation of the UUID
getClockSeqHiAndReserved()  : string
getClockSeqHiAndReservedHex()  : string
getClockSeqLow()  : string
getClockSeqLowHex()  : string
getClockSequence()  : string
getClockSequenceHex()  : string
getDateTime()  : DateTimeImmutable
getFactory()  : UuidFactoryInterface
Returns the factory used to create UUIDs
getFields()  : FieldsInterface
Returns the fields that comprise this UUID
getFieldsHex()  : array<string|int, string>
getHex()  : Hexadecimal
Returns the hexadecimal representation of the UUID
getInteger()  : Integer
Returns the integer representation of the UUID
getLeastSignificantBits()  : string
getLeastSignificantBitsHex()  : string
getMostSignificantBits()  : string
getMostSignificantBitsHex()  : string
getNode()  : string
getNodeHex()  : string
getNumberConverter()  : NumberConverterInterface
getTimeHiAndVersion()  : string
getTimeHiAndVersionHex()  : string
getTimeLow()  : string
getTimeLowHex()  : string
getTimeMid()  : string
getTimeMidHex()  : string
getTimestamp()  : string
getTimestampHex()  : string
getUrn()  : string
getVariant()  : int|null
getVersion()  : int|null
isValid()  : bool
Returns true if the provided string is a valid UUID
jsonSerialize()  : string
Converts the UUID to a string for JSON serialization
serialize()  : string
Converts the UUID to a string for PHP serialization
setFactory()  : void
Sets the factory used to create UUIDs
toString()  : string
Returns the string standard representation of the UUID
unserialize()  : void
Re-constructs the object from its serialized form
uuid1()  : UuidInterface
Returns a version 1 (time-based) UUID from a host ID, sequence number, and the current time
uuid2()  : UuidInterface
Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the current time
uuid3()  : UuidInterface
Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name
uuid4()  : UuidInterface
Returns a version 4 (random) UUID
uuid5()  : UuidInterface
Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name
uuid6()  : UuidInterface
Returns a version 6 (ordered-time) UUID from a host ID, sequence number, and the current time

Constants

DCE_DOMAIN_NAMES

DCE Security domain string names

public mixed DCE_DOMAIN_NAMES = [self::DCE_DOMAIN_PERSON => 'person', self::DCE_DOMAIN_GROUP => 'group', self::DCE_DOMAIN_ORG => 'org']
Tags
link

DCE 1.1, §11.5.1.1

NIL

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

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

RFC 4122, § 4.1.7: Nil UUID

UUID_TYPE_PEABODY

Version 6 (ordered-time) UUID

public mixed UUID_TYPE_PEABODY = 6

This is named UUID_TYPE_PEABODY, since the specification is still in draft form, and the primary author/editor's name is Brad Peabody.

Tags
link

UUID version 6 IETF draft
link

"Version 6" UUIDs

VALID_PATTERN

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}$'
Tags
deprecated

Use ValidatorInterface::getPattern() instead.

Properties

$factoryReplaced

private static bool $factoryReplaced = false

flag to detect if the UUID factory was replaced internally, which disables all optimizations for the default/happy path internal scenarios

Methods

__construct()

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

public __construct(Fields $fields, NumberConverterInterface $numberConverter, CodecInterface $codec, TimeConverterInterface $timeConverter) : 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 : Fields

The fields from which to construct a UUID

$numberConverter : 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

$timeConverter : TimeConverterInterface

The time converter to use for converting timestamps extracted from a UUID to unix timestamps

Return values
mixed —

__serialize()

public __serialize() : array<string|int, mixed>
Return values
array<string|int, mixed> —

__toString()

Casts the UUID to the string standard representation

public __toString() : string
Tags
psalm-return

non-empty-string

Return values
string —

__unserialize()

public __unserialize(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>
Return values
void —

compareTo()

Returns -1, 0, or 1 if the UUID is less than, equal to, or greater than the other 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

The UUID to compare

Return values
int —

-1, 0, or 1 if the UUID is less than, equal to, or greater than $other

equals()

Returns true if the UUID is equal to the provided object

public equals(object|null $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 the UUID.

Parameters
$other : object|null

An object to test for equality with this UUID

Return values
bool —

True if the other object is equal to this UUID

fromBytes()

Creates a UUID from a byte string

public static fromBytes(string $bytes) : UuidInterface
Parameters
$bytes : string

A binary string

Tags
psalm-pure

note: changing the internal factory is an edge case not covered by purity invariants, but under constant factory setups, this method operates in functionally pure manners

psalm-suppress

ImpureStaticProperty we know that the factory being replaced can lead to massive havoc across all consumers: that should never happen, and is generally to be discouraged. Until the factory is kept un-replaced, this method is effectively pure.

Return values
UuidInterface —

A UuidInterface instance created from a binary string representation

fromDateTime()

Creates a UUID from a DateTimeInterface instance

public static fromDateTime(DateTimeInterface $dateTime[, Hexadecimal|null $node = null ][, int|null $clockSeq = null ]) : UuidInterface
Parameters
$dateTime : DateTimeInterface

The date and time

$node : Hexadecimal|null = null

A 48-bit number representing the hardware address

$clockSeq : int|null = 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 —

A UuidInterface instance that represents a version 1 UUID created from a DateTimeInterface instance

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

Tags
psalm-pure

note: changing the internal factory is an edge case not covered by purity invariants, but under constant factory setups, this method operates in functionally pure manners

Return values
UuidInterface —

A UuidInterface instance created from the string representation of a 128-bit integer

fromString()

Creates a UUID from the string standard representation

public static fromString(string $uuid) : UuidInterface
Parameters
$uuid : string

A hexadecimal string

Tags
psalm-pure

note: changing the internal factory is an edge case not covered by purity invariants, but under constant factory setups, this method operates in functionally pure manners

psalm-suppress

ImpureStaticProperty we know that the factory being replaced can lead to massive havoc across all consumers: that should never happen, and is generally to be discouraged. Until the factory is kept un-replaced, this method is effectively pure.

Return values
UuidInterface —

A UuidInterface instance created from a hexadecimal string representation

getBytes()

Returns the binary string representation of the UUID

public getBytes() : string
Tags
psalm-return

non-empty-string

Return values
string —

getDateTime()

public getDateTime() : DateTimeImmutable
Tags
deprecated

In ramsey/uuid version 5.0.0, this will be removed. It is available at UuidV1::getDateTime().

throws
UnsupportedOperationException

if UUID is not time-based

throws
DateTimeException

if DateTime throws an exception/error

Return values
DateTimeImmutable —

An immutable instance of DateTimeInterface

getInteger()

Returns the integer representation of the UUID

public getInteger() : Integer
Return values
Integer —

getLeastSignificantBits()

public getLeastSignificantBits() : string
Tags
deprecated

This method will be removed in 5.0.0. There is no direct alternative, but the same information may be obtained by splitting in half the value returned by UuidInterface::getHex().

Return values
string —

getLeastSignificantBitsHex()

public getLeastSignificantBitsHex() : string
Tags
deprecated

This method will be removed in 5.0.0. There is no direct alternative, but the same information may be obtained by splitting in half the value returned by UuidInterface::getHex().

Return values
string —

getMostSignificantBits()

public getMostSignificantBits() : string
Tags
deprecated

This method will be removed in 5.0.0. There is no direct alternative, but the same information may be obtained by splitting in half the value returned by UuidInterface::getHex().

Return values
string —

getMostSignificantBitsHex()

public getMostSignificantBitsHex() : string
Tags
deprecated

This method will be removed in 5.0.0. There is no direct alternative, but the same information may be obtained by splitting in half the value returned by UuidInterface::getHex().

Return values
string —

isValid()

Returns true if the provided string is a valid UUID

public static isValid(string $uuid) : bool
Parameters
$uuid : string

A string to validate as a UUID

Tags
psalm-pure

note: changing the internal factory is an edge case not covered by purity invariants, but under constant factory setups, this method operates in functionally pure manners

Return values
bool —

True if the string is a valid UUID, false otherwise

jsonSerialize()

Converts the UUID to a string for JSON serialization

public jsonSerialize() : string
Return values
string —

serialize()

Converts the UUID to a string for PHP serialization

public serialize() : string
Return values
string —

setFactory()

Sets the factory used to create UUIDs

public static setFactory(UuidFactoryInterface $factory) : void
Parameters
$factory : UuidFactoryInterface

A factory that will be used by this class to create UUIDs

Return values
void —

toString()

Returns the string standard representation of the UUID

public toString() : string
Tags
psalm-return

non-empty-string

Return values
string —

unserialize()

Re-constructs the object from its serialized form

public unserialize(string $serialized) : void
Parameters
$serialized : string

The serialized PHP string to unserialize into a UuidInterface instance

Tags
phpcsSuppress

SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint

Return values
void —

uuid1()

Returns a version 1 (time-based) UUID from a host ID, sequence number, and the current time

public static uuid1([Hexadecimal|int|string|null $node = null ][, int $clockSeq = null ]) : UuidInterface
Parameters
$node : Hexadecimal|int|string|null = 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 —

A UuidInterface instance that represents a version 1 UUID

uuid2()

Returns a version 2 (DCE Security) UUID from a local domain, local identifier, host ID, clock sequence, and the current time

public static uuid2(int $localDomain[, Integer|null $localIdentifier = null ][, Hexadecimal|null $node = null ][, int|null $clockSeq = null ]) : UuidInterface
Parameters
$localDomain : int

The local domain to use when generating bytes, according to DCE Security

$localIdentifier : Integer|null = null

The local identifier for the given domain; this may be a UID or GID on POSIX systems, if the local domain is person or group, or it may be a site-defined identifier if the local domain is org

$node : Hexadecimal|null = null

A 48-bit number representing the hardware address

$clockSeq : int|null = 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 (in a version 2 UUID, the lower 8 bits of this number are replaced with the domain).

Return values
UuidInterface —

A UuidInterface instance that represents a version 2 UUID

uuid3()

Returns a version 3 (name-based) UUID based on the MD5 hash of a namespace ID and a name

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

The namespace (must be a valid UUID)

$name : string

The name to use for creating a UUID

Tags
psalm-suppress

ImpureMethodCall we know that the factory being replaced can lead to massive havoc across all consumers: that should never happen, and is generally to be discouraged. Until the factory is kept un-replaced, this method is effectively pure.

psalm-pure

note: changing the internal factory is an edge case not covered by purity invariants, but under constant factory setups, this method operates in functionally pure manners

Return values
UuidInterface —

A UuidInterface instance that represents a version 3 UUID

uuid4()

Returns a version 4 (random) UUID

public static uuid4() : UuidInterface
Return values
UuidInterface —

A UuidInterface instance that represents a version 4 UUID

uuid5()

Returns a version 5 (name-based) UUID based on the SHA-1 hash of a namespace ID and a name

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

The namespace (must be a valid UUID)

$name : string

The name to use for creating a UUID

Tags
psalm-pure

note: changing the internal factory is an edge case not covered by purity invariants, but under constant factory setups, this method operates in functionally pure manners

psalm-suppress

ImpureMethodCall we know that the factory being replaced can lead to massive havoc across all consumers: that should never happen, and is generally to be discouraged. Until the factory is kept un-replaced, this method is effectively pure.

Return values
UuidInterface —

A UuidInterface instance that represents a version 5 UUID

uuid6()

Returns a version 6 (ordered-time) UUID from a host ID, sequence number, and the current time

public static uuid6([Hexadecimal|null $node = null ][, int $clockSeq = null ]) : UuidInterface
Parameters
$node : Hexadecimal|null = null

A 48-bit number representing the hardware address

$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 —

A UuidInterface instance that represents a version 6 UUID

Search results