Redis for PHP

When to use

• The user wants to cache expensive query results, computed values, or fragments in memory to reduce database load and speed up responses.
• The user needs to choose or configure a Redis client for PHP — phpredis (the C extension) versus predis (pure PHP) — or connect PHP to a Redis server or cluster.
• The user wants to store sessions, rate-limiter counters, locks, or a queue backend in Redis, and needs the right data structure, expiry, and persistence.

When NOT to use

• Do not use Redis as the primary durable store for records you cannot afford to lose; keep the source of truth in a relational or document database.
• Do not reach for Redis when the workload needs ad-hoc queries, joins, secondary indexes, or transactions across many rows; use a relational database instead.

Core guidance

• Prefer phpredis in production, predis when you cannot install extensions — Use the phpredis C extension for production throughput; fall back to predis (pure PHP) only when you cannot install PHP extensions, such as some managed hosts.
• Set a TTL on every cache key — Give every cache entry an explicit TTL (SET key val EX 3600 or SETEX) so stale data expires and memory is reclaimed automatically.

Decision Engine

Walk this section before choosing an implementation path.

Can you install PHP C extensions on the host, and do you need horizontal scale
or high availability beyond a single Redis node?

├── Dataset or write load exceeds one node: → Redis Cluster — data sharded across nodes with hash slots; use hash tags to keep
related keys co-located and accept that multi-key ops must stay in one slot.

├── Can install extensions, single node is enough: → phpredis (C extension) against a single primary — the fastest, lowest-memory
client and the default choice for throughput on one node.

├── Cannot install extensions: → predis (pure PHP) — no extension to compile, easy to deploy on locked-down
managed hosts; accept lower throughput than phpredis.

└── Need failover but data fits one master: → Redis Sentinel with a primary/replica set — automatic failover and read
replicas while the dataset still fits one master's memory.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Cache Aside

Progress:
- [ ] Compose a namespaced, versioned key (`user:v1:42:profile`) and `GET` it; on a hit,
decode and return the cached value without touching the database
- [ ] On a miss, take a short `SET lock NX EX` so only one worker recomputes, load from
the database, then `SET key value EX <ttl>` (add jitter) and release the lock
- [ ] When the underlying record changes, `DEL` the cache key (or bump the key version)
inside the same write path so the next read repopulates fresh data

1. Compose a namespaced, versioned key (user:v1:42:profile) and GET it; on a hit, decode and return the cached value without touching the database.
   • Verify: A warm key returns from Redis and the database query is skipped.
2. On a miss, take a short SET lock NX EX so only one worker recomputes, load from the database, then SET key value EX <ttl> (add jitter) and release the lock.
   • Verify: Concurrent misses trigger one database load and the value is stored with a TTL.
3. When the underlying record changes, DEL the cache key (or bump the key version) inside the same write path so the next read repopulates fresh data.
   • Verify: Updating the record makes the next read miss the cache and reload from the database.

Workflow: Configure Client

Progress:
- [ ] Install the phpredis extension (`pecl install redis`), then in code `pconnect()`
to the host and `AUTH` if required, setting connect and read timeouts
- [ ] In redis.conf set `maxmemory` to a safe ceiling, choose `maxmemory-policy`
(allkeys-lru for cache), and set persistence (RDB save points and/or `appendonly yes`)
- [ ] Run a smoke test that writes and reads a TTL key, then check `INFO` for
used_memory, evicted_keys, and connected_clients to confirm healthy operation

1. Install the phpredis extension (pecl install redis), then in code pconnect() to the host and AUTH if required, setting connect and read timeouts.
   • Verify: $redis->ping() returns true and the connection is persistent across requests.
2. In redis.conf set maxmemory to a safe ceiling, choose maxmemory-policy (allkeys-lru for cache), and set persistence (RDB save points and/or appendonly yes).
   • Verify: CONFIG GET maxmemory and maxmemory-policy return the intended values.
3. Run a smoke test that writes and reads a TTL key, then check INFO for used_memory, evicted_keys, and connected_clients to confirm healthy operation.
   • Verify: The smoke key round-trips, expires on schedule, and INFO shows stable memory and client counts.

Best practices

• For a pure cache, set maxmemory and maxmemory-policy allkeys-lru (or allkeys-lfu); for a store mixing cache and durable keys, use volatile-lru so only keys with a TTL are eligible for eviction
• Use RDB snapshots when a cache can tolerate losing the last few minutes on crash; enable AOF (appendonly yes, appendfsync everysec) when you need near write-durability; run both for fast restarts plus a durable log
• Under PHP-FPM, open persistent connections with pconnect() (or a pool in long-running workers) so each request reuses a socket instead of a fresh handshake
• When issuing many commands, batch them with a pipeline (multi(Redis::PIPELINE)) or multi-key ops like MGET/MSET instead of one blocking call per key

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Using KEYS in production blocks the server — Redis processes commands one at a time, so a full scan stalls all concurrent requests. Fix: Iterate with SCAN/HSCAN/SSCAN using a cursor and small COUNT, or maintain a purpose-built index Set instead of scanning at runtime.
2. Cache keys without TTL leak memory — Redis never removes a key on its own without a TTL or an eviction policy that targets it. Fix: Always SET ... EX <seconds> (or SETEX) for cache data, and configure an eviction policy so keyless growth cannot OOM the instance.
3. Non-atomic check-then-set races between requests — The gap between read and write lets a concurrent client change the value, corrupting locks and counters. Fix: Use atomic primitives — INCR/INCRBY for counters, SET key val NX EX for locks, or a Lua script via EVAL for multi-step logic that must be atomic.
4. Mismatched serialization corrupts cached values — Redis stores opaque bytes, so writer and reader must agree on the encoding. Fix: Pick one serialization strategy per key namespace, set the phpredis serializer consistently, and version or prefix keys when you change the format.

Performance notes

• Using KEYS in production blocks the server — Calling KEYS pattern* (or SMEMBERS on a huge set) scans the whole keyspace in one blocking pass, freezing the single-threaded server for every other client.
• Cache keys without TTL leak memory — Writing cache entries with no expiry lets the keyspace grow without bound until Redis hits maxmemory and either evicts unpredictably or rejects writes.
• Match the maxmemory-policy to the workload — For a pure cache, set maxmemory and maxmemory-policy allkeys-lru (or allkeys-lfu); for a store mixing cache and durable keys, use volatile-lru so only keys with a TTL are eligible for eviction.
• Reuse connections with pconnect or a pool — Under PHP-FPM, open persistent connections with pconnect() (or a pool in long-running workers) so each request reuses a socket instead of a fresh handshake.
• Prefer phpredis in production, predis when you cannot install extensions — Use the phpredis C extension for production throughput; fall back to predis (pure PHP) only when you cannot install PHP extensions, such as some managed hosts.
• Pipeline or MGET batches instead of chatty round-trips — When issuing many commands, batch them with a pipeline (multi(Redis::PIPELINE)) or multi-key ops like MGET/MSET instead of one blocking call per key.
• Set a TTL on every cache key — Give every cache entry an explicit TTL (SET key val EX 3600 or SETEX) so stale data expires and memory is reclaimed automatically.

Production checklist

• Counters use INCR, locks use SET NX EX, and multi-step logic uses a Lua script rather than a read-modify-write race.
• maxmemory is capped and an eviction policy (allkeys-lru or volatile-lru) is chosen, never the default noeviction for a cache.
• Hot paths use SCAN or an index Set instead of KEYS, and no single key holds an unbounded blob or collection.
• RDB and/or AOF are configured to match how much recent data the workload can afford to lose on restart.
• The app uses pconnect or a pool with sane timeouts so it does not open a fresh socket per operation.
• Every cache entry is written with an explicit TTL so stale data expires and memory is reclaimed.

Version notes

• LFU eviction and phpredis serializers (PHP >=7.4) — allkeys-lfu/volatile-lfu eviction policies are available from Redis 4.0, and the phpredis igbinary serializer requires the igbinary extension; older Redis supports only LRU/random/ttl policies.
• phpredis and predis both support PHP 7.4+ (PHP >=7.4) — phpredis 5.x and predis 1.1/2.x both run on PHP 7.4 and up; predis 2.x drops PHP 7.2 support, so pin predis 1.1 only if you must stay on very old PHP.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/databases/redis.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: audit/performance, audit/project-analysis, laravel/queues, security/rate-limiting

Skill contract

Produces: cache.redis-configured, infra.redis-connected
Risk: medium · Confidence: 0.9