Autobus Bus Sample Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require autobus-php/autobus-bus-sample-bundle
   

   Register the bundle in config/app.php under extra.bundles:

   Autobus\BusSampleBundle\AutobusBusSampleBundle::class,
   

2. First Use Case The bundle provides a sample implementation of the Autobus event bus pattern. To send a command or event:

   use Autobus\BusSampleBundle\Command\SampleCommand;
   use Autobus\BusSampleBundle\Event\SampleEvent;
   
   // Send a command
   $bus->dispatch(new SampleCommand('Hello, Autobus!'));
   
   // Listen to an event
   $bus->subscribe(SampleEvent::class, function (SampleEvent $event) {
       logger()->info('Event received:', ['message' => $event->getMessage()]);
   });
   

3. Where to Look First

   • Commands/Events: Check src/Command/ and src/Event/ for predefined examples.
   • Handlers: Review src/Handler/ for how commands/events are processed.
   • Configuration: Inspect config/packages/autobus_bus_sample.yaml for customization.

Implementation Patterns

Core Workflows

1. Command Dispatching Use the bus to trigger actions (e.g., sending emails, processing payments):

   $bus->dispatch(new ProcessPaymentCommand($userId, $amount));
   

   • Handler: Implement Autobus\BusSampleBundle\Handler\CommandHandlerInterface for custom logic.

2. Event Subscribing React to domain events (e.g., user registration, order updates):

   $bus->subscribe(UserRegisteredEvent::class, function (UserRegisteredEvent $event) {
       Mail::to($event->getEmail())->send(new WelcomeEmail());
   });
   

   • Priority: Use Autobus\BusSampleBundle\Subscriber\SubscriberInterface::getPriority() for ordering.

3. Middleware Integration Add cross-cutting concerns (logging, auth) via middleware:

   $bus->pipe(new LoggingMiddleware());
   $bus->pipe(new AuthMiddleware());
   

Integration Tips

• Laravel Service Provider: Bind the bus to the container in register():

  $this->app->bind('bus', function ($app) {
      return new Autobus\BusSampleBundle\Bus($app['autobus_bus_sample']);
  });
  

• Dependency Injection: Inject the bus into controllers/services:

  public function __construct(private Bus $bus) {}
  

• Testing: Mock the bus for unit tests:

  $bus = Mockery::mock(Bus::class);
  $bus->shouldReceive('dispatch')->once();
  

Gotchas and Tips

Common Pitfalls

1. Circular Dependencies Avoid circular references between handlers/subcribers (e.g., Handler A calls Handler B, which calls Handler A).

   • Fix: Use Autobus\BusSampleBundle\Bus::dispatchLater() for deferred execution.

2. Event Ordering Subscribers with the same priority may execute in arbitrary order.

   • Fix: Assign explicit priorities (e.g., getPriority(): int { return 100; }).

3. Middleware Conflicts Middleware may interfere with expected behavior (e.g., logging before validation).

   • Fix: Reorder middleware using Bus::pipe() or Bus::unpipe().

Debugging Tips

• Enable Logging: Configure the bus to log dispatched commands/events:

  # config/packages/autobus_bus_sample.yaml
  logging: true
  

• Check Handlers: Ensure handlers are registered in the container or manually bound.
• Validate Payloads: Use Autobus\BusSampleBundle\Validator\ValidatorInterface to reject malformed commands/events early.

Extension Points

1. Custom Handlers Extend Autobus\BusSampleBundle\Handler\AbstractHandler for reusable logic:

   class CustomHandler extends AbstractHandler {
       public function handle(SampleCommand $command) {
           // Custom logic
       }
   }
   

2. Dynamic Subscribers Register subscribers dynamically (e.g., based on user roles):

   if (auth()->check()) {
       $bus->subscribe(UserEvent::class, new RoleBasedSubscriber());
   }
   

3. Async Processing Offload heavy tasks to queues by integrating with Laravel Queues:

   $bus->dispatch(new AsyncCommand())->delay(now()->addMinutes(5));