Referenceable: Flexible Template-Driven References for Laravel | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [home](https://msaied.com) / [articles](https://msaied.com/articles) / Referenceable: Flexible Template-Driven References for Laravel ![Referenceable: Flexible Template-Driven References for Laravel](https://cdn.msaied.com/28/01KT7MBVQD1B1QA62RM6Y4XS1J.jpg) Laravel PHP Open Source Reference Generation Multi-Tenancy CLI Referenceable: Flexible Template-Driven References for Laravel ============================================================== 3 Jun 2026 6 min read Referenceable Laravel Package: Flexible Reference Number Generation for Eloquent Models ======================================================================================= **GitHub Repository:** https://github.com/EG-Mohamed/Referenceable Introduction ------------ Referenceable is a powerful Laravel package that helps you generate unique, customizable reference numbers for Eloquent models. It is useful for applications that need readable IDs for orders, invoices, bookings, tickets, products, assets, subscriptions, or any record that should have a human-friendly reference instead of relying only on database IDs. With Referenceable, you can generate random references, sequential numbers, or fully customized template-based references using prefixes, dates, counters, and random strings. Why Use Referenceable? ---------------------- In many Laravel applications, using a plain auto-increment ID is not ideal for business-facing records. For example, an order number like `ORD-2026-0001` is clearer, more professional, and easier to share with customers than `#153`. Referenceable solves this by giving you a clean, configurable way to automatically generate and manage references for your models. Key Features ------------ - Multiple reference generation strategies: random, sequential, and template-based - Custom prefixes, suffixes, separators, length, and character sets - Template placeholders such as `{YEAR}`, `{MONTH}`, `{DAY}`, `{SEQ}`, and `{RANDOM}` - Sequential numbering with optional daily, monthly, or yearly reset - Built-in validation and uniqueness checking - Automatic collision handling - Tenant-aware reference generation for multi-tenant applications - Artisan commands for generating, validating, and regenerating references - Batch processing support - Configuration caching and database transaction support - Compatible with modern Laravel applications Installation ------------ Install the package using Composer: ```bash composer require eg-mohamed/referenceable ``` Then run the installation command: ```bash php artisan referenceable:install ``` This command publishes the configuration file and creates the required database tables. Quick Start ----------- ### 1. Add a Reference Column to Your Migration ```php Schema::create('orders', function (Blueprint $table) { $table->id(); $table->string('reference')->unique()->index(); $table->timestamps(); }); ``` ### 2. Use the Trait in Your Model ```php use MohamedSaid\Referenceable\Traits\HasReference; class Order extends Model { use HasReference; protected $fillable = ['total', 'customer_id']; } ``` ### 3. Create a Model Record ```php $order = Order::create([ 'customer_id' => 1, 'total' => 99.99, ]); echo $order->reference; ``` Example output: ```txt AB12CD34 ``` The reference is generated automatically when the model is created. Reference Generation Strategies ------------------------------- Referenceable supports three main generation strategies. ### Random Strategy The random strategy is useful when you need short, unique, non-sequential references. ```php protected $referenceStrategy = 'random'; protected $referencePrefix = 'ORD'; protected $referenceLength = 6; protected $referenceCase = 'upper'; ``` Example output: ```txt ORD-AB12CD ``` ### Sequential Strategy The sequential strategy is ideal for invoices, orders, tickets, and other records that need ordered numbering. ```php protected $referenceStrategy = 'sequential'; protected $referencePrefix = 'INV'; protected $referenceSequential = [ 'start' => 1000, 'min_digits' => 6, 'reset_frequency' => 'yearly', ]; ``` Example output: ```txt INV-001000 INV-001001 INV-001002 ``` ### Template Strategy The template strategy gives you full control over the reference format. ```php protected $referenceStrategy = 'template'; protected $referenceTemplate = [ 'format' => '{PREFIX}{YEAR}{MONTH}{SEQ}', 'sequence_length' => 4, ]; protected $referencePrefix = 'ORD'; ``` Example output: ```txt ORD2026060001 ORD2026060002 ``` Available Template Placeholders ------------------------------- | Placeholder | Description | Example | |---|---|---| | `{PREFIX}` | Custom prefix | `ORD` | | `{SUFFIX}` | Custom suffix | `2026` | | `{YEAR}` | Four-digit year | `2026` | | `{YEAR2}` | Two-digit year | `26` | | `{MONTH}` | Two-digit month | `06` | | `{DAY}` | Two-digit day | `03` | | `{SEQ}` | Sequential number | `0001` | | `{RANDOM}` | Random string | `AB12` | | `{MODEL}` | Model class name | `Order` | | `{TIMESTAMP}` | Unix timestamp | `1780459200` | Model-Level Configuration ------------------------- You can customize the reference behavior directly inside each model. ```php class Order extends Model { use HasReference; protected $referenceColumn = 'order_number'; protected $referenceStrategy = 'template'; protected $referencePrefix = 'ORD'; protected $referenceSuffix = ''; protected $referenceSeparator = '-'; protected $referenceLength = 8; protected $referenceCharacters = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'; protected $referenceExcludedCharacters = '01IOL'; protected $referenceCase = 'upper'; protected $referenceSequential = [ 'start' => 1, 'min_digits' => 6, 'reset_frequency' => 'yearly', ]; protected $referenceTemplate = [ 'format' => '{PREFIX}{YEAR}{MONTH}{SEQ}', 'random_length' => 4, 'sequence_length' => 4, ]; protected $referenceValidation = [ 'pattern' => '/^ORD-\d{4}-\w{6}$/', 'min_length' => 8, 'max_length' => 20, ]; protected $referenceUniquenessScope = 'model'; protected $referenceTenantColumn = 'company_id'; protected $referenceCollisionStrategy = 'retry'; protected $referenceMaxRetries = 100; } ``` Global Configuration -------------------- You can define default behavior in: ```txt config/referenceable.php ``` Example: ```php return [ 'strategy' => 'random', 'column_name' => 'reference', 'length' => 6, 'prefix' => '', 'suffix' => '', 'separator' => '-', 'characters' => '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'excluded_characters' => '01IOL', 'case' => 'upper', 'sequential' => [ 'start' => 1, 'min_digits' => 6, 'reset_frequency' => 'never', 'counter_table' => 'model_reference_counters', ], 'template' => [ 'format' => '{PREFIX}{YEAR}{MONTH}{SEQ}', 'random_length' => 4, 'sequence_length' => 4, ], 'validation' => [ 'enabled' => true, 'min_length' => 3, 'max_length' => 50, ], 'uniqueness_scope' => 'model', 'collision_strategy' => 'retry', 'max_retries' => 100, 'performance' => [ 'cache_config' => true, 'cache_ttl' => 60, 'use_transactions' => true, 'batch_size' => 100, ], ]; ``` Manual Reference Generation --------------------------- You can generate, regenerate, and check references manually when needed. ```php $reference = $order->generateReference(); $newReference = $order->regenerateReference(save: true); if ($order->hasReference()) { echo $order->reference; } ``` Reference Validation -------------------- Validate the current model reference: ```php if ($order->validateReference()) { echo 'Valid reference'; } ``` Validate a custom reference: ```php if ($order->validateReference('ORD-123456')) { echo 'Valid format'; } ``` Query Scopes ------------ Find a model by reference: ```php $order = Order::findByReference('ORD-123456'); ``` Get models with references: ```php $ordersWithRefs = Order::withReference()->get(); ``` Get models without references: ```php $ordersWithoutRefs = Order::withoutReference()->get(); ``` Find references starting with a specific value: ```php $todayOrders = Order::referenceStartsWith('ORD-2026')->get(); ``` Batch Operations ---------------- ```php use MohamedSaid\ModelReference\ModelReference; $modelReference = app(ModelReference::class); $references = $modelReference->generateBatch(Order::class, 100); $results = $modelReference->validateBulk($references->toArray()); $stats = $modelReference->getStats(Order::class); ``` Artisan Commands ---------------- ### Installation ```bash php artisan referenceable:install php artisan referenceable:install --force ``` ### Generate References ```bash php artisan referenceable:generate "App\\Models\\Order" php artisan referenceable:generate "App\\Models\\Order" --dry-run php artisan referenceable:generate "App\\Models\\Order" --batch=500 ``` ### Validate References ```bash php artisan referenceable:validate "App\\Models\\Order" php artisan referenceable:validate "App\\Models\\Order" --fix ``` ### Regenerate References ```bash php artisan referenceable:regenerate "App\\Models\\Order" --id=123 php artisan referenceable:regenerate "App\\Models\\Order" --all --dry-run ``` ### View Statistics ```bash php artisan referenceable:stats "App\\Models\\Order" php artisan referenceable:stats "App\\Models\\Order" --json ``` ### Show Package Commands ```bash php artisan referenceable php artisan referenceable --list ``` Multi-Tenancy Support --------------------- Referenceable supports tenant-aware uniqueness, which is useful for SaaS and multi-company systems. ```php class Order extends Model { use HasReference; protected $referenceUniquenessScope = 'tenant'; protected $referenceTenantColumn = 'company_id'; } ``` With this setup, references can be unique per tenant instead of globally unique across the entire application. Performance Optimization ------------------------ For better performance, make sure your reference columns are indexed. ```php Schema::table('orders', function (Blueprint $table) { $table->index('reference'); $table->index(['company_id', 'reference']); }); ``` You can also enable configuration caching and transactions: ```php 'performance' => [ 'cache_config' => true, 'cache_ttl' => 60, 'use_transactions' => true, 'batch_size' => 100, ], ``` Common Use Cases ---------------- Referenceable is suitable for: - Order numbers - Invoice numbers - Booking references - Ticket IDs - Product codes - Shipment tracking references - Customer account numbers - Asset tracking numbers - Subscription references - Multi-tenant business records Example Reference Formats ------------------------- ```txt ORD-2026-0001 INV-000125 TCK-AB92KD BOOK-202606-0042 ASSET-2026-XY91 ``` Migration Guide from v1.x to v2.x --------------------------------- ### 1. Run the Installation Command ```bash php artisan referenceable:install ``` ### 2. Update Your Model Configuration Old format: ```php protected $referenceLength = 8; ``` This is still supported, but you can also use the newer template configuration: ```php protected $referenceTemplate = [ 'format' => '{PREFIX}{RANDOM}', 'random_length' => 8, ]; ``` ### 3. Validate Existing References ```bash php artisan referenceable:validate "App\\Models\\Order" ``` Conclusion ---------- Referenceable gives Laravel developers a clean and flexible way to generate professional reference numbers for Eloquent models. It supports random references, sequential numbering, custom templates, validation, collision handling, tenant-aware uniqueness, and helpful Artisan commands. This makes it a strong choice for Laravel applications that need reliable reference generation for orders, invoices, tickets, bookings, assets, or any business-facing record. For source code and installation details, visit the GitHub repository: https://github.com/EG-Mohamed/Referenceable More Articles [View all →](https://msaied.com/articles) [ ![RulesJson: Convert Laravel Validation Rules to JSON Request Bodies](https://cdn.msaied.com/32/01KT7NRXW0Q33S81H8AX48ZMYJ.jpg) ### RulesJson: Convert Laravel Validation Rules to JSON Request Bodies RulesJson is a free client-side tool that converts Laravel validation rules into ready-to-use JSON request bod... 4 Jun 2026 12 min read Read ](https://msaied.com/articles/rulesjson-convert-laravel-validation-rules-to-json-request-bodies) [ ![OpenCharity: Open-Source Charity Management Platform Built with Laravel and Filament](https://cdn.msaied.com/31/01KT7NCC0QYT01D5XYZJGZ8JQE.jpg) ### OpenCharity: Open-Source Charity Management Platform Built with Laravel and Filament OpenCharity is an open-source Laravel and Filament platform for managing charity cases, families, visits, assi... 4 Jun 2026 17 min read Read ](https://msaied.com/articles/opencharity-open-source-charity-management-platform-built-with-laravel-and-filament) [ ![Notable: A Laravel Notes Package for Eloquent](https://cdn.msaied.com/29/01KT7MCCMPZQ59D2E4B5H01G2A.jpg) Laravel PHP Open Source ### Notable: A Laravel Notes Package for Eloquent Notable empowers Laravel apps to attach notes to any Eloquent model using polymorphic relationships. It ships... 3 Jun 2026 2 min read Read ](https://msaied.com/articles/notable-a-laravel-notes-package-for-eloquent) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com)