[opensourcedex]

predis is a free, open source databases project written in PHP and released under MIT. It has 7,779 GitHub stars, 997 forks and 25 open issues, and was last pushed 9 hours ago. On this registry it ranks #97 of 143 tracked projects in Databases, with 5 head-to-head comparisons available.

What is predis?

Predis is a flexible, feature-complete Redis and Valkey client for PHP 7.2 and newer, distributed as the Composer package predis/predis under the MIT licence.

What it is

Predis is a pure-PHP client library that speaks to Redis and Valkey servers. It lives in the PHP ecosystem and installs through Composer and Packagist, follows the PSR-4 autoloading standard, and targets PHP 7.2 and newer. Its stated scope runs from Redis 3.0 up to Redis 8.0, with Valkey covered alongside. It is not a server, a proxy, or a hosted service — it is the client layer that an application uses to open connections, send commands, and read replies.

The concrete thing it replaces is hand-rolled PHP code for talking to Redis: connection setup, protocol handling, command abstraction, and the topology-specific logic for sharding, replication, and failover. Predis supplies a Predis\Client class that handles those concerns directly, so an application configures connection parameters and issues commands instead of assembling raw protocol traffic or writing its own cluster routing. Topologies that would otherwise require custom plumbing — client-side sharding, redis-cluster, master-slave replication with redis-sentinel — are exposed as configuration rather than as new code.

Key capabilities

  • Support for Redis 3.0 through 8.0, plus Valkey.
  • Support for redis-cluster where Redis is 3.0 or newer, and support for master-slave replication setups with redis-sentinel.
  • Clustering through client-side sharding with pluggable keyspace distributors.
  • Command pipelining on single nodes and on client-side sharded clusters, plus abstraction for Redis transactions (Redis 2.0 and newer) and CAS operations (Redis 2.2 and newer).
  • Lua scripting abstraction (Redis 2.6 and newer) with automatic switching between EVALSHA and EVAL, and abstraction for Hinted Hash Templates (HIMPORT, Redis 8.10 and newer) with automatic per-connection fieldset replay.
  • Abstractions for SCAN, SSCAN, ZSCAN and HSCAN (Redis 2.8 and newer) built on PHP iterators.
  • Connections opened lazily on the first command and optionally persisted, over TCP/IP including TLS/SSL encryption or over UNIX domain sockets, with transparent key prefixing, custom commands, and custom connection classes.

Who uses it and how

  • PHP applications running on PHP 7.2 or newer that talk to a Redis or Valkey instance, including the default local case where the client assumes 127.0.0.1 and 6379.
  • Teams operating sharded or clustered deployments that would otherwise maintain their own routing logic, using the client-side sharding and pluggable keyspace distributors or redis-cluster support.
  • Operators running master-slave replication behind redis-sentinel, who let the client resolve the current master rather than pointing applications at a fixed host.
  • Workloads that batch commands over pipelining, or that push logic to the server through Lua scripts, using the automatic EVALSHA/EVAL switching to avoid resending script bodies.
  • Applications needing non-default behaviour, such as custom connection classes for different network or protocol backends, override or custom commands, or transparent key prefixing through a configurable prefix strategy.

Getting started

Install with composer require predis/predis, or register the bundled autoloader with require 'Predis/Autoloader.php'; Predis\Autoloader::register(); in projects without Composer. Then instantiate Predis\Client, either with no parameters for 127.0.0.1:6379 and a 5-second connect timeout, or with a named array such as ['scheme' => 'tcp', 'host' => '10.0.0.1', 'port' => 6379] or the equivalent URI string tcp://10.0.0.1:6379.

How it compares

No peer client libraries and no list of paid products are named in the facts for this entry, so there is nothing to contrast it against on licence, self-hosting, data ownership, or cost model. On the evidence available, it stands alone in this registry as a PHP Redis and Valkey client.

When to use it — and when not to

A team adopting Predis still operates the Redis or Valkey server itself, including whatever it needs for authentication and transport: a password for protected servers, both username and password when Redis 6.0 or newer runs with ACLs, TLS/SSL material for encrypted remote instances, and a socket path for the unix scheme. Anyone who wants a managed service, or who is not building on PHP 7.2 and newer, should look elsewhere. The repository README documents installation, autoloading, connection parameters, and TLS/UNIX socket usage, but defers deeper detail to the FAQ and wiki, so expect to read beyond the README before wiring up sentinel or cluster topology.

project readme (upstream, from github) — read inline

Predis

![Software license][ico-license] [![Latest stable][ico-version-stable]][link-releases] [![Latest development][ico-version-dev]][link-releases] [![Monthly installs][ico-downloads-monthly]][link-downloads] [![Build status][ico-build]][link-actions] [![Coverage Status][ico-coverage]][link-coverage]

A flexible and feature-complete Redis / Valkey client for PHP 7.2 and newer.

More details about this project can be found on the frequently asked questions.

Main features

  • Support for Redis from 3.0 to 8.0.
  • Support for clustering using client-side sharding and pluggable keyspace distributors.
  • Support for redis-cluster (Redis >= 3.0).
  • Support for master-slave replication setups and redis-sentinel.
  • Transparent key prefixing of keys using a customizable prefix strategy.
  • Command pipelining on both single nodes and clusters (client-side sharding only).
  • Abstraction for Redis transactions (Redis >= 2.0) and CAS operations (Redis >= 2.2).
  • Abstraction for Lua scripting (Redis >= 2.6) and automatic switching between EVALSHA or EVAL.
  • Abstraction for Hinted Hash Templates (HIMPORT, Redis >= 8.10) with automatic per-connection fieldset replay.
  • Abstraction for SCAN, SSCAN, ZSCAN and HSCAN (Redis >= 2.8) based on PHP iterators.
  • Connections are established lazily by the client upon the first command and can be persisted.
  • Connections can be established via TCP/IP (also TLS/SSL-encrypted) or UNIX domain sockets.
  • Support for custom connection classes for providing different network or protocol backends.
  • Flexible system for defining custom commands and override the default ones.

How to install and use Predis

This library can be found on Packagist for an easier management of projects dependencies using Composer. Compressed archives of each release are available on GitHub.

composer require predis/predis

Loading the library

Predis relies on the autoloading features of PHP to load its files when needed and complies with the PSR-4 standard. Autoloading is handled automatically when dependencies are managed through Composer, but it is also possible to leverage its own autoloader in projects or scripts lacking any autoload facility:

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

Predis\Autoloader::register();

Connecting to Redis

When creating a client instance without passing any connection parameter, Predis assumes 127.0.0.1 and 6379 as default host and port. The default timeout for the connect() operation is 5 seconds:

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

Connection parameters can be supplied either in the form of URI strings or named arrays. The latter is the preferred way to supply parameters, but URI strings can be useful when parameters are read from non-structured or partially-structured sources:

// 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');

Password protected servers can be accessed by adding password to the parameters set. When ACLs are enabled on Redis >= 6.0, both username and password are required for user authentication.

It is also possible to connect to local instances of Redis using UNIX domain sockets, in this case the parameters must use the unix scheme and specify a path for the socket file:

$client = new Predis\Client(['scheme' => 'unix', 'path' => '/path/to/redis.sock']);
$client = new Predis\Client('unix:/path/to/redis.sock');

The client can leverage TLS/SSL encryption to connect to secured remote Redis instances without the need to configure an SSL proxy like stunnel. This can be useful when connecting to nodes running on various cloud hosting providers. Encryption can be enabled with using the tls scheme and an array of suitable options passed via the ssl parameter:

// 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');

The connection schemes redis (alias of tcp) and rediss (alias of tls) are also supported, with the difference that URI strings containing these schemes are parsed following the rules described on their respective IANA provisional registration documents.

Since Redis 8.6, you can authenticate a client using the Subject CN from its TLS client certificate (mTLS). When this is enabled on the server, the client is authenticated during the TLS handshake, so you don’t need to send an AUTH command.

To use this, configure:

  • a CA certificate used to verify the server certificate (cafile),
  • a client certificate (local_cert) signed by a CA trusted by the Redis server for client authentication,
  • the corresponding private key (local_pk).

Make sure:

  • the Redis server certificate is signed by a CA trusted by the client, and
  • the client certificate is signed by a CA trusted by the Redis server (mTLS).
// Named array of connection parameters:
$client = new Predis\Client([
    'scheme' => 'tls',
    'ssl' => [
        'cafile'      => 'ca.pem',          // CA used to verify the server certificate
        'local_cert'  => 'client.crt',      // client certificate (Subject CN maps to ACL user)
        'local_pk'    => 'client.key',      // client private key
        'verify_peer' => true,
    ],
]);

// ACL user must exist and match the certificate Subject CN (example: CN=CN_NAME).
// Enable the user and grant permissions as needed:
$client->acl->setUser('CN_NAME', 'on', '>clientpass', 'allcommands', 'allkeys')

echo $client->acl->whoami() // CN_NAME

The actual list of supported connection parameters can vary depending on each connection backend so it is recommended to refer to their specific documentation or implementation for details.

Predis can aggregate multiple connections when providing an array of connection parameters and the appropriate option to instruct the client about how to aggregate them (clustering, replication or a custom aggregation logic). Named arrays and URI strings can be mixed when providing configurations for each node:

$client = new Predis\Client([
    'tcp://10.0.0.1?alias=first-node', ['host' => '10.0.0.2', 'alias' => 'second-node'],
], [
    'cluster' => 'predis',
]);

See the aggregate connections section of this document for more details.

Connections to Redis are lazy meaning that the client connects to a server only if and when needed. While it is recommended to let the client do its own stuff under the hood, there may be times when it is still desired to have control of when the connection is opened or closed: this can easily be achieved by invoking $client->connect() and $client->disconnect(). Please note that the effect of these methods on aggregate connections may differ depending on each specific implementation.

Persistent connections

To increase a performance of your application you may set up a client to use persistent TCP connection, this way client saves a time on socket creation and connection handshake. By default, connection is created on first-command execution and will be automatically closed by GC before the process is being killed. However, if your application is backed by PHP-FPM the processes are idle, and you may set up it to be persistent and reusable across multiple script execution within the same process.

To enable the persistent connection mode you should provide following configuration:

// Standalone
$client = new Predis\Client(['persistent' => true]);

// Cluster
$client = new Predis\Client(
    ['tcp://host:port', 'tcp://host:port', 'tcp://host:port'],
    ['cluster' => 'redis', 'parameters' => ['persistent' => true]]
);

Important

If you operate on multiple clients within the same application, and they communicate with the same resource, by default they will share the same socket (that's the default behaviour of persistent sockets). So in this case you would need to additionally provide a conn_uid ident

readme truncated — read the full docs on github

Frequently asked questions

Is predis free to use?

predis is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does predis do?

A flexible and feature-complete Redis/Valkey client for PHP.

What is predis written in?

predis is primarily written in PHP. Its source is publicly available at https://github.com/predis/predis, and it has 7,779 GitHub stars.