Simple Bus Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require bengor-user/simple-bus-bridge-bundle
   composer require simplebus/simple-bus
   composer require bengor-user/user-bundle
   

   Ensure UserBundle and SimpleBus are registered in config/bundles.php.

2. Configure the Bridge Add to config/packages/simple_bus_bridge.yaml:

   simple_bus_bridge:
       user_bundle: true  # Enable UserBundle integration
   

3. First Use Case: Dispatching User Events

   use SimpleBus\Message\Bus\MessageBus;
   use BenGorUser\UserBundle\Event\UserRegisteredEvent;
   
   // In a controller/service
   $event = new UserRegisteredEvent($user);
   $this->get('simple_bus.message_bus')->dispatch($event);
   

Key Files to Review

• src/DependencyInjection/SimpleBusBridgeExtension.php (Configuration logic)
• src/EventListener/UserEventListener.php (Default event handling)
• tests/ (SpecBDD examples for expected behavior)

Implementation Patterns

Core Workflow: Event-Driven User Actions

1. Triggering Events Use UserRegisteredEvent, UserUpdatedEvent, etc., from BenGorUser\UserBundle\Event.

   $bus->dispatch(new UserUpdatedEvent($user, ['email' => 'new@example.com']));
   

2. Handling Events Subscribe to events via SimpleBus handlers:

   use SimpleBus\Message\Handler\MessageHandlerInterface;
   
   class SendWelcomeEmailHandler implements MessageHandlerInterface
   {
       public function __invoke(UserRegisteredEvent $event)
       {
           // Logic to send email
       }
   }
   

   Register the handler in config/packages/simple_bus.yaml:

   simple_bus:
       handlers:
           BenGorUser\UserBundle\Event\UserRegisteredEvent: App\Handler\SendWelcomeEmailHandler
   

3. Middleware Integration Use SimpleBus middleware to cross-cut concerns (e.g., logging, validation):

   use SimpleBus\Message\Bus\Middleware\Middleware;
   
   class ValidateUserEventMiddleware implements Middleware
   {
       public function handle($message, callable $next)
       {
           if (!$message instanceof UserEventInterface) {
               return $next($message);
           }
           // Validation logic
           return $next($message);
       }
   }
   

Common Patterns

• Event Chaining: Dispatch multiple events sequentially (e.g., UserRegisteredEvent → UserProfileCreatedEvent).
• Command-Event Duality: Use SimpleBus commands to trigger events (e.g., RegisterUserCommand dispatches UserRegisteredEvent).
• Laravel-Specific: Wrap the bundle in a Laravel service provider to expose the bus:

  $this->app->bind(MessageBus::class, function ($app) {
      return $app->make('simple_bus.message_bus');
  });
  

Gotchas and Tips

Pitfalls

1. Event Naming Collisions Ensure event classes (e.g., UserRegisteredEvent) are namespaced uniquely to avoid conflicts with other bundles. Fix: Use FQCNs (e.g., App\Event\UserRegisteredEvent) or alias namespaces in composer.json.

2. Circular Dependencies Avoid circular references between handlers (e.g., HandlerA dispatches an event handled by HandlerB, which dispatches back to HandlerA). Fix: Use middleware to enforce constraints or refactor into linear flows.

3. Outdated Bundle Last release in 2017 may lack compatibility with modern Symfony/Laravel. Mitigation:

   • Fork and update dependencies (e.g., simplebus/simple-bus:^2.0).
   • Patch UserBundle integration manually if needed.

4. Missing Event Interfaces The bundle assumes events implement BenGorUser\UserBundle\Event\UserEventInterface. Override or extend this interface if custom events are added.

Debugging Tips

• Enable SimpleBus Logging Add to config/packages/simple_bus.yaml:

  simple_bus:
      logging: true
  

  Logs will appear in var/log/dev.log.

• Inspect Dispatch Chain Use Xdebug to trace event dispatching:

  $bus->dispatch($event); // Set breakpoint here
  

• Test Event Flow Use PHPSpec to verify handlers:

  vendor/bin/phpspec run --format=pretty src/Handler/SendWelcomeEmailHandler
  

Extension Points

1. Custom Event Types Extend UserEventInterface for domain-specific events:

   namespace App\Event;
   
   use BenGorUser\UserBundle\Event\UserEventInterface;
   
   class CustomUserActionEvent implements UserEventInterface
   {
       // ...
   }
   

2. Dynamic Handler Registration Register handlers dynamically in a service:

   $container->register('simple_bus.handler.custom_event', CustomHandler::class)
       ->addTag('simple_bus.handler', ['message' => CustomEvent::class]);
   

3. Laravel Service Provider Override the bundle’s services in AppServiceProvider:

   public function register()
   {
       $this->app->extend('simple_bus.message_bus', function ($bus, $app) {
           return $bus->withMiddleware(new CustomMiddleware());
       });
   }
   

Configuration Quirks

• UserBundle Dependency: The bridge assumes UserBundle is installed. If using a custom user system, mock the UserEventInterface or disable the bridge:

  simple_bus_bridge:
      user_bundle: false
  

• Symfony 4+: May require adjusting autowiring or service aliases due to changes in Symfony’s DI system.