Goridge Laravel Package

Product Decisions This Supports

• Framing the real decision: "adopt RoadRunner?" not "adopt Goridge?" — Goridge is the PHP-side protocol/codec that lets PHP talk to Go over net/rpc across TCP, Unix sockets, or pipes. In practice it arrives transitively with roadrunner/roadrunner. Treat it as an architectural enabler of the worker-runtime decision, not a standalone dependency debate. (The "0 dependents" figure on Packagist is misleading — it is pulled in through the RoadRunner metapackage, not required directly. Note that as of 4.5.0 the package is published as roadrunner/goridge, so the new Packagist entry restarts its dependent/download counters at zero; that is a naming artifact, not a signal about adoption.) The 4.6.0 change to require roadrunner/roadrunner instead of spiral/roadrunner confirms the ecosystem-wide namespace consolidation is proceeding — useful corroboration if anyone still doubts the rename is permanent.
• Build vs. buy on IPC/RPC plumbing — the alternative is hand-rolling a socket protocol, framing, and error handling on both the PHP and Go sides, or standing up gRPC/Protobuf. Goridge is a MIT-licensed, RoadRunner-maintained codec covering transport errors, service-level errors, sequence handling, and multi-codec support (JSON, MsgPack, Protobuf). Buying is the default; building is only justified for hard protocol requirements (TLS/mTLS, auth, backpressure, schema governance) it deliberately does not provide.
• Codec standardization is now a live decision (new, 4.6.0) — MsgPack support is deprecated: MsgpackCodec and the Frame::CODEC_MSGPACK constant are on a removal path. For a PM this converts "which codec do we use?" from a low-stakes engineering preference into a roadmap item with a deadline attached. The practical answer is JSON for small, debuggable calls and Protobuf where we want schema-typed, compact payloads. If any current or planned workload depends on MsgPack, put the migration in the same ticket as the RoadRunner upgrade rather than letting it surface as a breakage. Choosing Protobuf is not free — it implies owning .proto files, codegen in CI, and a schema-evolution policy, which is a process commitment, not a library flag.
• Incremental modernization / strangler-fig roadmap — supports keeping the PHP application as the product surface while offloading hot paths (media processing, pricing/risk calculation, ML inference, PDF/image work) into Go services called over a low-overhead bridge. This lets you sequence "extract one workload per quarter" instead of committing to a rewrite, and each extraction has a clean rollback (put the work back in PHP behind the same interface).
• Performance budget decisions — the 300k calls/sec figure (Ryzen 1700X, 20 threads) is a relative signal: RPC-style worker calls avoid per-request HTTP overhead, connection setup, and JSON-on-the-wire overhead where a binary codec is used. Use it to justify removing a hop, not as a product SLA. Ask engineering for a benchmark against the actual payload shape before putting a latency promise in a roadmap. Note the deprecation removes MsgPack from the "cheap binary win" column; the replacement binary story is Protobuf, which carries the schema overhead described above.
• Feature scoping around payload types — binary []byte transfer, streaming output (v3.2.0), multi-relay async RPC (v4.2.0), and Protobuf support are the capabilities that unlock specific use cases (large file/stream transfer, fire-and-forget notifications, schema-typed calls). If our use case is small JSON-shaped calls, we need none of the advanced surface — which keeps the integration small.
• Platform/deployment decisions — the transport choice (TCP vs. Unix socket vs. pipes) and the fact that Unix sockets work on Windows (build 17056+) affect our container topology, sidecar design, and Windows support story. Pipes relay means no listening port, which is a security/ops simplification worth calling out.
• Dependency-governance and upgrade-cadence planning (updated, 4.6.0) — the spiral/* → roadrunner/* migration has now happened in two waves: the package itself in 4.5.0, and the RoadRunner dependency constraint in 4.6.0. Treat "we have no spiral/goridge or spiral/roadrunner references anywhere" as a single clean-up acceptance criterion rather than two separate tasks — check Composer constraints, lockfiles, CI caches, SBOM/licence allowlists, Dockerfiles, and internal docs. Budget an hour or two of engineering time, not a sprint. The 4.6.0 bug fix also means that when ext-msgpack is absent, MsgpackCodec pulls in the userland rybakit/msgpack package — if we run any MsgPack path, that's a new transitive dependency appearing in our SBOM, which is another reason to just get off MsgPack.
• Release cadence as a mild signal — 4.5.0 and 4.6.0 landed nine days apart, both small and low-risk. This is healthy maintenance, not churn, but it reinforces that our upgrade cadence is coupled to theirs. Pin versions and batch upgrades rather than tracking releases individually.
• Decisions this should not drive — it should not be used to justify a Go migration on its own, to justify gRPC adoption, or as a reason to split services. It's a cost-reducer on a path we've already chosen. Likewise, neither the rename nor the MsgPack deprecation is a reason to accelerate or defer anything on the roadmap.

When to Consider This Package

Adopt (or rather, accept it as part of the stack) when:

• We are already on, or actively evaluating, RoadRunner as the PHP application server. This is the primary and almost only honest criterion — everything else is secondary.
• We have (or will have) a Go service exposing net/rpc-compatible methods and want PHP to call it without an HTTP/gRPC layer in between.
• We need binary or large-payload transfer where JSON-over-HTTP framing overhead is measurable — with the caveat that the binary-codec path is now Protobuf (MsgPack is deprecated), so we should be willing to own schema governance.
• We want a PHP ↔ Go bridge inside a single host/container (worker process to Go process) with no external broker or service discovery.
• PHP 8.1+ is acceptable (v4.x floor) and we're comfortable with ext-sockets or pipes.

Look elsewhere when:

• No RoadRunner and no Go service in the plan. Adopting Goridge alone means implementing the protocol on both ends — that's a research project, not a dependency.
• Service-to-service across network boundaries / multiple teams. Use gRPC or HTTP+JSON. You get TLS, auth, deadlines, load balancing, schema tooling, and mainstream observability, none of which Goridge provides.
• Asynchronous decoupling / durability is the actual need. That's a queue (RabbitMQ, SQS, Redis Streams), not an IPC codec.
• Security or compliance requirements are load-bearing. Goridge is a raw transport codec: no authn/authz, no encryption, no rate limiting. If those are on the roadmap, plan for a service mesh or private network, and get that in writing before committing.
• MsgPack is a hard requirement on either end. It is deprecated as of 4.6.0 and should be assumed to be removed in a future major. If a Go service or a persisted message format depends on MsgPack, that constraint needs to be resolved before adoption, not after.
• Team has no Go capability and no appetite to own a second runtime. The bridge cost is low; the operations cost (build pipelines, Go memory tuning, restarts, version lockstep) is not.
• Vendor-risk tolerance is low and dependency count is a board-level metric. Maintenance is concentrated in the RoadRunner/SpiralScout team; the release history shows version lockstep with RoadRunner releases ("Allow RoadRunner 2025", "support for RoadRunner v2024.1", and now requiring roadrunner/roadrunner), meaning your upgrade cadence is coupled to theirs. The rename into the roadrunner/ namespace improves the ownership signal — it is now unambiguously a first-party RoadRunner component rather than a sibling-brand package — but it does not widen the contributor base. Modest bus-factor consideration remains; mitigate by pinning versions and keeping the integration behind our own interface.

Migration notes (engineering action, PM owns the sequencing):

• 4.5.0 rename: swap the Composer requirement to roadrunner/goridge (or let the metapackage pull it) and re-run the suite; the codec API is unchanged, so the work is dependency hygiene, not code.
• 4.6.0 MsgPack deprecation: grep for MsgpackCodec and CODEC_MSGPACK in our code and in any Go peer. If there are zero hits, note it and move on — this release is a no-op for us. If there are hits, schedule a switch to JsonCodec (if payloads are small) or Protobuf (if we need compact/typed), and add a test that pins the wire format so the swap doesn't silently change behaviour.
• 4.6.0 RoadRunner constraint: confirm we resolve roadrunner/roadrunner, not spiral/roadrunner. The old name is on a deprecation path; if it's still in a lockfile or Dockerfile, fold it into the same clean-up ticket.
• SBOM/allowlist: audit lockfiles, CI caches, and licence tooling for the old spiral/* strings, and decide in advance whether rybakit/msgpack (the fallback dependency) is acceptable if it ever appears.
• Because the version line continues at 4.5.x/4.6.0 rather than resetting, these are semver-quiet but operationally meaningful for anyone requiring the package or codec by name. Call that out explicitly in the upgrade ticket so nobody judges risk from the "minor version" number alone.

How to Pitch It (Stakeholders)

One-liner: Goridge is the free, MIT-licensed plumbing that lets our PHP code call Go code in-process-fast instead of over HTTP — it comes bundled with RoadRunner, so the decision to make is about the runtime, not this library. (It now ships as roadrunner/goridge, and as of 4.6.0 its MsgPack codec is deprecated; if we're on JSON we do nothing.)

For executives: No purchase, no license cost, no new vendor. The strategic value is optionality: it lets us move our slowest workloads into Go one at a time, behind existing interfaces, without rewriting the product or standing up a new service mesh. The cost isn't the library — it's the operational maturity to run a second language runtime and keep its versions in step with ours. The recent releases are administrative: the namespace consolidation under the RoadRunner brand is a small positive for accountability, and the MsgPack deprecation is a routine modernization that costs us nothing if we're on JSON and one small scheduled task if we're not. Approve it as part of a worker-runtime decision with a defined pilot workload, not as a line item.

For engineering: It's a small, focused codec with a clean abstraction (Relay for transport, RPC for calls, pluggable codecs). Supports TCP, Unix sockets, and stdio pipes; binary and streamed payloads; structured service/message/transport error handling. Constraints to design around: PHP 8.1+, ext-sockets or pipes, no built-in auth/TLS, and a version cadence tied to RoadRunner releases. Wrap it behind an internal client interface so we can swap transports (or fall back to HTTP) without touching call sites, and pin both ends. Changed in 4.6.0: MsgpackCodec and Frame::CODEC_MSGPACK are deprecated — standardize on JSON for small calls and Protobuf where we need compact typed payloads (accepting the .proto/codegen/schema-evolution overhead that implies), and remove MsgPack references rather than starting new ones. When ext-msgpack is missing the codec now falls back to the userland rybakit/msgpack; verify whether that lands in our dependency tree. The package now requires roadrunner/roadrunner rather than spiral/roadrunner, so finish the namespace clean-up across lockfiles, CI caches, SBOM/allowlists, and docs in the same pass.

What not to promise: don't quote the 300k calls/sec benchmark as a product improvement. Promise "removes a network hop and a serialization layer on the specific workloads we move," and put a number on it only after a benchmark on our own payloads. Don't present the namespace moves as features or maturity milestones — they're housekeeping with a short maintenance tail. And don't describe the MsgPack deprecation as a capability loss; present it as the codec set settling on the two options we'd have chosen anyway.