Laravel Eloquent Uuid Slug Laravel Package

Product Decisions This Supports

• Deciding the public identifier strategy for every model exposed in a URL or API. The core decision this package touches is "do we leak sequential auto-increment IDs, or do we expose an opaque token?" That is a product-visible decision (shareable links can't be guessed or enumerated; support can't be socially engineered by incrementing a number), not just an implementation detail.
• Feature scoping for public share links, invite links, and unauthenticated deep links. Anything a user can copy-paste into Slack or email inherits the identifier scheme. If the roadmap includes sharing, exports, or public read-only views, the identifier choice becomes a prerequisite for those features rather than a later refactor.
• Build vs. buy vs. framework-native. The honest PM framing is a three-way comparison, not two: (a) adopt this package, (b) write ~20 lines of getRouteKeyName() + UUID column + model trait in-house, or (c) use Laravel's built-in HasUuids / HasUniqueStringIds traits, which cover the same ground natively on modern Laravel. This package is a thin convenience layer over a problem the framework mostly solved itself.
• Migration and backwards-compatibility sequencing. Adding a UUID alongside existing integer IDs is a schema and data-backfill project with a deprecation window for old URLs. The decision this package informs is whether to do that work now (pre-public-launch, cheap) or later (post-launch, requires redirects and dual-lookup support).
• Multi-tenant and IDOR-adjacent risk posture. Opaque identifiers are a defense-in-depth measure against insecure direct object reference bugs. Choosing UUIDs is a risk-reduction line item a PM can carry into a security review, with the explicit caveat that it does not replace authorization checks — it only makes the exploit require more effort.
• Use cases where this is clearly the right shape: public-facing SaaS URLs, API resources consumed by third parties, anything with a "copy link" button, and audit/event records where exposing row counts via ID gaps would be commercially sensitive.
• Use cases where it is actively the wrong shape: internal admin panels, join tables, high-volume time-series rows, and anything where a sequential primary key's index locality matters for write throughput. UUIDv4 primary keys cost storage and B-tree performance; the PM should expect engineering pushback here and be ready to scope it to a separate public column rather than the primary key.

When to Consider This Package

Consider it when:

• You are on an older Laravel version (pre-9) where HasUuids is not available, and you need route-key UUIDs with minimal ceremony.
• You want an explicit, named "slug" concept rather than UUID primary keys — i.e., the identifier exists purely for URL/route lookup while integer keys remain the internal join key. This is the safer architecture, and a package that assumes it is a better fit than retrofitting the framework trait.
• You have a small, non-critical surface area — a handful of models — where the cost of a hand-rolled trait genuinely exceeds the cost of a dependency.
• You need it this sprint and the alternative is a bespoke implementation nobody has time to test.

Look elsewhere (or build in-house) when:

• You are on Laravel 9+. HasUuids and HasUniqueStringIds ship in the framework. Adopting a 23-star third-party package to duplicate a first-party trait is a net negative on maintenance, security review surface, and onboarding.
• Adoption signal is the deciding factor for you. 23 stars and zero dependents is a weak signal. Zero dependents in particular means the edge cases (soft deletes, route model binding with scoped bindings, whereUuid resolution, pivot lookups, model events firing on creation) have likely been exercised by approximately one person: the author.
• Bus factor matters. Single-maintainer, MIT, small surface area — the practical mitigations are "vendor the trait" or "fork it," both of which are cheap here. But a PM should not put this on a critical path without a documented exit plan.
• You need SEO-friendly slugs, not opaque identifiers. A UUID is not a slug in the marketing sense. If the requirement is /products/blue-widget-2xl, this package does not address it and you need a transliteration-based slug library instead.
• You are concerned about index performance at scale. Confirm with engineering whether the UUID is a secondary indexed column (acceptable) or the primary key (a real trade-off at millions of rows). The package's design choice here should be verified from the source, not assumed from the description.
• You need auditable, security-reviewed dependencies. No evidence of a security review process; the mitigation is that the code is ~100 lines and readable in one sitting.

Decision rule: treat this as a reading reference and a shortcut for legacy stacks, not as a long-term dependency for a new build.

How to Pitch It (Stakeholders)

For executives (one paragraph):

We expose database record numbers in our URLs and API responses today, which means anyone can increment a number and walk through our customers' data. The fix is to give each record a random, unguessable public identifier instead. The good news is this is a small, well-understood change and our framework now supports it natively — we do not need to buy anything or adopt a risky new dependency. The work is in the data migration and the redirect window for existing links, not in the code. I recommend we scope it as a two-week hardening item before the public launch of [feature], because doing it after launch means maintaining dual URL formats indefinitely.

For engineering (the actual ask):

• Verify the package's model: does it override getRouteKeyName() and add a unique indexed UUID column, or does it replace the primary key? We want the former. If it's the latter, stop — that's a write-throughput and storage cost we don't need to accept.
• On our Laravel version, check whether HasUuids / HasUniqueStringIds gets us there with less surface area. If yes, the recommendation is build in-house, ~20 lines, and use this repo only as a reference for the route-binding edge cases.
• If we do adopt it: pin the version, vendor it or fork it under our org, and add the models it touches to the security review list. Zero dependents means we are the de facto QA.
• Non-negotiables regardless of path: UUID as a secondary unique column, not the primary key; backfill migration with a null-tolerant rollout; whereUuid()-style lookups on hot paths; explicit decision on whether legacy integer URLs 301-redirect or 404 during the deprecation window.
• Explicitly out of scope: this is not a substitute for authorization. Policy checks stay. We are reducing enumeration ease, not fixing IDOR.