DEV Community

Cover image for Referenceable: Generate Unique Laravel Model References the
Mohamed Said
Mohamed Said

Posted on

Referenceable: Generate Unique Laravel Model References the

#laravel #php #opensource

In many web applications, generating unique reference numbers for models is a common requirement.
Whether you're building:

  • an e-commerce platform that needs order numbers,
  • an invoicing system requiring invoice references, or
  • any application that needs trackable identifiers,

managing reference number generation can quickly become complex.

Referenceable is a Laravel package by Mohamed Said that simplifies this challenge.
It enables the generation of customizable model reference numbers with flexible formats and powerful configuration options.

✨ Main Features

  • Multiple Generation Strategies
    Random, sequential, and template-based reference generation.

  • Highly Configurable
    Define 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 Optimized
    Caching, batch processing, and database transactions.

🚀 Example Usage

1️⃣ Migration

Create a migration with a reference_number column:

Schema::create('status_letters', function (Blueprint $table) {
    $table->id();
    $table->string('reference_number')->unique()->index();
    // other columns...
    $table->timestamps();
});
Enter fullscreen mode Exit fullscreen mode

2️⃣ Model Configuration

Use the HasReference trait and configure the reference strategy:

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';
    // Generates: STL-2025090001, STL-2025090002...
}
Enter fullscreen mode Exit fullscreen mode

🔀 Other Strategies

Random Strategy:

protected $referenceStrategy = 'random';
protected $referencePrefix = 'STL';
protected $referenceLength = 6;
protected $referenceCase = 'upper';
// Generates: STL-A12BC3
Enter fullscreen mode Exit fullscreen mode

Sequential Strategy:

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

✅ Tip: You can also configure references globally in config/referenceable.php instead of per model.

🛠 Useful Methods & Scopes 

// Manually generate without saving
$reference = $statusLetter->generateReference();

// Check if a model has a reference
if ($statusLetter->hasReference()) {
    echo "Reference Number: " . $statusLetter->reference;
}

// Find a record by reference number
$statusLetter = StatusLetter::findByReference('STL-2025090001');

// Query references starting with a prefix
$lettersThisMonth = StatusLetter::referenceStartsWith('STL-202509')->get();
Enter fullscreen mode Exit fullscreen mode

⚡ Installation

Install via Composer and run the install command:

composer require eg-mohamed/referenceable
php artisan referenceable:install
Enter fullscreen mode Exit fullscreen mode

View the source code on GitHub: github.com/EG-Mohamed/Referenceable

Top comments (0)