clue/reactphp-redis

README

clue/reactphp-redis

Async Redis client implementation, built on top of ReactPHP.

Development version: This branch contains the code for the upcoming 3.0 release. For the code of the current stable 2.x release, check out the 2.x branch.

The upcoming 3.0 release will be the way forward for this package. However, we will still actively support 2.x for those not yet on the latest version. See also installation instructions for more details.

Redis is an open source, advanced, in-memory key-value database. It offers a set of simple, atomic operations in order to work with its primitive data types. Its lightweight design and fast operation makes it an ideal candidate for modern application stacks. This library provides you a simple API to work with your Redis database from within PHP. It enables you to set and query its data or use its PubSub topics to react to incoming events.

Async execution of Commands - Send any number of commands to Redis in parallel (automatic pipeline) and process their responses as soon as results come in. The Promise-based design provides a sane interface to working with async responses.
Event-driven core - Register your event handler callbacks to react to incoming events, such as an incoming PubSub message event.
Lightweight, SOLID design - Provides a thin abstraction that is just good enough and does not get in your way. Future or custom commands and events require no changes to be supported.
Good test coverage - Comes with an automated tests suite and is regularly tested against versions as old as Redis v2.6 and newer.

Table of Contents

Support us
Quickstart example
Usage
- Commands
- Promises
- PubSub
API
- RedisClient
  - __construct()
  - __clone()
  - __call()
  - callAsync()
  - end()
  - close()
  - error event
  - close event
Install
Tests
License

Support us

We invest a lot of time developing, maintaining and updating our awesome open-source projects. You can help us sustain this high-quality of our work by becoming a sponsor on GitHub. Sponsors get numerous benefits in return, see our sponsoring page for details.

Let's take these projects to the next level together! 🚀

Quickstart example

Once installed, you can use the following code to connect to your local Redis server and send some requests:

<?php

require __DIR__ . '/vendor/autoload.php';

$redis = new Clue\React\Redis\RedisClient('localhost:6379');

$redis->set('greeting', 'Hello world');
$redis->append('greeting', '!');

$redis->get('greeting')->then(function (string $greeting) {
    // Hello world!
    echo $greeting . PHP_EOL;
});

$redis->incr('invocation')->then(function (int $n) {
    echo 'This is invocation #' . $n . PHP_EOL;
});

Usage

Commands

Most importantly, this project provides a RedisClient instance that can be used to invoke all Redis commands (such as GET, SET, etc.).

$redis = new Clue\React\Redis\RedisClient('localhost:6379');

$redis->get($key);
$redis->set($key, $value);
$redis->exists($key);
$redis->expire($key, $seconds);
$redis->mget($key1, $key2, $key3);

$redis->multi();
$redis->exec();

$redis->publish($channel, $payload);
$redis->subscribe($channel);

$redis->ping();
$redis->select($database);

// many more…

Each method call matches the respective Redis command. For example, the $redis->get() method will invoke the GET command.

All Redis commands are automatically available as public methods via the magic __call() method or through the more explicit [callAsync() method]. Listing all available commands is out of scope here, please refer to the Redis command reference.

Any arguments passed to the method call will be forwarded as command arguments. For example, the $redis->set('name', 'Alice') call will perform the equivalent of a SET name Alice command. It's safe to pass numeric arguments where applicable (for example $redis->expire($key, 60)), but internally Redis requires all arguments to always be coerced to string values.

Each of these commands supports async operation and returns a Promise that eventually fulfills with its results on success or rejects with an Exception on error. See also the following section about promises for more details.

Promises

Sending commands is async (non-blocking), so you can actually send multiple commands in parallel. Redis will respond to each command request with a response message, pending commands will be pipelined automatically.

Sending commands uses a Promise-based interface that makes it easy to react to when a command is completed (i.e. either successfully fulfilled or rejected with an error):

$redis->get($key)->then(function (?string $value) {
    var_dump($value);
}, function (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

PubSub

This library is commonly used to efficiently transport messages using Redis' Pub/Sub (Publish/Subscribe) channels. For instance, this can be used to distribute single messages to a larger number of subscribers (think horizontal scaling for chat-like applications) or as an efficient message transport in distributed systems (microservice architecture).

The PUBLISH command can be used to send a message to all clients currently subscribed to a given channel:

$channel = 'user';
$message = json_encode(['id' => 10]);
$redis->publish($channel, $message);

The SUBSCRIBE command can be used to subscribe to a channel and then receive incoming PubSub message events:

$channel = 'user';
$redis->subscribe($channel);

$redis->on('message', function (string $channel, string $payload) {
    // pubsub message received on given $channel
    var_dump($channel, json_decode($payload));
});

Likewise, you can use the same client connection to subscribe to multiple channels by simply executing this command multiple times:

$redis->subscribe('user.register');
$redis->subscribe('user.join');
$redis->subscribe('user.leave');

Similarly, the PSUBSCRIBE command can be used to subscribe to all channels matching a given pattern and then receive all incoming PubSub messages with the pmessage event:

$pattern = 'user.*';
$redis->psubscribe($pattern);

$redis->on('pmessage', function (string $pattern, string $channel, string $payload) {
    // pubsub message received matching given $pattern
    var_dump($channel, json_decode($payload));
});

Once you're in a subscribed state, Redis no longer allows executing any other commands on the same client connection. This is commonly worked around by simply creating a second client connection and dedicating one client connection solely for PubSub subscriptions and the other for all other commands.

The UNSUBSCRIBE command and PUNSUBSCRIBE command can be used to unsubscribe from active subscriptions if you're no longer interested in receiving any further events for the given channel and pattern subscriptions respectively:

$redis->subscribe('user');

Loop::addTimer(60.0, function () use ($redis) {
    $redis->unsubscribe('user');
});

Likewise, once you've unsubscribed the last channel and pattern, the client connection is no longer in a subscribed state and you can issue any other command over this client connection again.

Each of the above methods follows normal request-response semantics and return a Promise to await successful subscriptions. Note that while Redis allows a variable number of arguments for each of these commands, this library is currently limited to single arguments for each of these methods in order to match exactly one response to each command request. As an alternative, the methods can simply be invoked multiple times with one argument each.

Additionally, you can listen for the following PubSub events to get notifications about subscribed/unsubscribed channels and patterns:

$redis->on('subscribe', function (string $channel, int $total) {
    // subscribed to given $channel
});
$redis->on('psubscribe', function (string $pattern, int $total) {
    // subscribed to matching given $pattern
});
$redis->on('unsubscribe', function (string $channel, int $total) {
    // unsubscribed from given $channel
});
$redis->on('punsubscribe', function (string $pattern, int $total) {
    // unsubscribed from matching given $pattern
});

When the underlying connection is lost, the unsubscribe and punsubscribe events will be invoked automatically. This gives you control over re-subscribing to any channels and patterns as appropriate.

API

RedisClient

The RedisClient is responsible for exchanging messages with your Redis server and keeps track of pending commands.

$redis = new Clue\React\Redis\RedisClient('localhost:6379');

$redis->incr('hello');

Besides defining a few methods, this interface also implements the EventEmitterInterface which allows you to react to certain events as documented below.

Internally, this class creates the underlying connection to Redis only on demand once the first request is invoked on this instance and will queue all outstanding requests until the underlying connection is ready. This underlying connection will be reused for all requests until it is closed. By default, idle connections will be held open for 1ms (0.001s) when not used. The next request will either reuse the existing connection or will automatically create a new underlying connection if this idle time is expired.

From a consumer side this means that you can start sending commands to the database right away while the underlying connection may still be outstanding. Because creating this underlying connection may take some time, it will enqueue all outstanding commands and will ensure that all commands will be executed in correct order once the connection is ready.

If the underlying database connection fails, it will reject all outstanding commands and will return to the initial "idle" state. This means that you can keep sending additional commands at a later time which will again try to open a new underlying connection. Note that this may require special care if you're using transactions (MULTI/EXEC) that are kept open for longer than the idle period.

While using PubSub channels (see SUBSCRIBE and PSUBSCRIBE commands), this client will never reach an "idle" state and will keep pending forever (or until the underlying database connection is lost). Additionally, if the underlying database connection drops, it will automatically send the appropriate unsubscribe and punsubscribe events for all currently active channel and pattern subscriptions. This allows you to react to these events and restore your subscriptions by creating a new underlying connection repeating the above commands again.

Note that creating the underlying connection will be deferred until the first request is invoked. Accordingly, any eventual connection issues will be detected once this instance is first used. You can use the end() method to ensure that the connection will be soft-closed and no further commands can be enqueued. Similarly, calling end() on this instance when not currently connected will succeed immediately and will not have to wait for an actual underlying connection.

__construct()

The new RedisClient(string $uri, ConnectorInterface $connector = null) constructor can be used to create a new RedisClient instance.

The $uri can be given in the standard form [redis[s]://][:auth@]host[:port][/db]. You can omit the URI scheme and port if you're connecting to the default port 6379:

// both are equivalent due to defaults being applied
$redis = new Clue\React\Redis\RedisClient('localhost');
$redis = new Clue\React\Redis\RedisClient('redis://localhost:6379');

Redis supports password-based authentication (AUTH command). Note that Redis' authentication mechanism does not employ a username, so you can pass the password h@llo URL-encoded (percent-encoded) as part of the URI like this:

// all forms are equivalent
$redis = new Clue\React\Redis\RedisClient('redis://:h%40llo@localhost');
$redis = new Clue\React\Redis\RedisClient('redis://ignored:h%40llo@localhost');
$redis = new Clue\React\Redis\RedisClient('redis://localhost?password=h%40llo');

You can optionally include a path that will be used to select (SELECT command) the right database:

// both forms are equivalent
$redis = new Clue\React\Redis\RedisClient('redis://localhost/2');
$redis = new Clue\React\Redis\RedisClient('redis://localhost?db=2');

You can use the standard rediss:// URI scheme if you're using a secure TLS proxy in front of Redis:

$redis = new Clue\React\Redis\RedisClient('rediss://redis.example.com:6340');

You can use the redis+unix:// URI scheme if your Redis instance is listening on a Unix domain socket (UDS) path:

$redis = new Clue\React\Redis\RedisClient('redis+unix:///tmp/redis.sock');

// the URI MAY contain `password` and `db` query parameters as seen above
$redis = new Clue\React\Redis\RedisClient('redis+unix:///tmp/redis.sock?password=secret&db=2');

// the URI MAY contain authentication details as userinfo as seen above
// should be used with care, also note that database can not be passed as path
$redis = new Clue\React\Redis\RedisClient('redis+unix://:secret@/tmp/redis.sock');

This method respects PHP's default_socket_timeout setting (default 60s) as a timeout for establishing the underlying connection and waiting for successful authentication. You can explicitly pass a custom timeout value in seconds (or use a negative number to not apply a timeout) like this:

$redis = new Clue\React\Redis\RedisClient('localhost?timeout=0.5');

By default, idle connections will be held open for 1ms (0.001s) when not used. The next request will either reuse the existing connection or will automatically create a new underlying connection if this idle time is expired. This ensures you always get a "fresh" connection and as such should not be confused with a "keepalive" or "heartbeat" mechanism, as this will not actively try to probe the connection. You can explicitly pass a custom idle timeout value in seconds (or use a negative number to not apply a timeout) like this:

$redis = new Clue\React\Redis\RedisClient('localhost?idle=10.0');

If you need custom DNS, proxy or TLS settings, you can explicitly pass a custom instance of the ConnectorInterface:

$connector = new React\Socket\Connector([
    'dns' => '127.0.0.1',
    'tcp' => [
        'bindto' => '192.168.10.1:0'
    ],
    'tls' => [
        'verify_peer' => false,
        'verify_peer_name' => false
    ]
]);

$redis = new Clue\React\Redis\RedisClient('localhost', $connector);

__clone()

The __clone() method is a magic method in PHP that is called automatically when a RedisClient instance is being cloned:

$original = new Clue\React\Redis\RedisClient($uri);
$redis = clone $original;

This method ensures the cloned client is created in a "fresh" state and any connection state is reset on the clone, matching how a new instance would start after returning from its constructor. Accordingly, the clone will always start in an unconnected and unclosed state, with no event listeners attached and ready to accept commands. Invoking any of the commands will establish a new connection as usual:

$redis = clone $original;
$redis->set('name', 'Alice');

This can be especially useful if the original connection is used for a PubSub subscription or when using blocking commands or similar and you need a control connection that is not affected by any of this. Both instances will not be directly affected by any operations performed, for example you can close() either instance without also closing the other. Similarly, you can also clone a fresh instance from a closed state or overwrite a dead connection:

$redis->close();
$redis = clone $redis;
$redis->set('name', 'Alice');

__call()

The __call(string $name, list<string|int|float> $args): PromiseInterface<mixed> method can be used to invoke the given command.

This is a magic method that will be invoked when calling any Redis command on this instance. Each method call matches the respective Redis command. For example, the $redis->get() method will invoke the GET command.

$redis->get($key)->then(function (?string $value) {
    var_dump($value);
}, function (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

All Redis commands are automatically available as public methods via this magic __call() method. Note that some static analysis tools may not understand this magic method, so you may also the callAsync() method as a more explicit alternative. Listing all available commands is out of scope here, please refer to the Redis command reference.

callAsync()

The callAsync(string $command, string|int|float ...$args): PromiseInterface<mixed> method can be used to invoke a Redis command.

For example, the GET command can be invoked like this:

$redis->callAsync('GET', 'name')->then(function (?string $name): void {
    echo 'Name: ' . ($name ?? 'Unknown') . PHP_EOL;
}, function (Throwable $e): void {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

The string $command parameter can be any valid Redis command. All Redis commands are available through this method. As an alternative, you may also use the magic __call() method, but note that not all static analysis tools may understand this magic method. Listing all available commands is out of scope here, please refer to the Redis command reference.

The optional string|int|float ...$args parameter can be used to pass any additional arguments that some Redis commands may require or support. Values get passed directly to Redis, with any numeric values converted automatically since Redis only works with string arguments internally:

$redis->callAsync('SET', 'name', 'Alice', 'EX', 600);

This method supports async operation and returns a Promise that eventually fulfills with its results on success or rejects with an Exception on error. See also promises for more details.

end()

The end():void method can be used to soft-close the Redis connection once all pending commands are completed.

close()

The close():void method can be used to force-close the Redis connection and reject all pending commands.

error event

The error event will be emitted once a fatal error occurs, such as when the client connection is lost or is invalid. The event receives a single Exception argument for the error instance.

$redis->on('error', function (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

This event will only be triggered for fatal errors and will be followed by closing the client connection. It is not to be confused with "soft" errors caused by invalid commands.

close event

The close event will be emitted once the client connection closes (terminates).

$redis->on('close', function () {
    echo 'Connection closed' . PHP_EOL;
});

Install

The recommended way to install this library is through Composer. New to Composer?

Once released, this project will follow SemVer. At the moment, this will install the latest development version:

composer require clue/redis-react:^3@dev

See also the CHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHP extensions and supports running on PHP 7.1 through current PHP 8+. It's highly recommended to use the latest supported PHP version for this project.

We're committed to providing long-term support (LTS) options and to provide a smooth upgrade path. You may target multiple versions at the same time to support a wider range of PHP versions like this:

composer require "clue/redis-react:^3@dev || ^2"

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

composer install

To run the test suite, go to the project root and run:

vendor/bin/phpunit

The test suite is set up to always ensure 100% code coverage across all supported environments. If you have the Xdebug extension installed, you can also generate a code coverage report locally like this:

XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text

The test suite contains both unit tests and functional integration tests. The functional tests require access to a running Redis server instance and will be skipped by default.

If you don't have access to a running Redis server, you can also use a temporary Redis Docker image:

docker run --net=host redis

To now run the functional tests, you need to supply your login details in an environment variable like this:

REDIS_URI=localhost:6379 vendor/bin/phpunit

On top of this, we use PHPStan on max level to ensure type safety across the project:

vendor/bin/phpstan

License

This project is released under the permissive MIT license.

Did you know that I offer custom development services and issuing invoices for sponsorships of releases and for contributions? Contact me (@clue) for details.

README