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)