Relay Base Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dbp/relay-base-bundle
   

   Register the bundle in config/app.php under providers:

   DBP\RelayBaseBundle\RelayBaseBundle::class,
   

2. First Use Case Use the bundle’s core features for event-driven data relay (e.g., forwarding logs, metrics, or notifications between microservices). Example:

   use DBP\RelayBaseBundle\Relay\RelayInterface;
   
   // Inject RelayInterface via DI (configured in bundle)
   $relay = $this->container->get(RelayInterface::class);
   
   // Publish an event (e.g., "user.created")
   $relay->publish('user.created', ['user_id' => 123]);
   

3. Configuration Check config/packages/dbp_relay_base.yaml for default settings (e.g., transport adapters like RabbitMQ, Redis, or HTTP). Override as needed:

   dbp_relay_base:
       transports:
           rabbitmq:
               dsn: 'amqp://guest:guest@localhost:5672/%2f'
               exchange: 'relay_events'
   

Implementation Patterns

Core Workflows

1. Event Publishing Use RelayInterface to emit events with metadata:

   $relay->publish('order.processed', [
       'order_id' => $order->id,
       'status'   => 'paid',
       'metadata' => ['customer_id' => 456]
   ]);
   

   • Best Practice: Group related events under a namespace (e.g., ecommerce.order.*).

2. Event Subscribing Implement DBP\RelayBaseBundle\Relay\SubscriberInterface:

   class OrderSubscriber implements SubscriberInterface {
       public function handle(string $eventName, array $payload): void {
           if ($eventName === 'order.processed') {
               // Process payload (e.g., update inventory)
           }
       }
   }
   

   Register subscribers in services.yaml:

   services:
       App\Subscriber\OrderSubscriber:
           tags: ['dbp_relay.subscriber']
   

3. Transport Abstraction Swap transports dynamically via configuration (e.g., switch from RabbitMQ to Redis for testing):

   dbp_relay_base:
       transports:
           default: 'redis'  # Override default transport
   

Integration Tips

• Laravel-Specific: Use Laravel’s event system as a fallback:

  $relay->publish('user.login', ['ip' => request()->ip()]);
  // Fallback: event(new UserLoggedIn(request()->ip()));
  

• Middleware: Add a middleware to log relay events:

  public function handle($request, Closure $next) {
      $response = $next($request);
      if ($request->relayEvent) {
          $this->relay->publish('api.request', [
              'path' => $request->path(),
              'status' => $response->status()
          ]);
      }
      return $response;
  }
  

Gotchas and Tips

Pitfalls

1. Transport Failures

   • Issue: If the transport (e.g., RabbitMQ) is down, events may silently drop.
   • Fix: Enable retry logic in dbp_relay_base.yaml:

     dbp_relay_base:
         retry:
             max_attempts: 3
             delay: 100  # ms
     

2. Subscriber Order

   • Issue: Subscribers may not execute in expected order if not explicitly defined.
   • Fix: Use tags with priorities in services.yaml:

     tags: ['dbp_relay.subscriber', { priority: 100 }]
     

3. Payload Size Limits

   • Issue: Large payloads (e.g., >1MB) may be truncated by transports like RabbitMQ.
   • Fix: Compress payloads or use external storage (e.g., S3) for large data.

Debugging

• Enable Logging: Add to config/logging.php:

  channels:
      relay:
          driver: single
          path: storage/logs/relay.log
          level: debug
  

  Then configure the bundle to use this channel:

  dbp_relay_base:
      logging_channel: 'relay'
  

• Test Locally: Use the in_memory transport for development:

  dbp_relay_base:
      transports:
          default: 'in_memory'
  

Extension Points

1. Custom Transports Implement DBP\RelayBaseBundle\Transport\TransportInterface:

   class S3Transport implements TransportInterface {
       public function publish(string $event, array $payload): void {
           // Upload to S3 with event as key
       }
   }
   

   Register in services.yaml:

   services:
       App\Transport\S3Transport:
           tags: ['dbp_relay.transport']
   

2. Event Transformers Modify payloads before publishing:

   $relay->publish('user.created', ['user_id' => 123], [
       'transformer' => function ($payload) {
           $payload['timestamp'] = now()->toIso8601String();
           return $payload;
       }
   ]);
   

3. Security

   • Tip: Sanitize payloads to prevent injection:

     $cleanPayload = array_map('htmlspecialchars', $payload);
     $relay->publish('user.input', $cleanPayload);