Configuration

All configuration for Redis Cache Pro happens with a single PHP constant: WP_REDIS_CONFIG. Any configuration error will generate an error log entry, and if WP_DEBUG is enabled, additionally throw an exception.

Be sure to define the WP_REDIS_CONFIG constant towards the top of your wp-config.php, not the very bottom.

To easily disable the object cache, you may use the WP_REDIS_DISABLED constant or environment variable. Read more about it in the debugging instructions.

Connecting to an instance

You can either connect using the host and port combination:

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => '...',
'host' => '127.0.0.1',
'port' => 6379,
'password' => 'secret',
]);

Or a unix socket without a port:

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => '...',
'host' => '/var/run/redis/redis-server.sock',
'password' => 'secret',
]);

Connecting to a cluster

To connect to a cluster, use the cluster option instead of host.

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => '...',
'password' => 'secret',
'cluster' => [
'tcp://127.0.0.1:7001',
'tcp://127.0.0.1:7002',
'tcp://127.0.0.1:7003',
'tcp://127.0.0.1:7004',
],
]);

Utilizing environment variables

In some cases you may want to use environment variables to configure the object cache, in PHP you can use the getenv() function to do so.

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => getenv('WP_REDIS_TOKEN'),
'prefix' => getenv('WP_REDIS_PREFIX') ?: null,
'maxttl' => getenv('WP_REDIS_MAXTTL') ?: 3600,
]);

Recommended configurations

Standard

For standard setups, the configuration below is recommend for production environments.

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => '...',
// 'host' => '127.0.0.1',
// 'port' => 6379,
// 'password' => 'secret',
// 'database' => 0,
'maxttl' => 3600 * 24 * 7, // 7 days
'timeout' => 0.5,
'read_timeout' => 0.5,
'async_flush' => true, // requires Redis 4.0 or greater
'debug' => false,
]);

High performance

When optimizing for milliseconds, the configuration below is recommended as well as setting an Eviction Policy.

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => '...',
// 'host' => '127.0.0.1',
// 'port' => 6379,
// 'password' => 'secret',
// 'database' => 0,
'timeout' => 0.5,
'read_timeout' => 0.5,
'async_flush' => true, // requires Redis 4.0 or greater
'compression' => 'zstd', // requires PhpRedis 5.1 to be compiled with support
'serializer' => 'igbinary', // requires PhpRedis to be compiled with support
'split_alloptions' => true,
'debug' => false,
'save_commands' => false,
]);

Configuration options

These are all available Configuration options and their default values.

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => null, // (string) Your license token
'logger' => null, // (string) The logger class name
'log_levels' => ['emergency', 'alert', 'critical', 'error'], // (array) Log levels
'host' => null, // (string) The hostname of the instance
'port' => null, // (integer) The port of the instance
'database' => 0, // (integer) The Redis database
'password' => null, // (string) The instance/cluster password
'prefix' => null, // (string) The prefix for all keys
'maxttl' => null, // (integer) The maximum time-to-live in seconds
'timeout' => 0.0, // (float) Connection timeout in seconds
'read_timeout' => 0.0, // (float) Read timeout in seconds
'retry_interval' => 0, // (integer) Retry interval in milliseconds
'persistent' => false, // (bool) Whether the connection is persistent
'async_flush' => false, // (bool) Whether flushing is asynchronous
'cluster' => null, // (array|string) The cluster configuration name as string, or an array of cluster nodes
'slave_failover' => null, // (string) Slave failover / distribution strategy (`none`, `error`, `distribute`, `distribute_slaves`)
'serializer' => 'php', // (string) The data serializer (`php` or `igbinary` supported)
'compression' => 'none', // (string) The data compression format (`none`, `lzf` or `zstd` supported)
'global_groups' => null, // (array) The list of global cache groups that are not blog-specific in a network environment
'non_persistent_groups' => null, // (array) The non-persistent groups that will only be cached for the duration of a request
'debug' => false, // (bool) Whether debug mode is enabled
'save_commands' => false, // (bool) Whether all executed commands should be logged
'split_alloptions' => false, // (bool) Whether the `alloptions` key should be stored as a hash
]);

Token

The token option should be set to the license token you received when after purchasing. It's a 60 characters long string and will enable automatic plugin updates and unlock features.

wp-config.php
define('WP_REDIS_CONFIG', [
'token' => '02269ec4add8cac59...',
]);

Logger

The logger configuration option allow a custom log class to be set. Read more about it in the logging documentation.

Log Levels

The log_levels option defaults to ['emergency', 'alert', 'critical', 'error'] and all errors with these levels will be logged in silent mode by the ErrorLogLogger.

The available logging levels are:

wp-config.php
define('WP_REDIS_CONFIG', [
'log_levels' => [
'emergency', // System is unusable
'alert', // Action must be taken immediately
'critical', // Critical conditions
'error', // Runtime errors that do not require immediate action but should typically be logged and monitored
'warning', // Exceptional occurrences that are not errors
'notice', // Normal but significant events
'info', // Interesting events
'debug', // Detailed debug information
],
]);

Host

The host option defines the IP address, hostname unit socket and scheme used to connect to Redis.

wp-config.php
define('WP_REDIS_CONFIG', [
'host' => '127.0.0.1'
'host' => 'tcp://127.0.0.1'
'host' => 'tls://xxxxxx.cache.amazonaws.com',
'host' => '/var/run/redis/redis-server.sock',
]);

Port

The port option is mandatory when connecting to a single instance via TCP or TLS.

wp-config.php
define('WP_REDIS_CONFIG', [
'port' => 6379,
]);

Database

The database option determines Redis database used to store all cache data. The default is 0.

wp-config.php
define('WP_REDIS_CONFIG', [
'database' => 2,
]);

Prefix

Similar to WP’s $table_prefix variable, which prefixes all database table names, the prefix option will place the given string in front of all cache keys.

wp-config.php
define('WP_REDIS_CONFIG', [
'prefix' => 'mysitename',
]);

MaxTTL

The maxttl option will enforce a "maximum time-to-live" for all new cache keys in seconds. It's value must be an integer.

This option will only affect keys created in the future. You might want to flush your cache once to purge keys without an expiration.

wp-config.php
define('WP_REDIS_CONFIG', [
'maxttl' => 3600 * 24, // 24 hours
]);

Timeout

The connection timeout to Redis, expressed in seconds.

wp-config.php
define('WP_REDIS_CONFIG', [
'timeout' => 1.5, // 1.5 seconds
]);

Read Timeout

The connection's read timeout, expressed in seconds.

wp-config.php
define('WP_REDIS_CONFIG', [
'read_timeout' => 1.5, // 1.5 seconds
]);

Retry Interval

The connection's retry interval, expressed in milliseconds.

wp-config.php
define('WP_REDIS_CONFIG', [
'retry_interval' => 300, // 0.3 seconds
]);

Persistent

Defines if a persistent connection should be used.

wp-config.php
define('WP_REDIS_CONFIG', [
'persistent' => true,
]);

Async Flush

Asynchronous flushing was introduced in Redis 4.0 and can be enabled using the async_flush option. It allows deleting large amounts of keys in the background without blocking the server.

wp-config.php
define('WP_REDIS_CONFIG', [
'async_flush' => true, // boolean
]);

Slave Failover

When using a Redis cluster commands will only ever be send to master nodes, but can be configured differently for read-only commands if requested.

wp-config.php
define('WP_REDIS_CONFIG', [
// Only send commands to master nodes (default)
'slave_failover' => 'none',
// In the event we can't reach a master, and it has slaves, failover for read commands
'slave_failover' => 'error',
// Always distribute readonly commands between masters and slaves, at random
'slave_failover' => 'distribute',
// Always distribute readonly commands to the slaves, at random
'slave_failover' => 'distribute_slaves',
]);

Serializer

All data store in Redis is serialized using PHP's serialize() and unserialize() functions.

Alternatively you can use igbinary, which is a drop in replacement that stores php data structures in a compact binary form. The average reduction in size is around 50%.

Supported values are php and igbinary.

wp-config.php
define('WP_REDIS_CONFIG', [
'serializer' => 'igbinary', // store data in binary format
]);

You must flush your cache when changing serializers to avoid corrupt data.

Compression

The compression option determines the data compression format used for all data stored in Redis. Supported formats are lzf and zstd. Both formats require PhpRedis to be compiled with support for them. zstd was added in PhpRedis 5.1. The default is none (no data compression).

wp-config.php
define('WP_REDIS_CONFIG', [
'compression' => 'zstd', // Zstandard (level 3)
]);

You must flush your cache after changing data compression to avoid corrupt data.

Global Groups

The list of global cache groups that are not blog-specific in a network environment. These will be added in addition to what WordPress Core defines as global groups.

wp-config.php
define('WP_REDIS_CONFIG', [
'global_groups' => ['redirects', '...'],
]);

Non-persistent Groups

The non-persistent groups that will only be cached for the duration of a request. These will be added in addition to what WordPress Core defines as non-persistent groups.

wp-config.php
define('WP_REDIS_CONFIG', [
'non_persistent_groups' => ['themes'],
]);

Splitting "alloptions"

Whether the alloptions key should be split into individual keys and stored in a hash. This will help avoid race conditions in some scenarios.

wp-config.php
define('WP_REDIS_CONFIG', [
'split_alloptions' => true, // use hash for `alloptions` key
]);