Simple Bus Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require bengor-user/simple-bus-bridge
   

   Ensure your composer.json includes matthiasnoback/simple-bus as a dependency.

2. Register the Bridge In your Laravel service provider (e.g., AppServiceProvider.php), bind the bridge to SimpleBus:

   use BenGorUser\SimpleBusBridge\Bridge\SimpleBusBridge;
   use MatthiasNoback\SimpleBus\MessageBus;
   
   public function register()
   {
       $this->app->bind(MessageBus::class, function ($app) {
           return new SimpleBusBridge($app->make('bus')); // Laravel's default queue bus
       });
   }
   

3. First Use Case: Dispatching Commands Define a command class (e.g., CreateUserCommand) and dispatch it:

   use BenGorUser\User\Command\CreateUserCommand;
   
   $command = new CreateUserCommand('john@example.com', 'password123');
   $this->app->make(MessageBus::class)->dispatch($command);
   

Implementation Patterns

Workflow: Command/Event Handling

1. Define Commands/Events Extend BenGorUser\User\Command\Command or BenGorUser\User\Event\Event for domain-specific logic. Example:

   namespace App\Commands;
   
   use BenGorUser\User\Command\Command;
   
   class UpdateUserProfileCommand extends Command
   {
       public function __construct(public string $userId, public array $data) {}
   }
   

2. Register Handlers Bind handlers to commands/events in a service provider:

   $this->app->bind(
       \MatthiasNoback\SimpleBus\MessageHandler::class,
       function ($app) {
           return new UpdateUserProfileHandler($app->make(UserRepository::class));
       }
   );
   $this->app->bind(
       \MatthiasNoback\SimpleBus\MessageBus::class,
       function ($app) {
           $bridge = new SimpleBusBridge($app->make('bus'));
           $bridge->addHandler(UpdateUserProfileCommand::class, $app->make(\MatthiasNoback\SimpleBus\MessageHandler::class));
           return $bridge;
       }
   );
   

3. Leverage Middleware Use SimpleBus middleware (e.g., logging, validation) by wrapping the bridge:

   $bus = new MessageBus([
       new \MatthiasNoback\SimpleBus\Middleware\LogMessages(),
       new \MatthiasNoback\SimpleBus\Middleware\ValidateMessages(),
   ]);
   $bridge = new SimpleBusBridge($bus);
   

Integration Tips

• Laravel Queues: The bridge works seamlessly with Laravel’s queue system. Dispatch commands via bus facade or Bus::dispatch().
• Testing: Use Mockery or PHPUnit to mock MessageBus and verify command dispatching:

  $mockBus = Mockery::mock(MessageBus::class);
  $mockBus->shouldReceive('dispatch')->once();
  $this->app->instance(MessageBus::class, $mockBus);
  

Gotchas and Tips

Pitfalls

1. Deprecated SimpleBus Version The package targets SimpleBus v1.x. Ensure compatibility by checking:

   composer show matthiasnoback/simple-bus
   

   If using SimpleBus v2+, manually adapt the bridge or fork the package.

2. Handler Registration Order Handlers must be registered before the MessageBus is instantiated. Late binding (e.g., in a controller) will fail:

   // ❌ Fails: Handlers not registered
   $bus = $this->app->make(MessageBus::class);
   $bus->dispatch($command);
   
   // ✅ Works: Register handlers first
   $bridge = new SimpleBusBridge($this->app->make('bus'));
   $bridge->addHandler(...);
   $bridge->dispatch($command);
   

3. Circular Dependencies Avoid circular references between commands/events and their handlers. Use dependency injection sparingly:

   // ❌ Risky: Handler depends on a command it processes
   class UpdateUserHandler implements MessageHandler
   {
       public function __construct(private UpdateUserCommand $command) {}
   }
   

Debugging

• Missing Handlers: Check for NoHandlerForMessage exceptions. Ensure:
  • Handlers are properly bound in the container.
  • Handler classes implement MatthiasNoback\SimpleBus\MessageHandler.
• Queue Failures: Laravel’s queue worker may silently fail. Enable logging:

  $bus = new MessageBus([
      new \MatthiasNoback\SimpleBus\Middleware\LogMessages(),
  ]);
  

Extension Points

1. Custom Middleware Extend the bridge to add Laravel-specific middleware (e.g., auth checks):

   class AuthMiddleware implements Middleware
   {
       public function handle($message, callable $next)
       {
           if (!auth()->check()) {
               throw new \RuntimeException('Unauthorized');
           }
           return $next($message);
       }
   }
   

2. Event Listeners Convert SimpleBus events to Laravel listeners for seamless integration:

   $bus->subscribeTo(UserCreatedEvent::class, function ($event) {
       event(new \Illuminate\Queue\Events\JobProcessed($event->user));
   });
   

3. Retry Logic Use Laravel’s retryAfter() with SimpleBus by wrapping handlers:

   $handler = new RetryHandler(
       $originalHandler,
       new \Illuminate\Bus\Retryable
   );