Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require splash/bridge-bundle
   

   Publish the configuration:

   php artisan vendor:publish --provider="Splash\BridgeBundle\BridgeServiceProvider"
   

2. Define a Worker: Edit config/bridge.php to register a PHAR worker:

   workers:
       payment_processor:
           phar: "/path/to/payment-worker.phar"
           command: "process {payload}"
           queue: "legacy"
           timeout: 300
   

3. Create a PHAR Worker: Build a PHAR from your legacy connector script:

   box compile payment-connector.php payment-worker.phar
   

   Ensure the PHAR’s entrypoint handles the {payload} argument (e.g., JSON-decoded input).

4. Dispatch a Job: Dispatch a job to trigger the worker:

   use Splash\BridgeBundle\Jobs\WorkerJob;
   
   WorkerJob::dispatch('payment_processor', ['amount' => 100, 'currency' => 'USD']);
   

5. Run the Queue Worker: Start processing jobs:

   php artisan queue:work
   

First Use Case: Legacy API Poller

• Problem: A legacy SOAP API requires polling every 5 minutes.
• Solution:
  1. Wrap the SOAP client in a PHAR (soap-poller.phar).
  2. Configure the worker in bridge.php:

     workers:
         soap_poller:
             phar: "/path/to/soap-poller.phar"
             command: "poll {api_endpoint}"
             queue: "pollers"
             schedule: "*/5 * * * *"
     

  3. Dispatch a ScheduledWorkerJob (or use Laravel’s task scheduling):

     WorkerJob::dispatch('soap_poller', ['api_endpoint' => 'https://legacy-api.example.com']);
     

Implementation Patterns

Workflow: Strangler Pattern Integration

1. Isolate Legacy Logic:

   • Extract a legacy connector (e.g., LegacyPaymentGateway) into a standalone script.
   • Build it into a PHAR:

     box compile --main=LegacyPaymentGateway::process payment-gateway.php payment-worker.phar
     

2. Laravel Integration:

   • Register the worker in config/bridge.php:

     workers:
         payment_gateway:
             phar: "/path/to/payment-worker.phar"
             command: "process {request}"
             queue: "payments"
             retry_after: 60
     

   • Replace direct calls with queue jobs:

     // Old: Direct call (monolithic)
     $result = (new LegacyPaymentGateway())->process($request);
     
     // New: Queue-based (decoupled)
     PaymentProcessed::dispatch($request)
         ->onQueue('payments')
         ->afterCommit();
     

3. Gradual Replacement:

   • Use feature flags to toggle between old/new paths:

     if (featureEnabled('new_payment_flow')) {
         // Call modern service
     } else {
         // Dispatch to legacy worker
         WorkerJob::dispatch('payment_gateway', $request);
     }
     

Integration Tips

• Dependency Injection: Pass dependencies (e.g., HTTP clients, databases) via PHAR arguments or environment variables:

  workers:
      api_connector:
          phar: "/path/to/api-worker.phar"
          command: "fetch {url} --client {http_client}"
          env:
              HTTP_CLIENT: "guzzle"
  

  In the PHAR, access args via $argv or parse --client flags.

• Event-Driven Workflows: Trigger workers from Laravel events:

  // In an event listener
  event(new OrderCreated($order));
  

  // In Bridge config
  events:
      order_created:
          worker: "order_processor"
          payload: "{order}"
  

• PHAR Customization: Extend the PHAR template to include:

  • Shared libraries (e.g., vendor/autoload.php).
  • Custom error handlers (log failures to a central system).
  • Health checks (e.g., ping command).

• Queue Strategies:

  • Use queue connections to route workers to specific queues (e.g., database for critical jobs, beanstalkd for high-volume).
  • Leverage queue middleware to add retries or timeouts:

    $job->onQueue('high_priority')->retryUntil(1440); // Retry for 1 day
    

Gotchas and Tips

Pitfalls

1. PHAR Security:

   • Risk: PHARs can execute arbitrary code. Restrict worker directories to read-only for untrusted users.
   • Fix: Use phar.readonly=1 in php.ini and validate PHAR signatures.

2. Worker Timeouts:

   • Risk: Long-running workers may hit Laravel’s queue timeout (default: 60s).
   • Fix: Increase queue_worker_timeout in .env or set per-worker in bridge.php:

     workers:
         long_running:
             timeout: 1800 # 30 minutes
     

3. Stateful Workers:

   • Risk: Workers with shared state (e.g., in-memory caches) may fail under load.
   • Fix: Offload state to Redis or a database. Avoid global variables in PHARs.

4. Dependency Conflicts:

   • Risk: PHARs bundle dependencies, which may conflict with Laravel’s composer.json.
   • Fix: Use phive to manage PHAR dependencies or isolate workers in containers.

5. Debugging:

   • Risk: Worker logs are hard to trace if not centralized.
   • Fix: Pipe worker output to a log file or use monolog:

     workers:
         debug_worker:
             phar: "/path/to/debug-worker.phar"
             log_file: "/var/log/bridge/debug-worker.log"
     

Debugging Tips

• Local Testing: Test PHARs locally before deployment:

  php payment-worker.phar process '{"amount":100}'
  

  Use --debug flag if supported by the PHAR.

• Queue Inspection: Check stuck jobs:

  php artisan queue:failed-table
  php artisan queue:work --once --queue=legacy
  

• Worker Process Management: Use supervisor to manage worker processes with auto-restart:

  [program:payment_worker]
  command=php /path/to/payment-worker.phar process {payload}
  autostart=true
  autorestart=true
  stderr_logfile=/var/log/bridge/payment_worker.err.log
  stdout_logfile=/var/log/bridge/payment_worker.out.log
  

Extension Points

1. Custom Worker Classes: Extend Splash\BridgeBundle\Worker to add pre/post-processing:

   namespace App\BridgeWorkers;
   
   use Splash\BridgeBundle\Worker;
   
   class CustomWorker extends Worker {
       protected function beforeExecute(array $payload): array {
           // Add metadata
           $payload['timestamp'] = now()->toIso8601String();
           return $payload;
       }
   }
   

   Register in config/bridge.php:

   workers:
       custom_worker:
           class: App\BridgeWorkers\CustomWorker
           phar: "/path/to/worker.phar"
   

2. Dynamic PHAR Loading: Load PHARs from a remote URL (e.g., S3) for zero-downtime updates:

   workers:
       remote_worker:
           phar_url: "https://storage.example.com/workers/latest.phar"
           command: "process {payload}"
   

3. Worker Metrics: Integrate with Prometheus by extending the worker:

   use Prometheus\CollectorRegistry;
   
   class MetricWorker extends Worker {
       public function __construct() {
           $this->registry = new CollectorRegistry();
       }
   
       protected function execute(array $payload): void {
           $this->registry->getOrRegisterCounter('worker', 'executions', 'Worker executions')
               ->inc();
           // ... rest of logic
       }
   }
   

4. PHAR Build Automation: Automate PHAR builds with Git hooks or CI:

   # Example Git hook (post-commit)
   if [ "$(git diff --name-only HEAD~1 HEAD | grep -E '\.(php|phar)$')" ]; then
       box compile --main=Worker::process worker.php worker.phar
       scp worker.phar user@server:/path/to/workers/
   fi
   

Configuration Quirks

• Queue Binding: Workers default to the queue defined in `bridge