Set Up Redis Object Cache

An owned object-cache.php drop-in backing WordPress’s object cache with Redis. It complements the page cache: it speeds up the requests that cannot be cached, which on a store is most of the important ones.

Off by default. Configure it on the Object Cache tab.

Requirements

• The PhpRedis extension (the PHP Redis class). The Drop-in status panel shows PhpRedis extension: Available or Not installed.
• A reachable Redis server over TCP, TLS, or a Unix socket.

Install

1. Turn on Enable Redis object cache, enter the connection details (or define constants, below), and save.
2. Click Test Redis connection to run a bounded connect, authenticate, select-database, and ping check.
3. Click Test and install Redis (also on the Dashboard under Operations).

Installation runs the connection test first and refuses rather than installing a drop-in that cannot connect. It also refuses when the PhpRedis extension is missing or another plugin already owns object-cache.php. A broken object-cache drop-in degrades every request on the site, so this is deliberately not a one-click-and-hope operation.

The drop-in is published with an atomic rename, so a request never loads a half-written file. After a plugin update, an owned drop-in is republished automatically whenever the bundled copy changes.

Settings

Setting	Key	Default	Notes
Enable Redis object cache	redis.enabled	off	Turn off before moving to another object-cache owner
Redis host or socket	redis.host	127.0.0.1	Hostname, IP address, or Unix socket path (starts with /). A redis:// or tls:// prefix is stripped on save; use Use TLS instead
Redis port	redis.port	6379	0 with a Unix socket
Redis database number	redis.database	0	0 to 255
Redis username	redis.username	empty	Optional ACL username
Redis password	redis.password	empty	Encrypted at rest; a blank field on save keeps the saved password
Use TLS	redis.tls	off	Connects with tls://
Reuse Redis connections	redis.persistent	on	Persistent PhpRedis connections; may not suit hosts that tightly limit Redis clients
Cache key prefix	redis.prefix	empty (automatic)	Letters, digits, :, _, and - only
Connection timeout	redis.connection_timeout	0.5 s	0.1 to 10 seconds
Read timeout	redis.read_timeout	0.5 s	0.1 to 10 seconds

Key prefix and shared databases

Every key is <prefix>:<scope>:<group>:<md5 of key>, where the scope is global for WordPress’s global cache groups and blog-<id> otherwise. Left blank, the prefix is gtperf: plus a hash of the database name and WordPress path, so it is site-specific without any setup.

Use a unique prefix whenever several WordPress installs share one Redis database. Flushing the object cache (from WordPress or the admin bar’s Flush object cache) deletes only keys under this site’s prefix, found with SCAN, never the whole Redis database.

wp-config.php constants

GT Performance reads the same WP_REDIS_* constants as Till Krüss’s Redis Object Cache, so an existing configuration keeps working unchanged. Its own GTPERF_REDIS_* constants take highest precedence. The Compatible wp-config.php overrides panel on the Object Cache tab shows a copy-ready example.

Value	GT Performance constant	Compatible constant
Enabled	GTPERF_REDIS_ENABLED	WP_REDIS_DISABLED (true turns it off)
Host or socket	GTPERF_REDIS_HOST	WP_REDIS_HOST, or WP_REDIS_PATH for a socket
Port	GTPERF_REDIS_PORT	WP_REDIS_PORT
Database	GTPERF_REDIS_DATABASE	WP_REDIS_DATABASE
Username	GTPERF_REDIS_USERNAME	first element of an array WP_REDIS_PASSWORD
Password	GTPERF_REDIS_PASSWORD	WP_REDIS_PASSWORD (string, or array( 'username', 'password' ))
TLS	GTPERF_REDIS_TLS	WP_REDIS_SCHEME of tls, rediss, or ssl
Persistent connections	GTPERF_REDIS_PERSISTENT
Prefix	GTPERF_REDIS_PREFIX	WP_REDIS_PREFIX, else WP_CACHE_KEY_SALT
Connection timeout	GTPERF_REDIS_TIMEOUT	WP_REDIS_TIMEOUT
Read timeout	GTPERF_REDIS_READ_TIMEOUT	WP_REDIS_READ_TIMEOUT

Precedence, lowest to highest: saved settings, then compatible constants, then GTPERF_REDIS_* constants.

• WP_REDIS_PATH is used as a socket (port 0) when WP_REDIS_SCHEME is unix or WP_REDIS_HOST is not defined.
• Without WP_REDIS_PREFIX, a defined WP_CACHE_KEY_SALT replaces the saved prefix.
• Defining GTPERF_REDIS_HOST, WP_REDIS_HOST, or WP_REDIS_PATH turns Redis on, WP_REDIS_DISABLED set to true turns it off, and GTPERF_REDIS_ENABLED overrides both.

Constants alone are enough: the drop-in applies them even when no saved configuration exists. Full list: Constants Reference.

How the drop-in reads its configuration

object-cache.php has no plugin dependency by design: it has to define the global wp_cache_*() API before plugins load. Saved settings reach it through wp-content/cache/gt-performance/redis-config.json, which is authenticated encrypted JSON (AES-256-GCM, key derived from the site’s AUTH_KEY). The drop-in reads it with file_get_contents(), decrypts it, and applies constants on top. It is never included or executed.

That file holds a host, username, and password, so it is protected three ways: encryption, 0600 permissions, and an .htaccess rule denying .json files in the cache root. Writing it needs PHP OpenSSL and a real AUTH_KEY (at least 16 characters, not the sample placeholder). If it cannot be written, the settings save reports a configuration error and keeps the previous settings. See Architecture.

When Redis is unavailable

• Timeouts. Both default to 0.5 seconds, and that is deliberate. A Redis instance that has gone away should degrade WordPress to a non-persistent cache quickly, not hold every request open for several seconds. If 0.5 seconds is genuinely too tight on your network, raise it, but treat a needed increase as a signal about the network rather than a tuning win.
• Circuit breaker. After a failed connect, authentication, or database selection, the drop-in stops trying for 30 seconds, so a Redis outage costs one timeout rather than one per request.
• Fallback. While Redis is unreachable, the drop-in keeps working as a request-local cache. Every Redis call degrades instead of throwing.

Monitoring

• The Object Cache tab shows the drop-in as Installed by GT Performance, Not installed, or Owned by another plugin.
• The admin bar has Test Redis connection, Flush object cache, and Object cache settings.
• With Redis enabled, the health report includes an Object-cache drop-in check. wp gt-performance doctor lists the Redis drop-in status. See Diagnostics and Tools.

Redis settings are never exported, imported, or restored by settings history.

Another object-cache drop-in

GT Performance never overwrites an object-cache.php it did not install, and it never removes one. Remove or migrate the other plugin’s drop-in first. On xCloud, the xCloud status panel reports whether xCloud’s Redis or Object Cache Pro is on.

Removing it

• Turning off Enable Redis object cache leaves the drop-in in place but stops it connecting, so it works as a request-local cache only.
• WP_REDIS_DISABLED (or GTPERF_REDIS_ENABLED set to false) is the emergency off switch that needs no admin access.
• Deactivating the plugin removes the drop-in if GT Performance owns it.