Enable Object Cache Pro for WordPress
How to install and configure Object Cache Pro for WordPress.
Before You Begin
Before you can install and activate Object Cache Pro, verify that you have:
A working site on Pantheon
- A Performance or Elite site plan is required
- Redis is enabled for the site
- The site is running PHP 7.4 or higher
Terminus installed and authenticated with a machine token to your local machine.
Activate Redis
You can activate Redis either from the Pantheon dashboard or with Terminus.
On the Dashboard
Navigate to your Pantheon Site Dashboard, select Settings, and then select Add Ons.
Click the Add button under Redis. It might take a couple of minutes for the Object Cache server to come online. You will see a success message in a green box stating that Redis has been enabled.
With Terminus
Run the command below to enable Redis via the command line with Terminus:
terminus redis:enable <site>Installation and Configuration
Ensure that your site is on a paid Performance or Elite plan. This can be verified by navigating to your Pantheon Site Dashboard, selecting Settings, selecting About Site, and then looking at the Service Level.
Ensure that your site has Redis enabled via the steps above.
Add the Terminus Addon Installer Plugin to your machine.
Information:NoteYour local version of Terminus must be 3.2 or higher.terminus self:plugin:install terminus-addons-installer-pluginRun the installation workflow to install Object Cache Pro on your development or multidev environment. NOTE: This workflow cannot be run on test or live environments.
terminus install:run <site>.<environment> ocpWait for the workflow to run. The terminus command will only trigger the workflow, but the progress is visible in the Pantheon Site Dashboard in the Workflows dropdown. This will take some time to complete
Information:NoteIf the workflow text in the dashboard turns red, it did not succeed. Please create a ticket with support to debug this further.
Once complete, activate the Object Cache Pro plugin from the WordPress Admin or via WP-CLI through Terminus on your development or multidev environment. NOTE: This workflow cannot be run on test or live environments.
WordPress Admin:
- Navigate to the Plugins page, activate Object Cache Pro, then go to the Object Cache page in the Settings menu. Note: WordPress Multisite users will need to go to the Network Admin Plugins page and network activate Object Cache Pro from there. In order to access the Network Admin, you must be logged in as a Super Admin.
Terminus:
Open your terminal.
Run the following command:
terminus wp -- <site>.<env> plugin activate object-cache-proRun the
git pullcommand if you did not create the file locally.
Note: WordPress Multisite users will need to append the
--networkflag to network activate the plugin.Navigate to
/wp-admin/options-general.php?page=objectcacheto see the current status of Object Cache Pro on your site as well as live graphs of requests, memory usage, and more.Information:NoteSubsites do not get their own configuration or graphs if you are using WordPress Multisites. Navigate to
/wp-admin/network/settings.php?page=objectcacheto view network-wide configuration and graphs. This is the only screen throughout the network that displays this information.
Refer to the official Object Cache Pro documentation for full configuration instructions.
Ensure that your site has Redis enabled via the steps above.
Ensure that your site is using Redis version 6.2 or higher.
Open your
pantheon.ymlfile and modify theobject_cacheentry or add anobject_cacheentry if there is not one already such that yourpantheon.ymlfile includes:api_version: 1 object_cache: version: 6.2Commit and push this file to your site.
Obtain the license token and apply it directly to the Composer
auth.jsonto be able to authenticate against Object Cache Pro's Composer repository.composer config --auth http-basic.objectcache.pro token $(terminus remote:wp <site>.<env> -- eval "echo getenv('OCP_LICENSE');")This will pull the Object Cache Pro license token directly into the
auth.jsonfile. You can open theauth.jsonfile locally to ensure that it has a structure that looks like this:{ "http-basic": { "objectcache.pro": { "username": "token", "password": "<LICENSE-TOKEN>" } } }Information:NoteThe
auth.jsonfile is only necessary for authenticating against the Object Cache Pro Composer repository. For this reason, we recommend adding it to your.gitignoreso you are not committing secrets to your Git repository. However, excluding it from version control means that anyone else who may want to update Object Cache Pro locally will need to repeat the steps above to generate their ownauth.jsonfile.Open your
composer.jsonfile and locate therepositoriessection. If it doesn't exist, add it in the "repositories" section as shown below:repositories: [ { "type": "composer", "url": "https://objectcache.pro/repo/" } ],Install Object Cache Pro via Composer using one of the methods listed below.
Locally with Composer:
Run the command below:
composer require rhubarbgroup/object-cache-pro --ignore-platform-reqs- The
--ignore-platform-reqsflag is being passed because Object Cache Pro expects that Redis is running on the machine that the plugin is being installed on. This is likely an untrue assumption on your local machine (but it might be true inside the container or virtual machine you are using for local development, more on that later). The ignore flag allows you to install the plugin while bypassing the platform (local machine) requirements.
Locally with Lando:
Run the command below inside your development environment where Redis does exist. The Lando machine already has the Redis PHP extension installed. This allows you to run the command without flags. For example, if you're using Lando:
lando composer require rhubarbgroup/object-cache-proInformation:NoteUsing Composer commands locally while requiring Object Cache Pro via Composer necessitates adding the
--ignore-platform-reqsflag to all localcomposer require,composer update, andcomposer installcommands.- The
Commit the changes to your repository:
git add composer.* && git commit -m "Require Object Cache Pro"Add the license token your
config/application.phpfile. Normally, the license key is provided by the platform. However, when you are working locally, Lando (or your local development environment) does not have access to the platform environment variable. However, you can extract it from theauth.jsoncreated in the previous steps.Open your
config/application.phpfile to add configuration values to Object Cache Pro for your site.Locate the
Config::apply()line at the bottom of the file and add the following code above that line.$token = getenv( 'OCP_LICENSE' ); // Get the license from the Pantheon environment variables. // If working locally, set $token based on the local auth.json file. if ( isset( $_ENV['LANDO'] ) && 'ON' === $_ENV['LANDO'] ) { // Change this if you are not using Lando. $auth_json = ABSPATH . '/auth.json'; if ( file_exists( $auth_json ) ) { $auth_json = json_decode( file_get_contents( $auth_json ) ); $token = $auth_json['http-basic']['objectcache.pro']['password']; } }Set the Object Cache Pro settings using the license key either from the Pantheon environment or your local
auth.json. You can put this directly under theWP_DEBUGrules so it looks like this:/** * Debugging Settings */ Config::define('WP_DEBUG_DISPLAY', false); Config::define('WP_DEBUG_LOG', false); Config::define('SCRIPT_DEBUG', false); ini_set('display_errors', '0'); /** * Object Cache Pro config */ Config::define( 'WP_REDIS_CONFIG', [ 'token' => $token, ] );Add Object Cache Pro configuration options after
Config::define( 'WP_REDIS_CONFIG', [inconfig/application.phpfor WordPress (Composer Managed) sites. The full, recommended contents of the WP_REDIS_CONFIG constant are:'token' => $token, 'host' => getenv('CACHE_HOST') ?: '127.0.0.1', 'port' => getenv('CACHE_PORT') ?: 6379, 'database' => getenv('CACHE_DB') ?: 0, 'password' => getenv('CACHE_PASSWORD') ?: null, 'maxttl' => 86400 * 7, 'timeout' => 0.5, 'read_timeout' => 0.5, 'split_alloptions' => true, 'prefetch' => true, 'debug' => false, 'save_commands' => false, 'analytics' => [ 'enabled' => true, 'persist' => true, 'retention' => 3600, // 1 hour 'footnote' => true, ], 'prefix' => "ocppantheon", // This prefix can be changed. Setting a prefix helps avoid conflict when switching from other plugins like wp-redis. 'serializer' => 'igbinary', 'compression' => 'zstd', 'async_flush' => true, 'strict' => true,Refer to the Object Cache Pro documentation for detailed explanations of all the configuration settings.
Make sure you add and
git pushyour changes up to your repository before you activate the plugin.Activate the plugin and enable Redis in the plugin. You can activate the Object Cache Pro plugin from the WordPress Admin, locally with WP-CLI, or via Terminus.
WordPress Admin:
Navigate to the Plugins page, activate Object Cache Pro, then go to the Object Cache page in the Settings menu.
Ensure that you are in an environment with file write permissions (either SFTP mode, if activating on your Pantheon Dev environment or in a local development environment).
Click the Enable button. This will create the
object-cache.phpdrop-in file.Commit the change.
- Make the commit in SFTP mode if you did this in your Pantheon Dev environment.
- Commit the file to your repository if you did this locally.
WP-CLI:
Refer to the WP-CLI guide for instructions.
Terminus:
Open your terminal.
Run the following commands:
terminus connection:set sftp terminus wp -- <site>.<env> plugin activate object-cache-pro terminus wp -- <site>.<env> redis enable terminus env:commit <site>.<env> --message="Add Object Cache Pro drop-in" terminus connection:set gitRun the
git pullcommand if you did not create the file locally.
Navigate to
/wp-admin/options-general.php?page=objectcacheto see the current status of Object Cache Pro on your site as well as live graphs of requests, memory usage, and more.- If you are using WordPress Multisite, subsites do not get their own configuration or graphs. Navigate to
/wp-admin/network/settings.php?page=objectcacheto view network-wide configuration and graphs. This is the only screen throughout the network that displays this information.
- If you are using WordPress Multisite, subsites do not get their own configuration or graphs. Navigate to
See the "Database Cleanup" section above for steps on how to truncate the existing cache tables to make sure the latest data populates object cache properly.
Database Cleanup (Required)
By default, when Redis is not available on a WordPress site, WordPress stores transient data in the database. Transients are bits of data that are intended to be stored temporarily and then cleared automatically. When object caching like Redis is available, WordPress automatically stores transients into the object cache. However, after enabling Redis, any transients that previously existed in the database will not necessarily be cleared automatically, even when the cache is cleared. For sites that were live for awhile before Redis was enabled, there could be significant amounts of data in these tables. Removing this data could increase the speed of cloning, exporting, and backing up the database.
Use the following script to cleanup cache tables in the database:
#!/bin/bash
echo 'Provide the site name (e.g. your-awesome-site), then press [ENTER]:';
read SITE;
echo 'Provide the environment name (multidev, dev, test, or live), then press [ENTER]:';
read ENV;
# Delete all transient options - these are now stored in Redis
terminus wp $SITE.$ENV -- db query "DELETE FROM wp_options WHERE option_name LIKE ('%\_transient\_%');"Local configuration with Lando
Lando's Pantheon recipe includes Redis in its Docker configuration. However, to get Object Cache Pro to work correctly with Lando locally, you'll need to make a few changes to your Object Cache Pro and Lando configuration.
First, in your
.lando.ymlfile add the following:services: cache: type: redis:6.0- This ensures that the Redis version in your Lando environment matches the 6.x environment on Pantheon. Object Cache Pro will still work with the default version of Redis that is included in the Pantheon Lando recipe, so this step is optional.
Next, in your
wp-config.php(orconfig/application.phpfor Bedrock-based WordPress Composer sites), find theWP_REDIS_CONFIGsettings. Lando does not supportigbinaryserialization orzstdcompression, so you will need to modify these settings for Lando locally. The simplest solution is to store the configuration values to a variable and then modify the variable for Lando environments. For example:$ocp_settings = [ 'token' => $token, // The dynamically fetched token from above. 'host' => getenv('CACHE_HOST') ?: '127.0.0.1', 'port' => getenv('CACHE_PORT') ?: 6379, 'database' => getenv('CACHE_DB') ?: 0, 'password' => getenv('CACHE_PASSWORD') ?: null, // ...the rest of your settings... 'serializer' => 'igbinary', 'compression' => 'zstd', // ... ]; if ( isset( $_ENV['LANDO'] ) && 'ON' === $_ENV['LANDO'] ) { $ocp_settings['serializer'] = 'php'; $ocp_settings['compression'] = 'none'; } define( 'WP_REDIS_CONFIG', $ocp_settings );Information:NoteIf you don't want to bother with changing the configuration for local environments, you can simply disable Object Cache Pro for Lando and leave the existing configuration:if ( isset( $_ENV['LANDO'] ) && 'ON' === $_ENV['LANDO'] ) { define( 'WP_REDIS_DISABLED', true ); }
Make sure to commit your code back to your environment when you have made the appropriate changes.
Additional Considerations
When moving from Dev to Test, and from Test to live with OCP for the first time, note that you must activate the plugin and then flush the cache via
terminus wp <site>.<env> -- cache flush.- If you already have WP-Redis or other Redis plugins installed, these should be disabled before merging code.
- To summarize, the full order of steps are:
- Disable wp-redis or other redis plugins if present
- Merge code
- Activate OCP
- Flush Redis cache
- To summarize, the full order of steps are:
- If you already have WP-Redis or other Redis plugins installed, these should be disabled before merging code.
The
object-cache.phpdrop-in file must be created in your development or multidev environment and committed or pushed to live to work.When installed as a
mu-pluginon a WordPress Multisite, Object Cache Pro handles each subsite separately. The dashboard widget applies to the current site and none of the other sites on the network.- Flushing the network cache from the network admin will flush all caches across the network.
- Subsites do not get their own configuration or graphs.
- If installed on a WordPress Multisite, the Flush cache button in the subsite dashboard widget flushes the cache of the entire network, not just the subsite cache. The default behavior can be modified by adjusting the
WP_REDIS_CONFIGsettings. Alternatively, you can flush a single site's cache by using the WP-CLI command. - You must manually click the Enable Cache button in the Network Admin Object Cache Pro settings page while in SFTP mode to enable Object Cache Pro. Alternatively, you can use the Terminus commands above and commit the
object-cache.phpdrop-in to your repository.
When working locally with Lando, it's possible that Lando's self-signed SSL certificate will cause issues connecting to the Object Cache Pro license API resulting in a license error. To resolve this, add the following code to a mu-plugin:
if ( isset( $_ENV['LANDO'] ) && 'ON' === $_ENV['LANDO'] ) { add_filter( 'http_request_args', function ( $args ) { $args['sslverify'] = false; return $args; } ); }You may wish to make this file local-only by adding it to your
.gitignorefile. This error will not cause any issues with the functioning of Object Cache Pro or the behavior of the plugin on Pantheon but it might prevent you from being able to make updates to the plugin locally.