Polyfill Uuid Laravel Package

Product Decisions This Supports

This package is infrastructure, not a product feature. It supports decisions about runtime support, deployment portability, and whether to build or buy UUID compatibility plumbing.

• Runtime support matrix: Decide to support PHP environments where ext-uuid is unavailable—shared hosting, minimal containers, serverless, CI/CD—without writing or maintaining a custom UUID fallback.
• Build vs. buy: Buy a Symfony-maintained, MIT-licensed polyfill instead of building uuid_* compatibility in-house. It auto-defers to the native ext-uuid extension when present, so adopting it does not block future performance work.
• Deployment portability: Enables product delivery to AWS Lambda, Heroku, Docker, PaaS, air-gapped systems, and other environments where installing PECL extensions is impractical or prohibited. Reduces environment-specific UUID code and deployment friction.
• Legacy modernization: Keeps older Laravel/PHP applications and third-party libraries that call uuid_* functions working during PHP upgrades without refactoring UUID logic.
• Compliance and audit support: Provides RFC 4122-style UUID generation backed by random_bytes() for identifiers used in audit trails and operational records. It is not a complete security control; entropy and validation requirements still need review.
• Laravel/Symfony ecosystem hygiene: Often already present transitively in Symfony-heavy stacks. The PM decision is usually to audit, document, and standardize rather than add another UUID library or duplicate UUID approaches.
• Roadmap for hybrid/serverless architectures: Supports microservices, modular monoliths, multi-cloud, and edge deployments where environment heterogeneity is normal.
• Maintenance signal: Recent releases add UUID v6/v7 and vendor types and fix v1 timestamp behavior, indicating active Symfony maintenance and reducing the risk of relying on a stale polyfill.

When to Consider This Package

Adopt when:

• Your code or dependencies call uuid_* functions and target PHP runtimes without ext-uuid.
• You deploy to serverless, PaaS, shared hosting, CI/CD, or minimal Docker images where PECL extensions cannot be installed.
• You maintain legacy Laravel/PHP applications or third-party libraries relying on uuid_* functions and want to avoid refactoring UUID code during upgrades.
• You want a zero-configuration, MIT-licensed, Symfony-backed compatibility shim that defers to native ext-uuid when available.
• You need basic uuid_* function coverage, including recent v1/v4/v6/v7/vendor-type alignment, and do not need a full UUID abstraction.
• You already have it transitively and want to document/support the dependency intentionally rather than treat it as accidental.

Look elsewhere when:

• ext-uuid is guaranteed across all environments and UUID generation is performance-critical; native functions are faster.
• You need advanced UUID features: validation, parsing, namespace management, deterministic v3/v5 generation, custom types, or a rich API. Use ramsey/uuid or equivalent.
• You rely on Laravel’s Str::uuid() or Eloquent UUID keys with full library behavior; this polyfill is not a replacement for a full UUID library.
• You generate millions of UUIDs per second; benchmark first and prefer native ext-uuid where possible.
• Your environment lacks reliable entropy and you cannot add SYS_RANDOM or otherwise test random_bytes(); mitigate entropy risk before adopting.
• You need a product-level UUID abstraction, not just function-level compatibility.

How to Pitch It (Stakeholders)

Executives: This is a low-cost risk reducer, not a product feature. It removes environment-specific UUID failures and lets us run on serverless, legacy, or restricted hosting without PECL extensions. It is MIT-licensed, Symfony-maintained, and automatically defers to native PHP functions when available. Recommendation: accept it as transitive infrastructure, document the supported runtime matrix, and avoid building a custom UUID fallback.

Engineering: Treat this as a Composer-level compatibility shim. If our code or dependencies call uuid_* functions, it makes them work without ext-uuid and defers to native when present. There is no runtime configuration. It is not a substitute for ramsey/uuid when we need validation, v3/v5 namespaces, or Laravel’s full UUID API. Audit composer.lock for duplicate UUID approaches, benchmark only if UUID generation becomes hot-path, and ensure entropy is available in Docker/CI before relying on random_bytes().