philiprehberger/php-uuid-tools

UUID v4 and v7 generation, validation, and ordered UUIDs for database indexing

v1.0.2 2026-03-17 20:06 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.0
• phpstan/phpstan: ^1.12|^2.0
• phpunit/phpunit: ^11.0

MIT

• Philip Rehberger

• database
• validation
• uuid
• v4
• ordered
• v7

README

UUID v4 and v7 generation, validation, and ordered UUIDs for database indexing. Framework-agnostic, zero dependencies.

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"

Validate a UUID

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

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

Nil UUID

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

API

Method	Description
Uuid::v4(): string	Generate a random UUID v4
Uuid::v7(): string	Generate a time-ordered UUID v7
Uuid::isValid(string $uuid): bool	Validate a UUID string (any version)
Uuid::version(string $uuid): ?int	Extract the version number (null if invalid)
Uuid::toBytes(string $uuid): string	Convert UUID to 16-byte binary
Uuid::fromBytes(string $bytes): string	Convert 16-byte binary to UUID string
Uuid::toOrdered(string $uuid): string	Reorder UUID for database index performance
Uuid::fromOrdered(string $ordered): string	Reverse an ordered UUID to standard format
Uuid::nil(): string	Return the nil UUID (all zeros)

Development

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

License

MIT