Simple Bus Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require bengor-file/simple-bus-bridge-bundle
   composer require symfony/bundle:^2.8 simplebus/simple-bus:^1.0 ben-gor-file/file-bundle:^1.0
   

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

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

   simple_bus_bridge:
       file_bundle: true
       bus: 'default'  # Matches your SimpleBus configuration
   

3. First Use Case: Dispatching File Events Create a command to dispatch a file event:

   use BenGorFile\FileBundle\Event\FileUploadedEvent;
   use SimpleBus\Message\Bus\Bus;
   
   class DispatchFileEventCommand extends Command
   {
       protected function configure(): void
       {
           $this->setName('app:dispatch-file-event');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output, Bus $bus): int
       {
           $event = new FileUploadedEvent('/path/to/file');
           $bus->dispatch($event);
           return Command::SUCCESS;
       }
   }
   

Implementation Patterns

Core Workflow: Event-Driven File Processing

1. File Upload → Event Dispatch

   // In a controller or service
   $file = $request->file('document');
   $event = new FileUploadedEvent($file->getPathname());
   $this->bus->dispatch($event);
   

2. Handling Events with SimpleBus Handlers

   use BenGorFile\FileBundle\Event\FileUploadedEvent;
   use SimpleBus\Message\Handler\MessageHandlerInterface;
   
   class FileProcessor implements MessageHandlerInterface
   {
       public function handle(FileUploadedEvent $event): void
       {
           // Process file (e.g., store metadata, generate thumbnails)
           $this->fileService->process($event->getFilePath());
       }
   }
   

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

   simple_bus:
       handlers:
           BenGorFile\FileBundle\Event\FileUploadedEvent: App\Handler\FileProcessor
   

3. Chaining Handlers for Complex Workflows Use SimpleBus middleware to transform or validate events before processing:

   simple_bus:
       middleware:
           - SimpleBus\Middleware\ValidateMessageMiddleware
           - App\Middleware\LogFileEventMiddleware
   

Integration Tips

• Leverage FileBundle’s Events The bundle bridges FileBundle events (e.g., FileUploadedEvent, FileDeletedEvent) to SimpleBus. Extend FileBundle to create custom events:

  class CustomFileEvent extends FileEvent
  {
      public function __construct(string $filePath, array $metadata)
      {
          parent::__construct($filePath);
          $this->metadata = $metadata;
      }
  }
  

• Async Processing with Queues Combine with Symfony Messenger or a queue system (e.g., RabbitMQ) to offload heavy file processing:

  # config/packages/messenger.yaml
  messenger:
      transports:
          async: '%env(MESSENGER_TRANSPORT_DSN)%'
      routing:
          'BenGorFile\FileBundle\Event\FileUploadedEvent': async
  

• Testing Use SimpleBus’s Testing\MessageBus for unit tests:

  $bus = new Testing\MessageBus();
  $bus->shouldDispatch()->fileUploadedEvent();
  

Gotchas and Tips

Pitfalls

1. Event Naming Collisions Ensure custom events extend BenGorFile\FileBundle\Event\FileEvent to avoid serialization issues. SimpleBus requires events to be serializable.

2. Bundle Dependency Order Register FileBundle before SimpleBusBridgeBundle in config/bundles.php to avoid autowiring conflicts.

3. Outdated Documentation The package lacks recent updates. Refer to:

   • FileBundle’s docs for event types.
   • SimpleBus docs for handler/middleware patterns.

4. PHP 5.5+ Limitation Avoid modern PHP features (e.g., typed properties, attributes) in events/handlers due to the PHP version constraint.

Debugging

• Event Not Dispatched? Verify the event class is registered in simple_bus.yaml under handlers. Check for typos in event namespaces.

• Handler Not Invoked? Ensure the handler implements SimpleBus\Message\Handler\MessageHandlerInterface and is autowired correctly. Use:

  php bin/console debug:container App\Handler\FileProcessor
  

• Serialization Errors Events must implement __construct() with all properties. Use #[AllowDynamicProperties] (PHP 8.1+) or initialize properties in the constructor if dynamic properties are needed.

Extension Points

1. Custom Middleware Add middleware to transform events or validate file paths:

   use SimpleBus\Message\Middleware\Middleware;
   
   class ValidateFilePathMiddleware implements Middleware
   {
       public function handle($message, callable $next)
       {
           if (!$this->isValidPath($message->getFilePath())) {
               throw new \InvalidArgumentException('Invalid file path');
           }
           return $next($message);
       }
   }
   

   Register in config/packages/simple_bus.yaml:

   simple_bus:
       middleware:
           - App\Middleware\ValidateFilePathMiddleware
   

2. Dynamic Event Dispatching Use reflection to dispatch events dynamically (e.g., for bulk operations):

   $eventClass = new \ReflectionClass($eventName);
   $event = $eventClass->newInstanceArgs($filePath);
   $this->bus->dispatch($event);
   

3. FileBundle Configuration Override FileBundle settings in config/packages/file.yaml to customize file storage paths or event triggers:

   file:
       storage:
           path: '%kernel.project_dir%/var/files'
       events:
           enabled: true