Laravel Model Tools Laravel Package

Product Decisions This Supports

• Public identifier strategy (build vs. buy vs. adopt). This package is a thin, opinionated implementation of a decision most teams eventually face: exposing opaque references in URLs/APIs while keeping auto-increment IDs private. Adopting it is effectively a decision to standardize on UUID references rather than letting each squad choose between UUIDs, ULIDs, Hashids, or nothing.
• Security/enumeration hardening as a roadmap item. Preventing ID enumeration (/pages/1, /pages/2) is a low-effort, high-signal security win that reduces scraping and IDOR-adjacent exposure. The reference() / referenceOrFail() helpers plus reference-based route binding make this a convention rather than a per-controller discipline.
• API and URL contract decisions. Configurable route model binding and configurable reference column names force an explicit answer to "what is the stable public key of this resource?" — which directly affects API versioning, caching keys, deep links, and SEO. Decide this before shipping public endpoints, not after.
• Scope and sequencing of rollout. Because the migration generator is per-table (model-tools:reference-migration pages), adoption can be incremental and prioritized: start with resources exposed to unauthenticated or cross-tenant users (share links, public profiles, invoices, downloads), defer internal admin-only tables.
• Reducing per-team reinvention. The BaseModel option (soft deletes, datetime casts, HasReference) is a candidate internal standard, replacing N slightly-different base models across services.
• Vendor/roadmap risk budgeting. Pre-1.0, single-maintainer package: the PM decision is not "yes/no" but "adopt behind a seam" — use the trait today, keep our own thin interface so swapping to a first-party trait later is a one-file change.

When to Consider This Package

Consider it when:

• You are greenfield or early-stage on Laravel 11–13 / PHP 8.3+, so there is no backfill problem.
• You expose Eloquent models in public URLs or APIs and currently leak sequential IDs.
• You want a convention enforced across multiple teams/squads with minimal code and zero infrastructure.
• Your team is small and the alternative — writing a trait, a migration stub, and a route-binding resolver — is a recurring 1–2 day distraction per service.
• The scope is single-database, single-region, no offline or client-generated IDs needed.

Look elsewhere (or build in-house) when:

• You have an existing identifier standard (ULID, Snowflake, Hashids, prefixed IDs like Stripe's cus_...). Adding a second scheme creates long-term confusion; consolidation cost exceeds the package's value.
• You must backfill existing rows. The release notes describe a migration generator that adds a column — backfilling and the unique-index/rollout order on large tables are unaddressed. Verify before committing a launch date.
• Reference stability is a hard requirement. The notes say generation happens "when models are created or updated." If an update regenerates the reference, bookmarks, shared links, external webhooks, and partner integrations break silently. This is the single most important diligence question for a PM — confirm behavior and, if needed, lock references to creation only.
• Write-heavy or very high-throughput tables where an extra uniquely-indexed UUID column plus per-save generation is measurable overhead.
• Regulated/audited environments requiring a supported, versioned dependency with security SLAs — a 0.1.0 single-maintainer package with no LTS commitment is a compliance conversation, not just a technical one.
• You need multi-column, composite, or tenant-scoped references, custom ID formats, or exposure auditing out of the box.

How to Pitch It (Stakeholders)

• To executives (30 seconds): "A small open-source add-on that stops our public links and APIs from exposing sequential database IDs, which today let anyone enumerate and scrape our records. It's a day of work per service, no new infrastructure, and it reduces a class of security and privacy findings. Risk is low because it's a thin layer we can replace without touching product code."
• To engineering: "One trait plus a generated migration gives us UUID references, lookup helpers, and route model binding — replacing hand-rolled equivalents. It standardizes the pattern across squads and gives us an optional BaseModel. We'll pin to ^0.1, wrap it behind a small internal interface, and roll it out table-by-table starting with publicly exposed resources."
• Framing the trade-off honestly: the value is convention and consistency, not novel capability — any team could write this in a day. Adopt for speed and uniformity; do not adopt expecting a maintained platform. Treat 0.1.0 as "vendored-ish": pin the version, keep the integration surface to one trait, and revisit at 1.0 or if maintenance stalls.
• Success signals to track post-adoption: share of public endpoints using references, zero new sequential-ID exposures in security review, and no reference-stability incidents (broken links/webhooks) in the first quarter.