Async Event Dispatcher Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require enqueue/async-event-dispatcher
   

   Requires php-enqueue/amqp-ext or php-enqueue/amqp-bunny for AMQP support.

2. Basic Configuration Add to your Laravel config/services.php:

   'async_event_dispatcher' => [
       'dsn' => env('ASYNC_DISPATCHER_DSN', 'amqp://guest:guest@localhost:5672/%2f'),
       'queue' => env('ASYNC_DISPATCHER_QUEUE', 'async_events'),
       'connection' => env('ASYNC_DISPATCHER_CONNECTION', 'default'),
   ],
   

3. First Use Case Replace Laravel’s default dispatcher in AppServiceProvider:

   use Enqueue\AsyncEventDispatcher\AsyncEventDispatcher;
   use Symfony\Component\EventDispatcher\EventDispatcher;
   
   public function register()
   {
       $dispatcher = new AsyncEventDispatcher(
           new EventDispatcher(),
           $this->app['enqueue.client']
       );
       $this->app->singleton('event', fn() => $dispatcher);
   }
   

4. Verify Dispatch an event and check the AMQP queue for messages:

   php artisan tinker
   >>> event(new \App\Events\TestEvent);
   

Implementation Patterns

Workflow: Async Event Dispatching

1. Event Listeners Register listeners as usual, but they’ll execute asynchronously:

   Event::listen(MyEvent::class, function ($event) {
       // Runs in background
   });
   

2. Priority Queues Use custom queues for critical events:

   $dispatcher->dispatch(new UrgentEvent(), 'urgent_queue');
   

3. Error Handling Wrap dispatch calls in try-catch:

   try {
       event(new PaymentProcessed($user));
   } catch (\Enqueue\Client\Exception\ConnectionException $e) {
       Log::error('Async dispatch failed', ['exception' => $e]);
       // Fallback to sync dispatch
   }
   

Integration Tips

• Laravel Queues Combine with Laravel’s queue system for hybrid workflows:

  $dispatcher->dispatch(new JobSubmitted($job), 'jobs');
  

• Middleware Apply middleware to async events via AsyncEventDispatcher constructor:

  $dispatcher = new AsyncEventDispatcher(
      $dispatcher,
      $client,
      [$middleware1, $middleware2]
  );
  

• Testing Mock the AMQP client for unit tests:

  $mockClient = Mockery::mock(ClientInterface::class);
  $dispatcher = new AsyncEventDispatcher($dispatcher, $mockClient);
  

Gotchas and Tips

Pitfalls

1. Connection Issues

   • Symptom: Events silently fail to dispatch.
   • Fix: Ensure the AMQP broker is running and credentials are correct. Use ConnectionException handling.

2. Duplicate Events

   • Cause: Consumer crashes mid-processing.
   • Fix: Implement idempotent listeners or use Event::unique() (if supported).

3. Ordering Guarantees

   • Warning: Async dispatch does not preserve event order. Use a task queue (e.g., Laravel Jobs) for ordered operations.

4. Memory Leaks

   • Cause: Unclosed AMQP channels/connections.
   • Fix: Ensure the ClientInterface is properly closed (e.g., in Laravel’s terminate()).

Debugging

• Check Queue Use php-amqpcli or RabbitMQ Management UI to inspect the queue:

  php-amqpcli get queue async_events
  

• Log Dispatches Enable debug logging in config/logging.php for enqueue channel.

Extension Points

1. Custom Serializer Override the default EventSerializer for complex event payloads:

   $dispatcher = new AsyncEventDispatcher(
       $dispatcher,
       $client,
       null,
       new CustomEventSerializer()
   );
   

2. Dynamic Queue Routing Implement QueueNameResolverInterface to route events dynamically:

   $dispatcher->dispatch($event, $resolver->resolve($event));
   

3. Consumer Integration Extend the AsyncEventDispatcher to integrate with Laravel’s queue workers:

   // In a custom worker class
   $dispatcher->consume($queue, fn($event) => $this->handle($event));