jp3cki / uuid
Requires
- php: >= 8.3
- php-64bit: >= 8.3
- ext-date: *
- ext-hash: *
- ext-pcre: *
- ext-random: *
- ext-spl: *
- paragonie/constant_time_encoding: ^3.1.4
Requires (Dev)
- ergebnis/composer-normalize: ^2.57.0
- jp3cki/coding-standard: ^2.0.0
- phpstan/phpstan: ^2.3.5
- phpunit/phpunit: ^12.5.44
- squizlabs/php_codesniffer: ^4.0.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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-000000000000jp3cki\uuid\NS::dns():6ba7b810-9dad-11d1-80b4-00c04fd430c8jp3cki\uuid\NS::url():6ba7b811-9dad-11d1-80b4-00c04fd430c8jp3cki\uuid\NS::oid():6ba7b812-9dad-11d1-80b4-00c04fd430c8jp3cki\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 byUuid::sha256()in v6.x or earlier and need to reproduce them, switch those calls to the newUuid::sha256Draft(). -
new Mac()(andnew 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, andUuid::v1()/Uuid::v6()use it when the MAC address is omitted.isUnicast()now returnsfalseandisMulticast()returnstruefor 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 throughUuid::fromString()andisValid()in v5 may now be reported as invalid. -
Uuid::v7()no longer guarantees monotonic ordering within the same millisecond. The previous process-widerand_acounter 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\Randomclass 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