Pantheon Advanced Page Cache

For sites wanting fine-grained control over how their responses are represented in their edge cache, Pantheon Advanced Page Cache is the golden ticket. Here’s a high-level overview of how the plugin works:

1. When a response is generated, the plugin uses surrogate keys based on WordPress’ main WP_Query object to “tag” the response with identifers for the data used in the response. See the “Adding Custom Keys” section for including your own surrogate keys.
2. When WordPress data is modified, the plugin triggers a purge request for the data’s corresponding surrogate keys.

Because of its surrogate key technology, Pantheon Advanced Page Cache empowers WordPress sites with a significantly more accurate cache purge mechanism, and generally higher cache hit rate. It even works with the WordPress REST API.

Go forth and make awesome! And, once you’ve built something great, send us feature requests (or bug reports).

How It Works

Pantheon Advanced Page Cache makes heavy use of surrogate keys, which enable responses to be “tagged” with identifiers that can then later be used in purge requests. For instance, a home page response might include the Surrogate-Key header with these keys:

Surrogate-Key: front home post-43 user-4 post-41 post-9 post-7 post-1 user-1

Similarly, a GET requests to /wp-json/wp/v2/posts might include the Surrogate-Key header with these keys:

Surrogate-Key: rest-post-collection rest-post-43 rest-post-43 rest-post-9 rest-post-7 rest-post-1

Because cached responses include metadata describing the data therein, surrogate keys enable more flexible purging behavior like:

• When a post is updated, clear the cache for the post’s URL, the homepage, any index view the post appears on, and any REST API endpoints the post is present in.
• When an author changes their name, clear the cache for the author’s archive and any post they’ve authored.

There is a limit to the number of surrogate keys in a response, so we’ve optimized them based on a user’s expectation of a normal WordPress site. See the “Emitted Keys” section for full details on which keys are included, and the “Adding Custom Keys” section following for information on how to add your own.

Adding Custom Keys

By default, Pantheon Advanced Page Cache generates surrogate keys based on an interpretation of the main WP_Query query object. Because WordPress sends headers before the page is rendered, you need to use the pantheon_wp_main_query_surrogate_keys filter to include additional surrogate keys for any data present on the page.

For example, to include surrogate keys for a sidebar rendered on the homepage, you can filter the keys using the is_home() template tag:

Read the full description on the official page →