Bdf Queue Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require b2pweb/bdf-queue
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       B2PWeb\BDFQueue\BDFQueueServiceProvider::class,
   ],
   

2. Configuration: Publish the config file:

   php artisan vendor:publish --provider="B2PWeb\BDFQueue\BDFQueueServiceProvider"
   

   Edit config/bdf-queue.php to define your broker (e.g., Redis, RabbitMQ, SQS).

3. First Use Case: Dispatch a job:

   use B2PWeb\BDFQueue\Queue;
   
   Queue::dispatch(new \App\Jobs\ProcessOrder);
   

4. Key Files:

   • config/bdf-queue.php: Broker settings.
   • app/Jobs/: Your job classes (must implement B2PWeb\BDFQueue\Contracts\Job).

Implementation Patterns

Core Workflows

1. Job Dispatching:

   // Dispatch with payload
   Queue::dispatch(new ProcessOrder, ['order_id' => 123]);
   
   // Dispatch with delay (seconds)
   Queue::later(60, new ProcessOrder);
   

2. Job Handling: Extend B2PWeb\BDFQueue\Contracts\Job:

   namespace App\Jobs;
   
   use B2PWeb\BDFQueue\Contracts\Job;
   
   class ProcessOrder implements Job {
       public function handle() {
           // Job logic here
       }
   }
   

3. Broker-Specific Config: Define adapters in config/bdf-queue.php:

   'connections' => [
       'redis' => [
           'driver' => 'redis',
           'host' => '127.0.0.1',
           'queue' => 'default',
       ],
       'sqs' => [
           'driver' => 'aws',
           'key' => env('AWS_KEY'),
           'secret' => env('AWS_SECRET'),
           'queue' => 'my-queue',
       ],
   ],
   

4. Middleware Integration: Register middleware in config/bdf-queue.php:

   'middleware' => [
       \App\Middleware\LogJob::class,
   ],
   

5. Batch Processing:

   Queue::batch([
       new ProcessOrder(1),
       new ProcessOrder(2),
   ])->dispatch();
   

Integration Tips

• Laravel Compatibility: Works alongside Laravel’s native queue system. Use Queue::dispatch() for consistency.
• Job Serialization: Ensure job payloads are serializable (use Serializable or Arrayable).
• Error Handling: Implement B2PWeb\BDFQueue\Contracts\Job::failed() for retries.

Gotchas and Tips

Pitfalls

1. Broker-Specific Quirks:

   • Redis: Ensure the queue name matches the Redis key pattern (default: queue:*).
   • AWS SQS: Validate IAM permissions for sqs:SendMessage and sqs:ReceiveMessage.
   • Database: Avoid large payloads; use external storage (e.g., S3) for attachments.

2. Job Deserialization:

   • Custom job classes must have a no-arg constructor for proper hydration.
   • Avoid circular references in job payloads (use json_encode/json_decode for complex data).

3. Connection Failures:

   • The package lacks built-in retry logic for broker failures. Implement a fallback (e.g., database queue) in config/bdf-queue.php:

     'fallback' => 'database',
     

4. Middleware Order:

   • Middleware runs in the order defined in config/bdf-queue.php. Place RetryMiddleware early if needed.

Debugging

• Logs: Enable Laravel’s queue logging ('logging' => true in config/queue.php).
• Job Events: Listen for job.processing and job.failed events:

  event(new JobProcessing($job));
  

• Broker-Specific Tools:
  • Redis: redis-cli monitor.
  • SQS: AWS Console → Queues → "View/Change Message Visibility".

Extension Points

1. Custom Drivers: Implement B2PWeb\BDFQueue\Contracts\Driver for unsupported brokers (e.g., Kafka):

   class KafkaDriver implements Driver {
       public function push($job, $data) { ... }
       public function pop() { ... }
   }
   

2. Job Metadata: Attach metadata via Queue::dispatch($job, [], ['priority' => 5]).

3. Testing: Use Queue::fake() for unit tests:

   Queue::fake();
   Queue::dispatch(new ProcessOrder);
   Queue::assertPushed(ProcessOrder::class);
   

4. Performance:

   • Batch small jobs to reduce broker overhead.
   • Use Queue::dispatchSync() for critical, synchronous tasks (bypasses the queue).