Documentation

Uuid
in package

This class provides a minimal implementation of UUID.

Important! This will not work on 32-bit systems. You must have a 64-bit proccessor and 64-bit PHP.

Supports:

  • UUIDv1
  • UUIDv4
  • UUIDv5

UUIDs are made of 5 parts:

  • 32b - time-low
  • 16b - time-mid
  • 16b - time-high-and-version
  • 16b - clock-seq (split into 2x8b reserve + low)
  • 48b - node
      low      mid  high seq  node
hex:  00000000-0000-0000-0000-0000000000
oct:  0 1 2 3  4 5  6 7  8 9  A B C D E

Essentially, we can stitch together whatever we need to form a base of 16 bits. Then we need to just apply the variant + version. Done.

Different versions are put together differently:

  • v1 - datetime + MAC address (collision prone because dates)
  • v2 - datetime + MAC address + DCE security (rarely-used)
  • v3 - md5 namespace + name (collision prone because md5)
  • v4 - random
  • v5 - sha1 namespace + name
  • v6 - host ID + sequence number + time (not actually RFC'd yet)

Table of Contents

Constants

NIL  : mixed = '00000000-0000-0000-0000-000000000000'
Nothing, nil, zero.
NS_DNS  : mixed = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
DNS addresses - host names mostly
NS_OID  : mixed = '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
Object IDs - ISO OID - like 4.1.2
NS_URL  : mixed = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
URLs - with all/some the bits: scheme, host, port, path
NS_X500  : mixed = '6ba7b814-9dad-11d1-80b4-00c04fd430c8'
ITU X.500 DN (in DER text output format)
V1_LAZY  : mixed = 1
Use less-accurate but faster datetime generation for UUIDv1.
V1_RANDOM  : mixed = 2
Use a random instead of mac addresses for UUIDv1.

Methods

applyVariant()  : int
Apply the variant-1 to the 16-bit clock sequence.
applyVersion()  : int
Apply the UUID version number.
empty()  : bool
Is this UUID nil?
format()  : string
Pretty format a UUID string.
hasHighPrecisionDatetime()  : bool
Does this system have support for high-precision datetimes?
hasMacAddress()  : bool
Does this system have a suitable MAC address.
nil()  : string
Get a nil UUID string.
uuid1()  : string
Get a valid UUIDv1 string.
uuid4()  : string
Get a valid UUIDv4 string.
uuid5()  : string
Get a valid UUIDv5 string.
uuidFromBytes()  : string
Apply variant mask + versions to a bytes string.
valid()  : bool
Is this UUID valid?
getMacAddress()  : string|null
The system mac address.
getOctalPair()  : int
Get a 16-bit number from a byte string + offset.
getSequence()  : int
Get a 'clock sequence'.
getSubNanoTime()  : int
Get a 60-bit timestamp from 15 Oct 1582.
strip()  : string
Normalize a hex string.

Constants

NIL

Nothing, nil, zero.

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

NS_DNS

DNS addresses - host names mostly

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

NS_OID

Object IDs - ISO OID - like 4.1.2

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

NS_URL

URLs - with all/some the bits: scheme, host, port, path

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

NS_X500

ITU X.500 DN (in DER text output format)

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

V1_LAZY

Use less-accurate but faster datetime generation for UUIDv1.

public mixed V1_LAZY = 1

V1_RANDOM

Use a random instead of mac addresses for UUIDv1.

public mixed V1_RANDOM = 2

Methods

applyVariant()

Apply the variant-1 to the 16-bit clock sequence.

public static applyVariant(int $clock_seq) : int
Parameters
$clock_seq : int

16-bits (no variant)

Return values
int —

16 bits

applyVersion()

Apply the UUID version number.

public static applyVersion(int $time_high, int $version) : int
Parameters
$time_high : int

16-bits (no version)

$version : int

UUID version (1-6)

Return values
int —

16-bits

empty()

Is this UUID nil?

public static empty(string $uuid) : bool

Note, true if invalid.

Parameters
$uuid : string
Return values
bool —

True if the UUID is valid + empty or invalid.

format()

Pretty format a UUID string.

public static format(string $uuid) : string

This doesn't validate. It doesn't do index checks.

Parameters
$uuid : string
Return values
string

hasHighPrecisionDatetime()

Does this system have support for high-precision datetimes?

public static hasHighPrecisionDatetime() : bool

This uses the unix date command.

Return values
bool

hasMacAddress()

Does this system have a suitable MAC address.

public static hasMacAddress() : bool
Return values
bool

nil()

Get a nil UUID string.

public static nil() : string
Return values
string

uuid1()

Get a valid UUIDv1 string.

public static uuid1([int $options = 0 ]) : string

Option flags:

  • V1_RANDOM - Force random MAC address
  • V1_LAZY - Use faster/less-accurate datetime

These flags may be enabled automatically if support is lacking:

  • missing MAC address will fallback to V1_RANDOM mode
  • missing hig-precision datetime will fallback to V1_LAZY
Parameters
$options : int = 0
Tags
throws
Exception

Not enough entropy

Return values
string

uuid4()

Get a valid UUIDv4 string.

public static uuid4() : string
Tags
throws
Exception

Not enough entropy

Return values
string

uuid5()

Get a valid UUIDv5 string.

public static uuid5(string $namespace, string $name) : string
Parameters
$namespace : string
$name : string
Return values
string

uuidFromBytes()

Apply variant mask + versions to a bytes string.

public static uuidFromBytes(string $bytes, int $version) : string
Parameters
$bytes : string

16-byte string

$version : int
Return values
string —

also bytes, but with version + variant stuff

valid()

Is this UUID valid?

public static valid(string $uuid[, int|null $version = null ][, int|null $variant = 1 ][, bool $nil = true ]) : bool

This verifies given version + variant.

Parameters
$uuid : string
$version : int|null = null

1,2,3,4,5

$variant : int|null = 1

0,1,2

$nil : bool = true

empty/NIL values are valid

Return values
bool

getMacAddress()

The system mac address.

private static getMacAddress() : string|null

Most systems will have an 'ethX' or 'enpXsN' interface.

Return values
string|null

getOctalPair()

Get a 16-bit number from a byte string + offset.

private static getOctalPair(string $bytes, int $offset) : int
Parameters
$bytes : string
$offset : int
Return values
int

getSequence()

Get a 'clock sequence'.

private static getSequence() : int

This is a kind of fallback if the datetimes are the same.

Return values
int —

16-bit number.

getSubNanoTime()

Get a 60-bit timestamp from 15 Oct 1582.

private static getSubNanoTime([bool $lazy = false ]) : int

A little weird, yes.

Parameters
$lazy : bool = false

force using microtime (faster, less accurate)

Return values
int

strip()

Normalize a hex string.

private static strip(string $hex) : string

Lowercase + numbers, nothing else.

Parameters
$hex : string
Return values
string
On this page

Search results