PHP code example of eg-mohamed / referenceable

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

eg-mohamed / referenceable example snippets

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

use MohamedSaid\Referenceable\Traits\HasReference;

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

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

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

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

// Generates: ORD-AB12CD

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

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

// Generates: ORD20240001, ORD20240002...

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

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,
    ],
];

// 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;
}

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

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

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

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

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

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

// 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
],

// 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,
];

bash
php artisan referenceable:install

bash
# Install package and create tables
php artisan referenceable:install

# Force reinstallation
php artisan referenceable:install --force

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

bash
php artisan referenceable:install

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