PHPackages welman91/filament-record-number-generator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. welman91/filament-record-number-generator ActiveLibrary[Utility & Helpers](/categories/utility) welman91/filament-record-number-generator ========================================= Configurable auto-generate record number for Filament v1.0.2(1mo ago)015MITPHPPHP ^8.2CI failing Since Jul 8Pushed 1mo agoCompare [ Source](https://github.com/welman91/filament-record-number-generator)[ Packagist](https://packagist.org/packages/welman91/filament-record-number-generator)[ Docs](https://github.com/welman91/filament-record-number-generator)[ GitHub Sponsors](https://github.com/welman91)[ RSS](/packages/welman91-filament-record-number-generator/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependencies (12)Versions (4)Used By (0) Filament Record Number Generator ================================ [](#filament-record-number-generator) Configurable auto-numbering for any Eloquent model in Filament (v4, v5) . Supports patterns like `INV-2026-0001`, `PO/{branch}/{sequence}`, per-tenant sequences, fiscal year resets, gap-free mode, and prefix/suffix rules. Installation ------------ [](#installation) Add the package to your Laravel project: ``` composer require welman91/filament-record-number-generator ``` Publish and run the migrations: ``` php artisan vendor:publish --tag=filament-record-number-generator-migrations php artisan migrate ``` Optionally publish the config file: ``` php artisan vendor:publish --tag=filament-record-number-generator-config ``` Setup ----- [](#setup) ### 1. Register the Plugin [](#1-register-the-plugin) Add the plugin to your Filament panel provider: ``` use Welman91\FilamentRecordNumberGenerator\FilamentRecordNumberGeneratorPlugin; public function panel(Panel $panel): Panel { return $panel ->plugin( FilamentRecordNumberGeneratorPlugin::make() ->navigationGroup('Settings') // optional, defaults to "Settings" ); } ``` ### 2. Add the Trait to Your Models [](#2-add-the-trait-to-your-models) Add `HasNumbering` to any model that needs auto-numbering: ``` use Welman91\FilamentRecordNumberGenerator\Concerns\HasNumbering; class Invoice extends Model { use HasNumbering; // Optional: explicitly declare which attributes to auto-number. // If omitted, the trait auto-detects from the numbering_sequences table. protected array $numberingFields = ['invoice_number']; } ``` ### 3. Create a Numbering Sequence [](#3-create-a-numbering-sequence) Navigate to **Settings > Numbering Sequences** in your Filament panel and create a sequence, or insert one directly: ``` use Welman91\FilamentRecordNumberGenerator\Models\NumberingSequence; NumberingSequence::create([ 'company_id' => 1, // tenant scope (null for global) 'name' => 'Invoice Number', 'model_type' => \App\Models\Invoice::class, 'attribute' => 'invoice_number', 'pattern' => 'INV-{year}-{sequence:4}', 'reset_frequency' => 'yearly', // never, yearly, monthly, daily 'fiscal_year_start_month' => 1, // 1 = January 'is_gap_free' => true, 'is_active' => true, 'initial_value' => 1, ]); ``` Now every time an `Invoice` is created, the `invoice_number` attribute is automatically filled (e.g. `INV-2026-0001`, `INV-2026-0002`, ...). Pattern Tokens -------------- [](#pattern-tokens) TokenExample OutputDescription`{sequence}``0001`Zero-padded sequence (default 4 digits)`{sequence:N}``000001`Zero-padded to N digits`{year}``2026`4-digit year`{year:2}``26`2-digit year`{month}``04`Zero-padded month`{day}``07`Zero-padded day`{prefix}``INV-`Value from the sequence's `prefix` column`{suffix}``-A`Value from the sequence's `suffix` column`{attribute:name}``Acme`Model attribute (supports dot notation for relations)### Example Patterns [](#example-patterns) PatternOutput`INV-{year}-{sequence:4}``INV-2026-0001``PO/{attribute:branch.code}/{sequence:5}``PO/HQ/00001``{prefix}{year:2}{month}-{sequence:3}{suffix}``CR-2604-001-A``REC-{sequence:6}``REC-000001`Custom Token Aliases -------------------- [](#custom-token-aliases) You can define custom token names that map to built-in resolvers, either via the admin UI or in the `custom_tokens` JSON column: ``` NumberingSequence::create([ // ... 'pattern' => '{branch}-{year}-{sequence:4}', 'custom_tokens' => [ 'branch' => 'attribute:branch.code', // {branch} resolves to $model->branch->code ], ]); ``` Custom Token Resolvers ---------------------- [](#custom-token-resolvers) Create a class implementing `TokenResolver` for completely custom logic: ``` use Welman91\FilamentRecordNumberGenerator\Contracts\TokenResolver; class DepartmentCodeResolver implements TokenResolver { public function resolve(string $token, ?string $argument, array $context): string { return $context['model']->department->short_code ?? 'GEN'; } public function supports(string $token): bool { return $token === 'dept'; } } ``` Register it in `config/filament-record-number-generator.php`: ``` 'custom_resolvers' => [ \App\NumberingResolvers\DepartmentCodeResolver::class, ], ``` Then use `{dept}` in your patterns. Reset Frequency --------------- [](#reset-frequency) FrequencyBehavior`never`Counter never resets — continuous numbering`yearly`Resets at the start of each fiscal year`monthly`Resets at the start of each month`daily`Resets at the start of each day### Fiscal Year [](#fiscal-year) When `reset_frequency` is `yearly`, the `fiscal_year_start_month` determines when the year rolls over: - `1` (January) — standard calendar year - `4` (April) — fiscal year runs Apr–Mar (e.g. Jan 2026 belongs to fiscal year 2025) - `7` (July) — fiscal year runs Jul–Jun Gap-Free Mode ------------- [](#gap-free-mode) When `is_gap_free` is `true`, the package uses database row-level locking (`SELECT ... FOR UPDATE`) to guarantee no gaps in the sequence. The counter increment and model save happen within the same transaction — if the save fails, the counter rolls back. **Trade-off:** Gap-free mode serializes concurrent requests for the same sequence. Use it only when regulatory or business requirements demand unbroken sequences (e.g. invoice numbers). When `is_gap_free` is `false` (default), an atomic increment is used. Gaps may occur if a model creation fails after the counter is incremented, but throughput is higher. Per-Tenant Isolation -------------------- [](#per-tenant-isolation) Each numbering sequence is scoped by `company_id`. Two companies with the same sequence pattern maintain independent counters: - Company A: `INV-2026-0001`, `INV-2026-0002`, ... - Company B: `INV-2026-0001`, `INV-2026-0002`, ... Set `company_id` to `null` for a global sequence shared across all tenants. Manual Override --------------- [](#manual-override) If a model's numbered attribute is already filled before creation, the trait skips auto-generation. This allows manual number entry when needed: ``` Invoice::create([ 'invoice_number' => 'MANUAL-001', // trait won't overwrite this // ... ]); ``` Programmatic Usage ------------------ [](#programmatic-usage) ### Generate a Number [](#generate-a-number) ``` use Welman91\FilamentRecordNumberGenerator\Services\NumberingEngine; $engine = app(NumberingEngine::class); $number = $engine->generate($invoice); ``` ### Preview the Next Number [](#preview-the-next-number) Returns what the next number will be without consuming a counter value: ``` $engine = app(NumberingEngine::class); $preview = $engine->preview($invoice); // e.g. "INV-2026-0043" ``` ### On the Model [](#on-the-model) ``` $invoice->generateNumber('invoice_number'); $invoice->previewNextNumber('invoice_number'); ``` Events ------ [](#events) The `NumberGenerated` event is dispatched after each number is generated: ``` use Welman91\FilamentRecordNumberGenerator\Events\NumberGenerated; Event::listen(NumberGenerated::class, function (NumberGenerated $event) { // $event->model // $event->attribute // $event->generatedNumber // $event->sequence }); ``` Plugin Configuration -------------------- [](#plugin-configuration) MethodDescription`sequenceResource(false)`Disable the Numbering Sequences resource in the panel`navigationGroup('Admin')`Change the navigation group``` FilamentRecordNumberGeneratorPlugin::make() ->sequenceResource(true) ->navigationGroup('Administration') ``` Config File ----------- [](#config-file) After publishing, the config is at `config/filament-record-number-generator.php`: KeyDefaultDescription`default_pattern``{prefix}{year}-{sequence:4}{suffix}`Default pattern for new sequences`default_reset_frequency``yearly`Default reset frequency`default_fiscal_year_start_month``1`Default fiscal year start`default_gap_free``false`Default gap-free mode`navigation_group``Settings`Filament navigation group`custom_resolvers``[]`Custom token resolver classesLocalization ------------ [](#localization) The package ships with English and Arabic translations. Publish them to customize: ``` php artisan vendor:publish --tag=filament-record-number-generator-translations ``` Testing ------- [](#testing) ``` php artisan test --filter=NumberingEngine php artisan test --filter=PatternParser ``` License ------- [](#license) MIT ### Health Score 40 — FairBetter than 86% of packages Maintenance90 Actively maintained with recent releases Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 48d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b8e707d15605b2b620f44a728b1a7074b1fa9422bf0e02668d446752123b7a5a?d=identicon)[welman91](/maintainers/welman91) --- Top Contributors [![welman91](https://avatars.githubusercontent.com/u/70043593?v=4)](https://github.com/welman91 "welman91 (6 commits)") --- Tags laravelfilamentfilament-pluginfilamentphpwelman91filament-record-number-generator ### Code Quality TestsPest Static AnalysisPHPStan, Rector Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/welman91-filament-record-number-generator/health.svg) ``` [![Health](https://phpackages.com/badges/welman91-filament-record-number-generator/health.svg)](https://phpackages.com/packages/welman91-filament-record-number-generator) ``` ### Alternatives [rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3915.5k](/packages/rawilk-profile-filament-plugin)[backstage/mails View logged mails and events in a beautiful Filament UI. 16429.7k](/packages/backstage-mails)[marcelweidum/filament-passkeys Use passkeys in your filamentphp app 6758.2k2](/packages/marcelweidum-filament-passkeys)[stephenjude/filament-two-factor-authentication Filament Two Factor Authentication: Google 2FA + Passkey Authentication 85240.3k10](/packages/stephenjude-filament-two-factor-authentication)[relaticle/custom-fields User Defined Custom Fields for Laravel Filament 16461.2k](/packages/relaticle-custom-fields)[hammadzafar05/mobile-bottom-nav A thumb-friendly mobile bottom navigation bar for Filament panels. It programmatically integrates with the Filament navigation registry to provide a seamless, ergonomic mobile experience with full support for dark mode and safe-area insets. 1821.3k1](/packages/hammadzafar05-mobile-bottom-nav) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)