Laravel Auto Sequence Laravel Package

Product Decisions This Supports

• Feature: customer-facing document numbering. Whether invoices read INV-2026-00001, include a branch prefix, or reset monthly is a product/brand decision, not a schema decision. The format_template ({type_code}, {date:d-M-Y}, {seq:5}) and period settings let us change numbering rules without a migration or model rewrite.
• Compliance and audit posture. transaction_mode (gapless vs gap_tolerant), max_value with SequenceExhaustedException, allow_manual => false, and continuous recycling are policy switches. If finance or a tax authority requires unbroken invoice numbering, that's a one-line config decision — and a scoping conversation we can have with legal early rather than in the release crunch.
• Roadmap: multi-tenant and multi-entity expansion. scope (e.g. tenant_id) isolates counters per tenant/branch, and type_relation derives prefix from a relationship with a default_type fallback. This means "sell to multi-branch customers" or "spin up a second entity" doesn't require a new numbering service — it's configuration.
• Roadmap: new geographies / fiscal calendars. A period closure supports fiscal-year resets (April 1st, etc.). Entering a market with a non-calendar fiscal year becomes a config task instead of a bespoke feature.
• Build vs. buy. The alternative is a custom sequences table with row locking, retry semantics, and period partitioning — realistically a few days to build and an ongoing tail of duplicate-number incidents at month boundaries and under concurrent writes. Buying gets a composite-key counter table, pluggable locking drivers, and pre-allocation for throughput.
• Internal vs. external identifiers. Multiple sequences per model cover the common split: an external branded number plus an internal REF-{seq:8} reference that never resets. Avoids one column doing two jobs.
• Ops and incident response. sequence:list, sequence:reset --value=, and sequence:verify --repair turn "our invoice numbers jumped / duplicated" from a data-migration fire drill into a runbook command. That's a support-cost decision worth naming.
• Use case breadth. Same package covers invoices, orders, credit notes, POs, tickets, customer codes — reduces the number of bespoke counter implementations across squads.

When to Consider This Package

Adopt when most of these hold:

• The stack is Laravel/Eloquent and the numbers are generated in the app layer at model-create time.
• Users need human-readable, sequential, patterned identifiers — not machine IDs.
• You need per-period or per-tenant scoping, or a branch/entity-derived prefix.
• Numbering rules are likely to change (prefixes, padding, reset cadence) and you want that to be config, not code.
• You want to avoid owning concurrency correctness for counter allocation.
• You can tolerate a small, single-maintainer MIT package — realistically: pin the version, fork or vendor it, and keep a maintainer-of-last-resort on the team.

Look elsewhere / avoid when:

• You only need uniqueness. UUIDv7/ULID already solves it with zero operational surface.
• Strict gapless and high write throughput. These are mutually exclusive here — pre_allocation is explicitly incompatible with gapless mode. Pick one and say so up front.
• Very high per-sequence concurrency. A single counter row is a contention point; pre-allocation softens it but introduces gaps and a hard dependency on a non-evicting cache store (Redis noeviction). If gaps are unacceptable, throughput is capped.
• Multiple services or non-PHP writers generate numbers. This is an Eloquent trait; a polyglot or event-driven write path argues for a dedicated numbering service or DB-native sequences.
• You need a support contract, SLA, or security review with a vendor. 16 stars and a single maintainer won't clear that bar; if procurement requires it, budget for in-house ownership.
• Your tests or app ship a replacement sequences table. Workable (load_migrations => false is honored in tests), but expect friction and document it.
• You need numbers before persistence. Generation is tied to model save; pre-computing reservation IDs for draft flows is out of scope.

How to Pitch It (Stakeholders)

To executives (30 seconds). We need sequential, formatted, non-duplicating document numbers — invoices, orders, credit notes. Today that's either hand-rolled code with a known duplicate risk at month boundaries and under concurrent load, or manual process. This MIT-licensed Laravel package gives us compliant numbering, per-tenant and per-branch isolation, and fiscal-year resets as configuration. It removes a recurring class of finance-visible defects and unblocks multi-entity sales conversations — for roughly the cost of an integration, not a build. The one caveat: it's a small, low-adoption open-source package, so we treat it as "adopt with a fork plan," not "adopt and forget."

To engineering. One contract (Sequenceable) and one trait (HasSequenceNumber); numbering rules live in getSequenceConfig(). It handles counter allocation, period partitioning, and locking (configurable driver, with the database driver using a bounded lock timeout rather than blocking the worker). There's real operational tooling — sequence:install, sequence:list, sequence:reset, and sequence:verify --repair for drift between the counter and the actual max in the table. Watch the known edges: manual override silently skips generation if the column isn't null, file/array cache drivers can't lock, soft deletes don't recycle until forceDelete(), and pre-allocation needs a dedicated non-evicting cache store or you get silent gaps. We pin the version, wrap the trait behind our own base model so a swap is a one-file change, and add a concurrent-creation test to CI on day one.

Decision framing. Treat this as a low-cost, reversible bet: adopt behind a thin internal abstraction, keep our own integration test for duplicate prevention, and revisit if throughput or compliance requirements outgrow it.