Eloquent Uuid Laravel Package

Product Decisions This Supports

• Identifier strategy for new tables / APIs: whether primary keys should be auto-increment integers or UUIDs. This package is a data point in that decision — it makes UUID primary keys on Eloquent models a one-line trait, so the "cost to try" is near zero.
• Exposing IDs publicly: UUIDs prevent enumeration (a competitor or scraper walking /orders/1001, /orders/1002) and let you hand out identifiers to partners, webhooks, and mobile clients without leaking volume or growth rate.
• Distributed / offline-first roadmap items: mobile sync, multi-region writes, or future service splits where client- or service-generated IDs must be globally unique without a central sequence.
• Data merges and imports: consolidating datasets from acquisitions, staging environments, or third-party systems where integer keys collide.
• Build vs. buy vs. use-native: the real decision this package informs is whether to write custom UUID plumbing on models. Given Laravel ships HasUuids / HasUlids natively (9.x+), the honest output of this evaluation is usually "use the framework, not this package" — but it's cheap to benchmark.
• Migration scope: whether to retrofit UUIDs onto existing tables (a schema + backfill + foreign-key project) or apply them only to new surfaces. Adoption of a trait is the low-commitment end of that spectrum.
• Not a roadmap bet: with 3 stars, 0 dependents, and a single-purpose trait, this is infrastructure glue, not a strategic dependency. Treat it as a spike input, not a platform choice.

When to Consider This Package

Consider it when:

• You are on an older Laravel version (pre-9) that lacks native HasUuids, and you want a drop-in trait rather than hand-rolling boot() logic for $incrementing = false and $keyType = 'string'.
• You want a ~100-line, MIT-licensed, auditable codebase you can read in ten minutes and vendor/fork into app/Support if the maintainer disappears.
• You are prototyping and want UUID keys on a handful of models today to validate a product idea, with no intention of this being the long-term answer.
• Your team has a policy of consuming small single-purpose packages over internal utility code — and accepts the accompanying supply-chain review.

Look elsewhere when:

• You are on Laravel 9+ — use the native HasUuids trait (or HasUlids if index locality matters). No third-party dependency, no version-drift risk, same outcome.
• You need ordered/time-sortable IDs (UUIDv7, ULID, Str::orderedUuid()). Random v4 UUIDs fragment InnoDB primary-key indexes and hurt write throughput on high-volume tables; that's a real product-level cost at scale.
• You need UUIDs as secondary columns (public-facing public_id) while retaining integer primary keys — usually the safer pattern, and outside this package's scope.
• You need binary(16) storage, custom UUID versions, per-tenant UUID namespaces, or validation rules — use ramsey/uuid directly (already a Laravel dependency).
• You require maintenance guarantees, security responsiveness, or a support path. 0 dependents and 3 stars means no ecosystem has stress-tested it; there is no CVE history to review and no community to catch a bad release.
• Your UUID keys will be foreign keys across many tables — verify charset/collation alignment and index sizes before committing; this is a schema decision a trait cannot make for you.

How to Pitch It (Stakeholders)

To executives: There's a small open-source helper that lets our Laravel models use UUIDs as IDs instead of sequential numbers. The business reason to care is exposure and scale: UUIDs stop outsiders from guessing how many customers or orders we have, and they let us merge data across systems without ID collisions. Cost is effectively zero and the license is permissive. The caveat is maturity — this specific package has almost no adoption (3 stars, no dependent projects), and the framework now ships this capability natively. Recommendation: do not adopt it as a dependency. Fund a short spike to confirm native UUID support meets our needs, and standardize on the framework feature. Net cost: a few engineering hours, no vendor risk, no new dependency to maintain.

To engineering: It's a trait that flips a model to string keys and generates a v4 UUID on create. If we're on Laravel 9+, HasUuids does the same thing with no supply-chain surface — prefer that. Be explicit about the tradeoffs before we commit at the schema level: v4 UUIDs are random, so clustered-index insert performance degrades on write-heavy tables; consider HasUlids or ordered UUIDs there. Plan for 36-char char(36) or binary(16) columns, matching types on every foreign key, and route-model-binding behavior. If we do pull this package in for a legacy branch, pin it, vendor it if the logic is trivial, and add a test asserting key generation on model creation so a silent break is caught.