Laravel Id Generator Laravel Package

Getting Started

• composer require omaressaouaf/laravel-id-generator — auto-discovered via package manifest, no manual provider registration.
• Publish the config first: php artisan vendor:publish --tag="id-generator-config", then read config/id-generator.php top to bottom. That file (not the README) is the real API surface: a default key plus a generators map where each entry defines its prefix, length and generation strategy.
• Use the facade as your entry point. The canonical first use case is a human-readable, non-guessable business identifier — invoice numbers, order references, ticket codes — e.g. IdGenerator::generate() for the default generator and IdGenerator::use('invoice')->generate() for a named one.
• v1.4.0 note: this release only widens the support matrix (Laravel 13, PHP 8.5). No new public API, no deprecations, no config changes. If you were pinned to v1.3.0 by a framework constraint, the bump is the whole upgrade — expect a drop-in composer update and nothing else.

Implementation Patterns

One named generator per domain. Resist using the default generator everywhere. Declare invoice, customer, ticket in the config so the format for each lives in one reviewable place, and let callers ask for the generator by name. When finance asks for a new prefix, it's a one-line config diff instead of a grep across the codebase.

Assign in a model event or observer, not in the controller. Generating the ID inside creating/booted guarantees every write path (HTTP, queued job, importer, artisan command, seeder) gets a value. Controllers that generate IDs inevitably miss the one path that isn't a controller.

Keep your auto-increment primary key and add a unique number column. Replacing the PK with a generated string is a much bigger migration than it looks — foreign keys, route() model binding behaviour, and index size all shift. Add a string column with a unique() index and treat the package output as a business reference, not the identity.

Treat uniqueness as the database's job. The unique index is the source of truth; the generator produces a candidate. Wrap creation in a small retry (catch the QueryException for the unique violation and regenerate) rather than trying to prove uniqueness in application code — that reasoning breaks the moment you run more than one worker.

Testing. Don't assert exact strings — assert shape. A regex or length/prefix check against the generator's rules survives config edits and clock changes. For determinism, freeze or swap the generator binding in the container so tests don't depend on randomness, and add one test that hits the real generator to prove the config itself is valid.

API resources and form requests. The generated ID is an output, never an input. Strip it from $fillable / validation rules so clients can't supply their own invoice number; expose it only in the resource.

Multi-tenant setups. Either define one generator per tenant (prefix carries the tenant slug) or resolve the prefix at runtime from the tenant context. Keep the suffix format identical across tenants so support staff can read an ID and know which tenant it belongs to.

Gotchas and Tips

• Config caching. config/id-generator.php edits are invisible until php artisan config:clear (or a config:cache re-run). This is the single most common "the package is broken" report.
• Length semantics are load-bearing. Confirm whether the configured length includes the prefix and how padding behaves; changing length later produces IDs of two different shapes in the same column. Treat the format as a schema: version it, don't silently edit it.
• Alphabet/strategy changes invalidate existing data. Switching from sequential to random (or narrowing the alphabet) means old IDs can no longer be parsed or validated by your own regexes. Add new formats as new named generators instead of mutating an existing one.
• Sequential strategies under concurrency. Anything that reads a "last value" and increments is racy across processes. Rely on the unique constraint plus retry, and never cache the counter in Redis without a lock.
• Never assume an ID was generated. Records created via raw SQL, seeders, or legacy imports won't have one. Make the column nullable in the schema, then backfill, then add NOT NULL — in that order.
• Laravel 13 / PHP 8.5 upgrade path. The blocker will be your other packages, not this one. Run composer why-not laravel/framework 13.* before bumping, and check anything that pins illuminate/* or ships compiled extensions. Also confirm your own CI matrix actually has a PHP 8.5 image — the release notes outrun most CI providers' defaults.
• Extension point: if a format can't be expressed in config, the escape hatch is a custom generator class wired into the generators map. That's the supported seam — avoid subclassing the facade or monkey-patching internals.
• Debugging format issues: log the generator name and the produced value at creation time for anything customer-facing. When an ID looks wrong in a support ticket, you want to know which generator and which config version made it.