README

A high-performance PHP extension for working with 128-bit identifiers including UUIDs and ULIDs.

Features

128-bit Base Class: Identifier\Bit128 for all 128-bit identifiers
Complete UUID Support: All UUID versions (1, 3, 4, 5, 6, 7) with proper RFC compliance
ULID Support: Universally Unique Lexicographically Sortable Identifiers with monotonic ordering
Thread Safety: Full thread safety for ULID monotonic generation using TSRM (Thread Safe Resource Manager)
Context System: Deterministic generation for testing with FixedContext
Exceptional Performance: Native C implementation delivering 9.9M+ ULID ops/sec, 2.8M+ UUID ops/sec
Type Safety: Proper PHP class hierarchy with inheritance

Installation

Requirements

PHP 8.1 or higher
Zig 0.15.2+ (Download from ziglang.org) - The amazing build system that makes this all possible

Build and Install

git clone https://github.com/your-org/php-ext-identifier.git
cd php-ext-identifier
zig build dev  # Build + test in one command

For production installation:

zig build install-system  # Install to system PHP (requires sudo)

Enable Extension

Add to your php.ini:

extension=identifier

Quick Start

use Identifier\Uuid\Version4;
use Identifier\Uuid\Version7;
use Identifier\Ulid;

// Generate random UUID v4
$uuid = Version4::generate();
echo $uuid->toString(); // e.g., "550e8400-e29b-41d4-a716-446655440000"

// Generate timestamp-based UUID v7
$uuid7 = Version7::generate();
echo $uuid7->toString();

// Generate ULID
$ulid = Ulid::generate();
echo $ulid->toString(); // e.g., "01ARZ3NDEKTSV4RRFFQ69G5FAV"

Testing with Fixed Context

use Identifier\Context\Fixed;
use Identifier\Uuid\Version4;

// Create deterministic context for testing
$ctx = Fixed::create(1640995200000, 12345);

// Generate deterministic UUIDs
$uuid1 = Version4::generate($ctx);
$uuid7 = Version7::generate($ctx);
$ulid = Ulid::generate($ctx);

// Both calls with same context will produce same results

Thread Safety

This extension is fully thread-safe for ULID monotonic generation in multi-threaded PHP environments (ZTS builds). The implementation uses PHP's TSRM (Thread Safe Resource Manager) to ensure proper thread isolation.

How Thread Safety Works

Thread Isolation: Each thread maintains its own monotonic state (last timestamp and randomness)
Zero Contention: No locks or synchronization required - each thread operates independently
Monotonic Ordering: ULIDs generated within a single thread are guaranteed to be monotonically increasing
Performance: Thread safety comes with zero performance overhead

Compatibility

✅ Apache mod_php (both threaded and non-threaded)
✅ Apache mod_worker (requires ZTS PHP build)
✅ Windows IIS (requires ZTS PHP build)
✅ PHP-FPM (process-based, inherently thread-safe)
✅ CLI (single-threaded by default)

Build Considerations

The same extension binary works for both ZTS (thread-safe) and non-ZTS PHP builds:

# Check if your PHP build supports threading
php -m | grep -i zts
php-config --configure-options | grep -i zts

For web servers that use threading (like Apache mod_worker or IIS), ensure you're using a ZTS PHP build to get full thread safety benefits.

API Documentation

Check the stub file for a detailed API documentation.

Testing

zig build test      # Run all tests
zig build dev       # Build + test

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass (zig build test)
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Zig Programming Language - This project is built using Zig's incredible embedded C compiler and build system. Zig's seamless C interop, cross-compilation capabilities, and modern build tooling make it the perfect choice for PHP extension development. Special thanks to the Zig team for creating such an outstanding development experience.
RFC 4122 - UUID specification
RFC 9562 - Updated UUID specification
ULID Specification - ULID format specification

castor / identifier

Maintainers

Details