Download the PHP package zenstruck/redis without Composer

zenstruck/redis

Lazy proxy for php-redis with DX helpers, utilities and a unified API.

Zenstruck\Redis is a unified proxy for \Redis|\RedisArray|\RedisCluster. With a few exceptions and considerations, the API is the same no matter the underlying client. This allows you to use the same API in development, where you are likely just using \Redis, and production, where you could be using \RedisArray or \RedisCluster.

The proxy is lazy in that, if created via a DSN, doesn't instantiate the underlying client until a command is executed.

This library integrates well with Symfony and a recipe is available.

Installation

Redis Factory

Creating a Redis client instance is done via a DSN string. The DSN must use the following format:

Redis Proxy Factory

It is recommended to use the proxy whenever possible. It has the following benefits over using the real client:

1. Lazy: a connection is not established until a Redis command is actually called.
2. Encapsulated: for the most part, knowledge of the real client is not required. You don't need to change your usage depending on the client used. There are exceptions to this.
3. Developer Experience (DX): use the fluent sequence and transaction api.

Here are some examples creating the proxy from a DSN.

You can also create a Proxy from an exising instance of \Redis|\RedisArray|\RedisCluster:

Redis Real Client Factory

An instance of \Redis|\RedisArray|\RedisCluster can be created directly:

Factory Options

Certain Redis options can be set via your DSN's query parameters or passed as an array to the second parameter of Zenstruck\Redis::create/createClient().

Prefix

You can set a prefix for all keys:

Serializer Option

By default, Redis stores all scalar/null values as strings and objects/arrays as "Array"/"Object". In order to store properly typed values and objects/arrays, you must configure a Redis serializer:

NOTE: There is a performance trade off when using Redis serialization. Consider creating a separate client for operations/logic that requires serialization.

Redis Proxy API

Sequences/Pipelines and Transactions

The proxy has a fluent, auto-completable API for Redis pipelines and transactions:

NOTE: When using sequence() with \RedisCluster, the commands are executed atomically as pipelines are not supported.

NOTE: When using sequence()/transaction() with a \RedisArray instance, the first command in the sequence/transaction must be a "key-based command" (ie get()/set()). This is to choose the node the transaction is run on.

Countable\Iterable

Zenstruck\Redis is countable and iterable. There are some differences when counting/iterating depending on the underlying client:

• \Redis: count is always 1 and iterates over itself once
• \RedisArray: count is the number of hosts and iterates over each host wrapped in a proxy.
• \RedisCluser: count is the number of masters and iterates over each master with node parameters pre-set. This enables running node commands on each master without passing node parameters to these commands (when iterating)

NOTE: If running commands that require being run on each host/master it is recommended to iterate and run even if using \Redis. This allows a seamless transition to \RedisArray/\RedisCluster later.

Utilities

ExpiringSet

Zenstruck\Redis\Utility\ExpiringSet encapsulates the concept of a Redis expiring set: a set (unordered list with no duplicates) whose members expire after a time. Each read/write operation on the set prunes expired members.

NOTE: In order to use complex types (arrays/objects) as members, your redis client must be configured with a serializer.

Below is a pseudocode example using this object for tracking active users on a website. When authenticated users login or request a page, their username is added to the set with a 5-minute idle time-to-live (TTL). A user is considered active within this time. On logout, they are removed from the set. If a user has not made a request within their last TTL, they are removed from the set.

Integrations

Symfony Framework

Add a supported Redis DSN environment variable:

Configure services:

Use Zenstruck\Redis for session storage (see Symfony Docs for more details/options):

Contributing

Running the test suite:

Credit

Much of the code to create php-redis clients from a DSN has been taken and modified from the Symfony Framework.