Polyfill Uuid Laravel Package

Getting Started

This polyfill provides uuid_*() functions (e.g., uuid_create(), uuid_generate_v4(), uuid_unparse()) for PHP versions or extensions that lack native UUID support (pre-7.1 or systems without ext-uuid). If you’re using Symfony or Laravel and need UUIDs but can’t guarantee ext-uuid is installed, this package ensures portability. Start by installing via Composer:

composer require symfony/polyfill-uuid

Laravel automatically discovers it as a dependency of symfony/http-foundation (via symfony/polyfill meta-package). Your first use case is likely generating UUIDs in migrations or models:

// Example: In a model's boot() method
protected static function boot()
{
    parent::boot();

    static::creating(function ($model) {
        $model->uuid = uuid_generate_v4();
    });
}

Implementation Patterns

• Transparent Replacement: Replace uuid_*() calls (e.g., from older projects or cross-platform code) without conditional function_exists() checks—the polyfill handles missing functions globally.
• Laravel Integration: Use it in seeders, factories, or domain services where UUIDs are required but you want to avoid hard dependencies on ext-uuid.
• Testing Strategy: In unit tests, mock uuid_generate_v4() or use factories that rely on the polyfill to ensure deterministic behavior (e.g., returning fixed UUIDs in test environments).
• Autoloading: No config needed—Composer’s autoloader loads the polyfill automatically. Avoid manual require statements to preserve PSR-4 best practices.

Gotchas and Tips

• No Real Randomness: This is a polyfill, not aUUID generator implementation. It often delegates to random_bytes() (PHP 7+), so ensure your system has adequate entropy. Fallback behavior may be non-deterministic if random_bytes() fails.
• Function Signature Compatibility: Not all uuid_*() functions are implemented identically. Check polyfill source for exact signatures—e.g., uuid_create() takes a UUID_TYPE_* constant (like UUID_TYPE_DEFAULT), and uuid_unparse() returns strings in canonical format.
• Performance: Each call may incur overhead vs ext-uuid. Avoid generating thousands of UUIDs synchronously in loops without caching (e.g., batch generate once per request if possible).
• Conflict with ext-uuid: If ext-uuid is later installed, the polyfill does not override native functions—your code will switch to native behavior automatically (safe upgrade path).
• Debugging Tip: Use function_exists('uuid_generate_v4') to confirm polyfill is loaded in CLI/web environments—differences here often reveal environment mismatches.