garrcomm/uuid

Small UUID library, for UUIDv1, UUIDv3, UUIDv4 and UUIDv5

Maintainers

Details

bitbucket.org/garrcomm/php-uuid

Homepage

Source

Issues

Documentation

Installs: 8

Dependents: 0

Suggesters: 0

Security: 0

v1.0.0 2023-04-17 21:53 UTC

Requires

Requires (Dev)

CC-BY-SA-4.0 2a26dae67c670fa58f0a48570037436061d71ccc

uuidUUIDv3UUIDv4UUIDv5uuidv1

This package is auto-updated.

Last update: 2024-11-22 12:06:52 UTC

README

Table of contents

Introduction

This library is a single-class UUID data model for PHP, supporting UUID versions 1, 3, 4 and 5. The reason this library has been made is that many UUID libraries are very large and contain quite some overhead. This is meant to be a single class file handling all your UUID needs.

How to install

Simply copy src/Uuid.php to your project or install through composer require garrcomm/uuid

Code quality

Code quality is checked with several tools to make sure everything is working and well documented. The following methods are in use:

Examples

// Create a default UUID version 1
$uuid = Garrcomm\Uuid::newV1();
echo $uuid; // 8e8bb6e0-daee-11ed-82fa-e7446a136fc7

// Create a UUID version 1 with a specific timestamp
$uuid = Garrcomm\Uuid::newV1(strtotime('1983-08-11 16:00:00'));
echo $uuid; // 98d14000-5fc9-11c1-bacc-e7446a136fc7
echo $uuid->getDateTime()->format(DateTimeInterface::RFC3339); // 1983-08-11T16:00:00+00:00
echo $uuid->getNode(); // e7:44:6a:13:6f:c7

// Create a UUID version 1 with a specific timestamp and node
$uuid = Garrcomm\Uuid::newV1(strtotime('1983-08-11 16:00:00'), 'ab:cd:ef:01:23:45');
echo $uuid; // 98d14000-5fc9-11c1-8b40-abcdef012345

// Create instance based on an existing UUID
$uuid = new Garrcomm\Uuid('98d14000-5fc9-11c1-8b40-abcdef012345');
echo $uuid->getDateTime()->format(DateTimeInterface::RFC3339); // 1983-08-11T16:00:00+00:00

// Create a namespaced version 3 UUID
$uuid = Garrcomm\Uuid::newV3('https://www.stefanthoolen.nl/', Garrcomm\Uuid::NAMESPACE_URL);
echo $uuid; // b288873f-2f8b-366d-86f6-0e024ad3cfb6

// Create a default UUID version 4
$uuid = Garrcomm\Uuid::newV4();
echo $uuid; // efdbd62e-f38a-4e36-aac9-983634b7e78c

There's also JSON support built-in;

$uuid = Garrcomm\Uuid::newV1();
echo json_encode($uuid, JSON_PRETTY_PRINT);

results in:

{
    "uuid": "bf23c020-db72-11ed-99a5-842282ee5183",
    "numeric": 2.5406817441082786e+38,
    "version": 1,
    "variant": "RFC_4122",
    "timestamp": {
        "date": "2023-04-15 09:48:59.789930",
        "timezone_type": 1,
        "timezone": "+00:00"
    },
    "node": "84:22:82:ee:51:83"
}

UUID versions

Why UUID v1, 3, 4 and 5 but not 2?

Maybe, in the future, there will be added support for UUIDv2, but there is not really a good use case for it in my humble opinion. Because of all the data stored in the UUID, with version 2, only 64 unique IDs can be generated within a timespan of 7 minutes.

When to use which version?

It's not that v5 is better than v1. It's different. Taking security and uniqueness into consideration, this table can help you choose:

VersionUniquenessPrivacySecureDescription
UUID v1⭐⭐⭐⭐⭐⭐⭐⭐Contains a timestamp and computer node. You may want to choose to keep this private, but it makes the UUID very unique.
UUID v3⭐⭐⭐⭐⭐⭐⭐⭐⭐Contains a namespace and string. Shall always be the same if you use the same namespace and string. Hashing is done with md5.
UUID v4⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐Completely random. Doesn't contain predictable or personal data, but there's a very small possibility the UUID exists somewhere else on the world.
UUID v5⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐Exactly the same as UUIDv3 but hashing is done with sha1.

It's true that the star rating is not really precise, but it can help decide.

Privacy is judged by the data that could possibly be extracted from the UUID. Also, MD5 is vulnerable (source) with some use cases, so v5 is slightly more secure compared to v3 and data could, in theory, be extracted from a UUIDv3.

Class synopsis

class Uuid implements JsonSerializable {

    /* Constants */
    public const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
    public const NAMESPACE_ISO_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
    public const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
    public const NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8';
    public const NIL = '00000000-0000-0000-0000-000000000000';
    public const VARIANT_NCS = 0b0;
    public const VARIANT_RFC_4122 = 0b10;
    public const VARIANT_MICROSOFT_GUID = 0b110;
    public const VARIANT_RESERVED_FUTURE_USE = 0b1110;

    /* Methods */
    public __construct(string $data)
    public __toString(): string
    public getBinaryValue(): string
    public getDateTime(): ?DateTime
    public getFormatted(): string
    public getNode(): ?string
    public getNumericValue(): float
    public getUnixTimestamp(): ?float
    public getUuidTimestamp(): ?int
    public getVariant(): int
    public getVersion(): int
    public jsonSerialize()
    public static newV1(?float $timestamp = null, ?string $node = null): self
    public static newV3(string $nameString, string $namespace = Uuid::NIL): self
    public static newV4(): self
    public static newV5(string $nameString, string $namespace = Uuid::NIL): self
}

Constants

Uuid::NAMESPACE_DNS
    Predefined namespace for fully-qualified domain names as name string

Uuid::NAMESPACE_ISO_OID
    Predefined namespace for ISO Object Identifiers as name string

Uuid::NAMESPACE_URL
    Predefined namespace for URLs as name string

Uuid::NAMESPACE_X500
    Predefined namespace for X.500 distinguished names as name string

Uuid::NIL
    A nil/null namespace; totally empty, but legal.

Uuid::VARIANT_MICROSOFT_GUID
    The UUID variant is a Microsoft GUID.

Uuid::VARIANT_NCS
    The UUID variant is reserved for NCS backward compatibility.

Uuid::VARIANT_RESERVED_FUTURE_USE
    The UUID variant is reserved for future use.

Uuid::VARIANT_RFC_4122
    The UUID variant complies with the RFC-4122.

Methods

Uuid::__construct

Description

public Uuid::__construct(string $data)

Returns a new UUID object

Parameters

  • data
    The data for this UUID. Three formats below are supported;
    1. Binary; 16 byte/128 bit string
    2. Canonical textual representation: 00000000-0000-0000-0000-000000000000
    3. Represented with surrounding braces: {00000000-0000-0000-0000-000000000000}
    4. As uniform resource name: urn:uuid:00000000-0000-0000-0000-000000000000.

Errors/Exceptions

An InvalidArgumentException is thrown when the UUID is not formatted correctly.

Uuid::__toString

Description

public Uuid::__toString(): string

Converts the UUID object to a string

Return Values

A string formatted as 00000000-0000-0000-0000-000000000000

Uuid::getBinaryValue

Description

public Uuid::getBinaryValue(): string

Returns the UUID as 16-byte binary value

Return Values

A string of 16 bytes

Uuid::getDateTime

Description

public Uuid::getDateTime(): ?DateTime

Returns the timestamp of the UUID as DateTime object (v1 only)

Return Values

The DateTime object, or null when there's no timestamp available

Uuid::getFormatted

Description

public Uuid::getFormatted(): string

Returns the UUID in Standard String Format (always 36 characters long)

Return Values

A string formatted as 00000000-0000-0000-0000-000000000000

Uuid::getNode

Description

public Uuid::getNode(): ?string

Returns the node from the UUID (v1 only)

Return Values

The node in 17:28:39:4a:5b:6c format, or null when there's no node available

Uuid::getNumericValue

Description

public Uuid::getNumericValue(): float

Gets the UUID as floating point value

Return Values

Returns a 128 bit integer number

Uuid::getUnixTimestamp

Description

public Uuid::getUnixTimestamp(): ?float

Returns the Unix timestamp

Return Values

Amount of seconds passed since 1970-01-01 00:00:00 UTC as float (microseconds included)
or null when no timestamp is available

Uuid::getUuidTimestamp

Description

public Uuid::getUuidTimestamp(): ?int

Returns the UUID timestamp

Return Values

Amount of seconds passed since 1582-10-15 00:00:00 UTC in 100-nanoseconds, or null when no
timestamp is available.

Uuid::getVariant

Description

public Uuid::getVariant(): int

Returns the UUID variant

Return Values

An integer matching one of the Uuid::VARIANT_ constants

Uuid::getVersion

Description

public Uuid::getVersion(): int

Returns the UUID version

Return Values

The UUID version (1, 3, 4 or 5)

Uuid::jsonSerialize

Description

public Uuid::jsonSerialize()

Returns this object, ready to be json serialized

Return Values

This object, ready to be json serialized

Uuid::newV1

Description

public static Uuid::newV1(?float $timestamp = null, ?string $node = null): self

Returns a new UUID object populated with a unique v1 UUID

Parameters

  • timestamp
    Timestamp of the UUID (null = current timestamp).
  • node
    Node string (null = auto detect).

Return Values

A UUID object containing a version 1 UUID

Errors/Exceptions

An InvalidArgumentException is thrown when the UUID is not formatted correctly.

Uuid::newV3

Description

public static Uuid::newV3(string $nameString, string $namespace = Uuid::NIL): self

Returns a new UUID object populated with a v3 UUID

Parameters

  • nameString
    Input string.
  • namespace
    Namespace UUID (one of the Uuid::NAMESPACE_ constants, or a custom namespace).

Return Values

A UUID object containing a version 3 UUID

Errors/Exceptions

An InvalidArgumentException is thrown when the UUID is not formatted correctly.

Uuid::newV4

Description

public static Uuid::newV4(): self

Returns a new UUID object populated with a unique v4 UUID

Return Values

A UUID object containing a version 4 UUID

Uuid::newV5

Description

public static Uuid::newV5(string $nameString, string $namespace = Uuid::NIL): self

Returns a new UUID object populated with a v5 UUID

Parameters

  • nameString
    Input string.
  • namespace
    Namespace UUID (one of the static::NAMESPACE_ constants, or a custom namespace).

Return Values

A UUID object containing a version 5 UUID

Errors/Exceptions

An InvalidArgumentException is thrown when the UUID is not formatted correctly.