Laravel Valkey Glide Laravel Package

Getting Started

Minimal path from zero to a working Valkey-backed cache in a Laravel app:

1. Install the package and its client dependency

   composer require sinemacula/laravel-valkey-glide:^1.2
   

   The GLIDE client ships as a native library (loaded via extension or FFI depending on your PHP build), so confirm your runtime satisfies the package's platform requirements before wiring config — a missing binary surfaces as a connection exception, not an install error.

2. Publish the config (if the package exposes one) and inspect what it registers:

   php artisan vendor:publish --provider="Sinemacula\LaravelValkeyGlide\...ServiceProvider"
   

   If no publishable config appears, the integration is driver-based: look in config/database.php for a valkey/glide connection entry and in config/cache.php for the store it adds. As of v1.2.0 the connection block also carries reconnect-strategy, cluster topology-check, and IAM keys — read the merged config, not just the stub.

3. Point a store at it

   // config/cache.php
   'default' => env('CACHE_STORE', 'valkey'),
   
   'valkey' => [
       'driver' => 'valkey-glide',
       'connection' => 'valkey',
   ],
   

4. Verify with a tinker round-trip:

   Cache::put('probe', 'ok', 60);
   Cache::get('probe'); // 'ok'
   

Where to look first: the service provider (what drivers it extends), then config/database.php for connection shape. Read those two before touching config — they tell you whether this is a cache-only driver, a full connection driver, or both.

First real use case: swapping the default cache store on a read-heavy app. This is the lowest-risk adoption point because Laravel's Cache contract hides the client, so a bad config is caught immediately and rollback is one env var.

Implementation Patterns

Store-level swap, not app-level rewrite. Treat the package as a driver behind Laravel's existing contracts (Illuminate\Contracts\Cache\Repository, session handler, etc.) rather than as a client you call directly. Code that stays on Cache:: / Session:: remains portable back to phpredis/predis if you need to bail out.

Per-store rollout. Run Valkey for a single non-critical store first rather than flipping CACHE_STORE globally:

'stores' => [
    'valkey' => ['driver' => 'valkey-glide', 'connection' => 'valkey'],
    'file'   => ['driver' => 'file', 'path' => storage_path('framework/cache')],
],

Then use Cache::store('valkey') in the specific call sites you want to migrate. This lets you measure latency and failure modes without a global blast radius.

Connection config belongs in config/database.php. Keep host/port/TLS/cluster settings there and reference the connection by name from the cache store. That way multiple stores (cache, sessions, rate limiter) share one connection definition instead of duplicating credentials.

Tune the reconnect strategy per workload. v1.2.0 lets you configure GLIDE's reconnect strategy. Web requests want fast failure and a hard timeout (a long reconnect stalls the response); long-running queue workers and Octane/Swoole workers want retries with backoff, because dying mid-job is worse than waiting. Set the strategy on the connection rather than relying on defaults, and give workers a lower retry ceiling than the CLI defaults if you also run cron tasks on the same connection definition.

Long-running processes: rely on client replacement, don't cache the raw client. v1.2.0 now closes replaced clients on reconnect. Any code that pulled the underlying GLIDE client out of the connection and held onto it across a reconnect is holding a dead handle. Resolve the connection per unit of work (Laravel's own resolution does this), and treat a cached client as invalidated after any reconnect.

Cluster topology checks for elastic clusters. If you point at a cluster whose membership can change under you (ElastiCache/MemoryDB cluster mode, autoscaling, failover, or managed maintenance), enable periodic topology checks on the connection. Without them the driver holds a stale slot map and you get MOVED/redirect errors after a reshard — the classic symptom is a burst of failures minutes after an otherwise-unrelated infrastructure event.

Sessions are the highest-value second target. Moving SESSION_DRIVER to Valkey gives you shared sessions across app servers and removes sticky-session requirements — but do it only after the cache store has run clean in production for a while, since session loss is user-visible in a way cache misses are not.

IAM auth (AWS-managed Valkey/Redis). With v1.2.0 you can express IAM auth declaratively in the connection block instead of injecting tokens yourself. Supply a complete iam block; the driver now validates it at connect time rather than silently connecting without the auth it was configured for.

Environment parity. Set the same connection values across local/dev/prod via env, and make the local default something that doesn't require the native client (e.g. file locally, valkey in staging/prod). Developers without the binary installed shouldn't be blocked on booting the app.

Testing. In phpunit.xml, force CACHE_STORE=array and keep test suites off the Valkey driver. Integration tests that genuinely need Valkey should be a separate, tagged group so CI can skip them when the client isn't available. Cluster/IAM reconnect paths can't really be unit-tested — cover them with a tagged integration suite against a throwaway cluster, or accept them as ops-verified.

Gotchas and Tips

Version floors moved — check your constraint. Laravel 13 support landed in v1.1.0; v1.2.0 is the current line and is the floor for the reconnect, topology-check, and IAM fixes. Pin ^1.2 if you're on Laravel 13 or want those fixes; note that v1.0.x will not resolve against Laravel 13, and v1.1.x lacks the bug fixes below.

A previously "working" IAM config may now fail at connect. The incomplete-IAM-block fix ([#84]) is a deliberate behaviour change: a partial iam block is now rejected instead of silently dropping IAM auth. If your config was missing a required key and still connected — because it fell through to another auth mechanism — upgrading will surface an exception at connection resolve. Audit IAM configs before deploying, and watch the first request after rollout rather than assuming a boot succeeds cleanly.

executeRaw on cluster connections changed routing. Raw commands now route per the cluster connection ([#80]) instead of the previous behaviour. If you wrote a workaround — pinning to a node, or sending raw commands via a non-cluster connection — remove it, or you'll be double-handling and possibly hitting the wrong node.

Native client availability is the #1 failure mode. GLIDE is not a pure-PHP client like Predis, so container images need the correct binary/extension for the target architecture. Symptoms of a mismatch are typically a class-not-found or a low-level FFI/extension error at container start rather than a clean ConnectionException. Bake the dependency into your base image and test it in CI, not just locally.

Don't retune reconnect under incident pressure. The new strategy knob is easy to reach for when you see connection churn, but aggressive retries during a cluster failover can turn a blip into a reconnect storm against a half-promoted node. Change it in staging against a simulated failover.

Queues and Horizon are likely out of scope. Laravel's redis queue driver and Horizon are built against phpredis/Predis semantics. Don't assume this package replaces them — verify explicitly before pointing QUEUE_CONNECTION at it. If it doesn't cover queues, plan to run Valkey for cache/sessions and keep a separate Redis-compatible connection for queues.

Cache tags and flush. If you rely on Cache::tags(), confirm the store advertises tag support. Tag operations on non-tagged stores throw rather than degrade silently — a good thing, but a nasty surprise mid-deploy if you migrate a store that previously had tag support.

Key prefix collisions. Laravel applies a prefix from config/cache.php. If you share one Valkey instance between multiple apps or between cache and sessions, set distinct prefixes per store or you'll get cross-environment key bleed that's very hard to trace.

Debugging order of operations: (1) can you PING the server with a plain client, (2) does the Laravel connection resolve (DB::connection('valkey') or the package's equivalent), (3) does the store round-trip. Isolating client-vs-config-vs-server in that order saves a lot of time. For cluster issues, add a step zero: confirm the slot map is current by checking for MOVED/redirect errors in logs before blaming the driver.

Extension points to check before forking: the service provider is the natural place to see whether the driver is registered via Cache::extend() / Session::extend() (composable, easy to wrap with a decorator for logging or metrics) or hard-wired (less flexible). Wrapping the driver with a decorator that times operations — and counts reconnects, now that they're configurable — is the cheapest way to get production insight without touching the package.