Bridge Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Legacy System Modernization: Ideal for encapsulating legacy PHP connectors (e.g., SOAP, REST APIs, or database-bound logic) as isolated PHAR workers, enabling a strangler pattern approach. Aligns with incremental modernization without full rewrites.
• Microservices Alignment: Facilitates decomposing monolithic Laravel apps into discrete, self-contained workers (e.g., payment processing, notifications). Reduces coupling and enables independent scaling.
• Event-Driven Workflows: Seamlessly integrates with Laravel’s Symfony Messenger and queue system, enabling asynchronous processing of external integrations (e.g., API polling, batch jobs).
• Laravel Ecosystem Synergy: Leverages native Laravel features (service container, configuration, events) while isolating Splash-specific logic, reducing boilerplate and maintaining consistency.

Integration Feasibility

• Service Registration: The bundle registers Splash services (e.g., workers, connectors) as Laravel queue jobs, enabling dispatch via dispatch() or event listeners.
• Configuration Flexibility: Supports YAML/JSON-based worker definitions, including PHAR paths, CLI arguments, and queue bindings. Example:

  workers:
    payment_connector:
      phar: "/path/to/payment-worker.phar"
      command: "process {payload}"
      queue: "legacy"
      retry_after: 60
  

• Dependency Isolation: PHAR workers bundle their dependencies, avoiding conflicts with the main Laravel app. Requires PHP CLI and a queue driver (e.g., Redis, database).
• Data Flow:
  • Input: Serialized payloads (JSON/array) passed via Laravel queue jobs.
  • Output: Workers return results via queue replies or external storage (e.g., database, S3).
  • State Management: Workers should avoid shared state; use databases/Redis for coordination.

Technical Risk

Key Questions

1. Connector Requirements:
   • Are connectors stateless (e.g., API calls) or stateful (e.g., database sessions)? Stateful workers may require external storage (e.g., Redis).
   • Do workers need shared memory (e.g., file system access, Redis)? If so, ensure PHARs have proper permissions.
2. Performance:
   • What’s the expected throughput (e.g., 1000 requests/hour)? Will workers need horizontal scaling (e.g., multiple supervisor processes)?
   • Are there hard real-time constraints (e.g., <1s response time)? PHAR workers may not suffice; consider containers/serverless.
3. Observability:
   • How will worker logs/metrics be aggregated (e.g., Prometheus, Datadog)? Workers lack built-in monitoring.
   • Is distributed tracing (e.g., OpenTelemetry) needed for cross-worker calls? Requires custom instrumentation.
4. Deployment:
   • How will PHARs be versioned and rolled back? Use semantic versioning and immutable deployments.
   • Will workers run on the same servers as Laravel or in a separate cluster? Separate clusters reduce blast radius.
5. Security:
   • Are workers exposed to untrusted networks? Restrict access via firewalls/VPC isolation.
   • How are secrets (e.g., API keys) managed? Use environment variables or a secrets manager (e.g., HashiCorp Vault).
6. Long-Term Roadmap:
   • Is this a temporary solution? Plan for migration to containers/serverless (e.g., AWS Lambda, Kubernetes) as legacy code is refactored.
   • Will workers need dynamic scaling? PHAR workers are limited to single-process scaling; consider Kubernetes for elasticity.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Queue System: Integrates with Laravel’s queue drivers (e.g., redis, database) for job dispatching and retries.
  • Event System: Workers can be triggered via Laravel events (e.g., OrderCreated → ProcessPaymentWorker).
  • Service Container: Inject dependencies (e.g., HTTP clients, config) into workers via PHAR configuration.
• Worker Runtime:
  • PHAR Format: Self-contained PHP archives with embedded dependencies, avoiding composer install per worker.
  • CLI Execution: Workers run as php worker.phar [args]; managed via supervisor, Kubernetes, or Laravel Forge.
  • Isolation: Workers run in separate processes, reducing risk of crashes affecting the main app.
• Data Handling:
  • Input/Output: Use Laravel’s serialize() or JSON for job payloads.
  • Shared State: Avoid; use databases/Redis for worker coordination (e.g., locking, caching).

Migration Path

1. Assessment Phase:
   • Inventory: Document legacy connectors (dependencies, statefulness, failure modes).
   • Benchmark: Measure performance (e.g., time to process 1000 requests) to set scaling targets.
   • Risk Analysis: Identify connectors with high failure rates or real-time constraints.
2. Pilot Phase:
   • Step 1: Containerize a Connector as a PHAR Worker
     • Build PHAR:

       composer create-project --stability=dev splash/bridge-bundle worker
       vendor/bin/phar build connector.php payment-worker.phar
       

     • Configure in config/bridge.php:

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

   • Step 2: Replace a Non-Critical Endpoint
     • Replace synchronous calls with queue jobs:

       // Before: Direct call
       LegacyPaymentGateway::process($request->all());
       
       // After: Queue job
       ProcessPaymentJob::dispatch($request->all());
       

   • Step 3: Test and Monitor
     • Validate worker logs, queue metrics, and error rates.
     • Adjust PHAR configuration (e.g., timeouts, retries) based on results.
3. Full Rollout:
   • Gradually migrate connectors to workers, retiring old endpoints.
   • Use feature flags to toggle between old/new paths during transition.
   • Implement canary releases for critical connectors (e.g., 5% traffic to workers).

Compatibility

Sequencing

1. Pre-requisites:
   • Configure and test Laravel queues (e.g., Redis, database).
   • Set up PHP CLI on worker servers (or use Docker).
   • Implement monitoring for queues/workers (e.g., laravel-queue-monitor, Prometheus).
2. Core Integration:
   • Build and test PHAR workers in isolation (e.g., local Docker containers).
   • Integrate workers into Laravel’s queue system via bridge-bundle.
   • Replace synchronous calls with queue jobs for one connector (pilot).
3. Post-Integration:
   • Implement retry logic for failed jobs (e.g., failed_jobs table, dead-letter queues).
   • Set up alerts for worker failures (e.g., supervisor events, PagerDuty).
   • Optimize worker concurrency based on load