Sequence Number Generator Laravel Package

Product Decisions This Supports

• Numbering becomes a named domain concern instead of scattered glue code. Invoice numbers, order references, ticket IDs, policy numbers, and document control IDs are all "sequential, human-readable, often scoped" identifiers. This package gives that requirement a first-class abstraction (SequenceNumberGenerator) rather than a counter table copy-pasted into each feature. That means one place to reason about numbering behavior, one place to test it, and one place to change it when a new requirement lands.
• Build vs. adopt vs. buy. The realistic comparison is "adopt a small open-source library" versus "write and maintain our own counter service." The package is cheap to adopt and cheap to replace, which lowers the cost of being wrong — a meaningful input to a build-vs-buy decision even when the answer ends up being "build a 50-line adapter on top of it."
• Roadmap items it enables or unblocks. Multi-tenant numbering (independent sequences per tenant), periodic resets (fiscal-year rollover), formatted and zero-padded output (INV/2025/000123), and the gap-free vs. gap-tolerant distinction. Each is a roadmap conversation you can now have with a concrete implementation option on the table instead of an open-ended estimate.
• Architecture decisions. It is interface-driven and framework-agnostic, so it supports hexagonal / DDD layering: the domain declares "I need the next invoice number," infrastructure decides how (database table in production, in-memory fake in tests, Redis if throughput demands it). This is a real decoupling win if the team is already committed to that style — and a neutral detail if not.
• Compliance and audit scoping. "Invoice numbers must be sequential and non-reusable" is a regulatory/audit constraint, not a UX nicety. A dedicated component makes it obvious where that guarantee lives, where it is tested, and where an auditor should look. It also forces us to answer, explicitly, whether our sequences must be gap-free or merely gap-tolerant — a compliance decision, not an engineering one.
• Use cases: billing and invoicing, ERP order intake, helpdesk ticketing, logistics waybills, HR contract numbering, document/records management.
• Caveat to weigh in the decision: the package has 0 stars and 0 dependents. Treat adoption as "we are taking on a maintenance dependency we may end up owning," not as "we are outsourcing a solved problem." The mitigating fact is that the blast radius is small enough to reimplement in a day.

When to Consider This Package

Consider it when:

• You need sequential, human-facing business identifiers — numbers a person will read aloud, quote over the phone, or print on a document. If you only need uniqueness, use UUIDv7/ULID and stop here.
• You are in a PHP/Laravel codebase with DDD or hexagonal leanings, and the team values keeping the domain layer free of Eloquent models and DB facades.
• Your throughput is modest. Numbering an invoice or an order is a low-frequency, transactional event; this is the right shape of problem for a counter-based generator. It is not a high-volume ID service.
• You want a pluggable storage strategy — production store in the database, in-memory fake in unit tests — without hand-rolling the abstraction.
• The blast radius of replacement is small. If the library stagnates, a competent engineer reimplements the interface in a day. That makes the vendor-risk conversation short and keeps the decision reversible.

Look elsewhere (or build) when:

• You need high-throughput or distributed generation at scale. Snowflake-style IDs, native database sequences, or a dedicated ID service are better fits. A counter row is a contention point.
• You need strictly gap-free numbering under failure. True gapless sequences require careful transactional design — usually a dedicated table locked in the same transaction as the business write, plus a reconciliation story for rollbacks. Verify the library's concurrency and transaction semantics before betting a compliance requirement on it, and be prepared to own that logic yourself.
• You are on a modern Laravel version and the package has not kept pace. Check supported PHP/Laravel versions, last release and commit date, test suite, and open issues. With 0 dependents there is little field evidence it runs in production anywhere.
• You need rich formatting rules — per-tenant prefixes, check digits, date-embedded formats. The core generator may only hand you the integer; the formatting layer is likely yours to build.
• Your team would rather standardize on database sequences and never think about it again. That is a legitimate and often correct choice.

Minimum due-diligence checklist before adoption: license compatibility, last release and commit recency, PHP/Laravel version support, test coverage, available storage backends, concurrency behavior under parallel workers and horizontal scaling, and whether maintainers respond to issues. Given the metrics, plan for the possibility that you become the maintainer — fork it internally or reimplement behind the same interface.

How to Pitch It (Stakeholders)

For executives: We have recurring requirements for sequential business identifiers — invoice numbers, order references, ticket IDs — that today get solved ad hoc in each feature. The result is duplicated logic, inconsistent behavior across tenants, and audit risk. This is a small, focused open-source component that standardizes the pattern in a few lines of integration. The financial case is straightforward: it removes a repeated piece of custom code from every future feature and shortens delivery on numbering-related work. Licensing cost is near zero and integration cost is low. The main risk is maturity — the library is young with essentially no adoption, so we should assume we may need to maintain it ourselves. That is acceptable because it is small enough to replace in a day. Recommendation: pilot it behind our own interface in one non-critical feature, and keep the abstraction so we can swap the implementation without touching the domain.

For engineering: This is a SequenceNumberGenerator abstraction with pluggable storage. Use it to keep numbering out of models and inside a domain service — the domain declares the need, infrastructure supplies the counter (DB table in production, in-memory fake in tests). It is a better fit than UUIDs anywhere a human has to read the number aloud. Two things to verify before we commit: behavior under concurrent requests, and whether it gives us what we need for gap-free/audit-grade numbering or whether we have to own that. Also confirm Laravel/PHP version support. Back it with our own adapter interface so the dependency stays at the edge of the codebase — do not let it become a hard dependency in the domain layer. Prove the mechanism with a short prototype (10k numbers across parallel processes, a rollback simulation, a throughput measure) and record the result in an ADR before it goes into production composer.json.