一个灵活且功能完备的 Redis/Valkey 客户端,适用于 PHP。
![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.
EVALSHA or EVAL.HIMPORT, Redis >= 8.10) with automatic per-connection fieldset replay.SCAN, SSCAN, ZSCAN and HSCAN (Redis >= 2.8) based on PHP iterators.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
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();
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:
Make sure:
…
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.
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 identifier for each client, this way each client will create its own socket so
the connection context won't be shared across clients. This socket behaviour explained
here
// Standalone
$client1 = new Predis\Client(['persistent' => true, 'conn_uid' => 'id_1']);
$client2 = new Predis\Client(['persistent' => true, 'conn_uid' => 'id_2']);
// Cluster
$client1 = new Predis\Client(
['tcp://host:port', 'tcp://host:port', 'tcp://host:port'],
['cluster' => 'redis', 'parameters' => ['persistent' => true, 'conn_uid' => 'id_1']]
);
$client2 = new Predis\Client(
['tcp://host:port', 'tcp://host:port', 'tcp://host:port'],
['cluster' => 'redis', 'parameters' => ['persistent' => true, 'conn_uid' => 'id_2']]
);
Many aspects and behaviors of the client can be configured by passing specific client options to the
second argument of Predis\Client::__construct():
$client = new Predis\Client($parameters, ['prefix' => 'sample:']);
Options are managed using a mini DI-alike container and their values can be lazily initialized only when needed. The client options supported by default in Predis are:
prefix: prefix string applied to every key found in commands.exceptions: whether the client should throw or return responses upon Redis errors.connections: list of connection backends or a connection factory instance.cluster: specifies a cluster backend (predis, redis or callable).replication: specifies a replication backend (predis, sentinel or callable).aggregate: configures the client with a custom aggregate connection (callable).parameters: list of default connection parameters for aggregate connections.commands: specifies a command factory instance to use through the library.readTimeout: (cluster only) Timeout between read operations while loop over connections.Users can also provide custom options with values or callable objects (for lazy initialization) that are stored in the options container for later use through the library.
Aggregate connections are the foundation upon which Predis implements clustering and replication and they are used to group multiple connections to single Redis nodes and hide the specific logic needed to handle them properly depending on the context. Aggregate connections usually require an array of connection parameters along with the appropriate client option when creating a new client instance.
Predis can be configured to work in clustering mode with a traditional client-side sharding approach to create a cluster of independent nodes and distribute the keyspace among them. This approach needs some sort of external health monitoring of nodes and requires the keyspace to be rebalanced manually when nodes are added or removed:
$parameters = ['tcp://10.0.0.1', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options = ['cluster' => 'predis'];
$client = new Predis\Client($parameters);
Along with Redis 3.0, a new supervised and coordinated type of clustering was introduced in the form of redis-cluster. This kind of approach uses a different algorithm to distribute the keyspaces, with Redis nodes coordinating themselves by communicating via a gossip protocol to handle health status, rebalancing, nodes discovery and request redirection. In order to connect to a cluster managed by redis-cluster, the client requires a list of its nodes (not necessarily complete since it will automatically disc
暂无开放 Issues，或尚未同步最近议题。