markhughes / redis-cache

A persistent object cache backend for WordPress powered by Redis. Supports Predis, PhpRedis, HHVM, replication and clustering.

Redis Object Cache for WordPress

A persistent object cache backend powered by Redis. Supports Predis, PhpRedis (PECL), HHVM, replication, clustering and WP-CLI.

Forked from Eric Mann's and Erick Hitter's Redis Object Cache.

Installation

For detailed installation instructions, please read the standard installation procedure for WordPress plugins.

1. Make sure Redis is installed and running.
2. Install and activate plugin.
3. Enable the object cache under Settings -> Redis, or in Multisite setups under Network Admin -> Settings -> Redis.
4. If necessary, adjust connection parameters.

If your server doesn't support the WordPress Filesystem API, you have to manually copy the object-cache.php file from the /plugins/redis-cache/includes/ directory to the /wp-content/ directory.

Connection Parameters

By default the object cache drop-in will connect to Redis over TCP at 127.0.0.1:6379 and select database 0.

To adjust the connection parameters, define any of the following constants in your wp-config.php file.

• WP_REDIS_CLIENT (default: not set)

  Specifies the client used to communicate with Redis. Supports hhvm, pecl and predis.

• WP_REDIS_SCHEME (default: tcp)

  Specifies the protocol used to communicate with an instance of Redis. Internally the client uses the connection class associated to the specified connection scheme. Supports tcp (TCP/IP), unix (UNIX domain sockets), tls (transport layer security) or http (HTTP protocol through Webdis).

• WP_REDIS_HOST (default: 127.0.0.1)

  IP or hostname of the target server. This is ignored when connecting to Redis using UNIX domain sockets.

• WP_REDIS_PORT (default: 6379)

  TCP/IP port of the target server. This is ignored when connecting to Redis using UNIX domain sockets.

• WP_REDIS_PATH (default: not set)

  Path of the UNIX domain socket file used when connecting to Redis using UNIX domain sockets.

• WP_REDIS_DATABASE (default: 0)

  Accepts a numeric value that is used to automatically select a logical database with the SELECT command.

• WP_REDIS_PASSWORD (default: not set)

  Accepts a value used to authenticate with a Redis server protected by password with the AUTH command.

• WP_REDIS_TIMEOUT (default: 5)

  Amount of time in seconds (fractions of a second allowed) to attempt initial connection to Redis server before failing.

• WP_REDIS_READ_TIMEOUT (default: 5)

  Amount of time in seconds (fractions of a second allowed) to attempt a read from the Redis server before failing.

• WP_REDIS_RETRY_INTERVAL (default: not set)

  Amount of time in miliseconds to retry a failed connection attempt.

Configuration Parameters

To adjust the configuration, define any of the following constants in your wp-config.php file.

• WP_CACHE_KEY_SALT (default: not set)

  Set the prefix for all cache keys. Useful in setups where multiple installs share a common wp-config.php or $table_prefix to guarantee uniqueness of cache keys.

• WP_REDIS_SELECTIVE_FLUSH (default: not set)

  If set to true, flushing the cache will only delete keys that are prefixed with WP_CACHE_KEY_SALT (instead of emptying the entire Redis database). The selective flush is an atomic O(n) operation.

• WP_REDIS_MAXTTL (default: not set)

  Set maximum time-to-live (in seconds) for cache keys with an expiration time of 0.

• WP_REDIS_GLOBAL_GROUPS (default: ['blog-details', 'blog-id-cache', 'blog-lookup', 'global-posts', 'networks', 'rss', 'sites', 'site-details', 'site-lookup', 'site-options', 'site-transient', 'users', 'useremail', 'userlogins', 'usermeta', 'user_meta', 'userslugs'])

  Set the list of network-wide cache groups that should not be prefixed with the blog-id (Multisite only).

• WP_REDIS_IGNORED_GROUPS (default: ['counts', 'plugins'])

  Set the cache groups that should not be cached in Redis.

• WP_REDIS_UNFLUSHABLE_GROUPS (default: not set)

  Set groups not being flushed during a selective cache flush.

• WP_REDIS_DISABLED (default: not set)

  Set to true to disable the object cache at runtime.

• WP_REDIS_GRACEFUL (default: not set)

  Set to false to disable graceful failures and throw exceptions.

• WP_REDIS_SERIALIZER (default: not set)

  Use PhpRedis’ built-in serializers. Supported values are Redis::SERIALIZER_PHP and Redis::SERIALIZER_IGBINARY.

• WP_REDIS_IGBINARY (default: not set)

  Set to true to enable the igbinary serializer. Ignored when WP_REDIS_SERIALIZER is set.

Replication & Clustering

To use Replication, Sharding or Clustering, make sure your server is running PHP7 or higher (HHVM is not supported) and you consulted the Predis or PhpRedis documentation.

For replication use the WP_REDIS_SERVERS constant, for sharding the WP_REDIS_SHARDS constant and for clustering the WP_REDIS_CLUSTER constant.

For authentication use the WP_REDIS_PASSWORD constant.

Replication (Master-Slave)

define( 'WP_REDIS_SERVERS', [
    'tcp://127.0.0.1:6379?database=5&alias=master',
    'tcp://127.0.0.2:6379?database=5&alias=slave-01',
] );

Replication (Redis Sentinel)

define( 'WP_REDIS_CLIENT', 'predis' );
define( 'WP_REDIS_SENTINEL', 'mymaster' );
define( 'WP_REDIS_SERVERS', [
    'tcp://127.0.0.1:5380',
    'tcp://127.0.0.2:5381',
    'tcp://127.0.0.3:5382',
] );

Sharding

define( 'WP_REDIS_SHARDS', [
    'tcp://127.0.0.1:6379?database=10&alias=shard-01',
    'tcp://127.0.0.2:6379?database=10&alias=shard-02',
    'tcp://127.0.0.3:6379?database=10&alias=shard-03',
] );

Clustering (Redis 3.0+)

define( 'WP_REDIS_CLUSTER', [
    'tcp://127.0.0.1:6379?alias=node-01',
    'tcp://127.0.0.2:6379?alias=node-02',
    'tcp://127.0.0.3:6379?alias=node-03',
] );

WP-CLI Commands

To use the WP-CLI commands, make sure the plugin is activated:

wp plugin activate redis-cache

The following commands are supported:

• wp redis status

  Show the Redis object cache status and (when possible) client.

• wp redis enable

  Enables the Redis object cache. Default behavior is to create the object cache drop-in, unless an unknown object cache drop-in is present.

• wp redis disable

  Disables the Redis object cache. Default behavior is to delete the object cache drop-in, unless an unknown object cache drop-in is present.

• wp redis update-dropin

  Updates the Redis object cache drop-in. Default behavior is to overwrite any existing object cache drop-in.