Id Generator Laravel Package

Getting Started

Install via Composer:

composer require alimarchal/id-generator

First Use Case: Generate a unique ID for an e-commerce order with prefix:

use Alimarchal\IdGenerator\Facades\IdGenerator;

$orderId = IdGenerator::generate('ORD', 'orders', 'order_no');
// Output: ORD-20250814-0001

Where to Look First:

• README.md for installation and basic usage
• API Documentation for method signatures
• Real-world Examples for e-commerce and ticketing systems

Implementation Patterns

Core Workflows

1. Basic ID Generation:

// Simple ID (e.g., invoice)
$invoiceId = IdGenerator::generate('invoice', 'invoices', 'invoice_no');

// Prefixed ID (e.g., order)
$orderId = IdGenerator::generateWithPrefix('ORD', 'orders', 'order_no');

2. Service Provider Integration:

// Register in config/app.php
'providers' => [
    Alimarchal\IdGenerator\IdGeneratorServiceProvider::class,
],

// Use facade in controllers
use Alimarchal\IdGenerator\Facades\IdGenerator;

3. High-Volume Scenarios:

// Thread-safe for concurrent requests
for ($i = 0; $i < 1000; $i++) {
    $id = IdGenerator::generate('invoice', 'invoices', 'invoice_no');
    // Guaranteed uniqueness
}

4. Custom Logic Extension:

// Extend via service provider bindings
$this->app->bind('custom.id', function ($app) {
    return new CustomIdGenerator($app['id-generator']);
});

Integration Tips

• Database: Ensure order_no, invoice_no columns are indexed for performance.
• Caching: Cache generated IDs if regeneration is expensive (e.g., for API responses).
• Validation: Use Laravel’s Rule::unique() with the generated ID in models:

  $request->validate([
      'order_no' => 'required|unique:orders,order_no',
  ]);
  

Gotchas and Tips

Pitfalls

1. Race Conditions (Mitigated):

   • Package now includes database transaction safety and proper locking (tested with 1000 concurrent requests).
   • Tip: Avoid manual DB::transaction() wrappers—let the package handle it.

2. Prefix Collisions:

   • Ensure prefixes (e.g., ORD, TKT) are globally unique across your application.
   • Fix: Use a naming convention like {ENTITY_TYPE}-{SYSTEM} (e.g., ORD-ECOM, TKT-SUPPORT).

3. PHP 8.2+ Requirement:

   • If using older PHP, pin to v1.0.0 via composer require alimarchal/id-generator:^1.0.0.

4. SQLite Testing Quirks:

   • Tests use SQLite in-memory, but production must use MySQL/PostgreSQL for proper locking behavior.

Debugging

• Fallback IDs: If generation fails, the package defaults to a timestamp-based fallback (e.g., ORD-20250814-123456).
• Logging: Enable debug mode in config/id-generator.php to log generation attempts:

  'debug' => env('ID_GENERATOR_DEBUG', false),
  

Extension Points

1. Custom ID Formats: Override the default YYYYMMDD-SEQUENCE format via config:

   'format' => 'SEQ-{YEAR}', // Output: SEQ-2025
   

2. Event Listeners: Publish and extend the package’s events:

   php artisan vendor:publish --provider="Alimarchal\IdGenerator\IdGeneratorServiceProvider" --tag="events"
   

3. Testing: Use the provided Pest test suite as a template for your own tests:

   use Alimarchal\IdGenerator\Tests\TestCase;
   
   test('generates unique IDs', function () {
       $id = IdGenerator::generate('test', 'tests', 'test_no');
       $this->assertMatchesRegularExpression('/^TEST-\d{8}-\d{4}$/', $id);
   });
   

Performance

• Bulk Generation: For batch inserts, generate IDs client-side (not in a loop) to avoid N+1 queries.
• Indexing: Add a composite index on (prefix, date, sequence) for large tables:

  CREATE INDEX idx_unique_ids ON orders(prefix, order_no);