Product Decisions This Supports
- Identifier strategy as a feature decision. Choosing UUID keys over auto-increment integers is a product-visible tradeoff: non-enumerable public IDs (account numbers, order references, share links), IDs generatable on the client before persistence, and safer data merging across environments. This package is a narrow enabler of that decision, not the decision itself.
- Offline-first and distributed-write roadmaps. If the roadmap includes mobile/edge clients that create records before connectivity, or multi-region/sharded writes where a central sequence is a bottleneck, UUID primary keys become a prerequisite. This trait is a one-line way to unblock that work in Eloquent models.
- Build vs. buy (vs. use the framework). The realistic comparison set is: (a) Laravel's built-in
HasUuids/HasUniqueStringIds traits, (b) a community package with maintenance guarantees, (c) ~20 lines of in-house trait code. This package sits closest to (c) with a Composer version constraint, so the decision is really "vendor a tiny trait" vs. "add a dependency."
- Data portability and integration features. UUID keys simplify importing/merging datasets from external systems, seeding demo data deterministically, and syncing between staging and production without key collisions — useful inputs to any data-migration or integration roadmap.
- Storage and performance budgeting. Every UUID PK decision carries index-size and write-locality costs (random UUIDv4 fragments B-tree indexes; ordered UUIDv7/ULID mitigates this). This package does not solve ordering, so teams must pair it with an explicit decision on UUID version — a roadmap item in its own right.
- Not supported: schema/migration generation, foreign-key type changes, route model binding conventions, UUIDv7/ULID, or key-format validation. Those remain your team's work.
When to Consider This Package
Consider it only when all of the following hold:
- You are on a Laravel version that predates the framework's native UUID key traits (or you are pinned to an older major and cannot upgrade yet), and you need UUID keys quickly.
- You want the smallest possible surface area — one trait, one
composer require — and your team can read and own the whole implementation in an afternoon.
- Your identifier needs are uncomplicated: primary keys only, no ordered/sequential IDs, no custom UUID versions, no cross-database portability requirements.
- You accept the maintenance risk: zero dependents and no observable adoption signal means no community bug-finding, no security review, and no guarantee of a release for the next Laravel major. Budget for forking or vendoring it.
Look elsewhere (or skip entirely) when:
- You are on Laravel 9+ — use the framework's
HasUuids trait; adding a dependency here is pure overhead.
- You need index-friendly ordered identifiers — use UUIDv7 or ULID support instead; randomized keys will hurt write throughput on large tables.
- You need migration stubs, foreign-key Uuid columns, factory helpers, or route-binding ergonomics — reach for a fuller package or write the ~20 lines yourself.
- You require vendor support, security review, or an SLA — an unmaintained single-author package cannot satisfy that.
- You are choosing an identifier strategy for a system where you'd be locked in — a dependency with no adoption history is a liability in a five-year architecture.
How to Pitch It (Stakeholders)
For executives: This is a small, single-purpose utility that lets our models use UUID primary keys with one line of code. It is not a strategic investment — it is commodity plumbing that the framework itself now provides. Treat it as a reference implementation or a stopgap, not a platform dependency. The cost is effectively zero; the risk is that it is unmaintained (no dependents, no adoption signal), so we should be prepared to own it.
For engineering: One trait, UUID keys on Eloquent models, minimal surface. In exchange, you inherit an unversioned, low-traffic dependency and must handle migrations, foreign keys, and route binding yourself. On Laravel 9+, use the native HasUuids instead and close this out as "no action." If you do adopt it, vendor or fork it and pin the version.
Recommendation: Default to framework-native UUID traits. Adopt this package only as a backport for older Laravel versions, or as the seed for an in-house trait — and record the decision to revisit when the platform is upgraded.