Configuration Options

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', 'warning'],

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

    // (integer) The time-to-live for keys in the `*-queries` cache groups
    'queryttl' => 86400,

    // (float) Connection timeout in seconds
    'timeout' => 2.5,

    // (float) Read timeout in seconds
    'read_timeout' => 2.5,

    // (integer) Retry interval in milliseconds
    'retry_interval' => 25,

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

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

    // (bool) Whether the connection is persistent
    'persistent' => false,
    
    // (bool) Whether the Redis server is shared between multiple apps
    'shared' => false,

    // (bool) Whether flushing is asynchronous (Redis 4+)
    'async_flush' => false,

    // (string) The group flushing method
    //  `scan`, `keys`, `atomic`, `incremental`, `full`
    'group_flush' => 'scan',

    // (string) Multisite flushing strategy
    //   `all`, `site`, `global`
    'network_flush' => 'all',

    // (string) The pattern (multisite) flushing method
    //  `scan`, `keys`, `incremental`
    'pattern_flush' => 'scan',

    // (array|string) The cluster configuration name as string, or an array of cluster nodes
    'cluster' => null,

    // (string) Replica failover / distribution strategy
    //   `none`, `error`, `distribute`, `distribute_replicas`
    'cluster_failover' => 'error',

    // (string) Relay cluster distribution strategy (Requires Relay v0.22.0+)
    //   `none`, `random`, `random_replica`, `replicas`, `all`
    'cluster_distribution_strategy' => null,

    // (string) Relay cluster failover/retry strategy (Requires Relay v0.22.0+)
    //   `none`, `random_replica`, `primary`, `replicas`, `all`
    'cluster_failover_strategy' => null,

    // (string) Relay cluster availability zone (Requires Relay v0.22.0+)
    'cluster_az' => null,

    // (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_replicas`, `concentrate`
    'replication_strategy' => 'distribute',

    // (string|callable) The used tracer
    //   `none`, `newrelic`, `opentelemetry`
    'tracer' => 'none',

    // (string) The data serializer
    //   `php`, `igbinary`
    'serializer' => 'php',

    // (string) The data compression format
    //   `none`, `lzf`, `lz4` (fastest), `zstd` (smallest)
    '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,

        // (array) Keys matching these patterns will not be cached in Relay's in-memory cache
        'ignored' => ['*:analytics:*'],

        // (array) When set, only keys matching these patterns will be cached in Relay's in-memory cache, unless they match `relay.ignored`
        'allowed' => null,

        // Adaptive cache configuration to only cache keys that match a read-write ratio
        // See "Using Relay" for a detailed description
        'adaptive' => [
            'width' => 0, // (required) Number of horizontal cells (supported values: 512 - 2^31)
            'depth' => 0, // (required) Number of vertical cells (supported values: 1 - 8)
            'events' => 10, // Minimum number of calculated events (reads + writes)
            'ratio' => 5.0, // Minimum ratio of reads to writes
            'formula' => 'pure', // The formula used to calculate the read/write ratio
        ],
    ],

    // (bool) Whether to batch prefetch keys for requests
    'prefetch' => false,

    // (bool) Whether the `alloptions` key should be stored as a hash
    'split_alloptions' => false,

    // (array) The TLS context options, such as `verify_peer` and `ciphers`.
    'tls_options' => null,

    // (bool) Whether to enable strict mode
    'strict' => true,

    // (bool) Whether to enable plugin updates
    'updates' => false,

    // (string) The object cache class name
    'cache' => null,

    // (string) The connector class name
    'connector' => 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 after purchasing. It’s a 60 characters long string and will enable automatic plugin updates and unlock features.

define('WP_REDIS_CONFIG', [
    'token' => '02269ec4add8cac59...',
]);

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',
]);

Host

The host option defines the IP address, hostname, unix 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 the Redis database used to store all cache data. The default is 0.

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

Username

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

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

Password

The password configuration option will be used to authenticate.

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

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',
]);

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
]);

Retries

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

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

Backoff Algorithm

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

Decorrelated jitter algorithm
Base for backoff computation is retry_interval
Backoff time capped at read_timeout

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

Persistent

Defines if a persistent connection should be used.

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

MaxTTL

The maxttl option will enforce a “maximum time-to-live” for all new cache keys in seconds. Its 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
]);

QueryTTL

The queryttl option will enforce an expiration (in seconds) for keys in the *-queries cache groups. Its value must be an integer. Regardless of this configuration option, Object Cache Pro will attempt to purge stale query cache keys once per hour.

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', [
    'queryttl' => 60 * 60 * 4, // 4 hours
]);

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,
]);

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
]);

Group Flushing

The method used to flush individual cache groups. See the Flushing documentation for details.

define('WP_REDIS_CONFIG', [
    'group_flush' => 'scan', // `scan`, `keys`, `atomic`, `incremental`, `full`
]);

Cluster

To connect to a cluster, provide an array of primary 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 sent to primary nodes, but can be configured differently for read-only commands if requested.

define('WP_REDIS_CONFIG', [
    // Only send commands to primary nodes
    'cluster_failover' => 'none',

    // If a primary can't be reached, and it has replicas, failover for read commands
    'cluster_failover' => 'error',

    // Always distribute readonly commands between primaries and replicas, at random
    'cluster_failover' => 'distribute',

    // Always distribute readonly commands to the replicas, at random
    'cluster_failover' => 'distribute_replicas',
]);

When using Relay consider using cluster_distribution_strategy=replicas, cluster_failover_strategy=all and cluster_az instead.

Cluster Distribution Strategy

When using Relay v0.22.0+ with a cluster, the cluster_distribution_strategy option controls how readonly commands are distributed across primary and replica nodes.

define('WP_REDIS_CONFIG', [
    // Send readonly commands to the primary node only
    'cluster_distribution_strategy' => 'none',

    // Distribute randomly between the primary and its replicas, stop on first failed attempt
    'cluster_distribution_strategy' => 'random',

    // Distribute randomly among replicas only, stop on first failed attempt
    'cluster_distribution_strategy' => 'random_replica',

    // Distribute randomly among replicas only, iterate through all until working
    'cluster_distribution_strategy' => 'replicas',

    // Distribute between the primary and its replicas, iterate through all until working
    'cluster_distribution_strategy' => 'all',
]);

Cluster Failover Strategy

When using Relay v0.22.0+ with a cluster, the cluster_failover_strategy option controls how readonly commands are retried after a node failure.

define('WP_REDIS_CONFIG', [
    // Don't retry
    'cluster_failover_strategy' => 'none',

    // Retry the readonly command on a randomly selected replica
    'cluster_failover_strategy' => 'random_replica',

    // Retry the readonly command on the primary node (only if failed node is a replica)
    'cluster_failover_strategy' => 'primary',

    // Retry the readonly command on all replicas, excluding the failed node
    'cluster_failover_strategy' => 'replicas',

    // Retry the readonly command on all other nodes, excluding the failed node
    'cluster_failover_strategy' => 'all',
]);

Cluster Availability Zone

When using Relay v0.22.0+ with a cluster, the cluster_az option pins the client to a specific availability zone so readonly commands prefer nodes within the same zone.

define('WP_REDIS_CONFIG', [
    'cluster_az' => 'us-east-1a',
]);

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',
    ],
]);

Service

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

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

Servers

To use a replicated primary with read-only replicas, provide the primary using the servers configuration option to have the replicas automatically discovered:

define('WP_REDIS_CONFIG', [
    'token' => '...',
    'servers' => [
        'tcp://127.0.0.1:7000?role=primary',
    ],
]);

You may also specify the read replicas.

Replication Strategy

By default read requests are distributed across all replicas as well as the primary. To change this behavior use the replication_strategy configuration option.

define('WP_REDIS_CONFIG', [
    // Distribute readonly commands between primary 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',
]);

Tracer

The tracer configuration option determines which tracer the underlying client will use. Object Cache Pro will determine the best tracer to use based on the system it runs on. Supported values are:

'none'
'newrelic'
'open-telemetry'
OpenTelemetry\API\Trace\TracerProviderInterface
OpenTelemetry\API\Trace\NoopTracer
callable

The default value is none, unless the New Relic extension is installed and newrelic.enabled is set. Please note that the newrelic tracer will only trace Relay calls, because New Relic supports PhpRedis natively.

To use an Open Telemetry tracer, which is supported by Datadog, Blackfire, Scout APM and many others, ensure the open-telemetry/api Composer package will be autoloaded.

define('WP_REDIS_CONFIG', [
    // use the "global" trace provider
    'tracer' => 'opentelemetry',

    // or supply a custom `TracerProviderInterface`
    'tracer' => new MyTracerProvider,
]);

Alternatively any callable can be supplied that will be used as callback:

define('WP_REDIS_CONFIG', [
    'tracer' => function ($cb, $method) {
        // do your own tracing
        return $cb();
    },
]);

Serializer

All data stored 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
]);

Compression

The compression option determines the data compression algorithm used for all data stored in Redis.

Supported algorithms are lzf, lz4 and zstd. All algorithms 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)
]);

The zstd algorithm compresses data the smallest, lz4 compresses data the fastest and lzf should only be used when the others aren’t available.

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' => [
        'wc_session_id',
        '*-queries', // wildcard are supported
    ],
]);

Non-prefetchable Groups

Some plugins choose to store PHP classes inside the object cache which will lead to a notice like:

The cache key `hello` is incompatible with prefetching and the group `world` should be added to the list of non-prefetchable groups.

The best course of action is to report the notice to 3rd party plugin and get them to store arrays instead of classes in the cache. To prevent a group being prefetched, use the non_prefetchable_groups configuration option:

define('WP_REDIS_CONFIG', [
    'non_prefetchable_groups' => [
        'read_by_capability_groups_read_post',
        'has_cap_*', // wildcard are supported
    ],
]);

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
The sample rate for analytics in the range of 0 to 100 (if set to 20 only 20% of randomly picked requests are measured)
Whether to print a HTML comment with non-sensitive metrics

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

Relay

The Relay configuration option allow you to configure:

Whether to use Relay’s in-memory cache
Whether to register Relay event listeners
Whether to enable client-side invalidation
Which key patterns are and aren’t stored in Relay’s in-memory cache

These are the defaults:

define('WP_REDIS_CONFIG', [
    'relay' => [
        'cache' => true,
        'listeners' => false,
        'invalidations' => true,
        'allowed' => null,
        'ignored' => [
            '*:analytics:*',
        ],
    ],
]);

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', '...'],
]);

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
]);

Make sure to flush the cache after changing alloptions splitting to avoid stale cache data.

Network Flushing

The flushing strategy for multisite networks. See the Flushing documentation for details.

define('WP_REDIS_CONFIG', [
    'network_flush' => 'all', // `all`, `site`, `global`
]);

Pattern Flushing

The method used for pattern-based key deletion during network flushing. See the Flushing documentation for details.

define('WP_REDIS_CONFIG', [
    'pattern_flush' => 'scan', // `scan`, `keys`, `incremental`
]);

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.

Strict

Whether to enable strict mode and perform cache integrity protection flushes (enabled by default, if no prefix is set).

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

Updates

Whether to enable plugin updates and show updates and update notices within WordPress (enabled by default).

define('WP_REDIS_CONFIG', [
    'updates' => false,
]);

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
{
    //
}

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,
]);

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', 'warning'] 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
    ],
]);

Debug

The debug configuration option is described in detail under Debugging.

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.

Configuration Options

#Overview

#Token

#Client

#Host

#Port

#Database

#Username

#Password

#Prefix

#Timeout

#Read Timeout

#Retry Interval

#Retries

#Backoff Algorithm

#Persistent

#MaxTTL

#QueryTTL

#Shared

#Asynchronous Flushing

#Group Flushing

#Cluster

#Cluster Failover

#Cluster Distribution Strategy

#Cluster Failover Strategy

#Cluster Availability Zone

#Sentinels

#Service

#Servers

#Replication Strategy

#Tracer

#Serializer

#Compression

#Global Groups

#Non-persistent Groups

#Non-prefetchable Groups

#Analytics

#Relay

#Prefetching

#Splitting “alloptions”

#Network Flushing

#Pattern Flushing

#TLS Options

#Strict

#Updates

#Cache

#Connector

#Logger

#Log Levels

#Debug

#Save Commands