Sequence Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aboutcoders/sequence-bundle:dev-master
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Abc\Bundle\SequenceBundle\AbcSequenceBundle::class => ['all' => true],
   ];
   

2. Configure in config/packages/abc_sequence.yaml:

   abc_sequence:
       db_driver: orm  # or 'doctrine' (alias for ORM)
   

3. First Use Case: Generate a sequence via the manager:

   $sequenceManager = $this->get('abc.sequence.sequence_manager');
   $nextId = $sequenceManager->getNextId('your_sequence_name');
   

Implementation Patterns

Core Workflows

1. Sequence Generation:

   • Use SequenceManager to fetch next IDs:

     $nextId = $sequenceManager->getNextId('user_id_seq');
     

   • Supports predefined sequences (configured in DB) or dynamic sequences (created on-the-fly).

2. Integration with Doctrine:

   • For ORM-backed sequences, define a sequence table (e.g., sequences) with columns:

     // Example migration
     Schema::create('sequences', function (Blueprint $table) {
         $table->string('name')->primary();
         $table->bigInteger('next_id')->default(1);
     });
     

   • Use SequenceManager to auto-increment IDs in entities:

     $user->id = $sequenceManager->getNextId('user_id_seq');
     

3. Custom Sequence Logic:

   • Extend SequenceManager or create a custom sequence provider:

     class CustomSequenceProvider implements SequenceProviderInterface {
         public function getNextId(string $sequenceName): int {
             // Custom logic (e.g., UUID, timestamp-based)
             return time();
         }
     }
     

   • Register the provider in services:

     services:
         App\Service\CustomSequenceProvider:
             tags: ['abc_sequence.sequence_provider']
     

4. Batch Processing:

   • Reserve multiple IDs at once (useful for bulk inserts):

     $batchIds = $sequenceManager->getNextIds('user_id_seq', 10);
     

Gotchas and Tips

Pitfalls

1. Database Locking:

   • ORM driver uses SELECT ... FOR UPDATE to prevent race conditions. In high-concurrency apps, this may cause bottlenecks. Consider:
     • Using a distributed lock (e.g., Redis) for critical sequences.
     • Switching to a non-transactional driver (if applicable) for read-heavy workloads.

2. Sequence Naming Collisions:

   • Ensure sequence names are globally unique (e.g., module_entity_seq). Avoid generic names like id_seq.

3. Initialization Issues:

   • If next_id is not set in the sequences table, the bundle defaults to 1. Explicitly initialize sequences:

     $sequenceManager->initializeSequence('user_id_seq', 1000);
     

Debugging

1. Missing Sequences:

   • Check if the sequences table exists and has the correct schema. Run:

     php bin/console doctrine:schema:validate
     

2. Provider Not Found:

   • Verify the db_driver in config matches your setup (orm/doctrine). For custom providers, ensure they’re tagged correctly.

3. Performance:

   • Monitor slow queries on the sequences table. Add indexes if needed:

     Schema::table('sequences', function (Blueprint $table) {
         $table->index('name');
     });
     

Extension Points

1. Event Listeners:

   • Hook into sequence generation via events (e.g., log sequence usage):

     // config/services.yaml
     App\EventListener\SequenceListener:
         tags:
             - { name: kernel.event_listener, event: abc.sequence.pre_generate, method: onPreGenerate }
     

2. Sequence Validation:

   • Override SequenceManager to validate sequence names or IDs:

     public function getNextId(string $sequenceName): int {
         if (!preg_match('/^[a-z_]+_[a-z_]+_seq$/', $sequenceName)) {
             throw new \InvalidArgumentException('Invalid sequence name format.');
         }
         return parent::getNextId($sequenceName);
     }
     

3. Multi-Database Support:

   • For multi-DB setups, bind the SequenceManager to a specific connection:

     services:
         abc.sequence.sequence_manager:
             arguments:
                 $connection: '@doctrine.dbal.default_connection'