kissous/uuid7

Lightweight, dependency-free PHP library to generate and handle time-ordered identifiers: UUIDv7 (RFC 9562) and ULID.

Maintainers

Package info

github.com/Kissous/uuid7

pkg:composer/kissous/uuid7

Transparency log

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.1.1 2026-05-31 18:25 UTC

Requires

  • php: ^8.3

Requires (Dev)

MIT 09717dc194a4e2824e1077fe03c3ea55384840e1

  • Omar Kissous

uuididentifierguidulidrfc9562uuidv7uuid7time-ordered

Published on Packagist.org on 2026-05-31 18:26 UTC

This package is auto-updated.

Last update: 2026-07-01 00:20:07 UTC

README

CI Packagist Version PHP Version License

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).

Why uuid7?

  • 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

Installation

composer require kissous/uuid7

Requires PHP 8.3 or higher.

Quick start

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) {
    // ...
}

Roadmap

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/.

Development

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/uuid

License

MIT © Omar Kissous