Search by

jp3cki / uuid

AIZAWA Hina

Package info

github.com/fetus-hina/uuid

pkg:composer/jp3cki/uuid

Statistics

Installs: 23 708

Dependents: 0

Suggesters: 0

Stars: 3

Open Issues: 0

v7.0.0 2026-11-15 13:34 UTC

This package is auto-updated.

Last update: 2026-11-15 13:44:22 UTC


README

Latest Stable Version License

A simple UUID and ULID implementation.
UUIDs follow RFC 9562, including UUIDv6, v7 and v8.

Earlier releases implemented UUIDv6, v7 and v8 from draft-ietf-uuidrev-rfc4122bis-03. The only place where the draft and the RFC give different results is the SHA-256 name-based UUIDv8. Uuid::sha256() now follows the RFC; the draft algorithm is still available as Uuid::sha256Draft() (see below).

Requirements

  • PHP ≥ 8.3 (64 bit)
  • Basic extensions
    • PCRE (preg)
    • Hash

Install

$ composer.phar require jp3cki/uuid

Usage

Timestamp-based UUID (version 1, 6, 7)

<?php

declare(strict_types=1);

use jp3cki\uuid\Uuid;

require_once __DIR__ . '/vendor/autoload.php'; // composer autoloader

// Without a MAC address, a random node ID with the multicast bit set is used (RFC 9562 §6.10).
echo Uuid::v1() . "\n";                    // outputs: 0865cc38-e0f5-11f1-ac4a-33c453f92b0c
echo Uuid::v1('08:00:2b:01:02:03') . "\n"; // outputs: 0865dc96-e0f5-11f1-bd82-08002b010203

// Sortable version of UUIDv1
echo Uuid::v6() . "\n";                    // outputs: 1f1e0f50-865d-6e58-907b-cf21a3edb222
echo Uuid::v6('08:00:2b:01:02:03') . "\n"; // outputs: 1f1e0f50-865d-6eda-9d9d-08002b010203

// Sortable and no host information
echo Uuid::v7() . "\n";                    // outputs: 01884666-7e1c-7cc2-a6e0-34adc6d76b52

Random-based UUID (version 4, aka GUID)

<?php

declare(strict_types=1);

use jp3cki\uuid\Uuid;

require_once __DIR__ . '/vendor/autoload.php'; // composer autoloader

echo Uuid::v4() . "\n"; // outputs: 4c9d5550-f58e-4259-ba00-5e59b15895a0

Hash-based UUID (version 3 or 5)

<?php

declare(strict_types=1);

use jp3cki\uuid\Uuid;
use jp3cki\uuid\NS as UuidNS;

require_once __DIR__ . '/vendor/autoload.php';

// version 3, MD5
echo Uuid::v3(UuidNS::dns(), 'www.example.com') . "\n"; // output: 5df41881-3aed-3515-88a7-2f4a814cf09e

// version 5, SHA-1
echo Uuid::v5(UuidNS::dns(), 'www.example.com') . "\n"; // output: 2ed6657d-e927-568b-95e1-2665a8aea6a2

Predefined UUIDs (for "namespace"):

  • jp3cki\uuid\NS::nil() : 00000000-0000-0000-0000-000000000000
  • jp3cki\uuid\NS::dns() : 6ba7b810-9dad-11d1-80b4-00c04fd430c8
  • jp3cki\uuid\NS::url() : 6ba7b811-9dad-11d1-80b4-00c04fd430c8
  • jp3cki\uuid\NS::oid() : 6ba7b812-9dad-11d1-80b4-00c04fd430c8
  • jp3cki\uuid\NS::x500() : 6ba7b814-9dad-11d1-80b4-00c04fd430c8

Hash-based UUID (version 8, sha2-256)

<?php

declare(strict_types=1);

use jp3cki\uuid\Uuid;
use jp3cki\uuid\NS as UuidNS;

require_once __DIR__ . '/vendor/autoload.php';

// RFC 9562 (Appendix B.2): SHA-256(namespace || name)
echo Uuid::sha256(UuidNS::dns(), 'www.example.com') . "\n";      // output: 5c146b14-3c52-8afd-938a-375d0df1fbf6

// draft-ietf-uuidrev-rfc4122bis-03 (Appendix C.8): SHA-256(hash_space_id || namespace || name)
echo Uuid::sha256Draft(UuidNS::dns(), 'www.example.com') . "\n"; // output: 401835fd-a627-870a-873f-ed73f2bc5b2c

Uuid::sha256() implements the name-based UUIDv8 shown in RFC 9562.

Uuid::sha256Draft() implements the earlier draft, which prepended a per-algorithm "Hash Space ID" (jp3cki\uuid\NS::hashSpace('sha256')) to the input. The RFC dropped the Hash Space ID, so the two methods return different UUIDs for the same input. Use sha256Draft() only to reproduce UUIDs generated with Uuid::sha256() in v6.x and earlier.

User-defined format UUID (version 8)

<?php

declare(strict_types=1);

use jp3cki\uuid\Uuid;

require_once __DIR__ . '/vendor/autoload.php';

// Returns an arbitrary 128-bit (16-octet) binary, adjusted to match UUIDv8.
echo Uuid::v8(str_repeat(chr(0x00), 16)) . "\n"; // output: 00000000-0000-8000-8000-000000000000

// You can also give a random number sequence, but you should use UUIDv4.
echo Uuid::v8(random_bytes(16)) . "\n";          // output: bfc47fb7-948f-8833-87e0-cae07c85d30d
echo Uuid::v4() . "\n";

ULID

<?php

declare(strict_types=1);

use jp3cki\uuid\Ulid;

require_once __DIR__ . '/vendor/autoload.php';

echo (new Ulid()) . "\n";

License

Under the MIT License.

Please refer the LICENSE file.

Breaking Changes

  • v7.0.0

    • Changed minimum requirement to PHP 8.3.

    • Uuid::sha256() now follows RFC 9562 and returns different UUIDs from v6.x for the same input. v6.x implemented draft-ietf-uuidrev-rfc4122bis-03, which mixed a "Hash Space ID" into the hash; the published RFC does not. If you have stored UUIDs generated by Uuid::sha256() in v6.x or earlier and need to reproduce them, switch those calls to the new Uuid::sha256Draft().

    • new Mac() (and new Mac('')) now generates a random locally administered multicast address instead of a unicast one: both the multicast bit (0x01) and the local bit (0x02) of the first octet are set. RFC 9562 §6.10 requires this for a random UUID node ID, and Uuid::v1() / Uuid::v6() use it when the MAC address is omitted. isUnicast() now returns false and isMulticast() returns true for such addresses.

  • v6.0.0

    • Uuid::isValid() now also validates the variant bits. UUIDs with the NCS variant (0b0xxx) or the reserved variant (0b111x) are no longer accepted; only the RFC 4122 variant (0b10xx) and the Microsoft GUID variant (0b110x) pass. Strings that round-tripped through Uuid::fromString() and isValid() in v5 may now be reported as invalid.

    • Uuid::v7() no longer guarantees monotonic ordering within the same millisecond. The previous process-wide rand_a counter has been replaced by per-call CSPRNG output, which removes cross-request correlation and the 4096-per-ms wrap hazard. Sortability is still guaranteed at millisecond granularity, which is what RFC 9562 §5.7 requires; code that relied on strict intra-millisecond order needs to switch to UUIDv6 or carry an explicit sequence column.

  • v5.0.0

    • Changed minimum requirement to PHP 8.2.

    • Removed deprecated Uuid::maxUuid() method.

    • Removed several static methods in the internal\Random class that had been marked as deprecated.

  • v4.0.0

    • Changed minimum requirement to PHP 8.1.
  • v3.0.0

    • Changed minimum requirement to PHP 8.0.

    • Strict type checking is performed by PHP engine.

  • v2.0.0

    • This library no longer works with the 32-bit version of PHP.

    • All public classes are marked as final. You are not permitted to inherit classes from this library.

    • The parameter type is now explicitly specified. I believe most users will not be affected by this, but you may get unexpected results if you call it using a variable of the wrong type.

  • v1.0.0

    • Changed minimum requirement to PHP 7.0