Command Launcher Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require digitalnoise/command-launcher-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       DigitalNoise\CommandLauncherBundle\CommandLauncherBundle::class => ['all' => true],
   ];
   

2. First Use Case: Define a CLI command to trigger a message directly:

   php bin/console command-launcher:dispatch ActivateUserMessage --user-id=123
   

   Ensure your message class (ActivateUserMessage) is autoloaded and has a constructor matching the CLI arguments.

3. Configuration: Check config/packages/digitalnoise_command_launcher.yaml for default settings (e.g., bus configuration, argument mapping).

Implementation Patterns

Workflows

1. CLI-Driven Message Dispatch: Use the bundle to replace manual CLI commands for complex workflows (e.g., cron jobs, admin tasks). Example:

   php bin/console command-launcher:dispatch ProcessPaymentMessage --order-id=456 --amount=99.99
   

2. Integration with Symfony Messenger: Leverage the bundle’s MessageBus integration to dispatch messages via CLI without writing custom commands.

   # config/packages/digitalnoise_command_launcher.yaml
   digitalnoise_command_launcher:
       bus: messenger.bus.default  # Use Symfony's default bus
   

3. Dynamic Argument Handling: Map CLI arguments to message properties using annotations or YAML:

   # config/packages/digitalnoise_command_launcher.yaml
   commands:
       ProcessPaymentMessage:
           arguments:
               orderId: order-id
               amount: amount
   

4. Event-Driven Extensions: Extend the bundle by creating custom dispatchers for non-Messenger buses (e.g., custom queues):

   // src/Command/Dispatcher/CustomBusDispatcher.php
   class CustomBusDispatcher implements DispatcherInterface {
       public function dispatch(MessageInterface $message, array $arguments): void {
           // Custom logic (e.g., RabbitMQ)
       }
   }
   

Gotchas and Tips

Pitfalls

1. Message Class Autoloading: Ensure message classes are PSR-4 autoloaded. Use composer dump-autoload if missing.

2. Argument Mismatches: CLI arguments must match message constructor parameters exactly (type and name). Use --help to debug:

   php bin/console command-launcher:dispatch ActivateUserMessage --help
   

3. Bus Configuration: The bundle defaults to Symfony Messenger. For custom buses, override the dispatcher service:

   services:
       DigitalNoise\CommandLauncherBundle\CommandLauncherBundle:
           arguments:
               $dispatcher: '@custom_bus.dispatcher'
   

4. Environment-Specific Commands: Restrict commands to specific environments (e.g., dev) via when in config/packages/*_command_launcher.yaml.

Debugging

• Dry Runs: Use --dry-run to validate arguments without dispatching:

  php bin/console command-launcher:dispatch ProcessPaymentMessage --order-id=456 --dry-run
  

• Logs: Enable debug mode (APP_DEBUG=1) for detailed argument parsing logs.

Extension Points

1. Custom Argument Parsers: Override DigitalNoise\CommandLauncherBundle\ArgumentParser\ArgumentParserInterface to support complex types (e.g., dates, enums).

2. Pre-Dispatch Hooks: Use Symfony’s event system to validate messages before dispatch:

   // src/EventListener/PreDispatchListener.php
   class PreDispatchListener implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [
               KernelEvents::CONTROLLER => 'onKernelController',
           ];
       }
       public function onKernelController(ControllerEvent $event): void {
           // Validate message here
       }
   }
   

3. Async Dispatch: Combine with Symfony Messenger’s async transport for background processing:

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               async: '%env(MESSENGER_TRANSPORT_DSN)%'