Configuration Options

Jump to heading# Overview

The configuration options and their default values:

define('WP_REDIS_CONFIG', [
    // (string) Your license token
    'token' => null,
    
    // (string) The name of the client
    'client' => 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 connection's username (Redis 6+).
    'username' => null,
    
    // (string) The connection's 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,

    // (int) The amount of retries
    'retries' => 5,

    // (string) The backoff algorithm.
    'backoff' => 'default',

    // (bool) Whether the connection is persistent
    'persistent' => false,
    
    // (bool) Whether the Redis database is shared
    'shared' => false,

    // (bool) Whether flushing is asynchronous (Redis 4+)
    '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) The array of Redis Sentinels
    'sentinels' => null,
    
    // (string) The Redis Sentinel service name.
    'service' => null,

    // (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,

    // (array) The analytics configuration
    'analytics' => [
        // (bool) Whether to collect and display analytics
        'enabled' => true,

        // (bool) Whether to restore analytics data after cache flushes
        'persist' => true,

        // (int) The number of seconds to keep analytics before purging them
        'retention' => 60 * 60 * 2,

        // (bool) Whether to print a HTML comment with non-sensitive metrics
        'footnote' => true,
    ],
  
    // (array) The Relay configuration options
    'relay' => [
        // (bool) Whether to register Relay event listeners
        'listeners' => false,

        // (bool) Whether to enable client-side invalidation
        'invalidations' => true,
    ],

    // (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 (Redis 4+)
    //   `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,
]);

Jump to heading# 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...',
]);

Jump to heading# Client

The client option determines the Redis client used for connections. It defaults to phpredis. If you have Relay installed, please read these notes carefully.

define('WP_REDIS_CONFIG', [
    'client' => 'phpredis',
]);

Jump to heading# Cache

The cache configuration option allows a custom object cache implementation to be set. It must implement the RedisCachePro\ObjectCaches\ObjectCacheInterface interface.

Using a fully qualified class name requires you to load the class before using it:

require_once __DIR__ . '/wp-content/plugins/object-cache-pro/bootstrap.php';
require_once __DIR__ . '/path/to/MyObjectCache.php'

define('WP_REDIS_CONFIG', [
    'cache' => MyObjectCache::class,
]);

We strongly recommend extending the existing PhpRedisObjectCache class:

<?php
# MyObjectCache.php

class MyObjectCache extends RedisCachePro\ObjectCaches\PhpRedisObjectCache
{
    //
} 

Jump to heading# Connector

The connector configuration option allows a custom connector to be set. It must implement the RedisCachePro\Connectors\Connector interface.

Using a fully qualified class name requires you to load the class before using it:

require_once __DIR__ . '/wp-content/plugins/object-cache-pro/bootstrap.php';
require_once __DIR__ . '/path/to/MyConnector.php';

define('WP_REDIS_CONFIG', [
    'connector' => MyConnector::class,
]);

To use the built-in Twemproxy support, set the value to twemproxy.

Jump to heading# Logger

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

Jump to heading# 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
    ],
]);

Jump to heading# 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',
]);

Jump to heading# Port

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

define('WP_REDIS_CONFIG', [
    'port' => 6379,
]);

Jump to heading# Database

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

define('WP_REDIS_CONFIG', [
    'database' => 2,
]);

Jump to heading# Username

When use Redis 6.0 ACLs, use the username option to specify the connection's username.

define('WP_REDIS_CONFIG', [
    'username' => 'wordpress',
]);

Jump to heading# Password

The password configuration option will be used to authenticate.

define('WP_REDIS_CONFIG', [
    'password' => 'super-s3cret',
]);

Jump to heading# 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',
]);

Jump to heading# 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
]);

Jump to heading# Timeout

The connection timeout to Redis, expressed in seconds.

define('WP_REDIS_CONFIG', [
    'timeout' => 1.5, // 1.5 seconds
]);

Jump to heading# Read Timeout

The connection's read timeout, expressed in seconds.

define('WP_REDIS_CONFIG', [
    'read_timeout' => 1.5, // 1.5 seconds
]);

Jump to heading# Retry Interval

The connection's retry interval, expressed in milliseconds.

define('WP_REDIS_CONFIG', [
    'retry_interval' => 300, // 0.3 seconds
]);

Jump to heading# Retries

When using PhpRedis 5.3.5+, you may set the maximum retries upon connection issues.

define('WP_REDIS_CONFIG', [
    'retries' => 5,
]);

Jump to heading# Backoff Algorithm

When using the retries configuration the default backoff configuration is used which is composed of:

• Decorrelated jitter algorithm
• Base for backoff computation is 500ms
• Backoff time capped at 750ms

define('WP_REDIS_CONFIG', [
    'backoff' => 'default',
]);

Jump to heading# Persistent

Defines if a persistent connection should be used.

define('WP_REDIS_CONFIG', [
    'persistent' => true,
]);

Jump to heading# Shared

Whether the Redis server/cluster is shared or dedicated. This affects how memory and key counts are displayed.

define('WP_REDIS_CONFIG', [
    'shared' => true,
]);

Jump to heading# 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
]);

Jump to heading# 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',
    ],
]);

Jump to heading# 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',
]);

Jump to heading# Sentinels

To connect to Redis Sentinel, provide the Sentinel nodes using the sentinels configuration option, instead of using host:

define('WP_REDIS_CONFIG', [
    'sentinels' => [
        'tcp://172.17.0.1:6379',
        'tcp://172.17.0.1:6379',
        'tcp://172.17.0.1:6379',
    ],
]);

Jump to heading# Service

When using Redis Sentinel, use the service configuration option to provide the Sentinel service name:

define('WP_REDIS_CONFIG', [
    'service' => 'my-cache',
]);

Jump to heading# 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.

Jump to heading# 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',
]);

Jump to heading# 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 enabling and switching data serializer.

define('WP_REDIS_CONFIG', [
    'serializer' => 'igbinary', // store data in binary format
]);

Jump to heading# 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. The default is none (no data compression).

To avoid corrupt data and crashing your site, learn more about enabling and switching data compression.

define('WP_REDIS_CONFIG', [
    'compression' => 'zstd', // Zstandard (level 3)
]);

Jump to heading# 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', '...'],
]);

Jump to heading# 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' => [
        'jetpack',
        'wpseo-*', // wildcard are supported
    ],
]);

Jump to heading# Non-prefetchable Groups

The non-prefetchable groups that will not be prefetched.

define('WP_REDIS_CONFIG', [
    'non_prefetchable_groups' => [
        'wpseo',
        '...',
    ],
]);

Jump to heading# Analytics

The analytics configuration option allow you to configure:

• Whether to collect and display analytics
• Whether to restore analytics data after cache flushes
• The number of seconds to keep analytics before purging them
• Whether to print a HTML comment with non-sensitive metrics

define('WP_REDIS_CONFIG', [
    'analytics' => [
        'enabled' => true,
        'persist' => true,
        'retention' => 3600, // 1 hour
        'footnote' => true,
    ],
]);

Jump to heading# Relay

The Relay configuration option allow you to configure:

• Whether to register Relay event listeners
• Whether to enable client-side invalidation

define('WP_REDIS_CONFIG', [
    'relay' => [
        'listeners' => false, // default
        'invalidations' => true, // default
    ],
]);

Jump to heading# 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' => ['wpseo', '...'],
]);

Jump to heading# 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.

When using Relay the alloptions key is stored in individual keys to avoid unnecessary invalidations.

The alloptions hash does not obey the maxttl option.

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

Jump to heading# 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 using the all option.

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' => 'global', // only flush individual sites
]);

Jump to heading# 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.

Jump to heading# Debug

The debug configuration option is described in detail under Debugging.

Jump to heading# Save Commands

The save_commands configuration option allow for all cache commands to be logged (and displayed in Query Monitor) without enabling the debug or WP_DEBUG options.