Eloquent Keygen Laravel Package

Product Decisions This Supports

• A scoping decision on the "scale-out" roadmap item. Client-side ID generation is a prerequisite for multi-region writes, sharding, and handing IDs to background workers before a row is committed. As a PM, the useful framing is not "should we use Snowflake?" but "does buying this adapter turn a schema-plus-strategy project into a config change plus a per-model opt-in?" If yes, it changes the estimate on an item already on the roadmap. If no such item exists in the next ~12 months, the decision defers at zero cost — and deferring is the correct call.
• Build vs. buy on the glue, with a deliberately low ceiling on the buy. The actual algorithm lives in godruoyi/php-snowflake; this package is a trait, a service provider, and a config file that hooks Eloquent's creating event. So the real choice is whether roughly a trait's worth of glue is a pinned dependency or our own code. Both are cheap. The value of deciding once is that three teams don't ship three different ID conventions. Frame it internally as buying the convention, not the code.
• Whether the write path is genuinely constrained. Adoption should be justified by a number: p95 latency or contention on high-write endpoints where LAST_INSERT_ID() round-trips and auto-increment contention are the bottleneck. Without that number, this is architecture aesthetics, and it should lose the argument to anything customer-visible.
• Rollout shape and reversibility — the thing that makes it approvable. Two adoption paths (extend Jetcod\Eloquent\Model, or apply the Snowflake trait) plus a per-model snowflake(): bool opt-out mean we can pilot on one non-critical service and revert model by model. That is a scoped experiment, not a primary-key referendum, and it should be written into the plan explicitly so nobody treats it as a one-way door.
• A paired decision about public identifiers. Snowflake IDs embed a creation timestamp and, at default settings, node identity. Any roadmap surface with user-visible IDs — share links, URLs, API payloads, support screenshots — needs a separate opaque public identifier decided in the same conversation, not retrofitted after a security review flags it.
• A dependency-risk register entry, sized honestly. Two stars, zero dependents, a single maintainer, three releases (initial, a trait refactor, a compatibility/behavior update). Treat it as a replaceable utility: never load-bearing on a platform-strategy slide, and never let an architecture be viable only because it exists. Mitigation is mundane and cheap: pin the version, keep the trait-vs-base-class choice such that vendoring is a half-day of work.

When to Consider This Package

Consider it when:

• The ID strategy is still open — a greenfield service, or a table that hasn't shipped. Adoption there is config; retrofitting a populated table is a migration project, and the estimate difference is an order of magnitude.
• You need 64-bit, globally unique, roughly time-ordered IDs across instances, regions, or services without standing up a sequence service or coordinating through the database.
• You need IDs before commit — queued jobs, workers, bulk imports, event payloads referencing a row that doesn't exist yet. This is the use case that most often can't be solved any other way without a schema gymnastics exercise.
• The team is comfortable with small, single-purpose, boring dependencies and with pinning versions. The integration surface is one base model, one trait, and one config file.
• Someone owns worker_id / datacenter_id allocation. That ownership is the actual cost of entry, and it belongs to platform/ops, not the package. Misconfiguration produces silent collisions, not exceptions — which is a class of bug that surfaces months later as corrupted joins.

Look elsewhere, or write the trait in-house, when:

• Dependency maturity is a gating procurement criterion. No community backstop, no security response process, one maintainer. If the org requires audited vendors, this doesn't clear the bar — and the honest answer is that writing the trait ourselves is genuinely small.
• ULIDs or UUIDv7 would do. Comparable sortability, far larger ecosystem, no worker-ID coordination burden. Snowflake's edge is compactness and generation speed, not ecosystem. Don't adopt it because it's the one that showed up first.
• IDs are user-facing — URLs, API responses, share links.
• The database already guarantees uniqueness and there's no sharding or multi-region plan. You'd take on BIGINT UNSIGNED migration work and operational overhead for no benefit.
• You need short, human-readable, or strictly sequential IDs for invoice numbering, support tooling, or customer references.

Three cheap pre-adoption checks to sequence before committing a date:

1. The id column must be BIGINT UNSIGNED before rollout — a blocking schema change, plus a backfill or dual-write story for any legacy auto-increment rows.
2. The README's php artisan vendor:publish --provider="eloquent-key-generator-config" looks incorrect. Verify the real service provider name in source before it lands in a plan, a runbook, or a setup doc.
3. v1.2.0 moved generation from saving to creating and sets the floor at 64-bit PHP 8.1+ with Laravel 10–13 (php-snowflake ≥3.2). Confirm our runtime matrix, and note that this is a behavioral change in a young package — a signal to re-read release notes on every bump rather than trusting semver.

How to Pitch It (Stakeholders)

For executives: "There is a cheap, contained option to take the database out of the ID-generation path and remove a constraint on horizontal scaling. It's a small MIT-licensed Laravel add-on — roughly a two-line change per model — that generates globally unique IDs inside the application instead of asking the database for them.

The upside is concrete and measurable: fewer round-trips on high-volume write endpoints, and no collisions when we run many instances across regions or hand IDs to background workers before a row is committed. The honest caveat is maturity: early-stage package, essentially no adoption, one maintainer. I would not standardize on it company-wide, and I would not let anything depend on it continuing to exist. I recommend a two-week pilot on one non-critical service, with an explicit fallback — the code is small enough to own ourselves in about half a day — if the maintainer stops maintaining it.

The cost of trying is days. The cost of the status quo is a scaling constraint we would otherwise hit on the critical path. This is plumbing, not a competitive bet, and I'd rather buy two days of plumbing than spend a sprint reinventing it."

For engineering: "jetcod/eloquent-keygen is an Eloquent adapter over godruoyi/php-snowflake. Prefer the Snowflake trait over extending Jetcod\Eloquent\Model — it keeps a third-party base class out of our model hierarchy and makes the fallback (copying the trait into our own codebase) trivial. The per-model snowflake(): bool escape hatch lets us stage rollout service by service and revert without a deploy of the package itself.

What it buys: 64-bit, roughly time-ordered IDs generated client-side, no LAST_INSERT_ID() round-trip, unique across nodes, and IDs available before commit for queued work. Generation now fires on creating, so updates no longer re-trigger it. What it costs: we own worker_id / datacenter_id allocation as a deployment concern — a misconfiguration is a silent collision rather than an exception, so it needs a deliberate per-environment env strategy and a review checkpoint, not a copy-pasted default of 1. We also own version pinning and the BIGINT UNSIGNED schema change ahead of rollout, plus a decision on public-facing identifiers so we don't leak timestamps and node identity into URLs.

Ask: one service, one non-critical table, two weeks. Success criteria are measurable — write-path latency and zero collision incidents — and the exit is deleting a use statement."