Product Decisions This Supports
- Primary key strategy (auto-increment vs. UUID): Informs the decision to expose non-sequential identifiers in public APIs, URLs, and exports — reducing enumeration/scraping risk and making record counts non-guessable without adding a separate "public ID" column and lookup layer.
- Distributed and offline-first write paths: UUIDs let clients, mobile apps, import jobs, or edge services mint IDs before hitting the server, which is a prerequisite for offline draft creation, idempotent retries, and multi-region or sharded writes without a central sequence.
- Multi-tenant and data-merging architecture: Non-colliding IDs make it safe to merge tenants, restore from separate environments, or consolidate acquired datasets without renumbering — a real constraint on M&A and data-migration roadmaps.
- Build vs. buy vs. use-the-framework: The core decision this package actually surfaces. The capability is ~100–300 lines of trait code and is now native in Laravel (
HasUuids, HasUniqueStringIds, uniqueIds()), so the honest conclusion is build/framework-native, not buy. The package is a candidate only as a copy-paste reference implementation.
- Migration cost and reversibility: Switching an existing table from
bigint to char(36) touches foreign keys, indexes, and every join — this is a one-way-ish door that deserves an explicit ADR (architecture decision record) rather than an incidental dependency choice.
- Dependency-risk budgeting: With 3 stars, 0 dependents, and an archived repo since the 2022-01-12 release, adopting this is effectively a commitment to own and maintain the code. That's a staffing and risk decision, not just a technical one.
When to Consider This Package
Consider it (narrowly) when all of the following hold:
- You are on Laravel 8 or earlier, where UUID keys are not first-class and you want a minimal trait rather than hand-rolling one.
- Your scope is a small internal service or prototype where a stale dependency carries low blast radius.
- You intend to vendor or fork the trait into your own codebase rather than depend on the package via Composer — which nullifies most of the reason to "adopt" it at all.
- You need a readable reference implementation of the trait pattern to adapt, and you're comfortable reviewing MIT-licensed code line by line.
Look elsewhere — or rather, look at the framework — when:
- You are on Laravel 9+, where native UUID/ULID traits exist and are maintained by the core team. Adding a third-party package here is strictly negative value.
- You need time-ordered identifiers (UUIDv7, ULID) for index locality and write throughput. Random v4 UUIDs on a clustered index cause page-split and insert-hotspot problems at scale; this package does not solve that, and it predates the v7 conversation entirely.
- You require a maintained dependency — security review, CVE response, framework-version compatibility, or an SBOM with a support commitment. An archived repo fails all of these.
- You need migration tooling for existing integer-keyed tables. The package provides a trait; it does not provide backfill, dual-write, or foreign-key rewrite support, and no dependents mean no community recipes.
- Your bottleneck is composite or tenant-scoped keys, custom ID formats, or database-level defaults — you'll want explicit control, not an opinionated trait.
How to Pitch It (Stakeholders)
Executive summary: We evaluated bmatovu/laravel-eloquent-uuid as a way to adopt UUID primary keys. It is MIT-licensed and free, but it is archived, has essentially no adoption (3 stars, zero dependents), and has not shipped since January 2022. Meanwhile, Laravel itself has provided UUID and ULID primary keys natively since version 9. Recommendation: do not add this as a dependency. If we need UUID keys, we use the framework's built-in traits; if we're on an older Laravel, we copy the ~200-line trait into our own codebase so we own it. Either path costs roughly a day of engineering and avoids taking on an unmaintained third-party dependency in the critical path of our data model.
For engineering: This is a trait package, not a platform. The value is the pattern, not the artifact. Treat it as a reference implementation, confirm your Laravel version's native support first, and if you do lift the code, decide deliberately between UUIDv4 (random, privacy-friendly, index-unfriendly) and UUIDv7/ULID (ordered, index-friendly) — the package only addresses the former. Budget the real work where it belongs: the schema migration, foreign-key rewrites, and index strategy, not the trait.