b1rdex/predis-compressible
A Predis plugin that transparently compresses Redis values, helping reduce memory usage and network payload sizes without changing your application code. It integrates with Predis connections and handles compression/decompression automatically.
b1rdex/predis-compressible is a Predis extension that transparently compresses values on write and decompresses them on read. It is a client-side concern: your application still calls set/get/mset/mget, but the bytes stored in Redis are compressed. The 1.1 release is a maintenance release — CI was added and the MSET command wasfixed — so start on ^1.1 and verify bulk writes as part of your smoke test.
Minimal setup:
composer require b1rdex/predis-compressible:^1.1
Requirements to check first:
'client' => 'predis' under config/database.php → redis.ext-zlib (or whatever compressor the package documents) must be available. Compression is a no-op failure waiting to happen if the extension is missing.composer.json before upgrading an existing app.Look first at the package README and its src/ directory. The important thing to identify is the supported command list: which Redis commands are wrapped with compression and which are passed through untouched. MSET is confirmed supported as of 1.1; arbitrary commands are probably not.
The first use case to try is a “large payload” Redis connection: rendered HTML fragments, JSON API responses, serialized Eloquent collections, or feature-flag documents. These are values where compression actually pays for itself; do not point this at counters, locks, or small scalar values.
A minimal way to prove it works, independent of Laravel’s connector:
use Predis\Client;
$client = new Client($config, [
// Register the package's compression profile/command processor here.
// Use the exact class name from the package README.
]);
$payload = json_encode(array_fill(0, 5000, ['id' => 1, 'name' => 'example']));
$client->set('smoke:key', $payload);
$roundTrip = $client->get('smoke:key');
assert($roundTrip === $payload); // decompressed on read
// Inspect the raw stored size — this bypasses the compression layer:
$storedBytes = $client->executeRaw(['STRLEN', 'smoke:key']);
echo strlen($payload) . ' -> ' . $storedBytes . PHP_EOL;
If those two sizes are close, compression is not active; if the round-trip fails, the package is not registered on the client you are using.
Keep compression at the client boundary. The package only helps if every read and write for a key goes through the compression-aware client. The practical pattern is a dedicated connection — for example redis.compressed or a Redis connection named compressed — used only for large-payload keys. Do not mix compressed and uncompressed writes to the same key namespace.
Laravel wiring. Laravel’s built-in PredisConnector constructs its own Predis\Client from config/database.php, so the package will not be active just by changing config. Two workable patterns:
// app/Providers/AppServiceProvider.php
$this->app->singleton('redis.compressed', function ($app) {
$config = $app['config']->get('database.redis.default');
return new Predis\Client($config, [
// Package profile / command processor registration — see README.
]);
});
Redis::connection('compressed') returns a compression-enabled client. This is more invasive but lets you use the normal Redis facade and Laravel cache stores.Cache store integration. Once you have a working connection, you can expose it as a Laravel cache store:
// config/cache.php
'stores' => [
'compressed' => [
'driver' => 'redis',
'connection' => 'compressed',
],
],
Then Cache::store('compressed')->put($key, $value, $ttl). Be aware that Laravel serializes the value before handing it to Redis; compression then applies to the serialized string. That is usually fine, but it means the “value” the compressor sees is not your raw PHP value.
Bulk operations. Prefer MSET/MGET for warm-up and batch reads now that 1.1 fixes MSET. This is where the package saves the most network and memory:
$client->mset([
'report:1' => $json1,
'report:2' => $json2,
'report:3' => $json3,
]);
$values = $client->mget(['report:1', 'report:2', 'report:3']);
Keep batches modest (hundreds, not tens of thousands) and be careful with Redis Cluster: multi-key commands must share a hash slot, or Predis will reject them. Use hash tags such as {report}:1 if you use MSET on a cluster.
Version your keys. Because decompression is transparent, legacy uncompressed values in the same namespace become a runtime failure. Use a prefix that includes a format version: v2:report:42. On migration, either backfill or implement a fallback read path that catches decompression failures and treats the value as raw.
Test at the Redis byte level. In feature tests, assert behaviour through the client and also inspect raw storage:
$client->set('v2:test', $payload);
$this->assertSame($payload, $client->get('v2:test'));
$this->assertLessThan(
strlen($payload),
(int) $client->executeRaw(['STRLEN', 'v2:test'])
);
Measure before rolling out. Compression trades CPU for memory. Benchmark write latency and Redis used_memory on a representative payload distribution (small records, medium JSON, large HTML). If most of your values are under a few hundred bytes, compression headers and CPU cost may make things worse.
Upgrade to 1.1 for MSET. The 1.1 release explicitly fixes the MSET command. If you are on 1.0 and use MSET for batch writes, you are at risk of values being stored or read incorrectly. Add a regression test for MSET + MGET round-trips as part of the upgrade.
Not all commands are compression-aware. Only the commands the package wraps will compress/decompress. Commands such as INCR, APPEND, SETRANGE, GETRANGE, BITCOUNT, or Lua scripts will operate on (or produce) raw bytes. Mixing these with compressed keys produces corrupt or nonsensical values. Check the package’s supported command list and keep compressed keys out of code paths that use unsupported commands.
STRLEN and other byte-level commands see compressed bytes. This is useful for verification but dangerous if application logic depends on lengths or string operations. Never use Redis-side string manipulation on a compressed value.
Laravel connector gotcha. Setting 'client' => 'predis' is necessary but not sufficient. Laravel’s Predis connector will build a vanilla client. If compression “silently doesn’t work”, the first thing to check is whether the client actually has the package’s profile/command processor registered — not the config file.
Serialization order matters. Laravel cache and session drivers serialize before writing. If you ever add compression manually in application code as well, you will double-compress. Pick exactly one layer and keep it there.
Decompression failures on legacy data. A get on an old uncompressed key may throw or return garbage depending on the implementation. Use versioned key prefixes and handle migration explicitly. In production, a fallback read path is cheaper than a backfill outage.
Small values can grow. Compression headers and incompressible data can make values larger. Enforce a minimum payload size (for example, skip compression for values under ~1 KB) or route small keys to an uncompressed connection.
Cluster and pipeline behaviour. MSET/MGET across different slots will fail on Redis Cluster. Use hash tags. Also verify that pipelines and transactions still behave — command processors can interact badly with MULTI/EXEC and pipeline response parsing.
Debugging with redis-cli. Use redis-cli --raw GET key | xxd | head to inspect stored bytes. If you see a compression header, writes are going through the package. If you see readable JSON, they are not. Comparing STRLEN before and after a deploy is the quickest sanity check.
Extension points. The package is small and command-oriented; if you need another command compressed, the natural extension point is adding/registering a compression-aware command class rather than wrapping application code. Keep any custom command in your app’s namespace and register it alongside the package’s commands so upgrades do not overwrite it.
CI is now in place. The 1.1 release adds GitHub CI. That does not change runtime behaviour, but it does mean you can reasonably expect the supported command matrix to be exercised on future releases; still pin a minor version and run your own round-trip tests for the commands you actually use.
How can I help you explore Laravel packages today?