Kv Laravel Package

Technical Evaluation

What it is. roadrunner/kv is a thin PHP SDK over the RoadRunner KV plugin's RPC protocol. RoadRunner is a Go application server that replaces PHP-FPM; the KV plugin exposes a unified key-value API in front of Redis, Memcached, BoltDB, or in-memory stores, with connection pooling and serialization handled in Go. The package gives PHP workers a client (KV class, KVInterface, DTOs like Item/ItemsList) plus a namespace-scoped API.

Architecture fit — conditional, and the condition is heavy. This package has no standalone value. It is inoperable outside a RoadRunner worker process: it speaks the worker↔server RPC protocol, not Redis/Memcached wire protocols. The realistic Laravel path is Laravel Octane with the RoadRunner driver. If our stack is PHP-FPM, nginx, and predis/phpredis, adopting this package means adopting a new application server, a Go binary in the deploy artifact, and a .rr.yaml config surface — an infrastructure program, not a composer require. If we are already on Octane + RoadRunner, the marginal integration cost drops to hours and the value proposition (pooled connections, lower per-op latency, backend-agnostic API) becomes legible.

Contract mismatch with Laravel. The SDK is a low-level KV client, not a PSR-16 or PSR-6 implementation, and it does not implement Illuminate\Contracts\Cache\Repository. Expect to write an adapter. Critically, verify feature gaps before assuming parity with the Redis driver: atomic increment/decrement, cache tags, atomic locks, TTL semantics on mset, and remember/rememberForever behavior all need explicit confirmation. Laravel's cache contract is richer than "get/set/delete," and a partial adapter that silently degrades will surface as production correctness bugs, not performance bugs.

Access boundary risk. Reads and writes are scoped to RoadRunner worker processes. Schedulers, queue workers not running under RoadRunner, artisan commands, and sidecar services cannot use this SDK. Anything needing KV access outside the RR runtime requires a second, parallel code path to the same backend — which reintroduces the very client library this package was meant to displace.

Technical risk — high, concentrated in three areas.

1. Maturity. 11 stars, 0 dependents, and a package score of 19.5 place this firmly in the unvalidated tier. MIT licensing is clean, and the RoadRunner org (Spiral Scout) is a credible steward, but the KV plugin specifically has negligible community mass. Bus factor is effectively the core maintainers.
2. Version coupling. The PHP SDK and the RoadRunner binary's KV plugin must agree on an RPC/protobuf contract. Upgrades are lockstep: bumping one side without the other is a runtime failure mode. Note the namespace/package rename history (spiral/roadrunner-kv → roadrunner/kv), which already implies churn for anyone who adopted early.
3. Metadata integrity. The listed last-release date is 2026-10-19 — future-dated. Treat this as a pipeline anomaly and verify the actual release history and commit cadence before reading it as a liveness signal. A stale repo and a broken release feed look identical from the outside.

Key questions for the vendor/team.

• Are we on Octane + RoadRunner today, or is that a roadmap item? (If no, stop here.)
• Which backend sits behind the plugin, and does it need to be shared with non-RoadRunner consumers?
• Do we depend on tags, locks, atomic counters, pub/sub, or Lua scripting? If yes, the SDK's abstraction likely cannot express them.
• What is our measured p99 delta between phpredis and a pooled Go client at current traffic? If sub-millisecond, the benefit is unquantified.
• What is our tolerance for pre-1.0 SDK churn across a 12-month horizon?

Integration Approach

Stack fit. Viable only in a Laravel 10/11 + Octane (RoadRunner driver) + PHP 8.1+ environment. Not viable for FPM, not viable for shared hosting, not viable for teams without Go-binary deployment experience.

Prerequisites and sequencing. The order matters; each step is a gate.

1. Adopt Octane + RoadRunner first, independently. Stabilize worker lifecycle, memory behavior, and .rr.yaml in production for a full release cycle. Do not co-mingle this with the KV decision.
2. Select the backend deliberately. Redis or Memcached for multi-node; BoltDB/in-memory are single-node only and unsuitable for anything horizontally scaled. This choice, not the SDK, determines the scaling story.
3. Install roadrunner/kv alongside roadrunner-php/roadrunner (or spiral/roadrunner-worker on older pins), matching versions explicitly and pinning both in composer.json with a caret on the minor.
4. Configure the kv section of .rr.yaml — driver, addresses, pool size, timeouts — and treat that file as reviewed infrastructure config, not application config.
5. Build the Laravel glue: a service provider binding KVInterface as a singleton, a config/kv.php that mirrors .rr.yaml (two sources of truth is a real hazard; generate one from the other if possible), and a facade.
6. Write the adapter, either a PSR-16 wrapper or a partial Repository implementation. Publish explicitly which methods are unsupported and make them throw rather than no-op.
7. Pilot on non-critical, cache-shaped data — rate-limit counters, feature-flag snapshots, session blobs with a durable fallback. Never on data where loss is unrecoverable.

Migration path. Do not migrate existing cache traffic wholesale. Run the KV path in parallel behind a config flag on one bounded workload, compare hit rates, latency, and error rates against the incumbent for two weeks, then expand or revert. Keep the existing Redis/phpredis client in the dependency tree as the fallback and as the escape hatch for unsupported operations.

Compatibility notes. Enforce a version matrix in CI: PHP version × RoadRunner binary version × SDK version. Add a smoke test that boots RoadRunner and round-trips a key; without it, protocol skew ships silently.

Operational Impact

Maintenance. Low code churn, high surface area. The application code is small; the owned infrastructure is not — a Go binary in the build artifact, a .rr.yaml to govern, and a third-party protocol contract to track. With 0 dependents, we are effectively an early adopter absorbing the cost of discovering breakage. Budget for reading RoadRunner release notes on every bump, not just this package's.

Support. Upstream support is community/org-driven with no commercial SLA in evidence. Internal support requires at least one engineer who can debug Go-side plugin behavior and read the RPC layer, not just PHP. That is a single point of failure unless deliberately duplicated.

Scaling. Scales exactly as far as the chosen backend. Redis/Memcached behind a pooled Go client is a reasonable high-throughput design and likely the package's strongest technical argument. BoltDB or in-memory silently caps you at one node — a trap worth documenting in the ADR. Also confirm plugin pool sizing against Octane worker count; undersized pools produce queueing that looks like backend latency.

Failure modes to instrument.

• Plugin unavailable or misconfigured → every KV call throws inside the request path. No built-in circuit breaker; wrap the adapter and degrade to a null/fallback cache rather than 500-ing.
• RPC timeout under load → latency spikes that present as application slowness, not as cache errors. Alert on KV call duration, not just error count.
• Binary/worker restart → connection re-establishment; verify behavior on RoadRunner worker recycling, which Octane does by default.
• Namespace collision → if the backend is shared, namespace discipline is manual and unenforced.
• Silent semantic gaps → an adapter that returns null for unsupported increment will corrupt counters without erroring.

Ramp-up. Assume 2–3 engineer-days to first working integration for someone fluent in Octane, and 1–2 weeks to production-grade (adapter hardening, observability, fallback, failure drills). For a team without Octane experience, front-load the RoadRunner learning curve separately — it is the dominant cost, and this package is downstream of it.

Recommendation. Do not adopt as a strategic dependency. The package is a narrow optimization whose payoff is real only inside an existing RoadRunner footprint, and whose adoption cost outside one is an order of magnitude larger than 11 stars and 0 dependents justify. Sanction it as a pilot-only evaluation, gated on (a) Octane + RoadRunner already in production, (b) a verified release cadence after resolving the future-dated release metadata, and (c) an explicit inventory of cache features we are willing to forgo. If any gate fails, use the native phpredis/predis client — it works in every process, needs no new runtime, and has a support ecosystem this package cannot match.