Roadrunner Grpc Laravel Package

Technical Evaluation

Architecture Fit

• High Performance RPC for Laravel: Ideal for Laravel applications deployed on RoadRunner, enabling low-latency, high-concurrency gRPC communication between microservices or internal APIs. Leverages RoadRunner’s Go-based worker pool for connection management while offloading request processing to PHP workers.
• Protocol Buffers (Protobuf) Integration: Enforces strict contract-driven development with type safety, versioning, and cross-language compatibility (e.g., PHP ↔ Go ↔ Java). Aligns with modern microservice architectures where schema-first design is critical.
• Hybrid PHP/Go Workloads: Supports mixed-language services (PHP + Go) under a single RoadRunner instance, reducing orchestration complexity for polyglot systems.
• Laravel Compatibility: Works seamlessly with Laravel’s dependency injection (DI), service containers, and event systems when bootstrapped via RoadRunner. Existing Laravel services (e.g., Eloquent, Queues) can be injected into gRPC handlers.

Integration Feasibility

• RoadRunner Dependency: Mandatory—this package cannot be used with traditional PHP-FPM or standalone Laravel. Requires RoadRunner v2024.1+ (or v2025 per latest release notes).
• Protobuf Workflow: Requires:
  1. .proto file definition (service + message schemas).
  2. Stub generation via protoc with PHP/gRPC plugins (included in google/protobuf and grpc/grpc packages).
  3. Manual bootstrap (grpc_server.php) to initialize the RoadRunner gRPC worker loop.
• Configuration Overhead: Minimal but non-trivial:
  • .rr.yaml snippet to enable the gRPC plugin.
  • Worker pool tuning (e.g., numWorkers, maxJobs).
  • TLS setup for secure gRPC channels (if needed).
• Laravel-Specific Gotchas:
  • No built-in HTTP/gRPC unification: Routes must be manually partitioned (e.g., HTTP via Laravel’s router, gRPC via RoadRunner).
  • Service Container Conflicts: RoadRunner’s DI container may clash with Laravel’s if not properly isolated (e.g., using Spiral\Framework\Core\Container as a facade).

Technical Risk

• Unknown Repository Risk: Low adoption (65 stars, 0 dependents) raises concerns about:
  • Long-term maintenance (last release: 2026-06-04, but no prior activity visible).
  • Security patches (MIT license is permissive, but no visible governance model).
  • Breaking changes (e.g., v3.0.0’s PHP 8.1+ requirement, RoadRunner version coupling).
• Protobuf Complexity:
  • Schema evolution requires careful versioning (no built-in migration tools).
  • Tooling dependency on protoc and plugins (e.g., grpc_php_plugin).
• Debugging Challenges:
  • Silent worker failures: RoadRunner restarts crashed workers without client-side visibility (requires logging middleware).
  • Limited observability: Prometheus metrics are available but not integrated with Laravel’s monitoring (e.g., Laravel Horizon, Sentry).
• Performance Pitfalls:
  • Worker pool sizing: Misconfigured numWorkers/maxJobs can lead to connection starvation or high memory usage.
  • Blocking handlers: Long-running gRPC calls (e.g., streaming) may block workers; async patterns (e.g., ReactPHP) are needed for I/O-bound tasks.

Key Questions for Stakeholders

1. RoadRunner Adoption:
   • Is RoadRunner already deployed in production? If not, what are the migration costs (e.g., Docker images, CI/CD, monitoring)?
2. Protobuf Maturity:
   • Does the team have experience with Protobuf schema design and tooling (protoc, buf for linting)?
   • Are there existing .proto files in the codebase, or will this require a new schema-first design?
3. Observability:
   • How will gRPC-specific metrics (e.g., latency, error rates) be surfaced to existing dashboards (e.g., Grafana, Datadog)?
4. Failure Modes:
   • What are the SLOs for gRPC endpoints (e.g., P99 latency, error budgets)? How will they be enforced?
5. Team Skills:
   • Is the team comfortable with persistent worker models (vs. request/response PHP-FPM) and gRPC idioms (e.g., streaming, metadata)?
6. Alternatives:
   • Would REST/JSON (via Laravel’s HTTP server) or message queues (e.g., Laravel Queues + Redis) suffice for the use case, reducing complexity?

Integration Approach

Stack Fit

• Core Stack:
  • RoadRunner v2024.1+ (mandatory; latest release supports v2025).
  • PHP 8.1+ (v3.x requires PHP 8.1; v2.x supported PHP 7.4–8.0).
  • Protocol Buffers v3.x (compatible with google/protobuf v4.x per v3.4.0+).
  • gRPC PHP Extension (grpc/grpc Composer package for stub generation).
• Laravel Integration Points:
  • Service Container: Use Spiral\Framework\Core\Container alongside Laravel’s container (may require bridge packages like spiral/laravel).
  • Dependency Injection: Inject Laravel services (e.g., App\Models\User) into gRPC handlers via constructor injection.
  • Events/Queues: Trigger Laravel events or dispatch jobs from gRPC handlers (e.g., event(new OrderCreated($data))).
• Tooling:
  • protoc: For .proto → PHP stub generation.
  • buf (optional): For Protobuf linting and schema registry.
  • Docker: RoadRunner’s Go runtime may require custom Docker images (e.g., roadrunner/roadrunner:latest).

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Set up a minimal RoadRunner + gRPC environment:
     • Install spiral/roadrunner-grpc and roadrunner/roadrunner.
     • Define a single .proto service (e.g., ping.pong).
     • Generate stubs and implement a handler.
     • Test locally with grpcurl or a Go client.
   • Goal: Validate performance, debugging workflow, and Protobuf tooling.
2. Phase 2: Laravel Integration
   • Option A (Shared Container): Use spiral/laravel to merge Laravel’s and Spiral’s containers.
   • Option B (Isolated Workers): Run gRPC handlers in a separate RoadRunner process (e.g., grpc.rr.yaml) to avoid container conflicts.
   • Bootstrap: Modify Laravel’s artisan or public/index.php to conditionally load RoadRunner’s gRPC worker.
3. Phase 3: Observability & Scaling
   • Integrate Prometheus metrics with Laravel’s monitoring (e.g., spiral/prometheus).
   • Set up logging middleware to capture gRPC exceptions (e.g., Monolog + Spiral\RoadRunner\Logger).
   • Benchmark worker pool sizes (e.g., numWorkers=4 vs. 8) under load.

Compatibility

• RoadRunner Versions:
  • v3.x: Requires RoadRunner v2024.1+ (or v2025 per v3.5.1).
  • v2.x: Supports older RoadRunner versions (e.g., v2.8+).
  • Upgrade Path: Test with RoadRunner’s latest stable to avoid hidden dependencies.
• Protobuf Compatibility:
  • Supports Protobuf v3.x and Google’s google/protobuf v4.x (added in v3.4.0).
  • Breaking Changes: Schema updates may require stub regeneration and client updates.
• Laravel-Specific:
  • No native Laravel support: Avoid packages like laravel-grpc; this is a RoadRunner-first solution.
  • Middleware: Use RoadRunner’s middleware stack (e.g., auth, logging) instead of Laravel’s HTTP middleware.

Sequencing

1. Infrastructure First:
   • Deploy RoadRunner with gRPC enabled before developing services.
   • Example .rr.yaml:

     version: '3'
     rpc:
       listen: tcp://0.0.0.0:6001
     grpc:
       active: true
       workers:
         command: 'php public/grpc_server.php'