Asynchronous Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dlakomski/asynchronous-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       SimpleBus\AsynchronousBundle\SimpleBusAsynchronousBundle::class => ['all' => true],
   ];
   

2. Configuration: Edit config/packages/simple_bus_asynchronous.yaml to define:

   • queue (e.g., doctrine, symfony, or custom)
   • middleware (e.g., SimpleBus\Asynchronous\Middleware\RetryMiddleware)
   • handlers (map message types to handler classes).

3. First Use Case: Create a message class (e.g., app/Message/ProcessOrder.php):

   namespace App\Message;
   class ProcessOrder {}
   

   Register it in config/packages/simple_bus_asynchronous.yaml:

   handlers:
       App\Message\ProcessOrder: App\Handler\ProcessOrderHandler
   

   Dispatch it in a controller:

   use SimpleBus\Message\Bus\Bus;
   public function handle(Bus $bus) {
       $bus->handle(new ProcessOrder());
   }
   

Implementation Patterns

Core Workflows

1. Synchronous-to-Asynchronous Transition: Use Bus interface for synchronous calls, but configure AsynchronousBundle to offload specific messages to queues. Example: Mark a handler as async by injecting AsynchronousBus:

   public function __construct(private AsynchronousBus $bus) {}
   

2. Queue Integration:

   • Doctrine Queue: Requires doctrine/doctrine-queue-bundle. Configure in config/packages/simple_bus_asynchronous.yaml:

     queue: doctrine
     

   • Symfony Messenger: Use symfony/messenger as the transport:

     queue: symfony
     

3. Middleware Stack: Extend the default middleware (e.g., add logging):

   middleware:
       - SimpleBus\Asynchronous\Middleware\RetryMiddleware
       - App\Middleware\LogAsyncMessageMiddleware
   

4. Handler Design:

   • Stateless Handlers: Prefer pure functions (no dependencies) for async messages.
   • Stateful Handlers: Use dependency injection for services (e.g., repositories). Example:

     public function __construct(private OrderRepository $orders) {}
     

5. Testing:

   • Mock AsynchronousBus in unit tests:

     $bus = $this->createMock(AsynchronousBus::class);
     $bus->expects($this->once())->method('handle');
     

   • Test queue consumers separately (e.g., with doctrine/queue-bundle's test utilities).

Gotchas and Tips

Pitfalls

1. Queue Configuration Mismatch:

   • Ensure the configured queue driver (doctrine, symfony, etc.) is installed and properly set up.
   • Debug: Check simple_bus_asynchronous.queue in Symfony’s container dump.

2. Handler Registration:

   • Case Sensitivity: Handler class names in config must match exactly (including namespace).
   • Circular Dependencies: Async handlers cannot depend on other async handlers (risk of deadlock).

3. Middleware Order:

   • Middleware runs in the order defined in config. Place RetryMiddleware early to avoid wasted retries.

4. Transaction Boundaries:

   • Async messages do not participate in the current transaction. Use EventDispatcher for transactional events instead.

5. Debugging:

   • Queue Backlog: Monitor queue size with:

     php bin/console doctrine:queue:list
     

   • Failed Messages: Check failed_jobs table (Doctrine) or Symfony Messenger’s failure transport.

Tips

1. Performance:

   • Batch async dispatches (e.g., after bulk operations) to reduce queue overhead.
   • Use AsynchronousBus::handle() for one-off messages; prefer Bus for synchronous workflows.

2. Extensibility:

   • Custom Queues: Implement SimpleBus\Asynchronous\Queue\Queue for non-Doctrine/Symfony transports.
   • Dynamic Handlers: Use SimpleBus\Asynchronous\HandlerResolver\HandlerResolver to resolve handlers dynamically.

3. Configuration:

   • Environment-Specific: Override config/packages/simple_bus_asynchronous.yaml per environment (e.g., disable async in tests).
   • Default Middleware: Start with:

     middleware:
         - SimpleBus\Asynchronous\Middleware\RetryMiddleware
         - SimpleBus\Asynchronous\Middleware\LogMiddleware
     

4. Error Handling:

   • Implement SimpleBus\Asynchronous\Middleware\HandleFailedMessageMiddleware to customize failure behavior.
   • Example:

     public function handle(FailedMessage $failedMessage) {
         // Log or notify (e.g., Slack)
     }
     

5. Laravel-Specific:

   • Service Provider: If using Laravel, bind the bundle in AppServiceProvider:

     $this->app->register(SimpleBusAsynchronousBundle::class);
     

   • Queue Workers: Run workers with:

     php bin/console doctrine:queue:consume --time-limit=3600