Weave Code
Roadrunner Kv Laravel Package
spiral/roadrunner-kv
PSR-16 cache bridge for the RoadRunner KV plugin. Install via Composer, configure one or more kv drivers in RoadRunner, then use Spiral\RoadRunner\KeyValue\Factory over RPC to select a named store and set, get, or delete cached values. Ideal for RoadRunner-powered PHP apps.
:electric_plug: RoadRunner Key-Value storage SDK
Frequently asked questions about Roadrunner Kv
- What is spiral/roadrunner-kv used for?
- It is a PSR-16 cache bridge for the RoadRunner KV plugin. It lets PHP applications select a named KV store over RPC and use set, get, and delete through a familiar cache interface. It is intended for apps already running under RoadRunner, including Laravel workers on RoadRunner v3, not for traditional PHP-FPM deployments.
- How do I install spiral/roadrunner-kv in a Laravel app?
- Install it with Composer using spiral/roadrunner-kv, and optionally install spiral/roadrunner-cli as a dev dependency to fetch a compatible RoadRunner binary. Add at least one kv driver to your RoadRunner configuration, for example a memory driver named test. Then instantiate Spiral\RoadRunner\KeyValue\Factory with an RPC connection and call select('test') to get the PSR-16 cache.
- Does this package work with Laravel?
- Yes, but only when Laravel runs under RoadRunner with the KV plugin enabled. It is not a drop-in cache driver for standard Laravel PHP-FPM deployments. The evaluation positions it as a fit for Laravel workers on RoadRunner v3, and you should validate the integration in your worker setup before replacing existing cache usage.
- Can I use spiral/roadrunner-kv without RoadRunner?
- No. The package is a client bridge to the RoadRunner KV plugin and requires an existing RoadRunner runtime with the kv plugin configured. It is unsuitable for traditional PHP-FPM or non-RoadRunner stacks unless you introduce RoadRunner and the KV plugin. If you are not on RoadRunner, use Laravel's built-in cache drivers instead.
- How do I select a named KV store and set or get values?
- Create a Factory with an RPC connection to the RoadRunner server, then call select('test') using the driver name from your RoadRunner kv configuration. The returned cache supports PSR-16 operations such as set, get, and delete. For example, $cache->set('key', 'value') writes a value and $cache->get('key') reads it back.
- What changed with the rename to roadrunner/kv?
- The technical evaluation notes that the package was renamed to roadrunner/kv in v4.5.0, even though the README still shows spiral/roadrunner-kv. Treat this as a dependency migration: update Composer requirements, lockfiles, CI scripts, and internal docs. Confirm whether the old package name remains aliased and whether PHP namespaces or configuration keys changed before upgrading.
- Which RoadRunner versions does v4.5.0 support?
- v4.5.0 adds support for RoadRunner v3, which improves compatibility for Laravel and Symfony workers on that runtime. Compatibility with older RoadRunner versions must be verified before upgrading. The minimum supported RoadRunner and KV plugin versions are not stated in the provided context, so check upstream documentation and pin versions together.
- How does the client behave if the KV backend or plugin fails?
- The provided context does not define fallback behavior for Redis or KV backend outages, plugin misconfiguration, or version mismatches. Those failure modes are called out as primary risks, so you should run failure-injection tests and define fallback behavior for critical versus non-critical state. Avoid using it for critical shared state until you have validated outage behavior.
- Is spiral/roadrunner-kv production-ready for Laravel?
- It can be used in production for Laravel apps already operating RoadRunner v3, but adoption appears low and public production evidence is limited. Pin the package, RoadRunner, and KV plugin versions together, assign an internal owner, and canary a low-risk worker-state or cache workload first. Avoid bundling the package rename with unrelated runtime upgrades.
- What are alternatives to spiral/roadrunner-kv?
- If you are not on RoadRunner, use Laravel cache drivers such as Redis, database, file, or array instead. If you are on RoadRunner and need KV semantics, this package is the PSR-16 bridge for the RoadRunner KV plugin; alternatives would depend on your backend and whether you need a PSR-16 interface. Evaluate serialization, key-size limits, and outage behavior before replacing existing Redis or cache usage.
Weaver
How can I help you explore Laravel packages today?