Lightweight, dependency-free PHP library to generate and handle time-ordered identifiers: UUIDv7 (RFC 9562), with ULID support coming next.
Built for database indexing performance: UUIDv7 values are sorted by time, which avoids B-tree index fragmentation (unlike random UUIDv4 values).
- Zero dependencies beyond the PHP standard library
- Crypto-secure: randomness from
random_bytes()only - Time-ordered: sequential inserts, compact B-tree indexes
- Monotonic: values generated by a single process within the same millisecond are strictly increasing
- Tiny API, focused on UUIDv7 (then ULID)
- PHP 8.3+:
final,readonly, immutable value objects - RFC 9562 compliant
composer require kissous/uuid7Requires PHP 8.3 or higher.
use Kissous\Uuid7\Uuid7;
// Generate a new UUIDv7
$uuid = Uuid7::generate();
echo $uuid->toString(); // e.g. 0190f3a4-7b2c-7def-8123-456789abcdef
echo $uuid; // same output (Stringable)
// Parse an existing string (case-insensitive, normalized to lowercase)
$parsed = Uuid7::fromString('0190F3A4-7B2C-7DEF-8123-456789ABCDEF');
// Validation: throws InvalidUuidException if the string is not a valid UUIDv7
use Kissous\Uuid7\Exception\InvalidUuidException;
try {
Uuid7::fromString('not-a-uuid');
} catch (InvalidUuidException $e) {
// ...
}| Version | Contents |
|---|---|
| v1.0 | UUIDv7: generate, fromString, toString, validation |
| v1.1 | Monotonicity within the same millisecond |
| v1.2 | timestamp(), equals(), compareTo() |
| v1.3 | toBytes/fromBytes, toHex/fromHex, toBase32/fromBase32 |
| v1.4 | Full ULID support + UUIDv7 ↔ ULID conversion |
| v1.5 | Injectable Clock / RandomSource, Uuid7Factory |
| v1.6 | Integrations: kissous/uuid7-doctrine, kissous/uuid7-eloquent |
Per-version details in docs/roadmap/.
composer install
composer test # PHPUnit (Unit + Property)
composer stan # PHPStan, max level
composer cs:check # PHP-CS-Fixer (dry-run)
composer cs # PHP-CS-Fixer (apply fixes)
composer bench # Benchmarks against ramsey/uuidMIT © Omar Kissous