Laravel Phpredis Laravel Package

Getting Started

This release is about connection plumbing, not new APIs — so the fastest way to get value is to point the package at a Redis instance and confirm which of the new options you actually need.

1. Install and publish config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=redis-config   # check README for the exact tag
   

2. Set the minimum env vars: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB. Leave the new timeout / persistent / prefix keys at their defaults on the first pass — changing them all at once makes failures hard to attribute.
3. First use case: wire it as the cache store (CACHE_DRIVER=redis) rather than jumping straight to queues. Cache traffic is easy to generate and easy to verify with redis-cli MONITOR, so it proves connectivity, auth, and prefixing in one shot.
4. Where to look first:
   • config/redis.php (or the package's config file) — the connection array, especially default vs named connections.
   • The service provider — confirm how the manager binds into the container and whether it replaces Laravel's redis binding.
   • README's connection-options table, which now documents timeout, persistent, and prefix.

Implementation Patterns

Named connections per workload. Keep default for general use, then add cache, session, and queue connections. In this release each connection can carry its own timeout, persistent, and prefix, so you can isolate a slow-report queue from latency-sensitive session reads without separate Redis servers.

Tuning the new options deliberately.

'connections' => [
    'default' => [
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', 6379),
        'database' => env('REDIS_DB', 0),
        'timeout' => 1.0,        // new
        'persistent' => false,   // new — opt in only where measured
        'prefix' => env('REDIS_PREFIX', 'app:'), // new
    ],
],

Set timeout low (fractions of a second) for request-path connections and higher for queue workers, where a hung connect is better than a failed job. Enable persistent for high-throughput, short-lived workers; leave it off for web requests until you have numbers showing connection setup is the bottleneck.

RedisCluster. The new cluster support expects a hosts array rather than a single host. Model it as its own connection and only switch default to it once every call site is cluster-safe (see gotchas — multi-key ops and SELECT are the usual breakers). Cluster connections generally should not set database.

Per-tenant prefixing. prefix is the cleanest lever for shared infrastructure: derive it at runtime from the tenant in a service provider or a small config override, keeping each tenant's keys namespaced without spawning connections.

Lumen. Register the provider in bootstrap/app.php, enable facades if you rely on the Redis facade, and copy the config file into config/ manually — Lumen has no vendor:publish. Because Lumen boots config differently, set connection values before registering the provider, not in a later middleware.

Integration tips. Point queue.php and session.php at the named connections rather than the default, so tuning one doesn't silently retune the others. For tests, use a separate database index and a distinct prefix, then flush by prefix — a FLUSHDB against a shared instance is how test suites wipe staging data.

Gotchas and Tips

• Double prefixing. Laravel's cache layer applies its own prefix on top of the connection prefix. Combining a non-empty connection prefix with a cache prefix produces keys like app:laravel_cache:foo. Pick one layer to own the namespace.
• Persistent connections ignore some hygiene. A persistent connection survives between requests, so SELECT-ing a different database or changing auth mid-process may not behave as expected. Don't flip persistent on per-request while code varies database.
• Cluster + database don't mix. Redis Cluster only has db 0. Any connection with a non-zero database pointed at a cluster will fail or behave inconsistently — and multi-key commands (MGET, EVAL, pipeline blocks, SCAN loops) need hash-tag key design to avoid CROSSSLOT errors.
• timeout semantics. In most clients this is the connect timeout, not the command read timeout. If you're chasing slow commands, raising timeout won't help — look at the read/response timeout option or the client-specific setting.
• Client parity. RedisCluster support and persistent behave differently between phpredis and Predis. Confirm which extension is installed in each environment (php -m | grep redis) before assuming a config key takes effect.
• Lumen edge cases. Facades must be explicitly enabled, and config values coming from .env need Dotenv loaded before provider registration. If the connection resolves but auth fails, this ordering is the usual culprit.
• Debugging playbook. Start with redis-cli MONITOR on the target instance to confirm the package is actually reaching it and to see the real (prefixed) key names. Then check Redis::connection()->client()->getLastError() after a failing call. For cluster issues, CLUSTER INFO and CLUSTER NODES tell you whether the problem is client config or slot coverage.
• Extension points. Custom connectors can be registered via the Redis manager's extend mechanism, which is the right place to add instrumentation (timing, key logging) before reaching for a fork. A decorator around the connection is usually safer than subclassing the manager.
• Upgrade safety. The three new options are additive and default-off, so existing configs should keep working; still, diff your published config against the new stub and confirm nothing was renamed. Run one deploy with persistent off to isolate any regression to the new code path rather than inherited config.