README

UUID v4, v5, and v7 generation, ULID support, short ID encoding, and ordered UUIDs for database indexing.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/php-uuid-tools

Usage

Generate UUID v4

use PhilipRehberger\UuidTools\Uuid;

$uuid = Uuid::v4();
// "f47ac10b-58cc-4372-a567-0e02b2c3d479"

Generate UUID v7

Time-ordered UUIDs with millisecond precision, ideal for database primary keys:

$uuid = Uuid::v7();
// "018e4f6c-1a2b-7000-8000-1234567890ab"

Generate UUID v5

Deterministic namespace-based UUIDs using SHA-1 hashing:

use PhilipRehberger\UuidTools\Uuid;

$uuid = Uuid::v5(Uuid::NAMESPACE_DNS, 'example.com');
// "cfbff0d1-9375-5685-968c-48ce8b15ae17"

// Same inputs always produce the same UUID
$uuid2 = Uuid::v5(Uuid::NAMESPACE_DNS, 'example.com');
// $uuid === $uuid2

// Available namespace constants:
// Uuid::NAMESPACE_DNS, Uuid::NAMESPACE_URL,
// Uuid::NAMESPACE_OID, Uuid::NAMESPACE_X500

ULID

Generate ULIDs (Universally Unique Lexicographically Sortable Identifiers):

use PhilipRehberger\UuidTools\Ulid;

$ulid = Ulid::generate();
// "01ARZ3NDEKTSV4RRFFQ69G5FAV"

Ulid::isValid($ulid); // true

// Convert between ULID and UUID
$uuid = Ulid::toUuid($ulid);
$ulid = Ulid::fromUuid($uuid);

// Extract timestamp (milliseconds since Unix epoch)
$ms = Ulid::timestamp($ulid);

// Decode the timestamp into a DateTimeImmutable (UTC by default)
$dt = Ulid::toDateTime($ulid);
$dtLocal = Ulid::toDateTime($ulid, new \DateTimeZone('America/New_York'));

// Convenience methods on Uuid class
$ulid = Uuid::ulid();
Uuid::isValidUlid($ulid); // true

Short IDs

Encode UUIDs as compact Base62 strings (~22 characters):

use PhilipRehberger\UuidTools\ShortId;

$shortId = ShortId::encode('550e8400-e29b-41d4-a716-446655440000');
// "2D5MNbitT4FNsgGOLfVm6q"

$uuid = ShortId::decode($shortId);
// "550e8400-e29b-41d4-a716-446655440000"

// Convenience methods on Uuid class
$shortId = Uuid::toShortId($uuid);
$uuid = Uuid::fromShortId($shortId);

Validate a UUID

Uuid::isValid('550e8400-e29b-41d4-a716-446655440000'); // true
Uuid::isValid('not-a-uuid');                            // false

// Validate many UUIDs at once; returns indices of invalid entries
Uuid::validateBatch([
    '550e8400-e29b-41d4-a716-446655440000',
    'not-a-uuid',
    '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
]);
// [1]

Extract Version

Uuid::version('550e8400-e29b-41d4-a716-446655440000'); // 4
Uuid::version('invalid');                               // null

Binary Conversion

Convert between UUID strings and 16-byte binary for compact storage:

$bytes = Uuid::toBytes('550e8400-e29b-41d4-a716-446655440000');
// 16-byte binary string

$uuid = Uuid::fromBytes($bytes);
// "550e8400-e29b-41d4-a716-446655440000"

Ordered UUIDs

Reorder UUID fields for optimal database index performance. Puts the most-significant time bits first so UUIDs sort chronologically:

$uuid = Uuid::v7();
$ordered = Uuid::toOrdered($uuid);

// Store $ordered in the database for better index locality

$original = Uuid::fromOrdered($ordered);
// Recovers the original UUID

Batch Generation

Generate multiple UUIDs at once:

$uuids = Uuid::batch(5);
// [
//     "f47ac10b-58cc-4372-a567-0e02b2c3d479",
//     "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
//     ...
// ]

$v7Uuids = Uuid::batch(3, 7);
// Three time-ordered v7 UUIDs

Comparison

$a = Uuid::v4();
$b = Uuid::v4();

Uuid::equals($a, $a);        // true
Uuid::equals($a, $b);        // false

Uuid::compareTo($a, $b);     // -1, 0, or 1

Nil UUID

$nil = Uuid::nil();
// "00000000-0000-0000-0000-000000000000"

API

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT