Symfony Messenger Application Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require cptburke/symfony-messenger-application
   

2. Define a basic application class (e.g., app/MessagingApplication.php):

   use CptBurke\MessengerApplication\Application;
   use Symfony\Component\Messenger\MessageBusInterface;
   
   class MessagingApplication extends Application
   {
       protected function configureBus(): MessageBusInterface
       {
           return $this->busFactory->createBus([
               // Configure transports, handlers, etc.
           ]);
       }
   }
   

3. Bootstrap and run (e.g., in console/messaging.php):

   require __DIR__.'/../vendor/autoload.php';
   
   $app = new MessagingApplication();
   $app->run();
   

First Use Case: CLI Dispatch

// Dispatch a message via CLI
$app = new MessagingApplication();
$app->getBus()->dispatch(new YourMessageClass());

Implementation Patterns

Worker/Worker Pool Integration

1. Define a worker entrypoint (e.g., console/worker.php):

   $app = new MessagingApplication();
   $app->runWorkers([
       'transport' => 'async', // e.g., 'doctrine', 'amqp', etc.
       'workers' => 4,
   ]);
   

2. Customize worker behavior via configureWorkers():

   protected function configureWorkers(): array
   {
       return [
           'transport' => 'async',
           'workers' => env('MESSENGER_WORKERS', 4),
           'options' => [
               'time_limit' => 300,
           ],
       ];
   }
   

Dependency Injection (DI) Integration

1. Extend for DI containers (e.g., Laravel, Symfony):

   class LaravelMessagingApplication extends MessagingApplication
   {
       public function __construct(private Container $container)
       {
           parent::__construct();
       }
   
       protected function getBusFactory(): BusFactoryInterface
       {
           return $this->container->get(BusFactoryInterface::class);
       }
   }
   

Message Dispatching in Controllers/Commands

1. Inject the bus (e.g., in a Laravel controller):

   public function __construct(private MessageBusInterface $bus)
   {
       // Resolve via Laravel's DI or manually via $app->getBus()
   }
   
   public function handle()
   {
       $this->bus->dispatch(new YourMessage());
   }
   

Transport Configuration

1. Define transports in configureBus():

   protected function configureBus(): MessageBusInterface
   {
       return $this->busFactory->createBus([
           'transports' => [
               'async' => [
                   'dsn' => env('MESSENGER_TRANSPORT_DSN'),
                   'options' => ['queue_name' => 'your_queue'],
               ],
           ],
           'handlers' => [
               YourMessage::class => [YourHandler::class],
           ],
       ]);
   }
   

Gotchas and Tips

Pitfalls

1. Bus Configuration Overrides:

   • Ensure configureBus() returns a fully configured bus. Partial configs may throw InvalidArgumentException.
   • Example of a common mistake:

     // ❌ Missing 'transports' key
     return $this->busFactory->createBus(['handlers' => [...]]);
     

2. Worker Lifecycle:

   • Workers do not auto-reload config changes. Restart workers after modifying configureWorkers().
   • Use SIGTERM/SIGINT to gracefully shut down workers (handled by the package).

3. Transport DSN Validation:

   • Always validate DSNs (e.g., amqp://, doctrine://) in .env or config. Invalid DSNs may silently fail.

Debugging Tips

1. Enable Messenger Debugging:

   $bus = $this->busFactory->createBus([
       'debug' => true, // Logs dispatched messages
   ]);
   

2. Check Worker Logs:
   • Workers log to stderr by default. Redirect to a file for debugging:

     php console/worker.php > worker.log 2>&1 &
     

Extension Points

1. Custom Bus Factories:

   • Override getBusFactory() to use a custom factory (e.g., for testing):

     protected function getBusFactory(): BusFactoryInterface
     {
         return new CustomBusFactory();
     }
     

2. Middleware Integration:

   • Add middleware to the bus in configureBus():

     'middleware' => [
         new YourMiddleware(),
     ],
     

3. Event Listeners:

   • Attach listeners to the application lifecycle:

     $app->on('before.run', function () {
         // Pre-run logic
     });
     

Laravel-Specific Quirks

1. Service Provider Integration:
   • Bind the application in a service provider:

     $this->app->singleton(MessagingApplication::class, function ($app) {
         return new MessagingApplication($app);
     });
     

2. Artisan Command Integration:
   • Create a command to dispatch messages:

     use Illuminate\Console\Command;
     use Symfony\Component\Messenger\MessageBusInterface;
     
     class DispatchMessageCommand extends Command
     {
         public function __construct(private MessageBusInterface $bus)
         {
             parent::__construct();
         }
     
         public function handle()
         {
             $this->bus->dispatch(new YourMessage());
         }
     }