Simple Laravel Eloquent Uuid Laravel Package

Technical Evaluation

Architecture fit. The package is a single Eloquent trait that hooks the model's boot lifecycle to assign a UUID on create, typically paired with $incrementing = false and $keyType = 'string'. That is a narrow, well-understood seam in Laravel — it composes with mass assignment, route model binding, and relationships without touching the query builder. Fit is high in principle, but the total functional surface is roughly 30–60 lines of code. This is a "commodity capability" dependency, not an architectural component.

Integration feasibility. Adoption is a composer require, a use statement on each model, and a migration changing the primary key column to a 36-char string (or 16-byte binary). Effort is measured in hours, not sprints. There is no service, no config surface, no external runtime dependency beyond a UUID generator.

Technical risk. Material, and mostly not about correctness:

• Staleness. Last release 2020-07-14. Laravel's major cadence has moved several versions since; there is no signal of a compatibility matrix for Laravel 9/10/11 or PHP 8.2/8.3.
• Effectively superseded. Laravel ships first-party HasUuids / HasUlids (and HasUniqueStringIds), plus Str::uuid(). A third-party trait from 2020 competes with a framework feature that is maintained, tested, and documented by the vendor. Build-vs-buy strongly favors build or buy-the-framework here.
• Low adoption signal. 13 stars implies near-zero community vetting, no meaningful issue history, and a single-maintainer bus factor of one. There is no security disclosure process.
• Dependency drag. Likely pins a ramsey/uuid range that can conflict with other packages in a mature composer.lock.
• Blast radius if it breaks is high, because the failure surface is the primary key of every affected table.

Key questions for the maintainer / spike.

1. Which Laravel and PHP versions are actually exercised in CI, if any?
2. Does it generate UUIDv4, or an ordered variant? (Drives the entire scaling analysis.)
3. Does it set $incrementing/$keyType itself, or expect the developer to?
4. How does it behave on insertOrIgnore, upsert, chunked inserts, and raw/DB-level inserts that bypass model events?
5. Does it support binary(16) storage, or only CHAR(36)?
6. Is the trait compatible with SoftDeletes, HasUlids, and other boot<Trait> hooks on the same model?

TPM verdict. Do not add this dependency to a new or actively maintained codebase. Replace with the framework's built-in UUID trait (or a ~40-line in-house trait) at effectively zero incremental cost. The package is defensible only for a frozen legacy Laravel 6/7 application where the cost of change exceeds the cost of carrying an unmaintained dependency — and even then, vendor or fork it rather than relying on Packagist.

Integration Approach

Stack fit. Best-case fit is a Laravel 6/7 application on PHP 7.x, MySQL/Postgres, with a small number of models needing opaque public identifiers. Poor fit for Laravel 9+, where native support removes the reason to exist.

Build vs. buy decision, made explicitly. Three options, in preference order:

1. Native — HasUuids / HasUlids on Laravel 9+ (ULIDs/UUIDv7 preferred for index locality). Zero dependency, vendor-tested.
2. In-house trait — 40 lines wrapping Str::uuid(), owned by the team, testable against our own model matrix.
3. This package — only when 1 and 2 are blocked by legacy constraints.

Compatibility work before commitment. Pin a throwaway branch and run: composer require against our locked dependency graph (watch for ramsey/uuid conflicts), a PHP/Laravel matrix in CI, and a model-level test covering create, upsert, insertOrIgnore, route binding, JSON serialization, and relationship hydration. This is a half-day spike and it will answer most of the open questions above.

Migration path — the real cost center. The trait is trivial; the schema and data migration is not.

• Column type decision. CHAR(36) is simple and readable but bloats every index and every foreign key by 4.5×. BINARY(16) is compact but requires conversion at the model boundary and complicates ad-hoc SQL and BI tooling. Choose deliberately; changing later is a second migration.
• Dual-key phase. Add a uuid column alongside the existing auto-increment PK, backfill, update application reads and route binding, then promote. This avoids a big-bang PK swap and keeps foreign keys intact. Dropping the integer PK is a third step, not part of the first deploy.
• Ordering assumptions audit. Grep for orderBy('id'), cursor pagination, and any analytics or export that assumes monotonic IDs. This is the most common silent regression.

Sequencing.

1. Spike + compatibility matrix (0.5 day).
2. Decide native vs. in-house vs. package (1 decision meeting).
3. Schema migration with additive uuid column; backfill job (1–2 days, mostly data).
4. Application read-path cutover and route binding tests (small).
5. PK promotion / integer column retirement — separate change, separate rollback plan.

Operational Impact

Maintenance. Treat the package as unmaintained. Concretely: add it to the dependency watchlist, assign an owner, and be prepared to fork or inline the trait on the next Laravel major. The ongoing cost is not fixing bugs — it is the recurring review burden of justifying an abandoned dependency in every security and upgrade audit.

Support. Community-only, single maintainer, no SLA, no disclosure channel. Escalation path is "read the source" — acceptable for 50 lines of code, unacceptable if the team does not have PHP/Laravel depth to own the fork.

Scaling. This is where the choice of UUID flavor becomes an infrastructure decision:

• Random UUIDv4 primary keys on InnoDB defeat clustered-index locality — every insert lands on a random page, causing page splits, buffer-pool churn, and write amplification that grows with table size. At 10M+ rows this is a measurable, sometimes severe, throughput tax.
• Index and storage footprint: 36 bytes vs. 8 for BIGINT, multiplied across every secondary index and foreign key. Expect 2–4× index growth on UUID-heavy schemas.
• If scaling matters, push for ULIDs or UUIDv7; a v4-only 2020 package may not offer that, which is itself an argument for the native trait.
• Read path is unaffected; this is purely a write/locality and storage-cost concern.

Failure modes to design against.

• Bypassed model events — bulk upsert, insertOrIgnore, chunked inserts, and any raw SQL or DBA-side write will not trigger the trait, producing NULL or duplicate keys. Enforce a DB-level NOT NULL + UNIQUE constraint as a backstop.
• Trait collision — two traits both defining boot<Trait> hooks or a generateUuid method; Laravel silently resolves some of these badly. Test on the actual model set.
• Key-type regressions — route model binding and JSON serialization silently change shape for API clients; version the API or coordinate with consumers.
• Rollback asymmetry — data generated under UUIDs cannot be cleanly re-keyed to integers. Rollback plans must be forward-only past step 3 of the sequencing above.

Ramp-up. Developer learning curve is near zero — one line per model, well-understood semantics. The hidden ramp-up is organizational: DBAs and analysts need to accept opaque, non-sortable identifiers in queries, dashboards, and support tooling. Budget for that conversation; it is usually the real source of friction, not the code.