Service Bus Symfony Bundle Laravel Package

Getting Started

1. Install the package and publish its config:

   composer require prooph/laravel
   php artisan vendor:publish --provider="Prooph\Laravel\ProophServiceProvider"
   

   If your app does not use package discovery, register Prooph\Laravel\ProophServiceProvider manually.

2. Look first at:

   • the published config/prooph.php (or equivalent package config),
   • the service provider bindings for command/query/event buses,
   • the message_detection section,
   • the router configuration for each bus.

3. First use case: define a command, handler, and route.

   use Prooph\Common\Messaging\HasMessageName;
   
   final class RegisterUser implements HasMessageName
   {
       public function __construct(public string $email) {}
   
       public function messageName(): string
       {
           return self::class;
       }
   }
   
   final class RegisterUserHandler
   {
       public function __invoke(RegisterUser $command): void
       {
           // handle command
       }
   }
   

   Map the command to the handler in the command bus router config, then inject and dispatch Prooph\ServiceBus\CommandBus from a controller/job.

Implementation Patterns

• Inject buses, do not resolve them manually. Use constructor injection for CommandBus, QueryBus, and EventBus so Laravel’s container and package bindings stay consistent.
• Keep message classes explicit. Implement Prooph\Common\Messaging\HasMessageName on commands, queries, and events. In v0.7.0 this is the only requirement for message detection, so you can drop unnecessary marker interfaces.
• Use static factories for messages with private constructors. Detection now supports private constructors, so value-object-style messages are viable:

  final class ChangeEmail implements HasMessageName
  {
      private function __construct(public string $email) {}
  
      public static function fromString(string $email): self
      {
          return new self($email);
      }
  
      public function messageName(): string
      {
          return self::class;
      }
  }
  

• Register handlers as container-resolved classes. Handlers can receive dependencies through their constructor; the package resolves them from Laravel’s container when a message is dispatched.
• Use private handlers sparingly. v0.7.0 allows private message handlers, which is useful for internal wiring, but public __invoke handlers remain easier to debug, test, and reason about.
• Configure async routing explicitly. If using async_switch, verify the router config after upgrading. A typical pattern is to route selected messages through an async switch while keeping the rest synchronous:

  'router' => [
      'type' => \Prooph\ServiceBus\Plugin\Router\AsyncSwitchMessageRouter::class,
      'async_switch' => \App\Messaging\AsyncSwitch::class,
      'routes' => [
          \App\Commands\RegisterUser::class => \App\Handlers\RegisterUserHandler::class,
      ],
  ],
  

• Write integration tests around dispatch. Assert that a command/query reaches the expected handler and that events are published. For async routes, assert the message is handed to the async transport rather than executed inline.

Gotchas and Tips

• Message detection is broader now. Because HasMessageName is the only requirement, classes that implement it may be auto-detected where you previously relied on another marker. After upgrading, check for unexpected routes or duplicate handler registrations and use explicit include/exclude config if needed.
• Private constructors are supported for detection, not for construction. You still need static factories or named constructors in your own code. Do not assume the bus can instantiate messages directly.
• async_switch config mistakes often fail quietly. If the router key or switch class is wrong, messages may fall back to synchronous handling. Test one message that must be async and confirm it is not handled inline.
• Clear config cache after changes. Router and message-detection changes are config-driven; run php artisan config:clear when debugging stale behavior.
• Prefer public handlers unless you need privacy. Private handlers are now allowed, but they can make container resolution, logging, and stack traces harder to follow.
• Keep messageName() stable. Changing the returned name can break routing, async queues, and event subscriptions. Prefer the FQCN unless you deliberately version message names.
• Use explicit mappings for ambiguous messages. Auto-detection is convenient, but explicit command/query/event routes are easier to audit in larger Laravel applications.