Configuration Options
Overview #
The configuration options and their default values:
define('WP_REDIS_CONFIG', [
// (string) Your license token
'token' => null,
// (string) The logger class name
'logger' => null,
// (array) Log levels
'log_levels' => ['emergency', 'alert', 'critical', 'error'],
// (string) The hostname of the instance
'host' => null,
// (integer) The port of the instance
'port' => null,
// (integer) The Redis database
'database' => 0,
// (string) The instance/cluster password
'password' => null,
// (string) The prefix for all keys
'prefix' => null,
// (integer) The maximum time-to-live in seconds
'maxttl' => null,
// (float) Connection timeout in seconds
'timeout' => 0.0,
// (float) Read timeout in seconds
'read_timeout' => 0.0,
// (integer) Retry interval in milliseconds
'retry_interval' => 0,
// (bool) Whether the connection is persistent
'persistent' => false,
// (bool) Whether flushing is asynchronous [requires Redis 4.0.0+]
'async_flush' => false,
// (array|string) The cluster configuration name as string, or an array of cluster nodes
'cluster' => null,
// (string) Slave failover / distribution strategy
// `none`, `error`, `distribute`, `distribute_slaves`
'cluster_failover' => 'none',
// (array) An array of replicated Redis servers
'servers' => null,
// (string) Replication failover strategy
// `distribute`, `distribute_slaves`, `concentrate`
'replication_strategy' => 'distribute',
// (string) The data serializer
// `php`, `igbinary`
'serializer' => 'php',
// (string) The data compression format
// `none`, `lzf`, `lz4`, `zstd`
'compression' => 'none',
// (array) The list of global cache groups that are not blog-specific in a network environment
'global_groups' => null,
// (array) The non-persistent groups that will only be cached for the duration of a request
'non_persistent_groups' => null,
// (array) The non-prefetchable groups that will not be prefetched
'non_prefetchable_groups' => null,
// (bool) Whether to batch prefetch keys for requests
'prefetch' => false,
// (bool) Whether the `alloptions` key should be stored as a hash
'split_alloptions' => false,
// (string) Multisite flushing strategy [requires Redis 4.0.0+]
// `all`, `site`, `global`
'flush_network' => 'all',
// (array) The TLS context options, such as `verify_peer` and `ciphers`.
'tls_options' => null,
// (bool) Whether debug mode is enabled
'debug' => false,
// (bool) Whether all executed commands should be logged
'save_commands' => false,
]);
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.
define('WP_REDIS_CONFIG', [
'token' => '02269ec4add8cac59...',
]);
Cache #
The cache
configuration option allows a custom object cache implementation to be set. It must implement the RedisCachePro\ObjectCaches\ObjectCacheInterface
interface, or ideally extend the existing RedisCachePro\ObjectCaches\PhpRedisObjectCache
class.
define('WP_REDIS_CONFIG', [
'cache' => MyObjectCache::class,
]);
Connector #
The connector
configuration option allows a custom connector to be set. It must implement the RedisCachePro\Connectors\Connector
interface.
define('WP_REDIS_CONFIG', [
'connector' => MyConnector::class,
]);
Logger #
The logger
configuration option allows 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:
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.
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.
define('WP_REDIS_CONFIG', [
'port' => 6379,
]);
Database #
The database
option determines Redis database used to store all cache data. The default is 0
.
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.
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.
define('WP_REDIS_CONFIG', [
'maxttl' => 3600 * 24, // 24 hours
]);
Timeout #
The connection timeout to Redis, expressed in seconds.
define('WP_REDIS_CONFIG', [
'timeout' => 1.5, // 1.5 seconds
]);
Read Timeout #
The connection's read timeout, expressed in seconds.
define('WP_REDIS_CONFIG', [
'read_timeout' => 1.5, // 1.5 seconds
]);
Retry Interval #
The connection's retry interval, expressed in milliseconds.
define('WP_REDIS_CONFIG', [
'retry_interval' => 300, // 0.3 seconds
]);
Persistent #
Defines if a persistent connection should be used.
define('WP_REDIS_CONFIG', [
'persistent' => true,
]);
Asynchronous Flushing #
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.
define('WP_REDIS_CONFIG', [
'async_flush' => true, // boolean
]);
Cluster #
To connect to a cluster, provide an array of master nodes using the cluster configuration option, instead of using host
:
define('WP_REDIS_CONFIG', [
'cluster' => [
'tcp://172.17.0.1:6379',
'tcp://172.17.0.1:6379',
'tcp://172.17.0.1:6379',
],
]);
Cluster 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.
define('WP_REDIS_CONFIG', [
// Only send commands to master nodes
'cluster_failover' => 'none',
// If a master can't be reached, and it has replicas, failover for read commands
'cluster_failover' => 'error',
// Always distribute readonly commands between masters and replicas, at random
'cluster_failover' => 'distribute',
// Always distribute readonly commands to the replicas, at random
'cluster_failover' => 'distribute_replicas',
]);
Servers #
To use a replicated master with read-only replicas, provide the master using the servers
configuration option to have the replicas automatically discovered:
define('WP_REDIS_CONFIG', [
'token' => '...',
'servers' => [
'tcp://127.0.0.1:7000?role=master',
],
]);
You may also specify the read replicas.
Replication Strategy #
By default read requests are distributed across all replicas as well as the master. To change this behavior use the replication_strategy
configuration option.
define('WP_REDIS_CONFIG', [
// Distribute readonly commands between master and replicas, at random
'replication_strategy' => 'distribute',
// Distribute readonly commands to the replicas, at random
'replication_strategy' => 'distribute_replicas',
// Send readonly commands to a single, random replica
'replication_strategy' => 'concentrate',
]);
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
.
To avoid corrupt data and crashing your site, learn more about switching data serializer.
define('WP_REDIS_CONFIG', [
'serializer' => 'igbinary', // store data in binary format
]);
Compression #
The compression
option determines the data compression format used for all data stored in Redis.
Supported formats are lzf
, lz4
and zstd
. Both formats require PhpRedis to be compiled with support for them. zstd
was added in PhpRedis 5.1 and lz4
was added in PhpRedis 5.3. The default is none
(no data compression).
To avoid corrupt data and crashing your site, learn more about switching data compression.
define('WP_REDIS_CONFIG', [
'compression' => 'zstd', // Zstandard (level 3)
]);
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.
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.
define('WP_REDIS_CONFIG', [
'non_persistent_groups' => ['acf'],
]);
Non-prefetchable Groups #
The non-prefetchable groups that will not be prefetched.
define('WP_REDIS_CONFIG', [
'non_prefetchable_groups' => ['acf'],
]);
Prefetching #
When prefetching is enabled the requested cache keys are stored on a per-request basis and batch loaded per group early on for consecutive requests.
The list of prefetchable keys is updated each request to keep it fresh.
define('WP_REDIS_CONFIG', [
'prefetch' => true,
// 'non_prefetchable_groups' => ['acf'],
]);
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.
define('WP_REDIS_CONFIG', [
'split_alloptions' => true, // use hash for `alloptions` key
]);
Flushing Networks #
Since individual sites in a multisite network share data such as users, logins and transients, by default, the entire Redis database is flushed when wp_cache_flush()
is called.
When using Redis 4.0.0 (or newer), you may only flush the data of an individual site, by setting the flush_network
configuration option to site
. Or if you also want to flush all global groups, but not data from other sites, set flush_network
to global
.
define('WP_REDIS_CONFIG', [
'flush_network' => 'site', // only flush individual sites
]);
TLS Options #
When using tls://
transports, you may set the context options, such as verify_peer
and ciphers
using the tls_options
configuration option:
define('WP_REDIS_CONFIG', [
'tls_options' => [
'verify_peer' => false,
],
]);
A full list of SSL/TLS context options is available on php.net.
Debug #
The debug
configuration option is described in detail under Debugging.