Sequence Bundle Laravel Package

Getting Started

First, establish what you actually have. Despite the framing, indragunawan/sequence-bundle is a Symfony bundle, not a Laravel package — it ships no service provider, facade, or config file that Laravel's container will auto-discover. If the project is genuinely Symfony, the setup is:

1. composer require indragunawan/sequence-bundle.
2. Register it in config/bundles.php (Symfony Flex usually does this).
3. Read vendor/indragunawan/sequence-bundle/DependencyInjection/Configuration.php first — that is the authoritative list of options (format/prefix/suffix, reset period, storage backend).
4. Inspect Resources/config/services.yaml (or .xml) to learn the generator's service id and constructor arguments before wiring anything.

The first use case to validate is a formatted, human-readable sequential identifier — e.g. an invoice or order number like INV/2024/000123 — that increments atomically and resets on a schedule. Prove that end-to-end (generate two IDs, confirm they increment and persist) before building on it.

If the project is Laravel: stop. There is no supported path to boot a Symfony bundle inside Laravel's container. The realistic options are (a) copy the sequence-generation logic into a small Laravel service, or (b) evaluate a Laravel-native alternative. Treat the bundle as a reference implementation, not a dependency.

Implementation Patterns

Config-driven formatting. Define the number format declaratively (prefix, date token, zero-padded counter, reset granularity) rather than concatenating strings in application code. Centralising the format means adding a new document type is a config change, not a code change.

Inject the generator, don't new it. In Symfony, autowire the generator service into the service that creates the entity (order/invoice handler). If the service id isn't guessable, it isn't autowireable — bind it explicitly or define an alias.

Generate inside the persistence transaction. The sequence read-and-increment and the entity insert should commit together. If you generate the number in a controller and persist later, you invite duplicates under concurrency and orphaned numbers on validation failure.

Use it for display identifiers, not primary keys. Keep auto-increment/UUID primary keys for referential integrity and joins; use the sequence for the value humans quote on the phone.

Wrap it behind your own interface. Define DocumentNumberGenerator in your domain and adapt the bundle's service to it. This isolates the (old, low-adoption) dependency so you can swap implementations without touching call sites — and it's the seam you'd use to port to Laravel later.

Test fixtures must reset state. Seed or truncate the sequence storage between tests, otherwise assertions on 000001 depend on test execution order.

Gotchas and Tips

• Framework mismatch is the headline risk. A Symfony bundle's Bundle class, DI extension, and compiler passes do nothing in Laravel. Don't spend a day trying to bridge it; port the concept.
• Last release 2020, 5 stars, 0 dependents. Verify PHP 8+ and current Doctrine compatibility before committing. Pin the version and read the source — there is effectively no community to catch bugs for you. Treat it as unaudited code.
• Concurrency correctness is unverified. Check whether the increment uses a DB-level lock/SELECT ... FOR UPDATE, a unique constraint with retry, or nothing. Under load, a naive read-then-write will hand out duplicate numbers. Test with parallel workers before trusting it.
• Gaps are normal; decide if they're acceptable. Rollbacks and crashes leave holes in the sequence. For invoice numbering some jurisdictions require gapless sequences — confirm the bundle (and your transaction boundaries) actually guarantee that, or use it only where gaps are fine.
• Storage/migrations. Find out whether it ships a Doctrine entity, a migration, or expects you to provision a table. Missing schema shows up as a runtime SQL error, not a config error — read the mapping files.
• Debugging in Symfony: bin/console debug:container <service> to confirm the service exists and its arguments; debug:config to verify your config was merged; enable SQL logging to watch the actual increment statement.
• Extension points: the DI configuration and (if present) format resolver/strategy interfaces are where you customise. Prefer configuring these over subclassing internals, and prefer your own adapter interface over depending on the bundle's classes directly.