A flexible and feature-complete Redis client for PHP.
MIT License
Bot releases are hidden (Show)
Predis v3.0 introduces support for new communication protocol RESP3 and new features based on it.
CLIENT
command (#1337)XGROUP
commands (#1324)XREADGROUP
command (#1327)XAUTOCLAIM
command (#1328)XINFO
commands (#1331)Published by tillkruss about 1 year ago
client_info
client parameterCLUSTER
container commandEXPIRETIME
not using prefix
CLIENT SETINFO
calls by defaultPublished by tillkruss about 1 year ago
WAITAOF
command (#1357)SHUTDOWN
command (#1359)FUNCTION
command (#1332)PEXPIRE
, PEXPIREAT
and COMMAND
KeyPrefixProcessor
(#1358)Published by tillkruss over 1 year ago
KeyPrefixProcessor
(#1051)ReplicationStrategy::$loadBalancing
option to disable replica reads (#1168)FCALL
and FUNCTIONS
commands (#1049)PEXPIRETIME
command (#1031)EXPIRETIME
command (#1029)EVAL_RO
command (#1032)LCS
command (#1035)SORT_RO
command (#1044)SINTERCARD
command (#1027)EVALSHA_RO
command (#1034)BITPOS
and BITCOUNT
commands (#1045)EXPIRE
and EXPIREAT
commands (#1046)Published by tillkruss about 2 years ago
is_resource()
before reading/writingPublished by tillkruss about 2 years ago
Published by tillkruss about 2 years ago
RedisCluster
with a default of 10ms
Connection\Parameters
Published by tillkruss over 2 years ago
Dropped support for PHP 7.1 and older
Accepted values for some client options have changed, this is the new list of
accepted values:
aggregate
: callable returning an aggregate connection.cluster
: string value (predis
, redis
), callable returning an aggregatereplication
: string value (predis
, sentinel
), callable returning ancommands
: command factory, named array mapping command IDs to PHP classes,connections
: connection factory, callable object returning a connectionprefix
: string value, command processor, callable.exceptions
: boolean.Note that both the cluster
and replication
options now return a closure
acting as initializer instead of an aggregate connection instance.
The connections
client option now accepts certain string values identifying
certain combinations of configurations for the connection factory. Currenlty
this is used to provide a short way to configure Predis to load our phpiredis
based connection backends simply, accepted values are:
phpiredis-stream
maps Phpiredis\Connection\PhpiredisStreamConnection
totcp
, redis
, unix
URI schemes.phpiredis-socket
maps Phpiredis\Connection\PhpiredisSocketConnection
totcp
, redis
, unix
URI schemes.phpiredis-stream
is simply an alias of phpiredis-stream
.Added the new Predis\Cluster\Hash\PhpiredisCRC16
class using ext-phpiredis
to speed-up the generation of the CRC16 hash of keys for redis-cluster. Predis
automatically uses this class when ext-phpiredis is loaded, but it is possible
to configure the hash generator using the new crc16
client option (accepted
values predis
, phpiredis
or an hash generator instance).
Replication backends now use the role
parameter instead of alias
in order
to distinguish the role of a connection. Accepted values are master
, slave
and, for redis-sentinel, sentinel
. This led to a redesign of how connections
can be retrieved from replication backends: the method getConnectionById() now
retrieves a connection only by its ID (ip:port pair), to get a connection by
its alias there is the new method getConnectionByAlias(). This method is not
supported by the redis-sentinel backend due to its dynamic nature (connections
are retrieved and initialized at runtime from sentinels) but it is possible to
get a single connection from the pool by using its ID. It is also possible to
retrive a connection by role using the method getConnectionByRole().
The concept of connection ID (ip:port pair) and connection alias (the alias
parameter) in Predis\Connection\Cluster\PredisCluster
has been separated.
This change does not affect distribution and it is safe for existing clusters.
Client option classes now live in the Predis\Configuration\Option
namespace.
Classes for Redis commands have been moved into the new Predis\Command\Redis
namespace and each class name mirrors the respective Redis command ID.
The concept of server profiles is gone, the library now uses a single command
factory to create instances of commands classes. The profile
option has been
replaced by the commands
option accepting Predis\Command\FactoryInterface
to customize the underlying command factory. The default command factory class
used by Predis is Predis\Command\RedisFactory
and it still allows developers
to define or override commands with their own implementations. In addition to
that, Predis\Command\RedisFactory
relies on a convention-over-configuration
approach by looking for a suitable class with the same name as the command ID
in the Predis\Command\Redis
when the internal class map does not contain a
class associated.
The method Predis\Client::getClientFor($connectionID)
has been replaced by
getClientBy($selector, $value, $callable = null)
which is more flexible as
it is not limited to picking a connection from the underlying replication or
cluster backend by ID, but allows users to specify a $selector
that can be
either id
(the old behavior), key
, slot
or command
. The client uses
duck-typing instead of type-checking to verify that the underlying connection
implements a method that matches the specified selector which means that some
selectors may not be available to all kinds of connection backends.
The method Predis\Client::getConnectionById($connectionID)
has been removed.
Changed the signature for the constructor of Predis\Command\RawCommand
.
The Predis\Connection\Aggregate
namespace has been split into two separate
namespaces for cluster backends (Predis\Connection\Cluster
) and replication
backends (Predis\Connection\Replication
).
The method Predis\Connection\AggregateConnectionInterface::getConnection()
has been renamed to getConnectionByCommand()
.
The methods switchToMaster()
and switchToSlave()
have been promoted to be
part of Predis\Connection\Replication\ReplicationInterface
while the method
switchTo($connection)
has been removed from it.
The method Predis\Connection\Cluster\PredisCluster::executeCommandOnNodes()
has been removed as it is possible to achieve the same by iterating over the
connection or, even better, over the client instance in order to execute the
same command against all of the registered connections.
The class Predis\CommunicationException
now uses the correct default types
for the $message
(string) and $code
(integer) parameters.
The method onConnectionError()
in Predis\Connection\AbstractConnection
class now passes the second argument as an integer value 0
as its default
value instead of null
.
Support Pub/Sub and Pipelines when using replication
The class Predis\Transaction\AbortedMultiExecException
now uses the correct
default types for the $code
(integer) parameter.
FIX: using strval
in getScanOptions()
method, part of
Predis\Collection\Iterator\CursorBasedIterator
to make sure we retrieve the
string value of $this->match
and not passing null
to strlen()
function.
FIX: the value returned from getArgument()
in isReadOperation()
method,
part of Predis\Replication\ReplicationStrategy
class, is checked to not pass
null
to sha1
function.
FIX: the value returned from getArgument()
in parseResponse()
method,
part of Predis\Command\Redis\SENTINEL
class, is checked to not pass null
to strtolower()
function.
Published by tillkruss over 2 years ago
Dropped support for PHP 7.1 and older
Accepted values for some client options have changed, this is the new list of
accepted values:
aggregate
: callable returning an aggregate connection.cluster
: string value (predis
, redis
), callable returning an aggregatereplication
: string value (predis
, sentinel
), callable returning ancommands
: command factory, named array mapping command IDs to PHP classes,connections
: connection factory, callable object returning a connectionprefix
: string value, command processor, callable.exceptions
: boolean.Note that both the cluster
and replication
options now return a closure
acting as initializer instead of an aggregate connection instance.
The connections
client option now accepts certain string values identifying
certain combinations of configurations for the connection factory. Currenlty
this is used to provide a short way to configure Predis to load our phpiredis
based connection backends simply, accepted values are:
phpiredis-stream
maps Phpiredis\Connection\PhpiredisStreamConnection
totcp
, redis
, unix
URI schemes.phpiredis-socket
maps Phpiredis\Connection\PhpiredisSocketConnection
totcp
, redis
, unix
URI schemes.phpiredis-stream
is simply an alias of phpiredis-stream
.Added the new Predis\Cluster\Hash\PhpiredisCRC16
class using ext-phpiredis
to speed-up the generation of the CRC16 hash of keys for redis-cluster. Predis
automatically uses this class when ext-phpiredis is loaded, but it is possible
to configure the hash generator using the new crc16
client option (accepted
values predis
, phpiredis
or an hash generator instance).
Replication backends now use the role
parameter instead of alias
in order
to distinguish the role of a connection. Accepted values are master
, slave
and, for redis-sentinel, sentinel
. This led to a redesign of how connections
can be retrieved from replication backends: the method getConnectionById() now
retrieves a connection only by its ID (ip:port pair), to get a connection by
its alias there is the new method getConnectionByAlias(). This method is not
supported by the redis-sentinel backend due to its dynamic nature (connections
are retrieved and initialized at runtime from sentinels) but it is possible to
get a single connection from the pool by using its ID. It is also possible to
retrive a connection by role using the method getConnectionByRole().
The concept of connection ID (ip:port pair) and connection alias (the alias
parameter) in Predis\Connection\Cluster\PredisCluster
has been separated.
This change does not affect distribution and it is safe for existing clusters.
Client option classes now live in the Predis\Configuration\Option
namespace.
Classes for Redis commands have been moved into the new Predis\Command\Redis
namespace and each class name mirrors the respective Redis command ID.
The concept of server profiles is gone, the library now uses a single command
factory to create instances of commands classes. The profile
option has been
replaced by the commands
option accepting Predis\Command\FactoryInterface
to customize the underlying command factory. The default command factory class
used by Predis is Predis\Command\RedisFactory
and it still allows developers
to define or override commands with their own implementations. In addition to
that, Predis\Command\RedisFactory
relies on a convention-over-configuration
approach by looking for a suitable class with the same name as the command ID
in the Predis\Command\Redis
when the internal class map does not contain a
class associated.
The method Predis\Client::getClientFor($connectionID)
has been replaced by
getClientBy($selector, $value, $callable = null)
which is more flexible as
it is not limited to picking a connection from the underlying replication or
cluster backend by ID, but allows users to specify a $selector
that can be
either id
(the old behavior), key
, slot
or command
. The client uses
duck-typing instead of type-checking to verify that the underlying connection
implements a method that matches the specified selector which means that some
selectors may not be available to all kinds of connection backends.
The method Predis\Client::getConnectionById($connectionID)
has been removed.
Changed the signature for the constructor of Predis\Command\RawCommand
.
The Predis\Connection\Aggregate
namespace has been split into two separate
namespaces for cluster backends (Predis\Connection\Cluster
) and replication
backends (Predis\Connection\Replication
).
The method Predis\Connection\AggregateConnectionInterface::getConnection()
has been renamed to getConnectionByCommand()
.
The methods switchToMaster()
and switchToSlave()
have been promoted to be
part of Predis\Connection\Replication\ReplicationInterface
while the method
switchTo($connection)
has been removed from it.
The method Predis\Connection\Cluster\PredisCluster::executeCommandOnNodes()
has been removed as it is possible to achieve the same by iterating over the
connection or, even better, over the client instance in order to execute the
same command against all of the registered connections.
The class Predis\CommunicationException
now uses the correct default types
for the $message
(string) and $code
(integer) parameters.
The method onConnectionError()
in Predis\Connection\AbstractConnection
class now passes the second argument as an integer value 0
as its default
value instead of null
.
The class Predis\Transaction\AbortedMultiExecException
now uses the correct
default types for the $code
(integer) parameter.
FIX: using strval
in getScanOptions()
method, part of
Predis\Collection\Iterator\CursorBasedIterator
to make sure we retrieve the
string value of $this->match
and not passing null
to strlen()
function.
FIX: the value returned from getArgument()
in isReadOperation()
method,
part of Predis\Replication\ReplicationStrategy
class, is checked to not pass
null
to sha1
function.
FIX: the value returned from getArgument()
in parseResponse()
method,
part of Predis\Command\Redis\SENTINEL
class, is checked to not pass null
to strtolower()
function.
Published by tillkruss almost 3 years ago
Session/Handler
Connection/Aggregate/SentinelReplication
Published by tillkruss about 3 years ago
StreamConnection
Published by tillkruss about 3 years ago
Published by tillkruss over 3 years ago
cweagans/composer-patches
dev dependency and apply patchespost-update-cmd
script.Published by nrk about 4 years ago
That was fast, but we had a bug in v1.1.5 so we needed to release a fix ASAP.
FIX: reverted support for sentinels authentication implemented in v1.1.5 as it was bugged (see ISSUE #658), sorry for the trouble. This is now postponed as it requires a more thorough investigation.
Published by nrk about 4 years ago
Here we have a new patch release!
NOTE: We are still missing handlers for commands added in Redis 4, 5 and 6. We will get on par eventually, in the meanwhile you can define your own ones or use Predis\Client::executeRaw()
. Read this post for details about how to properly implement support for new commands if you would like to add missing ones and share your work with us by creating pull requests, contributions are always greatly appreciated!
NOTE intentionally commented out, please read the release notes for v1.1.6
FIX: authentication for sentinels is now supported, previously it was not possible to specify a password
for sentinels as its value was stripped during initialization because sentinels did not support authentication until Redis 5. Please note that with the current implementation each sentinel must have its own password
parameter set in the parameters list despite this password is the same for all sentinels (read how requirepass
works on the Redis docs). In this case you should avoid using the global parameters
client option used to set default parameters for every connection created by Predis as this would end up using the same password even when connecting to actual Redis nodes. We are investiganting how to make it easier to specify the required password to access sentinels only once instead of repeating it for each sentinel.
FIX: the username is now correctly retrieved from the userinfo fragment of the URI when using the redis
scheme and a username:password
pair is present. Values retrieved from the userinfo fragment always override the ones specified in username
and password
if those fields are present in the query string.
FIX: Predis\Connection\WebdisConnection
was unable to connect to Webdis when using an IPv4 address in the URL and this is probably due to some change in cURL internals since the last time we tested it.
FIX: an exception is thrown when passing FALSE
or any value evaluating to FALSE
to the replication
client option. This was supposed to be unsupported, in fact it actually breaks client initialization and raises a PHP warning. Now the user is alerted with an InvalidArgumentException
and a proper message. (PR #381).
Published by nrk about 4 years ago
Here is a new patch release for v1.1
with more improvements and fixes.
NOTE: We are still missing handlers for commands added in Redis 4, 5 and 6. We will get on par eventually, in the meanwhile you can define your own ones or use Predis\Client::executeRaw()
. Read this post for details about how to properly implement support for new commands if you would like to add missing ones and share your work with us by creating pull requests, contributions are always greatly appreciated!
The client can now handle ACL authentication when connecting to Redis 6, just pass both username
and password
to connection parameters and Predis switches to using the augmented variant of AUTH
:
// When using an URI string for parameters:
$client = new Predis\Client('tcp://127.0.0.1?username=myuser&password=mypassword');
// When using a named array for parameters:
$client = new Predis\Client([
'username' => 'myuser',
'password' => 'mypassword',
]);
As usual Redis servers protected only by a password can still be accessed with just the password
parameter. See the Redis documentation for more details about Redis ACLs.
FIX: NULL
or zero-length string values in password
and database
do not trigger spurious AUTH
and SELECT
commands anymore when connecting to Redis.
// Won't trigger `AUTH` and `SELECT`:
$client = new Predis\Client('tcp://127.0.0.1?password=&database=');
// Won't trigger `AUTH` and `SELECT`:
$client = new Predis\Client([
'password' => null,
'database' => '',
]);
This fix addresses some old issues with certain libraries and frameworks (see ISSUE #436).
Empty connection parameters do not make much sense anyway so, in the next major release, any field containing NULL
or a zero-length string will be stripped away when converting URI strings and named arrays to instances of Predis\Connection\Parameters
.
FIX: SORT
now always triggers a switch to the master node in replication configurations instead of just when the STORE
modifier is specified. The reason for this change is that SORT
is always considered to be a write operation and it actually fails with a -READONLY
error response when executed against a replica node (ISSUE #554).
FIX: using foreach()
on a client instance when it is connected to a single Redis server does not throw an exception anymore but the iteration will run for just one loop returning a new client for the underlying single-node connection (ISSUE #552, PR #556).
$client = new Predis\Client('tcp://127.0.0.1');
foreach ($client as $clientNode) {
// Iterates just once, does not throw an exception anymore.
}
Using foreach()
actually makes sense when using aggregate connection backends for client-side sharding or redis-cluster
but there is no reason (and it is wrong anyway) to throw an exception in Predis\Client::getIterator()
when the client is connected to a single server.
FIX: Predis\Cluster\Distributor\HashRing::addNodeToRing()
was calculating the hash required for distribution by using crc32()
directly instead of the method Predis\Cluster\Hash\HashGeneratorInterface::hash()
implemented by the class itself. This fix does not have any impact on existing cluster deployments using client-side sharding based on this distributor simply because it does not take any external hash generators so distribution is not going to be affected.
Improved @method
annotations for methods responding to Redis commands defined by Predis\ClientInterface
and Predis\ClientContextInterface
(PR #456 and PR #497, other fixes applied after further analysys).
Published by tillkruss about 4 years ago
github.com/nrk/predis
to github.com/predis/predis
.cweagans/composer-patches
dependency to require-dev
..patch
files in exports.Published by tillkruss about 4 years ago
Predis is under new management. Read the announcement and checkout the roadmap 🚀
If you (or your business) would like to support the development of this fantastic library and ensure it's bright future, please use the GitHub Sponsor button 🙏🏻
hash()
method is an integer (PR #450).ZSCAN
and HSCAN
working witheach()
(PR #448).Published by nrk over 8 years ago
This is a patch release of Predis v1.1 that fixes a few bugs affecting the previous release. As usual you can read the CHANGELOG for a schematic list of the changes.
password
and database
from the global parameters
client option were still being applied to sentinels connections making them fail (sentinels do not understand the AUTH
and SELECT
commands) (PR #346).connect()
on the redis-sentinel connection backend should fall back to the master connection instead of failing (ISSUE #342).Published by nrk over 8 years ago
This is a minor release of Predis packed with new features and various improvements of existing ones. As usual you can read the CHANGELOG for a schematic list of the changes. Thanks to anyone who provided feedback, especially on the new features, and proposed changes implemented in this release! Starting today we also have a chat room on Gitter, for now it's kind of an experiment but we'll see on the long run if it'll prove to be useful.
IMPORTANT: if you are using "predis/predis": "dev-master"
in composer.json
then replace the requirement with tagged releases in the v1.1 branch as soon as possible! Starting today the master
branch will host the development of the next major version of Predis, the first few commits containing some major breaking changes will land there in a matter of days meaning that if you won't replace dev-master
your applications may (and most likely will) fail all of sudden.
NOTE: speaking of Predis v2.0 we are aiming to bump the minimum required version of PHP to 5.5.9 (most likely to happen) and drop PEAR for distribution (still to be decided). The v1.1 branch will be maintaned for fixes so if you are stuck with PHP 5.3 and 5.4 you don't have too much to worry about for a while. If you have anything to say on the matter please join the discussion by leaving a comment or a reaction on #335, we need your feedback!
Support for redis-sentinel is finally baked into Predis! As usual configuring the client is easy, it's just a matter of providing a list of sentinel servers and configure the client accordingly:
$parameters = ['tcp://127.0.0.1:5380', 'tcp://127.0.0.1:5381', 'tcp://127.0.0.1:5382'];
$options = [
'replication' => 'sentinel', // use the appropriate replication backend
'service' => 'mymaster', // provide a service name for discovery
];
$client = new Predis\Client($parameters, $options);
See replication_sentinel.php
for a complete example.
Redis servers protected by SSL-encrypted connections can be accessed by using the tls
or rediss
scheme in connection parameters along with SSL-specific options in the ssl
parameter (array):
// Parameters in the form of a named array
$parameters = [
'scheme' => 'tls',
'host' => '127.0.0.1',
'ssl' => [
'cafile' => '/path/to/redis.pem',
'verify_peer_name' => true,
],
];
// Parameters in the form of an URI string
$parameters = 'tls://127.0.0.1?ssl[cafile]=/path/to/redis.pem&ssl[verify_peer_name]=1';
Implemented the ability to specify default connection parameters for aggregate connections with the new parameters
client option. These parameters augment the usual user-supplied connection parameters (but do not take the precedence over them) when creating new connections and they are mostly useful when the client is using aggregate connections such as redis-cluster and redis-sentinel as these backends can create new connections on the fly based on responses and redirections from Redis:
$parameters = ['tcp://127.0.0.1:6381', 'tcp://127.0.0.1:6382', 'tcp://127.0.0.1:6383'];
$options = [
'cluster' => 'redis',
// New connections to Redis will be created using the same following parameters:
'parameters' => ['database' => 5, 'password' => $secret],
];
$client = new Predis\Client($parameters, $options);
Predis\Client
implements the IteratorAggregate
interface making it is possible to iterate over traversable aggregate connections and get a new client instance for each Redis node:
$client = new Predis\Client($parameters, ['cluster' => 'redis']);
foreach ($client as $nodeClient) {
$nodeClient->flushdb(); // executes FLUSHDB on each node of the cluster
}
SETNX
, MSETNX
, SMOVE
, SISMEMBER
, HSET
, HSETNX
, HEXISTS
, PFADD
, EXISTS
, MOVE
, PERSIST
, EXPIRE
, EXPIREAT
, RENAMENX
. This change does not have a significant impact unless when using strict comparisons (===
and !==
) on the returned value.unix:///path/to/socket
in URI strings to specify a UNIX domain socket file is now deprecated in favor of the format unix:/path/to/socket
(note the lack of the double slash after the scheme) and will not be supported starting with the next major release.SELECT
and AUTH
when database and password are set in connection parameters) regardless of the value of the exception option.Predis\Connection\Aggregate\RedisCluster
will return all the connections mapped in the slots map instead of just the ones in the in-memory pool. This change makes it possible, when the slots map is retrieved from Redis, to iterate over all of the master nodes in the cluster. When the use of CLUSTER SLOTS
is disabled via the useClusterSlots()
method, the iteration returns only the connections with slots ranges associated in their parameters or the ones initialized by -MOVED
responses in order to make the behaviour of the iteration consistent between the two modes of operation.Non-boolean string values passed to the persistent
connection parameter can be used to create different persistent connections to the same host-port pair:
// $parameters1 and $parameters2 will create two different persistent connections:
$parameters1 = "tcp://127.0.0.1:6379?persistent=first";
$parameters2 = "tcp://127.0.0.1:6379?persistent=second";
Note that this feature was already present in Predis but required both persistent
and path
to be set as illustrated by #139, this change was needed to prevent confusion with how path
is used to select a database when using the redis
scheme.
Various improvements to Predis\Connection\Aggregate\MasterSlaveReplication
(the "basic" replication backend, not the new one based on redis-sentinel):
-LOADING
response returned by Redis), the backend discards the failed connection and performs a new attempt on the next slave. When no other slave is available the master server is used for read-only commands as last resort.discover()
method which internally relies on the output of the command INFO REPLICATION
executed against the master server or one of the slaves. The backend can also be configured to do this automatically when it fails to reach one of the servers.switchToMaster()
and switchToSlave()
methods to make it easier to force a switch to the master server or a random slave when needed.