From the PHP Redis extension to the last option on the Advanced tab. Install Novra Object Cache, connect it to Redis over TCP, TLS or a Unix socket, and find out what each of its 21 settings actually does.
● All 15 guides are on this page — jump in from the contents
NOVRA OBJECT CACHE DOCUMENTATION · VERSION 1.0.1
Redis, understood. Documented end to end.
GUIDE 01
Start here
A checked environment and a working Redis come before the drop-in.
1. Check the environment
Novra Object Cache 1.1.1 requires WordPress 6.0 or later and PHP 8.0 or later. The activation hook enforces both the PHP version and the presence of the PHP redis extension: if either is missing, the plugin deactivates itself again and stops with an error message. On the Redis side, version 5.0 or later is required and 6.0 or later is recommended.
2. Install and activate
Download the Novra Object Cache ZIP from your Account. In WordPress, open Plugins → Add New Plugin → Upload Plugin, select the ZIP, install and activate it. Activation only writes a default configuration into the novra_object_cache_settings option — it does not touch wp-config.php and it does not install the drop-in yet.
3. Configure the connection
Open Novra Object Cache → Settings. Hovering the menu entry reveals Dashboard, Settings and License. The Connection tab holds host, port, database, username and password. Save Settings in the page header submits every tab at once, and Test Connection next to it reports straight away whether Redis answered.
4. Enable the cache
Switch to Novra Object Cache → Dashboard and use Enable Cache. The plugin copies its includes/object-cache.php to wp-content/object-cache.php and flushes Redis immediately afterwards. Until that file exists, WordPress keeps using its non-persistent in-memory cache and nothing is stored in Redis.
5. Activate your license
Novra Object Cache → License takes your key. The license gates plugin updates and nothing else: caching keeps running when a license is missing, inactive or expired, and the drop-in itself contains no licensing code at all.
What the plugin checks before it will run — and what it only recommends.
Versions
PHP 8.0 or higher, WordPress 6.0 or higher, Redis 5.0 or higher with 6.0 or higher recommended. The PHP redis extension (PhpRedis) is required; igbinary is recommended but optional.
PhpRedis does the talking
All Redis traffic goes through PhpRedis, and the connection code checks its version at runtime: connection option arrays are used from PhpRedis 5.0 onwards, and TLS stream context options from PhpRedis 5.3.0 onwards.
igbinary is detected, not assumed
The Serializer option offers PHP and igbinary. When the igbinary extension is not loaded, the settings screen marks that option (n/a) so you can see before saving that the recommended value is not available on this server.
Compression support is detected too
The Compression option marks LZ4 or ZSTD as (n/a) when Redis::COMPRESSION_LZ4 or Redis::COMPRESSION_ZSTD is not defined in your PhpRedis build. LZF and None are always available.
Conflicting plugins block the drop-in
The plugin carries a list of conflicting object cache plugins. If one of them is active, an admin notice appears and Enable Cache refuses to install the drop-in until it is deactivated. A wp-content/object-cache.php written by some other plugin is refused as well — Novra Object Cache never overwrites a drop-in it did not write.
TCP, TLS or a Unix socket — the host value decides which one you get.
Plain TCP
A hostname or IP address in Host / Socket Path together with a port connects over TCP. For a Redis on the same machine that is usually 127.0.0.1 and port 6379.
Unix socket
A value that starts with a slash is treated as a socket path, and the port is ignored for socket connections. The plugin strips any scheme prefix from the path before it connects. A socket avoids the TCP stack entirely and is the lower-latency option when Redis runs beside WordPress.
TLS
The connection layer parses schemes in the host value: tcp:// and redis:// stay unencrypted, while tls://, rediss:// and ssl:// all switch the connection to TLS. When the host URL carries no port, TLS falls back to 6380 and plain connections to 6379. Setting tls to true inside WP_REDIS_CONFIG has the same effect as writing the scheme.
Certificate verification is off by default
If TLS is active and you supply no tls_options, the plugin uses built-in defaults with verify_peer and verify_peer_name disabled and allow_self_signed enabled. That gets a first connection working, but it is not what you want in production. Pass your own tls_options array (for example verify_peer together with a cafile) in WP_REDIS_CONFIG; it is handed to PhpRedis as stream context options and needs PhpRedis 5.3.0 or newer.
Authentication
Username and Password map to Redis 6 ACL credentials. For a classic requirepass setup, leave Username empty and fill in Password only. The legacy constant WP_REDIS_PASSWORD is still read and also accepts an array in the form username, password.
Test before you enable
Test Connection on the Settings screen runs a real connection attempt against the values currently in the form and prints the error text Redis returned when it fails. Use it before installing the drop-in, not after.
Five fields. Where Redis is, and who is allowed to talk to it.
Host / Socket Path
Hostname, IP address or Unix socket path. A value starting with a slash is a socket. The settings screen starts from /var/run/redis/redis.sock as its default; the placeholder shows both forms.
Port
TCP port of the Redis server. Default 6379. The field is ignored when Host holds a socket path.
Database
Redis database number, accepted range 0 to 15, default 0. Use different numbers to keep several WordPress installations apart on one Redis instance — although a distinct key prefix per site is the more robust separation.
Username
Optional. Redis 6 ACL user name. Empty by default, and empty is correct for a Redis that only uses requirepass.
Password
Optional, empty by default. It is the one field that is deliberately not run through sanitisation on save, so special characters survive. See the Password encryption guide for storing it as ciphertext instead of plain text.
How keys are named, how they are packed, and how long the plugin waits.
Key Prefix
Every key this site writes carries this prefix, which is what keeps two WordPress installations apart on one Redis database. The default is novra-object-cache:, and on activation the plugin generates novra-object-cache: followed by the first eight characters of an MD5 of the site URL. The field shows the prefix without its trailing colon and the colon is added back automatically on save; an empty field regenerates the site-specific default.
Compression
None, LZ4, ZSTD or LZF. LZ4 is the default and is marked as the recommended balance of speed and size. LZ4 and ZSTD are marked (n/a) when your PhpRedis build does not expose them.
Query TTL
Lifetime for the *-queries cache groups that WordPress 6.3 and later create — post-queries, user-queries and their relatives. The dropdown offers 1 hour, 6 hours, 12 hours, 24 hours and 7 days, and marks 24 hours as recommended. The value the plugin itself defaults to is 0, meaning no expiry; because 0 is not one of the listed options, an untouched form that you simply save will store 24 hours instead.
Connection Timeout
How long a connection attempt may take. Choices are 0.5s, 1s, 2s and 5s; 1s is the default and is marked recommended.
Read Timeout
How long the plugin waits for a reply once connected. Same four choices, same 1s default. Raise both timeouts only when Redis lives on another host and the network is genuinely slow — a high timeout turns a broken Redis into a slow website instead of a fast fallback.
Two switches, both on by default, both marked recommended.
Enable Prefetching
Preloads frequently accessed keys so a page request fetches them in one go instead of one round trip at a time. Enabled by default.
Split Alloptions
WordPress loads the whole alloptions blob on every request. This option stores large alloptions as separate keys instead of a single value, which keeps one oversized key from dominating every request. Enabled by default.
Nine options. Every recommended value is already selected when you arrive.
Max TTL
Upper bound on the lifetime of any cache key. No Limit, 1 day, 3 days, 7 days or 30 days. No Limit is the default and is marked recommended; a cap is a safety net against stale data, not a tuning knob.
Connection Retries
How often the plugin reconnects after a failed attempt. No Retries, 1, 3 or 5. The default is 3, marked recommended. Retries use exponential backoff with jitter rather than a fixed delay.
Async Flush (UNLINK)
Deletes keys with the non-blocking UNLINK command instead of DEL, so a large flush does not stall the Redis event loop. Requires Redis 4.0 or newer. Enabled by default and marked recommended.
Debug Mode
Logs cache operations to debug.log. Off by default, and it should stay off in production — a busy site produces a great deal of output.
Log Level
Warning (errors only), Info (standard) or Debug (verbose). Default Warning. It only has an effect while Debug Mode is enabled.
Serializer
PHP or igbinary. igbinary is marked recommended and is what the plugin defaults to where the extension is present; it produces smaller payloads and serialises faster. Changing the serializer changes the on-disk format of every stored value, so the plugin flushes the cache when this setting changes — otherwise old entries could no longer be unserialised.
Stampede Protection
Uses distributed locks so that when a hot key expires, one request regenerates it instead of all of them at once. Enabled by default and marked recommended.
Soft Pruning
Serves the stale value while a fresh one is generated in the background, rather than making the visitor wait. Enabled by default and marked recommended.
Enable Analytics
Records historical performance data so the dashboard can draw hit ratio, memory and throughput over time. Enabled by default and marked recommended. Switching it off removes the charts, not the caching.
No input fields here — it reports a state and offers one action.
It is a status panel, not a form
The Security tab contains zero settings. It reads the current encryption status and shows one of three states: no password configured, password stored in plain text, or password encrypted and secure. That is by design, not a broken control.
Encrypt Password Now
When a password is present but unencrypted, the tab offers a single button. It creates an encryption key if none exists, encrypts the password, and updates the stored configuration to use the ciphertext — all over AJAX, without you editing wp-config.php by hand.
What “secure” means here
The success state means the Redis password is stored in wp-config.php as AES-256-GCM ciphertext instead of plain text. The details of the key and the format are in the Password encryption guide below.
When a constant is defined, the constant wins. Always.
The resolution order
Both the Dashboard and the Settings screen read one and the same array, resolved in a fixed order: WP_REDIS_CONFIG first, then NOVRA_OBJECT_CACHE_CONFIG, then the legacy WP_REDIS_* constants, and only when none of those exist the novra_object_cache_settings option row in the database.
The constant overrides the option
If WP_REDIS_CONFIG is defined as an array, it is merged over the built-in defaults and the option row is never consulted. The Settings screen still saves your input, but the constant keeps winning — so a change that stubbornly has no effect almost always means the same key is set in wp-config.php.
Writing the configuration in code
Add define(’WP_REDIS_CONFIG’, [ … ]) before the “That’s all, stop editing!” line in wp-config.php. Recognised keys are host, port, database, username, password, prefix, timeout, read_timeout, compression, serializer, query_ttl, maxttl, retries, prefetch, split_alloptions, stampede_protection, soft_pruning, async_flush, debug, log_level, analytics, plus tls and tls_options for encrypted connections.
NOVRA_OBJECT_CACHE_CONFIG
Same array, alternative name. It is only read when WP_REDIS_CONFIG is not defined, which makes it useful when another Redis plugin already owns WP_REDIS_CONFIG on the same installation.
Legacy WP_REDIS_* constants
WP_REDIS_HOST, WP_REDIS_PORT, WP_REDIS_DATABASE, WP_REDIS_PASSWORD, WP_REDIS_PREFIX, WP_REDIS_TIMEOUT, WP_REDIS_READ_TIMEOUT, WP_REDIS_SERIALIZER and WP_REDIS_COMPRESSION are still read, but only when neither modern constant exists. WP_REDIS_PASSWORD accepts a plain string or an array of username and password for Redis 6 ACLs.
What saving does to the file
Saving settings writes the plugin’s own configuration block into wp-config.php. Up to version 1.1.0 that block was removed and re-inserted at the “stop editing” anchor on every save, which could shift neighbouring constants such as NOVRA_OBJECT_CACHE_ENCRYPTION_KEY or WP_CACHE to the wrong side of it. Since 1.1.1 the block is replaced exactly where it stands, and the file is only touched at all when the new content genuinely differs from what is already on disk.
One file in wp-content decides whether any of this is actually running.
What it is
WordPress loads wp-content/object-cache.php before plugins, and that file is the object cache. Without it, nothing the plugin offers is active — WordPress simply uses its non-persistent in-memory cache and forgets everything at the end of the request.
Installing and removing it
Enable Cache on the dashboard copies includes/object-cache.php from the plugin folder to wp-content/object-cache.php and flushes Redis immediately afterwards. Disable removes the file again. On the command line, wp novra-object-cache enable and wp novra-object-cache disable do the same thing, and enable takes a --force flag.
It never overwrites a foreign drop-in
Before installing, the plugin reads any existing drop-in and checks whether it is its own. If another object cache plugin’s file is in place, the install is refused with a message rather than silently replacing it. An active conflicting plugin blocks it as well.
Outdated drop-in
The status check parses the version out of the installed drop-in and compares it against the running plugin version. If the drop-in is older, the dashboard flags it — run Enable Cache once after a plugin update to refresh the file.
No licensing code inside
The drop-in contains no licensing logic whatsoever. An expired or missing license stops plugin updates; it never stops the cache.
Deactivation and uninstall
Deactivating the plugin removes the drop-in, provided the file identifies itself as the plugin’s own. Uninstalling additionally deletes the novra_object_cache_settings option.
How the drop-in finds the plugin
It looks for the plugin folder in this order: the NOVRA_OBJECT_CACHE_PLUGIN_PATH constant, then a fixed list of known paths, then a scan of wp-content/plugins for a folder name containing novra-object-cache. Set NOVRA_OBJECT_CACHE_PLUGIN_PATH if you keep the plugin somewhere unusual.
The Redis password as ciphertext in wp-config.php instead of plain text.
AES-256-GCM
Encryption uses AES-256-GCM with a 12-byte initialisation vector and a 16-byte authentication tag. Encrypted values are recognisable by their ENC: prefix, so the plugin can tell an encrypted password from a plain one without guessing.
Where the key belongs
NOVRA_OBJECT_CACHE_ENCRYPTION_KEY in wp-config.php has priority and is the recommended place. It must be a base64-encoded 32-byte key; anything else is rejected with a warning in the error log and the plugin falls back to the database key.
The database fallback
With no constant defined, the plugin generates a key with random_bytes and stores it in the novra_object_cache_encryption_key option with autoload disabled. That works, but it keeps the key and the ciphertext in the same database — which is why the constant is the recommended route.
Turning it on
Open Settings → Security. If a plain-text password is present, Encrypt Password Now creates the key when needed, encrypts the password and updates the stored configuration in one step.
Do not lose the key
The password can only be decrypted with the key it was encrypted with. If you replace NOVRA_OBJECT_CACHE_ENCRYPTION_KEY or move the site without carrying the key across, re-enter the Redis password and encrypt it again.
Everything the dashboard does, plus a few things it does not.
Drop-in
wp novra-object-cache enable installs the drop-in, and accepts --force to overwrite an existing one. wp novra-object-cache disable removes it again.
Status and connection
wp novra-object-cache status shows connection status and cache statistics. wp novra-object-cache test runs a connection test. wp novra-object-cache info prints the Redis INFO output and takes --section=<section> to narrow it down. wp novra-object-cache groups lists cache groups with their key counts.
Flushing
wp novra-object-cache flush empties the object cache. wp novra-object-cache flush-group flushes a single cache group instead of everything.
Watching it live
wp novra-object-cache watch refreshes cache statistics in place. --interval=<seconds> sets the refresh rate (default 2) and --count=<count> the number of iterations, where 0 means run until you stop it.
Diagnostics and health
wp novra-object-cache diagnostics exports a full report, with --format=text or --format=json. wp novra-object-cache health runs the shorter check for the usual hit-ratio killers: evicted keys, transients in the database, memory pressure and compression status.
Maintenance
wp novra-object-cache clean-transients removes expired transients that are still sitting in wp_options, and reports how many it found first. wp novra-object-cache prune-queries sets a lifetime on the *-queries cache keys WordPress 6.3 and later create and drops the stale ones.
A Redis shell with your settings
wp novra-object-cache cli launches redis-cli using the host, port, database and credentials WordPress is configured with, so you do not have to reassemble them by hand.
Relay
wp novra-object-cache relay reports the state of the Relay extension, and wp novra-object-cache relay-flush flushes its in-memory layer.
Ten checks WordPress runs for you, and where else the plugin reports in.
Where to look
Tools → Site Health → Status. The plugin registers ten tests there, so you can see the state of the cache without opening its own dashboard.
Connection and drop-in
Redis Object Cache Connection reports whether Redis answered, including the error text when it did not. Object Cache Drop-in distinguishes three cases: no drop-in installed, a drop-in from a different plugin, and the plugin’s own drop-in.
Configuration
Redis Configuration grades what you have: configuration missing, configuration can be improved, or configuration is optimized. Use it as a second opinion on the Cache and Advanced tabs.
Memory and eviction policy
Redis Memory Usage reports how much memory the instance uses, and Redis Eviction Policy points out a noeviction policy — with it, a full Redis starts returning errors instead of making room. Both checks report honestly when they had to be skipped.
Versions
Redis Version and PhpRedis Version check the server and the extension. A missing redis extension is reported as PhpRedis extension not installed.
Errors and state
Object Cache Errors reports errors the cache ran into during the request. Object Cache State reports the cache as disabled when WP_REDIS_DISABLED or NOVRA_OBJECT_CACHE_DISABLED is defined and true, or when the WP_REDIS_DISABLED environment variable is set to anything other than false — useful when a staging environment is quietly running without cache.
Database transients
Database Transients checks that transients end up in Redis rather than in wp_options. If they are in the table, wp novra-object-cache clean-transients clears out the expired ones.
Beyond Site Health
The plugin also adds a WordPress dashboard widget, registers the REST namespace novra-object-cache/v1, and hooks into Query Monitor and Debug Bar when either of those is active.
The license buys updates. It never switches the cache off.
Activate a site
Copy your key from your Account and enter it under Novra Object Cache → License. Keys carry the NOVRA_OC- prefix. Activation is only accepted when the store answers with a valid status and returns an activation hash — both conditions have to be met.
What the license gates
Plugin updates, and nothing else. Without a valid, activated license the updater returns before it even builds a request, so WordPress is simply offered no version information. Every cache feature keeps running, and the drop-in contains no licensing code at all.
Expiry
Expiry applies on the day, with no grace period: once the stored expiration date has passed, updates stop even before the next scheduled check runs.
A failed check never revokes anything
Only a real answer from the store — HTTP 200 with a JSON status field — is written to the stored license. A timeout, DNS or TLS failure, a 5xx or a non-JSON body surfaces as an error before anything is read or saved, and only leaves a breadcrumb the license page uses to explain the retry.
Revalidation
A cron hook re-checks the license twice a day. Deactivating the plugin clears that schedule; it is set up again when the plugin comes back with a saved key.
Find out which layer is actually failing before you change more settings.
Nothing is being cached
Check that wp-content/object-cache.php exists — Site Health’s Object Cache Drop-in test answers this in one line. If it is missing, Enable Cache may have been refused by a conflicting object cache plugin or by a foreign drop-in. Also check whether WP_REDIS_DISABLED or NOVRA_OBJECT_CACHE_DISABLED is switched on somewhere in this environment.
The connection fails
Test Connection prints the error Redis returned; read it before changing anything. For a socket path, make sure the web server user may open that socket. For a TCP host, check port, firewall and whether Redis binds to anything beyond localhost. If Redis 6 ACLs are in use, both Username and Password have to match.
A setting I changed has no effect
Look in wp-config.php. When WP_REDIS_CONFIG or NOVRA_OBJECT_CACHE_CONFIG is defined, its values override the saved option for every key it contains, so the Settings screen saves your change and the constant keeps overriding it.
Unserialization errors
These come from data written with a different serializer. The plugin flushes the cache by itself when you change the Serializer setting; if the entries were written by another object cache plugin’s drop-in, flush once by hand with wp novra-object-cache flush.
The hit ratio is low
Run wp novra-object-cache health. It checks exactly the things that usually cause it: evicted keys from memory pressure, transients still sitting in the database, overall memory usage and whether compression is active.
Redis is running out of memory
Check the Redis Memory Usage and Redis Eviction Policy tests. Under a noeviction policy a full Redis answers writes with errors instead of making room. Either raise maxmemory or choose an eviction policy that suits a cache.
WordPress reports no update, but there is one
The updater caches the version information it fetched from the store in a transient for three hours. That cached answer is read before any request is built, so a release published minutes ago keeps being reported as “no update available” — and pressing Check again on the Updates screen does not help, because it only refreshes WordPress’s own update_plugins transient. The plugin’s cache is a separate transient whose name starts with fsl_, followed by a hash of the plugin file and the product ID, and ends in _version_info. Delete that transient and the new version appears immediately.
Putting together a useful support report
wp novra-object-cache diagnostics --format=json writes a complete report you can attach. Add the plugin, WordPress, PHP, Redis and PhpRedis versions, what you changed last, and the exact text of any error message.
