Customizable reference numbers for your models with Referenceable

In many web applications, generating unique reference numbers for models is a common requirement. Whether you're building an e-commerce platform that requires order numbers, an invoicing system that needs invoice reference numbers, or any application that needs trackable identifiers, managing reference number generation can quickly become complex.

Referenceable is a Laravel package created by Mohamed Said that helps to solve this challenge by enabling the generation of customisable model reference numbers with flexible formats and comprehensive configuration options.

#Main Features

• Multiple Generation Strategies: Random, sequential, and template-based reference generation
• Highly Configurable: Extensive configuration options for prefixes, suffixes, separators, and more
• Template System: Use placeholders like {YEAR}, {MONTH}, {SEQ}, {RANDOM} for complex formats
• Sequential Numbering: Auto-incrementing sequences with reset options (daily, monthly, yearly)
• Validation & Verification: Built-in reference validation and uniqueness checking
• Collision Handling: Automatic collision detection and resolution
• Multi-Tenancy Support: Tenant-aware reference generation
• Artisan Commands: Comprehensive CLI tools for management and maintenance
• Performance Optimised: Caching, batch processing, and database transactions

#Example

Let's say we have a system that allows users to submit requests for Status Letters at a University. We can create a migration that contains a column to store our reference number:

Schema::create('status_letters', function (Blueprint $table) {
    $table->id();
    $table->string('reference_number')->unique()->index();
    // other table columns for our status letters...
    $table->timestamps();
});

We then create a model and specify how we want to create our reference numbers:

use MohamedSaid\Referenceable\Traits\HasReference;
 
class StatusLetter extends Model
{
    use HasReference;
 
    protected $referenceColumn = 'reference_number';
    protected $referenceStrategy = 'template';
    protected $referenceTemplate = [
        'format' => '{PREFIX}-{YEAR}{MONTH}{SEQ}',
        'sequence_length' => 4,
    ];
    protected $referencePrefix = 'STL';
    // Will generate: STL-2025090001, STL-2025090002...
}

Instead of the template strategy, you can also use the random strategy:

protected $referenceStrategy = 'random';
protected $referencePrefix = 'STL';
protected $referenceLength = 6;
protected $referenceCase = 'upper';
 
// Will generate: STL-A12BC3

Or use the sequential strategy:

protected $referenceStrategy = 'sequential';
protected $referencePrefix = 'STL';
protected $referenceSequential = [
    'start' => 1000,
    'min_digits' => 4,
    'reset_frequency' => 'monthly', // never, daily, monthly, yearly
];
 
// Will generate: STL-001000, STL-001001, STL-001002...

Configuring your references can also be done globally in config/referenceable.php instead of on a per-model basis.

Referenceable offers numerous methods and model scopes. A few are:

// Manually generate without saving it
$reference = $statusLetter->generateReference();
 
// Check if your model has a reference
if ($statusLetter->hasReference()) {
    echo "Reference Number: " . $statusLetter->reference;
}
 
// Find an item by its reference number
$statusLetter = StatusLetter::findByReference('STL-2025090001');
 
// Find references starting with prefix
$lettersThisMonth = StatusLetter::referenceStartsWith('STL-202509')->get();

Stop wrestling with messy reference number generation in Laravel – the Referenceable package gives you professional order numbers, invoice IDs, and tracking codes with just a few lines of configuration.

Give this package a try by installing it via Composer and running the install command:

composer require eg-mohamed/referenceable
php artisan referenceable:install

Learn more about this package and view the source code on GitHub.