Goridge Laravel Package

Technical Evaluation

Architecture Fit

• Polyglot Integration: Ideal for PHP-to-Go IPC in hybrid architectures (e.g., legacy PHP apps calling Go microservices for performance-critical logic). Aligns with RoadRunner’s design (which uses this package internally), ensuring compatibility with Spiral’s ecosystem.
• Protocol Abstraction: Goridge’s multi-codec RPC (JSON/MsgPack/Protobuf) and transport-agnostic design (TCP/Unix/pipes) fit systems requiring low-latency, structured communication without HTTP overhead.
• Performance-Centric: Benchmarked at 300k calls/sec (Ryzen 1700X), making it suitable for high-throughput use cases (e.g., real-time data pipelines, batch processing).
• Extensibility: Supports custom relays/codecs (e.g., WebSocket, gRPC bridges) via RelayInterface/CodecInterface, enabling future-proofing for new protocols.

Integration Feasibility

• Drop-in Compatibility: Works with PHP 8.1+ (PHP 7.2+ for older versions) and Go’s net/rpc, requiring only ext-sockets (optional for Unix/TCP) or standard streams.
• RoadRunner Synergy: If using RoadRunner, this package is a native dependency, reducing friction for process management, load balancing, and worker pools.
• Binary Data Support: Critical for file/image processing, database bulk ops, or streaming (e.g., video transcoding) via []byte payloads.
• Error Handling: Granular service/transport/message-level errors simplify debugging in distributed systems.

Technical Risk

• Dependency on Go Services: Requires existing Go RPC services or willingness to build them. Risk mitigated by net/rpc’s ubiquity in Go ecosystems.
• Protocol Complexity: Goridge’s binary framing (vs. JSON-RPC) may require learning curve for teams unfamiliar with net/rpc. Mitigate with examples and RoadRunner docs.
• Stateful Connections: Long-lived relays (e.g., Unix sockets) need connection pooling or retry logic in PHP to handle failures gracefully.
• Windows Support: Unix sockets work on Windows (post-Build 17056), but pipe relays may need testing for edge cases (e.g., cross-process IPC).

Key Questions

1. Use Case Clarity:
   • Will this replace HTTP/gRPC for inter-service calls, or supplement them (e.g., for internal PHP-Go communication)?
   • Are we building new Go services or integrating with existing ones?
2. Performance Requirements:
   • Does the 300k calls/sec benchmark align with our latency/budget needs (e.g., <10ms for 99% of calls)?
   • Will binary payloads (MsgPack/Protobuf) reduce payload size vs. JSON?
3. Operational Overhead:
   • How will we monitor RPC failures (e.g., timeouts, service errors) in production?
   • Do we need circuit breakers or retries for transient Go service failures?
4. Migration Path:
   • Can we incrementally move PHP logic to Go (e.g., start with non-critical services)?
   • Will RoadRunner’s worker model (if used) simplify deployment vs. custom Go servers?
5. Team Skills:
   • Does the team have Go RPC expertise, or will we need to upskill on net/rpc?
   • Are developers comfortable with binary protocols vs. REST/gRPC?

Integration Approach

Stack Fit

• PHP Stack: Works seamlessly with Laravel/Symfony via Composer, but requires RoadRunner (or custom Go RPC server) for process management.
• Go Stack: Integrates with any Go service exposing net/rpc, including:
  • RoadRunner workers (native support).
  • Custom Go microservices (e.g., Kafka consumers, ML models).
  • Third-party Go libraries (e.g., github.com/go-redis/redis for Redis ops).
• Alternatives Considered:
  • gRPC: Higher latency (~10x vs. Goridge) but broader language support.
  • HTTP/REST: Easier to debug but 10–100x slower for internal calls.
  • Message Queues (RabbitMQ/Kafka): Better for async but adds complexity for synchronous RPC.

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Deploy a single Go RPC service (e.g., UserService) alongside PHP.
   • Replace a high-latency PHP function (e.g., PDF generation) with a Go call via Goridge.
   • Measure performance gain and error rates.
2. Phase 2: Incremental Adoption
   • Group services by domain: Migrate auth, payments, or search to Go first.
   • Use RoadRunner to manage PHP/Go workers, reducing orchestration overhead.
   • Wrap Goridge calls in a service layer (e.g., GoRPCClient) to abstract transport details.
3. Phase 3: Full Integration
   • Replace internal HTTP calls between PHP services with Goridge.
   • Implement circuit breakers (e.g., Hystrix) for Go service failures.
   • Monitor RPC metrics (latency, error rates) via Prometheus/Grafana.

Compatibility

• Protocol: Goridge’s binary framing is not compatible with standard JSON-RPC or gRPC. Requires Go services to use net/rpc.
• Transport:
  • TCP/Unix: Works out-of-the-box with ext-sockets (Linux/macOS/Windows).
  • Pipes: Zero-config for RoadRunner or local process communication.
  • Custom Relays: Extend RelayInterface for WebSocket, UDP, or QUIC.
• Data Formats:
  • JSON: Default, human-readable, but slower.
  • MsgPack: Binary, 3x faster than JSON for structured data.
  • Protobuf: Best for large payloads (e.g., serialized objects).

Sequencing

1. Prerequisites:
   • Go RPC Server: Deploy or ensure existing Go services expose net/rpc.
   • PHP Setup: Install spiral/goridge and ext-sockets (if using TCP/Unix).
   • RoadRunner (Optional): Simplifies worker management if using Spiral’s ecosystem.
2. Order of Operations:
   • Step 1: Implement a Go RPC service (e.g., greeter.Greeter).
   • Step 2: Write PHP client using Goridge\RPC\RPC.
   • Step 3: Test local calls (pipes) before remote (TCP/Unix).
   • Step 4: Add error handling (e.g., retry logic for ServiceException).
   • Step 5: Integrate with monitoring (e.g., log RPC failures).

Operational Impact

Maintenance

• Dependency Updates: Goridge is actively maintained (last release: 2026-05-11), with MIT license and Spiral’s backing.
• Debugging:
  • Service Errors: Thrown as ServiceException with Go stack traces.
  • Transport Errors: TransportException for network issues (e.g., socket timeouts).
  • Logging: Use Psr\Log to log RPC calls/errors (example in RoadRunner docs).
• Tooling:
  • IDE Support: PHPStorm autocompletion (via .phpstorm.meta.php).
  • Testing: Built-in PHPUnit tests; Psalm for static analysis.

Support

• Community: 123 stars, active Discord, and Spiral’s support network.
• Documentation:
  • Examples: GitHub examples cover TCP/Unix/pipes.
  • RoadRunner Docs: roadrunner.dev for production deployments.
• SLA Considerations:
  • Critical Path: If Goridge is used for real-time services (e.g., payments), ensure Go RPC services have high availability.
  • Fallback: Implement circuit breakers (e.g., goridge-php/circuit-breaker) for Go service outages.

Scaling

• Horizontal Scaling:
  • Go Side: Scale net/rpc services behind a load balancer (e.g., Nginx, Envoy).