Dispatcher Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acassan/dispatcher-bundle
   

   Add to config/app.php under providers:

   Acassan\DispatcherBundle\DispatcherServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Acassan\DispatcherBundle\DispatcherServiceProvider"
   

   This generates a config file at config/dispatcher.php with default settings.

3. First Use Case: Dispatching a Job Define a job class (e.g., app/Jobs/ProcessOrder.php):

   namespace App\Jobs;
   
   use Acassan\DispatcherBundle\Contracts\JobInterface;
   
   class ProcessOrder implements JobInterface
   {
       public function handle()
       {
           // Business logic here
       }
   }
   

   Dispatch it via the facade:

   use Acassan\DispatcherBundle\Facades\Dispatcher;
   
   Dispatcher::dispatch(new ProcessOrder());
   

Implementation Patterns

Core Workflows

1. Job Registration Register jobs in config/dispatcher.php under jobs:

   'jobs' => [
       'process_order' => [
           'class' => App\Jobs\ProcessOrder::class,
           'queue' => 'default',
           'delay' => 0,
       ],
   ],
   

   Dispatch via config key:

   Dispatcher::dispatch('process_order');
   

2. Queue Integration Configure queues in config/dispatcher.php:

   'queues' => [
       'default' => 'database',
       'high_priority' => 'redis',
   ],
   

   Use named queues when dispatching:

   Dispatcher::dispatch(new ProcessOrder())->onQueue('high_priority');
   

3. Middleware for Jobs Attach middleware to jobs in config:

   'jobs' => [
       'process_order' => [
           'class' => App\Jobs\ProcessOrder::class,
           'middleware' => [
               \App\Jobs\Middleware\LogJob::class,
           ],
       ],
   ],
   

   Create middleware implementing JobMiddlewareInterface:

   class LogJob implements JobMiddlewareInterface
   {
       public function handle($job, $next)
       {
           \Log::info("Job started: " . get_class($job));
           return $next($job);
       }
   }
   

4. Event-Driven Dispatching Listen for events and dispatch jobs:

   use Acassan\DispatcherBundle\Events\JobDispatched;
   
   Event::listen(JobDispatched::class, function ($event) {
       // Post-dispatch logic
   });
   

Gotchas and Tips

Pitfalls

1. Job Class Autoloading Ensure job classes are autoloaded. If using dispatch() with a string key, verify the class exists in config/dispatcher.php.

2. Queue Driver Mismatch The bundle assumes Laravel’s queue system is configured. If using a custom queue driver, ensure it’s registered in config/queue.php.

3. Middleware Order Middleware runs in the order defined in config/dispatcher.php. Reverse the array to change execution order.

4. Job Serialization Jobs must be serializable. Avoid closures or non-serializable properties. Use static methods or ensure properties are serializable.

Debugging Tips

1. Check Dispatch Logs Enable Laravel’s queue logging in config/queue.php:

   'log' => env('QUEUE_LOG', true),
   

2. Verify Job Payload Dump the job payload before dispatching:

   $job = new ProcessOrder();
   \Log::debug("Job payload:", $job->serialize());
   

3. Middleware Debugging Add debug logs in middleware:

   public function handle($job, $next)
   {
       \Log::debug("Middleware: " . get_class($this));
       return $next($job);
   }
   

Extension Points

1. Custom Job Resolvers Extend job resolution by implementing JobResolverInterface and binding it:

   $this->app->bind(
       \Acassan\DispatcherBundle\Contracts\JobResolverInterface::class,
       \App\Jobs\CustomJobResolver::class
   );
   

2. Dynamic Queue Configuration Override queue names dynamically:

   Dispatcher::dispatch(new ProcessOrder())
       ->onQueue(fn () => config('app.env') === 'production' ? 'high_priority' : 'default');
   

3. Event Customization Extend or override events (e.g., JobDispatched) for custom logic:

   class CustomJobDispatched extends JobDispatched
   {
       // Add custom properties/methods
   }