Predis: five connection schemes, lazy connections, and the difference from phpredis

Composer or a tarball, and the library ships its own autoloader

Installation is one Composer command:

composer require predis/predis

The library is on Packagist for dependency management, and compressed archives of each release are on GitHub.

Autoloading is the part worth reading. Predis relies on PHP's autoloading to load its files and complies with the PSR-4 standard. With Composer that happens automatically. Without it, which includes scripts and projects with no autoload facility at all, the library can register its own:

// Prepend a base path if Predis is not available in your "include_path".
require 'Predis/Autoloader.php';

Predis\Autoloader::register();

There is an `autoload.php` at the repository root as well.

For a library that has existed long enough to support PHP 7.2 and newer, having a fallback autoloader rather than requiring Composer is a deliberate compatibility choice, and the repository root shows both routes side by side.

No parameters means 127.0.0.1:6379 with a five second connect timeout

The simplest client needs nothing:

$client = new Predis\Client();
$client->set('foo', 'bar');
$value = $client->get('foo');

That works because of documented defaults: with no connection parameters, Predis assumes `127.0.0.1` and `6379`, and the default timeout for the connect operation is five seconds.

So the zero-configuration case has two things worth knowing before you rely on it. It points at localhost, which means an application with a cache on another host silently talking to nothing, and it waits five seconds before failing, which is a long time inside a web request.

Both defaults are the right starting point and the wrong production configuration, and the parameter form is how you change them.

Named arrays are preferred over URI strings, and the README says so

Connection parameters come in two forms, and the preference is stated:

// Parameters passed using a named array:
$client = new Predis\Client([
    'scheme' => 'tcp',
    'host'   => '10.0.0.1',
    'port'   => 6379,
]);

// Same set of parameters, passed using an URI string:
$client = new Predis\Client('tcp://10.0.0.1:6379');

The named array is the preferred way to supply parameters. URI strings are described as useful when parameters are read from non-structured or partially-structured sources, which is the case where a configuration file gives you one string.

There is a subtlety in the scheme names. The schemes `redis` (an alias of `tcp`) and `rediss` (an alias of `tls`) are also supported, and URI strings containing them are parsed following the rules in their IANA provisional registration documents rather than a private parser. That is a small detail that matters if your configuration is written by someone who read the IANA registration rather than this README.

Multiple connections can be aggregated when you pass an array of parameter sets with the option describing how, whether that is clustering, replication or custom aggregation logic.

TLS and mTLS are configuration, not a proxy

The client can use TLS/SSL to reach a secured Redis without an SSL proxy such as stunnel, which the README says is useful when connecting to nodes on various cloud hosting providers. Encryption is enabled with the `tls` scheme plus an array of SSL options:

// Named array of connection parameters:
$client = new Predis\Client([
  'scheme' => 'tls',
  'ssl'    => ['cafile' => 'private.pem', 'verify_peer' => true],
]);

// Same set of parameters, but using an URI string:
$client = new Predis\Client('tls://127.0.0.1?ssl[cafile]=private.pem&ssl[verify_peer]=1');

Since Redis 8.6 you can authenticate a client using the Subject CN from its TLS client certificate, mTLS. When enabled on the server, the client is authenticated during the TLS handshake, so you do not need to send an AUTH command. The configuration needs a CA certificate used to verify the server certificate, a client certificate signed by a CA the Redis server trusts, and the matching private key.

That last mechanism has a consequence beyond configuration: the ACL user is matched to the certificate's Subject CN rather than to a credential you send, so certificate rotation becomes a server-side trust question instead of a client-side secret.

Connections are lazy, and the abstractions sit above the commands

Two architectural facts shape how the library behaves.

Connections are established lazily by the client upon the first command, and they can be persisted. So constructing a Predis client opens nothing; the socket appears when the first command runs. That matters for failover and for tests, because a client that has never issued a command cannot fail to connect.

Above the commands there is a set of abstractions. Transactions and CAS operations are abstracted for Redis 2.0 and later, Lua scripting is abstracted for Redis 2.6 with automatic switching between `EVALSHA` or `EVAL`, `SCAN`, `SSCAN`, `ZSCAN` and `HSCAN` are wrapped in PHP iterators, Hinted Hash Templates with `HIMPORT` for Redis 8.10 come with automatic per-connection fieldset replay, and commands can be pipelined on both single nodes and clusters, the latter for client-side sharding only.

That list is the reason to choose this client over a raw socket. The command layer is thin; the work is in not having to remember the ordering rules for scripting and transactions.

Clustering, Sentinel and key prefixing are configuration choices

The features list covers the deployment topologies, and each is a switch rather than a separate library.

Clustering is supported two ways: client-side sharding with pluggable keyspace distributors, and `redis-cluster` for Redis 3.0 and later. Master-slave replication setups and `redis-sentinel` are supported as well. Command pipelining works on single nodes and on clusters, though the cluster case is client-side sharding only.

Key prefixing is transparent: keys are prefixed using a customizable prefix strategy, which is what lets two applications share one Redis instance without their key namespaces colliding.

There is also a flexible system for defining custom commands and overriding the default ones, and support for custom connection classes if you need a different network or protocol backend.

The server support range is stated as Redis from 3.0 to 8.0, and the library covers Redis and Valkey. Several of the topologies above have matching examples in the examples/ directory, including custom_cluster_distributor.php, replication_sentinel.php and key_prefixing.php, which is the fastest way to see which one you actually need.

The maintenance signals are a VERSION file, a changelog and a phpstan config

The repository root is conventional for a long-lived PHP library: a `VERSION` file, `CHANGELOG.md`, `FAQ.md`, `composer.json`, `src/`, `tests/` and `examples/`, plus `autoload.php`.

What is more specific is the static analysis setup. There are two phpstan configuration files, `phpstan.dist.neon` and `phpstan-tests.dist.neon`, which means the library's own code and its test suite are analysed with different rule sets. Formatting is handled by `.php-cs-fixer.dist.php`, there is a `.codespellrc` for spelling, and coverage goes to Coveralls through `.coveralls.yml`.

Two test configurations sit side by side as well: `phpunit.xml.dist` for the suite and `phpunit.relay.xml` for tests of the optional Relay integration, which the README describes as providing shared memory caching, serialization and compression.

Releases are v3.7.0 on 2026-10-08, v3.6.1 on 2026-09-17 and v3.6.0 on 2026-08-14, with the last push to main on 2026-11-01, and the stated floor is PHP 7.2 and newer.

Editorial conclusion

Predis suits a PHP application that needs Redis or Valkey without a compiled extension, or that wants connection options such as TLS, mTLS and client-certificate authentication that the README documents in detail. It does not suit you if you have already decided that a C extension is the right trade for your workload, since the repository presents Predis as a client rather than a benchmark against phpredis, and it does not suit you if you are on PHP older than 7.2. Verify three things before you pick it: which Redis version range your server falls into, since support is stated as Redis 3.0 to 8.0, whether you need TCP, TLS, a UNIX socket or client-certificate auth and whether the scheme you need is one of the ones listed, and how your project loads autoloading, since Composer handles it automatically but a script without an autoloader needs the library's own autoloader registered by hand.

Frequently asked questions

Official sources

1. License: MIT
2. predis/predis on GitHub
3. Project website
4. README
5. Releases