PHP Identifier Extension

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

Features

• 128-bit Base Class: Php\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
• 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)

See docs/README.md for complete build documentation and development tools.

Enable Extension

Add to your php.ini:

extension=identifier

Quick Start

use Php\Identifier\Uuid\Version4;
use Php\Identifier\Uuid\Version7;
use Php\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 Php\Identifier\Context\Fixed;
use Php\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

API Documentation

Base Classes

• Php\Identifier\Bit128 - Abstract base for 128-bit identifiers
• Php\Identifier\Uuid - Base UUID class
• Php\Identifier\Ulid - ULID implementation

UUID Versions

• Php\Identifier\Uuid\Version1 - Time-based UUID
• Php\Identifier\Uuid\Version3 - Name-based UUID (MD5)
• Php\Identifier\Uuid\Version4 - Random UUID
• Php\Identifier\Uuid\Version5 - Name-based UUID (SHA-1)
• Php\Identifier\Uuid\Version6 - Reordered time-based UUID
• Php\Identifier\Uuid\Version7 - Unix timestamp-based UUID

Context System

• Php\Identifier\Context - Context interface
• Php\Identifier\Context\System - Production context
• Php\Identifier\Context\Fixed - Testing context

Performance

This extension delivers world-class performance with native C implementation:

UUID Performance

• 🏆 2.8M+ UUID generations per second - Up to 12.5x faster than popular PHP libraries
• ⚡ 2.2M+ UUID parsing operations per second - Extremely efficient string processing
• 🔧 Production-ready scalability - Consistent performance under enterprise workloads

ULID Performance

• 🚀 9.9M+ ULID generations per second - 8.3x faster than Symfony UID
• ⚡ 3.0M+ ULID parsing operations per second - 5.6x faster than alternatives
• 📈 Monotonic ordering - Built-in timestamp-based sorting with overflow protection

See BENCH.md for comprehensive benchmark results and performance analysis.

Testing

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

Documentation

For detailed documentation, see the docs/README.md which covers:

• Build System - Complete guide to Zig build commands and options
• Stub Generation - Automatic PHP stub generation with rich documentation
• Development Workflow - How to develop and contribute to the extension

For comprehensive performance analysis, see BENCH.md which includes:

• Detailed benchmark results - Complete performance measurements
• Comparison with popular libraries - Head-to-head performance analysis
• Real-world performance impact - Scalability and efficiency metrics
• Benchmark methodology - How to run and interpret benchmarks

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (zig build test)
5. 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