Goridge Laravel Package

Technical Evaluation

Architecture fit Unchanged at the architectural level: Goridge is a transport/codec layer, not a framework. It plugs in as the wire protocol between a Laravel/PHP application and one or more Go services, and it fits where the product already has (or plans) a Go sidecar, worker, or service — especially under RoadRunner. It remains a poor fit as a standalone "RPC framework." 4.6.0 does, however, narrow the shape of the fit: with MsgPack deprecating, the package's codec story collapses toward JSON plus Protobuf/binary, which is fine for RPC-shaped request/response but is a real consideration if anyone was drawn to Goridge specifically for cheap binary payloads. Realistic usage stays "Laravel app calls a Go compute service over Unix socket or pipes."

Integration feasibility Install remains composer require roadrunner/goridge on PHP 8.1+ for the v4 line; the PHP surface (Relay::create(), RPC::call(...)) is unchanged, so a spike is still hours, not sprints. Two new integration costs land in 4.6.0. First, the internal requirement moved from spiral/roadrunner to roadrunner/roadrunner — the org rename has now propagated into the runtime dependency, not just our own composer.json, which means the cutover sweep has to cover the entire RoadRunner family (roadrunner-cli, roadrunner-http, worker packages, CI images, Dockerfiles). Second, MsgpackCodec and Frame::CODEC_MSGPACK are deprecated, so any payload design we do now should not target MsgPack. Integration cost still sits on the Go side: build or wrap a net/rpc-compatible service, match the Goridge Go module version, define the payload contract — and now also confirm the Go peer is not MsgPack-only.

Technical risk

• MsgPack deprecation (new in 4.6.0). MsgpackCodec and Frame::CODEC_MSGPACK are deprecated. Code keeps working at 4.x (deprecation, not removal), but the forward path is JSON or Protobuf. Our prior guidance named MsgPack as the choice for binary/large payloads — that recommendation is now stale and must be replaced before Phase 2 contract lock-in. The open question is the removal horizon: a v5 that deletes the constant is a hard runtime break for anyone who shipped MsgPack frames, and it interacts badly with the PHP↔Go symmetry requirement, since the Go module's timeline may differ from the PHP package's.
• Pure-PHP MsgPack fallback is a dead end (new in 4.6.0). The bug fix initializes MsgpackCodec with rybakit/msgpack when ext-msgpack is absent. Useful if we are already on MsgPack and running without the extension, but do not build on it — the fallback exists to keep a deprecated codec limping, not as a supported performance path.
• Rename sweep is wider than previously scoped (new in 4.6.0). spiral/roadrunner → roadrunner/roadrunner inside the package means the rename is a stack-wide event. Anything pinned, mirrored, SBOM'd, or allowlisted under spiral/* needs auditing, not just the Goridge requirement itself.
• Package identity change (from 4.5.0, still open). spiral/goridge → roadrunner/goridge. Does the new package replace/provide the old one; does the old name still receive releases; did the Goridge\ PHP namespace change or only the Composer name. If both names remain installable with a shared namespace, a monorepo can install duplicate code or collide.
• Version gap widened. The last fully reviewed baseline is 4.2.2. We are now jumping 4.3.x, 4.4.x, 4.5.0, and 4.6.0. Two of those are known to be non-trivial (rename, codec deprecation), which is strong evidence that "assume rename-only" would have been wrong. Treat the full changelog as required reading and pick a target pin deliberately.
• Version coupling to RoadRunner. Now doubly explicit — shared org name plus a direct dependency on roadrunner/roadrunner. Major upgrades (v3 → v4) were breaking; pin explicitly and treat upgrades as planned work.
• Adoption signal. Still positive: activity within ~9 days of the previous release, a rename follow-through, and a real bug fix. Maintenance looks alive. Stars/dependents remain a weak proxy; validate issue response directly.
• Protocol symmetry risk. PHP and Go codec versions must match; mismatch fails at runtime, potentially only under load or on large payloads. Codec deprecation adds drift surface.
• Team shape. Still requires Go fluency on at least one engineer.
• Not a Laravel-native integration. No service provider, no queue driver, no Eloquent hooks — all plumbing is ours.

Key questions

• Are we already on spiral/goridge or spiral/roadrunner anywhere in the estate? What is the cutover plan, and do the old names still get security fixes during our transition window?
• Did the PHP namespace change, or only the Composer package name? (Determines whether this is a lockfile edit or a code-touching change.)
• What is the MsgPack removal timeline, and does the Go module share it? Deprecated-in-4.6 implies removed-in-v5 — get a date or a stated policy before we design contracts.
• Which codec do we standardize on now — JSON for debuggability, Protobuf for payload size — and does our Go peer support it today?
• Are we already running RoadRunner? If so, the roadrunner/roadrunner requirement change is an immediate install-graph issue, not a future one.
• What shipped in 4.3.x, 4.4.x, and 4.5.0 that we are jumping over beyond the rename?
• Which specific capability justifies the cross-language boundary — CPU-heavy work, streaming/binary payloads, or high-frequency calls where HTTP/REST overhead matters? (If the honest answer was "binary payloads via MsgPack," re-litigate the business case.)
• Is there a Go owner, or are we hiring/partnering?
• What are the latency, throughput, and blast-radius targets for the first capability?
• What's the version pin and upgrade policy across PHP and Go halves? Is there an existing HTTP/gRPC path we can keep as a fallback?

Integration Approach

Stack fit Unchanged for Laravel 10/11 on PHP 8.1+, RoadRunner (or equivalent long-running worker model), and a Go service over Unix sockets (lowest latency, simplest failure isolation) or pipes (suits RoadRunner worker topology). TCP relays ease container/Kubernetes networking but add a hop and TLS/firewall surface. Codec guidance changes: JSON becomes the default for debuggability and schema evolution, Protobuf for binary/large or latency-sensitive payloads, and MsgPack is removed from the decision set for any new work. Note that the ext-msgpack-optional story is no longer a reason to pick Goridge — codec optionality is shrinking, not growing.

Migration path

• Phase 0a – Rename reconciliation, widened (days, not weeks): Confirm the old/new relationship for both spiral/goridge→roadrunner/goridge and spiral/roadrunner→roadrunner/roadrunner. Update composer.json, regenerate the lockfile, refresh CI/composer caches, private Satis/Packagist mirror entries, Docker layer caches, SBOM/allowlist entries, and internal docs and snippets. Add a smoke test asserting exactly one Goridge implementation and exactly one RoadRunner family is installed.
• Phase 0b – Spike (1–2 weeks): Trivial Go net/rpc echo service, called from a Laravel command over Unix socket and over pipes; measure p50/p99 and failure behavior. Run it in JSON and Protobuf, not MsgPack. Confirm codec symmetry. Fold in a read of the 4.3–4.5 changelogs here.
• Phase 0c – Codec disposition (new): If MsgPack is in use anywhere, inventory call sites and schedule the codec migration as an explicit work item tied to the deprecation, not as incidental cleanup. If it is not in use, record a written decision to exclude it so it does not get reintroduced by copy-paste.
• Phase 1 – Non-critical capability: Offload a low-blast-radius workload (thumbnails, PDF rendering, async audit logging, CPU-bound reporting) behind a feature flag, with the existing HTTP path intact as fallback.
• Phase 2 – Contract lock-in: Formalize request/response schemas, codec choice, error taxonomy (transport vs. service vs. message), timeouts, retry semantics; add contract tests across the PHP↔Go boundary. Codec is now an explicit contract field with a documented change process.
• Phase 3 – Promote a revenue-adjacent capability only after p99, error budget, and rollback drills are proven in staging.

Compatibility PHP 8.1+ for the v4 line; PHP 7.x only on v3-and-below (out of scope). Match the Goridge Go module to the PHP major version. One codec per service, documented — and the allowed set is now JSON and Protobuf. Mixed codecs per relay work but multiply the test matrix, and mixing in a deprecated codec multiplies it with an expiry date. Windows works but is not a production target for a Laravel deployment. Rename compatibility remains the open item for both package names: verify alias, replace, or deprecated-and-frozen before committing to a cutover date.

Sequencing

1. Resolve both rename questions (Goridge alias/replace/frozen; RoadRunner spiral/*→roadrunner/* impact on our runtime) and confirm namespace stability — this is the first gate.
2. Get the MsgPack removal policy and pick the standard codec.
3. Decide RoadRunner adoption — it determines whether Goridge is a "free" transitive dependency or a deliberate architectural addition, and now also whether the roadrunner/roadrunner requirement lands on us immediately.
4. Secure Go ownership (hire, contract, upskill) before code.
5. Review 4.3.x–4.5.0 changelogs and pick the target pin (not 4.5.0-and-assume).
6. Define the payload contract, codec, and error taxonomy before Phase 1.
7. Introduce version pinning in composer.json and go.mod, add both to the upgrade calendar.
8. Only then expand beyond the first capability.

Operational Impact

Maintenance Two runtimes, two dependency graphs, two upgrade streams, and now two package names in circulation across the ecosystem — plus a second rename one layer down. Goridge itself stays low-maintenance (small surface, stable API at v4), but its version is coupled to RoadRunner's release train — a RoadRunner upgrade can force a Goridge upgrade can force a Go module upgrade — and that chain is now visible in composer.json rather than implicit. Add the rename sweep to the backlog and budget the recurring quarterly alignment task. Add a codec-hygiene item: a periodic grep for MsgpackCodec / CODEC_MSGPACK / ext-msgpack so deprecated usage does not silently accumulate between majors. CI must build and test both PHP and Go halves. We still own the integration; the org move makes internal ownership more defensible to stakeholders but does not transfer it.

Support Primary maintainers are the Spiral/RoadRunner team, now publishing under the roadrunner-php org — a clearer support surface and a modest de-risking of the "will this be maintained" question. Velocity supports that read: 4.6.0 landed nine days after 4.5.0 with a fix and a deprecation rather than a stall. Community support remains the RoadRunner Discord; no formal SLAs, and no published deprecation-to-removal SLA either — which is why the MsgPack timeline has to be asked for rather than assumed. Plan for internal ownership of the integration plus a documented escalation path into the RoadRunner project. MIT license and a small codebase keep fork-and-patch viable, but only if someone on the team reads PHP and Go — and note a fork would now inherit the deprecated codec, so a fork is a maintenance liability on the codec axis too.

Scaling Unchanged and unaffected by 4.6.0. The "300k calls/sec over 20 threads" figure is raw protocol throughput on a benchmark rig, not application throughput. Real limits come from Go service concurrency, PHP worker count under RoadRunner/FPM, and relay connection topology. Default RPC is single-relay and synchronous; concurrency comes from many PHP workers each holding a relay, or the MultiRPC async relay. Plan connection counts per worker, socket backlog, and file-descriptor limits. Large binary payloads still work but need memory sizing on both sides — and the practical way to move them is now Protobuf or JSON-with-binary-encoding, not MsgPack, which may change size/CPU budgets on the Go side and should be re-measured in the spike rather than carried over from prior assumptions.

Failure modes

• Deprecated-codec decay (new). MsgPack paths continue to work at 4.x but do not receive new investment and will disappear in a future major. The failure is deferred, not absent: the break lands during an unrelated upgrade window unless the migration is scheduled. Detect with a CI grep and a deprecation-warning check on the test suite.
• Codec asymmetry after deprecation (new). A Go peer that still speaks MsgPack while PHP migrates to JSON is a runtime-only failure, often payload-size-dependent. Enforce one codec per service with a startup handshake test.
• Rename-layer failure (widened). Pinned CI images, private mirrors, allowlists, or Dockerfiles referencing spiral/roadrunner break the build at the worst time — after an unrelated upgrade, because the requirement changed inside Goridge. Fix during Phase 0a, not during an incident.
• Duplicate/split dependency. One monorepo with some services on spiral/goridge and others on roadrunner/goridge can install two copies of the same code, or collide if the namespace is shared. Assert on the dependency tree in CI.
• Transport failures: socket timeouts, refused connections, broken pipes (notably if the Go process crashes). Wrap with timeouts and circuit breakers.
• Service-level exceptions: Go method error surfaced as a service exception on the PHP side; map into Laravel-idiomatic exceptions and log with correlation IDs.
• Message-level errors: malformed payloads, codec mismatch, oversized frames — often only visible in staging if not contract-tested.
• Go panics / process death: pipe relay has panic handling, but a killed process breaks in-flight calls; design idempotency and retry at the capability level.
• Silent version skew: PHP and Go codec versions drift after an unrelated upgrade — enforce via lockfiles and a startup handshake test.

Ramp-up Engineers still need roughly a week to be productive with the Goridge PHP API and one to two weeks on the Go net/rpc side (more with no Go exposure). Documentation was refreshed in 4.5.0 and 4.6.0 keeps the package current, which helps — but older blog posts, StackOverflow answers, and internal snippets now show both the wrong composer require line and MsgPack codec examples that are deprecated on arrival. Onboarding material must be updated deliberately to steer new engineers to JSON/Protobuf; the examples/ directory is still the de facto reference and should be checked for MsgPack samples before it is handed to a new hire. Produce an internal runbook covering relay selection, codec choice and change policy, timeout/retry semantics, the PHP↔Go contract test process, and the package-name policy before Phase 2; that runbook, more than the library itself, determines whether the integration stays cheap.