Simple Bus Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require bengor-file/simple-bus-bridge
   

2. Register the bridge in Laravel: Add the bridge to your config/bus.php (or equivalent) to integrate with SimpleBus:

   'bridges' => [
       'file' => \BenGorFile\SimpleBusBridge\FileBridge::class,
   ],
   

3. Define a command bus: Use the bridge to create a file-backed bus in AppServiceProvider@boot():

   $bus = new \SimpleBus\MessageBus(
       new \BenGorFile\SimpleBusBridge\FileBridge(
           new \File\FileSystem($storagePath)
       )
   );
   

First Use Case: Persistent Command Queue

Use the bridge to store dispatched commands in a file system (e.g., JSON files) for later replay or debugging:

$bus->dispatch(new ProcessOrderCommand($orderId));

// Later, replay commands from storage
$storedCommands = $fileSystem->read('commands/ProcessOrderCommand_123.json');
$bus->dispatch($storedCommands);

Implementation Patterns

Workflows

1. Command Persistence:

   • Dispatch commands to a file-backed bus for audit trails or reprocessing.
   • Example: Log all SendEmailCommand instances to a directory for later replay.

   $bus = new \SimpleBus\MessageBus(
       new \BenGorFile\SimpleBusBridge\FileBridge($fileSystem)
   );
   $bus->dispatch(new SendEmailCommand($userId, $template));
   

2. Integration with Laravel Queues:

   • Use the bridge alongside Laravel’s queue system for hybrid persistence:

   // Dispatch to SimpleBus (file-backed) and Laravel queue
   $bus->dispatch($command);
   Queue::push(new DispatchCommandJob($command));
   

3. Middleware Chaining:

   • Apply SimpleBus middleware (e.g., logging, validation) before file persistence:

   $bus = new \SimpleBus\MessageBus(
       new \SimpleBus\Middleware\Chain(
           new \SimpleBus\Middleware\LogMessages(),
           new \BenGorFile\SimpleBusBridge\FileBridge($fileSystem)
       )
   );
   

Integration Tips

• File System Abstraction: Use Laravel’s Storage facade for cross-environment paths:

  $fileSystem = Storage::disk('local')->getDriver();
  

• Command Serialization: Ensure commands implement JsonSerializable or use serialize() for custom objects.
• Directory Structure: Organize files by command class (e.g., storage/app/commands/ProcessOrderCommand_123.json).

Gotchas and Tips

Pitfalls

1. File Naming Collisions:
   • Default naming uses get_class() + timestamp. Override FileBridge::getFileName() if needed:

   $bridge->setFileNameGenerator(function ($command) {
       return 'custom_' . md5($command->getId()) . '.json';
   });
   

2. Concurrency Issues:
   • File operations are not atomic. Use file locks or a database-backed bus for high-concurrency scenarios.
3. Serialization Errors:
   • Non-serializable commands (e.g., closures, resources) will fail. Use serialize() or exclude them.

Debugging

• Verify File Storage: Check storage/app/commands/ for generated files. Use dd($fileSystem->listContents()) to debug.
• Log Middleware: Wrap the bridge in a logging middleware to trace dispatches:

  $bus = new \SimpleBus\MessageBus(
      new \SimpleBus\Middleware\Chain(
          new class implements \SimpleBus\Middleware\Middleware {
              public function handle($message, callable $next) {
                  \Log::debug("Dispatching: " . get_class($message));
                  return $next($message);
              }
          },
          $fileBridge
      )
  );
  

Extension Points

1. Custom File System: Extend \File\FileSystem to add encryption or compression:

   $fileSystem = new CustomFileSystem($storagePath);
   

2. Event Triggers: Hook into file creation/deletion via events (e.g., FileCreated):

   $fileSystem->addListener(new class implements \File\EventListener {
       public function handle(FileEvent $event) {
           if ($event->getType() === FileEvent::CREATED) {
               event(new CommandStored($event->getFile()));
           }
       }
   });
   

3. Batch Processing: Use FileBridge::getAllCommands() to replay batches:

   foreach ($fileBridge->getAllCommands() as $command) {
       $bus->dispatch($command);
   }