Eloquent Uuid Laravel Package

Technical Evaluation

Architecture fit. The package is a narrow, single-responsibility Eloquent trait: it flips a model to a string primary key ($incrementing = false, $keyType = 'string') and generates a UUID on creating. That is an idiomatic Laravel extension point and imposes no framework-level coupling, no service provider gymnastics, and no runtime dependencies beyond illuminate/* and a UUID generator. Architecturally it slots in cleanly where it is needed — but the addressable need is shrinking. Laravel 9+ ships HasUuids in core, and Laravel 11+ generates time-ordered UUIDv7, which is materially better for database index locality than the v4 UUIDs a small 2018-era trait almost certainly produces. The realistic fit is therefore a legacy estate: Laravel 5.5–8 applications, or codebases with an existing UUID convention the team wants to standardize rather than rewrite.

Integration feasibility. Mechanically trivial: one composer require, one use statement on the model, done. The real feasibility question is the composer.json constraint block. A package with 7 stars and 0 dependents is very likely pinned to illuminate/support: 5.x|6.x and will refuse to install on Laravel 10/11/12 — meaning the "integration" degrades into "fork and patch." Budget a half-day spike to run composer require against the actual target stack before committing to any plan.

Technical risk. This is the dominant concern, and it is supply-chain, not code:

• Abandonment. 7 stars, 0 dependents, no dependents means no field validation — nobody is running this in production at scale that we can observe.
• No evidence of CI/tests. UUID generation correctness, collision handling, and whereKey behavior with string keys are untested territory unless we verify.
• Storage decision is implicit. The package almost certainly assumes char(36). That is 4.5× the index footprint of bigint and, if it's UUIDv4, random inserts into an InnoDB clustered index — page splits and write amplification at volume.
• Ecosystem friction. Sanctum's personal_access_tokens, Telescope, Horizon, and many third-party packages assume integer or bigint keys. String PKs ripple into Auth::id() typing, route model binding, and any package doing (int) casts.
• Opportunity cost. Laravel's native HasUuids does the same job with framework maintenance guarantees.

Key questions for the maintainer/repo audit.

1. What Laravel and PHP versions are actually supported by the current composer.json, and when was the last commit?
2. Which UUID version is generated, and via ramsey/uuid, Str::uuid(), or hand-rolled md5/uniqid (the latter would be disqualifying)?
3. Is there any handling for ordering (UUIDv7/ULID) or binary(16) storage?
4. Does it override getKeyType/getIncrementing correctly, and does it guard against mass-assignment of id?
5. Are there tests, and is there a published security policy?
6. What happens on find() with a non-UUID string — clean miss or SQL error?

Integration Approach

Stack fit. Do not adopt this as a greenfield choice. The decision matrix:

Migration path. Two distinct paths, and they should not be conflated:

• New models only: additive, low risk. Enable the trait on new tables, leave legacy tables on auto-increment. Mixed-key estate is acceptable if documented.
• Retrofitting existing tables: high risk. Changing a PK from bigint to char(36) requires dropping every foreign key, altering child columns, backfilling, and re-adding constraints — a multi-hour lock on large tables. The far safer pattern is the dual-key approach: keep the integer PK as the clustered index and add a unique indexed uuid column for external exposure. This gets the API-facing benefit without touching joins or index density.

Compatibility. Verify against the target matrix before sequencing any work: PHP 8.1/8.2/8.3, Laravel 10/11/12. Specifically test Route::model() binding, Auth::user()->id typing through Sanctum/Passport, JSON resource serialization, and any package with a hard FK to users.id. If the package's constraints block installation, the correct move is to vendor the trait (it is likely <80 lines) rather than fork the repo — you inherit the behavior without the maintenance surface.

Sequencing.

1. Spike: install against the real stack; if composer require fails, stop and vendor.
2. Read the source in full (~1 hour) and confirm UUID version and generation path.
3. Prototype on a single disposable model with a test asserting uniqueness and find() behavior.
4. Decide: native / vendor-copied trait / reject.
5. If proceeding, apply only to a new bounded context first.
6. Measure index size and insert throughput before any retrofit of existing tables.
7. Only then plan the legacy migration, with the dual-key pattern as the default.

Operational Impact

Maintenance. Treat this as an owned asset, not a dependency. With 7 stars and 0 dependents, expect zero upstream responsiveness — no CVE patches, no Laravel 13 compatibility, no PHP 9 support. Pinning the version and enabling Dependabot only tells you when it breaks; it doesn't fix it. Copying the trait into application code removes the Composer constraint risk entirely and is the lowest-TCO option for a package this small. If it must stay a dependency, fork it under an org namespace.

Support. No maintainer SLA, no Discord/Slack, no Stack Overflow footprint. Your engineers are the support tier. That is acceptable for ~80 lines of trait code, unacceptable if the team assumes "there's a package for that" and stops reading it.

Scaling. The operational bill arrives at the database. char(36) PKs inflate every secondary index and every foreign key in child tables; random UUIDv4 inserts fragment the InnoDB clustered index and degrade write throughput as tables grow past memory. Read-heavy or low-volume tables won't notice. High-insert tables (events, audit logs, orders) will, and by then the migration is expensive. If UUIDs are needed for external identity, the dual-key pattern (int clustered PK + unique uuid column) is the scaling-safe answer. UUIDv7/ULID is the next-best if a UUID must be the PK.

Failure modes to instrument.

• Silent misconfiguration: model saved without the trait booting → null PK or duplicate-key error in production, not in dev.
• Type mismatch in joins: WHERE user_id = '1' against a char(36) column returns nothing, silently, rather than erroring.
• Serialization drift: API clients and mobile apps that parse id as an integer break on deploy.
• Mass assignment: an id accepted from a request body could overwrite the generated key if $fillable isn't locked down.
• Composer freeze: a framework upgrade blocked by dead package constraints, discovered mid-sprint.

Ramp-up. Low for engineers — a trait plus two model properties is an hour of reading. The cost is in convention and review discipline, not knowledge: the team needs a written rule for when UUIDs are used, which storage strategy applies, and a PR checklist item for key type changes. Budget a short internal design note and a single pilot model rather than formal training. Realistic time-to-first-production-model: one sprint including the spike and the compatibility matrix.