Referenceable: Generate Unique Laravel Model References the

• 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();
});

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...
}

🔀 Other Strategies

Random Strategy:

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

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...

✅ 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();

⚡ Installation

Install via Composer and run the install command:

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

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