Download the PHP package idct/php-rapid-cache-client without Composer

IDCT Rapid Cache Client

IDCT Rapid Cache Client is a high-performance Redis-backed caching library for PHP. At its core it is a clean PSR-16 (SimpleCache) implementation, so it drops straight into any framework or library that speaks the standard cache contract. On top of that baseline it adds the features real applications keep reaching for but PSR-16 leaves out: tag-based grouping and invalidation, FIFO queues, sets, sorted sets, and atomic counters - all exposed through the CacheServiceInterface contract.

The package ships two clients that share the same PSR-16 + tagging surface but differ in how values land in Redis:

• RapidCacheClient — the general-purpose client. Stores any serializable PHP value (objects, nested arrays, DateTime, …) as a single Redis STRING using the compact binary ext-igbinary serializer. Adds queues, sets, sorted sets, and whole-value counters on top.
• HashRapidCacheClient — purpose-built for flat associative arrays of scalars. Each value is stored as a native Redis HASH so individual fields can be read, written, or atomically incremented without round-tripping the whole record (HGET/HSET/HINCRBY). No serializer — the wire format is plain Redis hash fields.

Speed comes from two deliberate choices: both clients talk to Redis (or any Redis-compatible server such as Valkey) through the native ext-redis C extension, and the string client serializes values with ext-igbinary so arbitrary PHP values round-trip losslessly and cheaply. Bulk operations are pipelined and chunked, connections are established lazily and re-established transparently, and every Redis-level error is translated into a PSR-16 exception so your calling code stays backend-agnostic.

Quick example

…and the same surface as a Redis HASH when the value is a flat record and you want per-field reads / writes / atomic counters:

Features

Shared by both clients:

• PSR-16 SimpleCache - drop-in compatible with any PSR-16 consumer (implements Psr\SimpleCache\CacheInterface).
• Core cache operations - get, set, delete, clear, has, plus the multi-key variants getMultiple, setMultiple, deleteMultiple.
• Atomic take - take() reads a key and removes it in one indivisible step, so a value can be claimed exactly once even when several processes go for it together. PSR-16 alone cannot express this.
• Flexible TTLs - int seconds or \DateInterval; a non-positive TTL deletes the entry, per the spec.
• Tagging system - associate keys with tags (setTagged, tag, untag) and read or invalidate them in bulk (getTagged, clearByTag, getTagCardinality). Each client uses its own tag-index namespace so the two can coexist on the same Redis instance without colliding.
• Key namespacing - an optional prefix isolates your keys on a shared Redis instance; clear() is prefix-scoped and never touches other apps' data.
• Resilient connections - lazy connect, transparent reconnect, optional retry-once on transient errors, and PSR-16 exception translation.
• Tunable performance - configurable pipeline batch size, persistent connections, and finite connect/read timeouts via RedisConnectionConfig.

Specific to RapidCacheClient:

• Lossless serialization - igbinary handles objects, nested arrays, DateTime, etc., automatically.
• Queues - Redis lists used as FIFO queues: enqueue, pop, peek, getQueue, getQueueLength.
• Sets - unique collections: createSet, addToSet, removeFromSet, getSet, getCardinality.
• Sorted sets - ordered, value-resolving iteration via getSorted.
• Atomic counters - increase / decrease backed by Redis INCRBY/DECRBY.

Specific to HashRapidCacheClient:

• Native Redis HASH storage - each value is a flat associative array of scalars stored field-for-field as a Redis HASH; no serializer, no whole-value round-trips for a single-field read.
• Single- and multi-field operations - getField / setField / hasField / deleteField (HGET/HSET/HEXISTS/HDEL) and the bulk forms getFields / setFields / deleteFields (HMGET/HMSET/HDEL).
• Atomic field counters - incrementField / decrementField backed by Redis HINCRBY / HINCRBYFLOAT operate in place on individual fields.

Sponsorship ❤️

This project is maintained on the side and looking for sponsors to keep the modernization moving forward. If your team relies on it, please consider chipping in - every contribution helps keep this library alive:

Thank you to everyone who already supports the project! 🙏

Contents

• Quick example
• Features
• Sponsorship ❤️
• Requirements
• Benchmarks
• Installation
• Testing
• Usage
  • Connecting & configuration
  • Basic cache operations (PSR-16)
  • Bulk operations
  • Tagging
  • Queues
  • Sets
  • Sorted sets
  • Atomic counters
  • Hash storage (HashRapidCacheClient)
  • Error handling
  • Behavior notes
• Contributing
• License
• Thank you

Requirements

• PHP 8.2 or higher
• ext-redis (phpredis) - built with igbinary support
• ext-igbinary
• A Redis server (6.0+) or any Redis-compatible server such as Valkey (the test suite runs against Valkey 7.2)

Benchmarks

The package ships with a self-benchmark that measures the throughput of both clients' operations against the same Valkey/Redis instance. There is no cross-library comparison - it answers "how many of each operation does each client sustain per second on this host". Results are grouped into six categories:

• RapidCacheClient → Core, Tagging, Counters
• HashRapidCacheClient → Hash Core, Hash Fields, Hash Tagging, Hash Counters

The chart is regenerated by CI and published to the assets branch:

Each bar is one operation, in operations per second (higher is better), on a scale local to its category. The useful signal is the shape, not the absolute height:

• Single-key operations (set, get, setTagged, increase, getField, …) each cost one network round-trip, so they cluster together - that floor is the round-trip latency to your Redis, not RapidCache's own overhead.
• Pipelined / bulk operations are far faster because they amortise round-trips: setMultiple / getMultiple chunk many keys per call, and getTagged / clearByTag resolve an entire tag with SMEMBERS + a single MGET or batched delete. This is the throughput path - prefer the multi-key and tag-bulk APIs in hot loops.
• The hash client's field-level operations (getField, setField, incrementField, …) cost the same single round-trip as a whole-value get / set but move only the affected field over the wire - the win is bandwidth and contention on big records, not raw ops/sec.

Absolute numbers depend entirely on the runner hardware and the network path to Redis - treat the chart as the relative cost of single round-trips vs. pipelined work, not a guaranteed throughput figure.

Reproduce locally from the benchmark/ directory (see its README for all options):

Installation

Install the package with Composer:

Make sure the required PHP extensions are present:

Verify they are loaded:

Testing

The library ships with a PHPUnit unit suite (100% line/method coverage) and a Behat functional suite that runs against a real Valkey container. The Composer scripts start and stop the container for you via Docker Compose, so you only need Docker installed - not a local Redis.

Quality tooling:

Managing the Valkey container by hand (exposed on host port 6380):

Developing the library itself? See HUMANS.md for a full contributor guide and AGENTS.md for the rules AI agents follow.

Usage

Connecting & configuration

The simplest form takes a host, port, and optional key prefix:

For full control (authentication, database selection, timeouts, persistent connections, retry behavior, pipeline batch size) pass a RedisConnectionConfig. It is an immutable value object whose defaults are tuned for safe production behavior (a finite 1s connect timeout, non-persistent connections):

No socket is opened during construction - the connection is established lazily on the first cache operation and re-established automatically if it drops.

Basic cache operations (PSR-16)

take() - claim a value exactly once

get() then delete() leaves a window in which another client reads the same value, so two callers can both believe they claimed it. take() closes it:

EXISTS and GETDEL are issued inside one MULTI/EXEC, so the read and the removal are indivisible. EXISTS rides along purely to tell a stored literal false from a miss, the same distinction get() makes. Tag associations are cleaned up exactly as delete() does.

Under eight processes racing for one key, take() produced exactly one winner where get() plus delete() produced seven.

Use it for anything meant to be consumed once: single-use tokens, job claims, one-shot coupons, idempotency keys.

Requires Redis or Valkey 6.2+, the release that introduced GETDEL. HashRapidCacheClient offers the same method, backed by HGETALL + DEL in one transaction.

PSR-16 key rules - keys must be non-empty strings; the characters {}()/\@: are reserved and rejected with a Psr\SimpleCache\InvalidArgumentException. A TTL of 0 (or negative) deletes the entry immediately, per the spec.

Bulk operations

Multi-key operations are pipelined and automatically chunked by the configured pipelineBatchSize, keeping request size bounded on large inputs:

Tagging

Tags group related entries so you can read or invalidate them as a unit. Since PSR-16 set() does not take a tag, use setTagged() or call tag() after a plain set():

Queues

Redis lists used as FIFO queues:

enqueue() rejects null values: phpredis cannot tell a stored null apart from "queue is empty" on pop.

Sets

Unique, unordered collections:

Sorted sets

getSorted() treats a Redis sorted set as an ordered index of cache keys: it reads a window of members and resolves each member's cached value, pruning any member whose underlying key has expired. Use reversed: true for highest-score-first ordering.

Atomic counters

Backed by Redis INCRBY / DECRBY (the key is auto-created at 0):

Hash storage (HashRapidCacheClient)

Use HashRapidCacheClient when each cached value is a flat associative array of scalars (a record) and you want to read, write, or atomically modify individual fields without ever round-tripping the whole record. Each value lives in Redis as a native HASH, indexed by field name — there is no serializer involved, so wire payloads are plain Redis hash fields.

Single-field operations don't move the rest of the record across the wire:

Multi-field reads/writes:

Atomic counters operate in place on a single field, so multiple processes can hit the same counter without a read-modify-write cycle:

Tagging mirrors the string client and uses a separate index namespace (H_TAG: / H_TAGS:) so both clients can share the same Redis prefix without colliding:

What you give up vs. RapidCacheClient:

• No type fidelity beyond scalars. bool, null, nested arrays, objects, resources are rejected at set() with Psr\SimpleCache\InvalidArgumentException. Use RapidCacheClient (with igbinary) when the cached value isn't a flat record.
• No per-field TTL. The whole hash expires as a unit via PEXPIRE. Set the TTL on set(); subsequent setField() calls leave the existing TTL in place.
• Queues / sets / sorted sets are not exposed — those live on RapidCacheClient and can be used side-by-side on the same connection.

Error handling

Argument-validation problems are thrown as IDCT\Cache\Exception\InvalidArgumentException, and storage/transport failures as IDCT\Cache\Exception\CacheException. Both implement the matching PSR-16 marker interfaces, so PSR-16 consumers can catch them through the standard contract and stay backend-agnostic:

Behavior notes

• clear() is prefix-scoped. With a prefix configured it uses SCAN + UNLINK to remove only keys under that prefix; with no prefix it falls back to FLUSHDB (current database only). It never calls FLUSHALL, so it will not destroy unrelated data on a shared Redis instance.
• get() distinguishes a stored false from a miss. Because the igbinary serializer makes a stored literal false indistinguishable from a missing key at the protocol level, get() adds an EXISTS probe: it returns the stored false when the key exists, and the $default only on a true miss.
• getMultiple() does not disambiguate. For throughput it issues a single MGET with no per-key EXISTS probe, so both a missing key and a stored false map to the default. Use get() per key when that distinction matters.
• Tags read the current value. Tagged-key membership is stored in a Redis SET at TAG:<tag>; member values are resolved at read time via MGET, so getTagged() always returns each key's current value - an overwrite via set() after setTagged() is reflected immediately.
• Self-healing reads. getTagged() and getSorted() prune entries whose underlying key has expired as a side effect of iteration. Breaking out of the generator early leaves the un-inspected entries for the next call.

Contributing

Contributions are welcome! In short:

1. Fork the repository and create a feature branch (git checkout -b feature/your-feature).
2. Make your change with tests and documentation. The project keeps 100% unit-test coverage, passes PHPStan level 8, follows PSR-12 + strict types, and is mutation-tested - new branches need matching tests.

3. Run the full gate before opening a PR:

4. Open a Pull Request against main with a clear description, and call out any breaking changes explicitly.

When reporting an issue, please include your PHP version, Redis/Valkey version, the library version, a minimal reproduction, and the full error and stack trace.

Full contributor documentation lives in HUMANS.md; the conventions AI agents must follow are in AGENTS.md.

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

This project is licensed under the MIT License. See the LICENSE file for details.

Thank you

Thank you for using and supporting IDCT Rapid Cache Client - whether by filing issues, opening pull requests, spreading the word, or sponsoring the project. Every bit of help keeps the modernization moving and the library alive. 🙏