README

An advanced Laravel package for making models referenceable with customizable reference numbers, flexible formats, sequential numbering, template-based generation, and comprehensive configuration options.

✨ 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 Optimized: Caching, batch processing, and database transactions
• Laravel 12 Ready: Full compatibility with the latest Laravel versions

🚀 Installation

Install the package via Composer:

composer require eg-mohamed/referenceable

Install the package (creates necessary tables and publishes config):

php artisan referenceable:install

📋 Quick Start

1. Add Reference Column to Migration

Schema::create('orders', function (Blueprint $table) {
    $table->id();
    $table->string('reference')->unique()->index(); // Add reference column
    $table->timestamps();
});

2. Use the Trait in Your Model

use MohamedSaid\Referenceable\Traits\HasReference;

class Order extends Model
{
    use HasReference;
    
    protected $fillable = ['total', 'customer_id'];
}

3. Generate References Automatically

$order = Order::create([
    'customer_id' => 1,
    'total' => 99.99,
]);

echo $order->reference; // Outputs: "AB12CD34" (random strategy)

🛠 Configuration

Generation Strategies

Choose from three powerful generation strategies:

Random Strategy (Default)

// In your model
protected $referenceStrategy = 'random';
protected $referencePrefix = 'ORD';
protected $referenceLength = 6;
protected $referenceCase = 'upper';

// Generates: ORD-AB12CD

Sequential Strategy

// In your model
protected $referenceStrategy = 'sequential';
protected $referencePrefix = 'INV';
protected $referenceSequential = [
    'start' => 1000,
    'min_digits' => 6,
    'reset_frequency' => 'yearly', // never, daily, monthly, yearly
];

// Generates: INV-001000, INV-001001, INV-001002...

Template Strategy

// In your model
protected $referenceStrategy = 'template';
protected $referenceTemplate = [
    'format' => '{PREFIX}{YEAR}{MONTH}{SEQ}',
    'sequence_length' => 4,
];
protected $referencePrefix = 'ORD';

// Generates: ORD20240001, ORD20240002...

Available Template Placeholders

Model-Level Configuration

class Order extends Model
{
    use HasReference;
    
    // Basic configuration
    protected $referenceColumn = 'order_number';     // Column name
    protected $referenceStrategy = 'template';       // random, sequential, template
    protected $referencePrefix = 'ORD';              // Prefix
    protected $referenceSuffix = '';                 // Suffix
    protected $referenceSeparator = '-';             // Separator
    
    // Random strategy options
    protected $referenceLength = 8;                  // Random part length
    protected $referenceCharacters = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
    protected $referenceExcludedCharacters = '01IOL'; // Avoid confusing chars
    protected $referenceCase = 'upper';              // upper, lower, mixed
    
    // Sequential strategy options
    protected $referenceSequential = [
        'start' => 1,
        'min_digits' => 6,
        'reset_frequency' => 'yearly', // never, daily, monthly, yearly
    ];
    
    // Template strategy options
    protected $referenceTemplate = [
        'format' => '{PREFIX}{YEAR}{MONTH}{SEQ}',
        'random_length' => 4,
        'sequence_length' => 4,
    ];
    
    // Validation options
    protected $referenceValidation = [
        'pattern' => '/^ORD-\d{4}-\w{6}$/', // Custom regex pattern
        'min_length' => 8,
        'max_length' => 20,
    ];
    
    // Advanced options
    protected $referenceUniquenessScope = 'model';   // global, model, tenant
    protected $referenceTenantColumn = 'company_id'; // For tenant-aware uniqueness
    protected $referenceCollisionStrategy = 'retry'; // retry, fail, append
    protected $referenceMaxRetries = 100;
}

Global Configuration

Configure defaults in config/referenceable.php:

return [
    'strategy' => 'random',
    'column_name' => 'reference',
    
    // Random generation options
    'length' => 6,
    'prefix' => '',
    'suffix' => '',
    'separator' => '-',
    'characters' => '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ',
    'excluded_characters' => '01IOL',
    'case' => 'upper',
    
    // Sequential generation options
    'sequential' => [
        'start' => 1,
        'min_digits' => 6,
        'reset_frequency' => 'never',
        'counter_table' => 'model_reference_counters',
    ],
    
    // Template generation options
    'template' => [
        'format' => '{PREFIX}{YEAR}{MONTH}{SEQ}',
        'random_length' => 4,
        'sequence_length' => 4,
    ],
    
    // Validation options
    'validation' => [
        'enabled' => true,
        'min_length' => 3,
        'max_length' => 50,
    ],
    
    // Uniqueness and collision handling
    'uniqueness_scope' => 'model', // global, model, tenant
    'collision_strategy' => 'retry',
    'max_retries' => 100,
    
    // Performance options
    'performance' => [
        'cache_config' => true,
        'cache_ttl' => 60,
        'use_transactions' => true,
        'batch_size' => 100,
    ],
];

🔧 Advanced Usage

Manual Reference Generation

// Generate without saving
$reference = $order->generateReference();

// Regenerate existing reference
$newReference = $order->regenerateReference(save: true);

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

Reference Validation

// Validate current reference
if ($order->validateReference()) {
    echo "Valid reference";
}

// Validate specific reference
if ($order->validateReference('ORD-123456')) {
    echo "Valid format";
}

Query Scopes

// Find by reference
$order = Order::findByReference('ORD-123456');

// Models with references
$ordersWithRefs = Order::withReference()->get();

// Models without references
$ordersWithoutRefs = Order::withoutReference()->get();

// References starting with prefix
$todayOrders = Order::referenceStartsWith('ORD-2024')->get();

Batch Operations

use MohamedSaid\ModelReference\ModelReference;

$modelReference = app(ModelReference::class);

// Generate multiple references
$references = $modelReference->generateBatch(Order::class, 100);

// Validate multiple references
$results = $modelReference->validateBulk($references->toArray());

// Get statistics
$stats = $modelReference->getStats(Order::class);

🎯 Artisan Commands

Installation & Setup

# Install package and create tables
php artisan referenceable:install

# Force reinstallation
php artisan referenceable:install --force

Reference Management

# Generate references for records without them
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 existing references
php artisan referenceable:validate "App\Models\Order"
php artisan referenceable:validate "App\Models\Order" --fix

# Regenerate references (use with caution!)
php artisan referenceable:regenerate "App\Models\Order" --id=123
php artisan referenceable:regenerate "App\Models\Order" --all --dry-run

# Show reference statistics
php artisan referenceable:stats "App\Models\Order"
php artisan referenceable:stats "App\Models\Order" --json

Package Information

# Show available commands
php artisan referenceable
php artisan referenceable --list

📊 Multi-Tenancy Support

For multi-tenant applications:

class Order extends Model
{
    use HasReference;
    
    protected $referenceUniquenessScope = 'tenant';
    protected $referenceTenantColumn = 'company_id';
    
    // References will be unique per company
}

⚡ Performance Optimization

Database Indexes

Schema::table('orders', function (Blueprint $table) {
    $table->index('reference');
    $table->index(['company_id', 'reference']); // For multi-tenant
});

Configuration Caching

// In config/referenceable.php
'performance' => [
    'cache_config' => true,  // Cache model configurations
    'cache_ttl' => 60,       // Cache for 60 minutes
    'use_transactions' => true, // Use DB transactions
    'batch_size' => 100,     // Batch size for bulk operations
],

🏗 Migration Guide

From v1.x to v2.x

1. Run the installation command:

php artisan referenceable:install

1. Update your models to use new configuration format:

// Old format
protected $referenceLength = 8;

// New format (still supported for backward compatibility)
protected $referenceLength = 8;

// Or use new configuration array
protected $referenceTemplate = [
    'format' => '{PREFIX}{RANDOM}',
    'random_length' => 8,
];

1. Test your references:

php artisan referenceable:validate "App\Models\Order"

🧪 Testing

composer test

📈 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

🏆 Credits

• Mohamed Said
• All Contributors

📄 License

The MIT License (MIT). Please see License File for more information.