Daniel Bachhuber

Chris Reynolds

Pantheon Systems

John Spellman

pwtyler

ryanshoover

rwagner00

kporras07

<p><a href="https://circleci.com/gh/pantheon-systems/pantheon-advanced-page-cache" rel="nofollow ugc"></a></p>
<p>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:</p>
<ol>
<li>When a response is generated, the plugin uses surrogate keys based on WordPress’ main <code>WP_Query</code> 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.</li>
<li>When WordPress data is modified, the plugin triggers a purge request for the data’s corresponding surrogate keys.</li>
</ol>
<p>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.</p>
<p>Go forth and make awesome! And, once you’ve built something great, <a href="https://github.com/pantheon-systems/pantheon-advanced-page-cache/issues" rel="nofollow ugc">send us feature requests (or bug reports)</a>.</p>
<h3>How It Works</h3>
<p>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 <code>Surrogate-Key</code> header with these keys:</p>
<pre><code>Surrogate-Key: front home post-43 user-4 post-41 post-9 post-7 post-1 user-1
</code></pre>
<p>Similarly, a <code>GET</code> requests to <code>/wp-json/wp/v2/posts</code> might include the <code>Surrogate-Key</code> header with these keys:</p>
<pre><code>Surrogate-Key: rest-post-collection rest-post-43 rest-post-43 rest-post-9 rest-post-7 rest-post-1
</code></pre>
<p>Because cached responses include metadata describing the data therein, surrogate keys enable more flexible purging behavior like:</p>
<ul>
<li>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.</li>
<li>When an author changes their name, clear the cache for the author’s archive and any post they’ve authored.</li>
</ul>
<p>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.</p>
<h4>Adding Custom Keys</h4>
<p>By default, Pantheon Advanced Page Cache generates surrogate keys based on an interpretation of the main <code>WP_Query</code> query object. Because WordPress sends headers before the page is rendered, you need to use the <code>pantheon_wp_main_query_surrogate_keys</code> filter to include additional surrogate keys for any data present on the page.</p>
<p>For example, to include surrogate keys for a sidebar rendered on the homepage, you can filter the keys using the <code>is_home()</code> template tag:</p>
<pre><code>/**
 * Add surrogate key for the featured content sidebar rendered on the homepage.
 */
add_filter( 'pantheon_wp_main_query_surrogate_keys', function( $keys ){
    if ( is_home() ) {
        $keys[] = 'sidebar-home-featured';
    }
    return $keys;
});
</code></pre>
<p>Then, when sidebars are updated, you can use the <code>pantheon_wp_clear_edge_keys()</code> helper function to emit a purge event specific to the surrogate key:</p>
<pre><code>/**
 * Trigger a purge event for the featured content sidebar when widgets are updated.
 */
add_action( 'update_option_sidebars_widgets', function() {
    pantheon_wp_clear_edge_keys( array( 'sidebar-home-featured' ) );
});
</code></pre>
<p>Similarly, to include surrogate keys for posts queried on the homepage, you can pre-fetch the posts before the page is rendered:</p>
<pre><code>/**
 * An example of pre-fetching a WP_Query to tag the
 * response with queried data. You'd use `papcx_wp_query()`
 * a second time within your template to use the data.
 */
add_filter( 'pantheon_wp_main_query_surrogate_keys', function( $keys ) {
    if ( is_home() ) {
        $query = papcx_wp_query( array(
            'post_type' => 'page',
        ) );
        foreach( $query->posts as $post ) {
            $keys[] = 'post-' . $post->ID;
        }
    }
    return $keys;
});

/**
 * Register a 'papc-non-persistent' cache group to cache data
 * in a non-persistent manner. We only want data in this group
 * to be cached within the page request.
 */
add_action( 'init', function(){
    wp_cache_add_non_persistent_groups( array( 'papc-non-persistent' ) );
});

/**
 * Helper function to instantiate a WP_Query object only
 * once per page request.
 *
 * @param array $args Arguments to pass to WP_Query.
 * @return WP_Query
 */
function papcx_wp_query( $args = array() ) {
    $cache_key = md5( serialize( $args ) );
    // WP_Query object will be in cache the second time we use the function.
    $cache_value = wp_cache_get( $cache_key, 'papc-non-persistent' );
    if ( false !== $cache_value ) {
        return $cache_value;
    }
    $query = new WP_Query( $args );
    wp_cache_set( $cache_key, $query, 'papc-non-persistent' );
    return $query;
}
</code></pre>
<p>Because Pantheon Advanced Page Cache already handles WordPress post purge events, there’s no additional call to <code>pantheon_wp_clear_edge_keys()</code>.</p>
<p>Lastly, the <code>pantheon_wp_rest_api_surrogate_keys</code> filter lets you filter surrogate keys present in a REST API response.</p>
<h4>Additional purging by path</h4>
<p>When a post is published for the first time, the permalink’s path is also purged even if it has no matching keys. This can be further filtered with the <code>pantheon_clear_post_path</code> filter.</p>
<pre><code>    add_action('pantheon_clear_post_path', function($paths) {
        // Add or remove paths from $paths
        return $paths
    }, 10, 3);
</code></pre>
<p>Need a bit more power? In addition to <code>pantheon_wp_clear_edge_keys()</code>, there are two additional helper functions you can use:</p>
<ul>
<li><code>pantheon_wp_clear_edge_paths( $paths = array() )</code> – Purge cache for one or more paths.</li>
<li><code>pantheon_wp_clear_edge_all()</code> – Warning! With great power comes great responsibility. Purge the entire cache, but do so wisely.</li>
</ul>
<h4>Ignoring Specific Post Types</h4>
<p>By default, Pantheon Advanced Page Cache is pretty aggressive in how it clears its surrogate keys. Specifically, any time <code>wp_insert_post</code> is called (which can include any time a post of any type is added or updated, even private post types), it will purge a variety of keys including <code>home</code>, <code>front</code>, <code>404</code> and <code>feed</code>. To bypass or override this behavior, since 1.5.0 we have a filter allowing an array of post types to ignore to be passed before those caches are purged. By default, the <code>revision</code> post type is ignored, but others can be added:</p>
<pre><code>/**
* Add a custom post type to the ignored post types.
*
* @param array $ignored_post_types The array of ignored post types.
* @return array
*/
function filter_ignored_posts( $ignored_post_types ) {
    $ignored_post_types[] = 'my-post-type'; // Ignore my-post-type from cache purges.
    return $ignored_post_types;
}

add_filter( 'pantheon_purge_post_type_ignored', 'filter_ignored_posts' );
</code></pre>
<p>This will prevent the cache from being purged if the given post type is updated.</p>
<h4>Setting the Cache Max Age with a filter</h4>
<p>The cache max age setting is controlled by the <a href="https://docs.pantheon.io/guides/wordpress-configurations/wordpress-cache-plugin" rel="nofollow ugc">Pantheon Page Cache</a> admin page. As of 2.0.0, there are three cache age options by default — 1 week, 1 month, 1 year. Pantheon Advanced Page Cache automatically purges the cache of updated and related posts and pages, but you might want to override the cache max age value and set it programmatically. In this case, you can use the <code>pantheon_cache_default_max_age</code> filter added in <a href="https://docs.pantheon.io/guides/wordpress-configurations/wordpress-cache-plugin#override-the-default-max-age" rel="nofollow ugc">Pantheon MU plugin 1.4.0+</a>. For example:</p>
<pre><code>add_filter( 'pantheon_cache_default_max_age', function() {
    return 10 * DAY_IN_SECONDS;
} );
</code></pre>
<p>When the cache max age is filtered in this way, the admin option is disabled and a notice is displayed.</p>
<h4>Updating the cache max age based on nonces</h4>
<p>Nonces created on the front-end, often used to secure forms and other data, have a lifetime, and if the cache max age is longer than the nonce lifetime, the nonce may expire before the cache does. To avoid this, you can use the <code>pantheon_cache_nonce_lifetime</code> action to set the <code>pantheon_cache_default_max_age</code> to less than the nonce lifetime. For example:</p>
<pre><code>do_action( 'pantheon_cache_nonce_lifetime' );
</code></pre>
<p>It’s important to wrap your <code>do_action</code> in the appropriate conditionals to ensure that the action is only called when necessary and not filtering the cache max age in cases when it’s not necessary. This might mean only running on certain pages or in certain contexts in your code.</p>
<h3>WP-CLI Commands</h3>
<p>This plugin implements a variety of <a href="https://wp-cli.org" rel="nofollow ugc">WP-CLI</a> commands. All commands are grouped into the <code>wp pantheon cache</code> namespace.</p>
<pre><code>$ wp help pantheon cache

NAME

  wp pantheon cache

DESCRIPTION

  Manage the Pantheon Advanced Page Cache.

SYNOPSIS

  wp pantheon cache <command>

SUBCOMMANDS

  purge-all       Purge the entire page cache.
  purge-key       Purge one or more surrogate keys from cache.
  purge-path      Purge one or more paths from cache.
</code></pre>
<p>Use <code>wp help pantheon cache <command></code> to learn more about each command.</p>
<h3>Debugging</h3>
<p>By default, Pantheon’s infrastructure strips out the <code>Surrogate-Key</code> response header before responses are served to clients. The contents of this header can be viewed as <code>Surrogate-Key-Raw</code> by adding on a debugging header to the request.</p>
<p>A direct way of inspecting headers is with <code>curl -I</code>. This command will make a request and show just the response headers. Adding <code>-H "Pantheon-Debug:1"</code> will result in <code>Surrogate-Key-Raw</code> being included in the response headers. The complete command looks like this:</p>
<pre><code>curl -IH "Pantheon-Debug:1" https://scalewp.io/
</code></pre>
<p>Piping to <code>grep</code> will filter the output down to just the <code>Surrogate-Key-Raw</code> header:</p>
<pre><code>curl -IH "Pantheon-Debug:1" https://scalewp.io/ | grep -i Surrogate-Key-Raw
</code></pre>
<p>Tada!</p>
<h3>Emitted Keys and Purge Events</h3>
<h4>Emitted Keys on Traditional Views</h4>
<p><strong>Home <code>/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>home</code>, <code>front</code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Single post <code>/2016/10/14/surrogate-keys/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>single</code>, <code>post-<id></code>, <code>post-user-<id></code>, <code>post-term-<id></code> (all terms assigned to post)</li>
</ul>
<p><strong>Author archive <code>/author/pantheon/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>archive</code>, <code>user-<id></code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Term archive <code>/tag/cdn/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>archive</code>, <code>term-<id></code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Day archive <code>/2016/10/14/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>archive</code>, <code>date</code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Month archive <code>/2016/10/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>archive</code>, <code>date</code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Year archive <code>/2016/</code></strong></p>
<ul>
<li>Emits surrogate keys: <code>archive</code>, <code>date</code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Search <code>/?s=<search></code></strong></p>
<ul>
<li>Emits surrogate keys: <code>search</code>, either <code>search-results</code> or <code>search-no-results</code>, <code>post-<id></code> (all posts in main query)</li>
</ul>
<p><strong>Not found (404)</strong></p>
<ul>
<li>Emits surrogate keys: <code>404</code></li>
</ul>
<h4>Emitted Keys on REST API Endpoints</h4>
<p><strong>Posts</strong></p>
<ul>
<li><code>/wp-json/wp/v2/posts</code> emits surrogate keys: <code>rest-post-collection</code>, <code>rest-post-<id></code></li>
<li><code>/wp-json/wp/v2/posts/<id></code> emits surrogate keys: <code>rest-post-<id></code></li>
</ul>
<p><strong>Pages</strong></p>
<ul>
<li><code>/wp-json/wp/v2/pages</code> emits surrogate keys: <code>rest-page-collection</code>, <code>rest-post-<id></code></li>
<li><code>/wp-json/wp/v2/pages/<id></code> emits surrogate keys: <code>rest-post-<id></code></li>
</ul>
<p><strong>Categories</strong></p>
<ul>
<li><code>/wp-json/wp/v2/categories</code> emits surrogate keys: <code>rest-category-collection</code>, <code>rest-term-<id></code></li>
<li><code>/wp-json/wp/v2/categories/<id></code> emits surrogate keys: <code>rest-term-<id></code></li>
</ul>
<p><strong>Tags</strong></p>
<ul>
<li><code>/wp-json/wp/v2/tags</code> emits surrogate keys: <code>rest-post_tag-collection</code>, <code>rest-term-<id></code></li>
<li><code>/wp-json/wp/v2/tags/<id></code> emits surrogate keys: <code>rest-term-<id></code></li>
</ul>
<p><strong>Comments</strong></p>
<ul>
<li><code>/wp-json/wp/v2/comments</code> emits surrogate keys: <code>rest-comment-collection</code>, <code>rest-comment-post-<post-id></code>, <code>rest-comment-<id></code></li>
<li><code>/wp-json/wp/v2/comments/<id></code> emits surrogate keys: <code>rest-comment-post-<post-id></code>, <code>rest-comment-<id></code></li>
</ul>
<p><strong>Users</strong></p>
<ul>
<li><code>/wp-json/wp/v2/users</code> emits surrogate keys: <code>rest-user-collection</code>, <code>rest-user-<id></code></li>
<li><code>/wp-json/wp/v2/users/<id></code> emits surrogate keys: <code>rest-user-<id></code></li>
</ul>
<p><strong>Settings</strong></p>
<ul>
<li><code>/wp-json/wp/v2/settings</code> emits surrogate keys: <code>rest-setting-<name></code></li>
</ul>
<h4>Purge Events</h4>
<p>Different WordPress actions cause different surrogate keys to be purged, documented here.</p>
<p><strong>wp_insert_post / transition_post_status / before_delete_post / delete_attachment</strong></p>
<ul>
<li>Purges surrogate keys: <code>home</code>, <code>front</code>, <code>404</code>, <code>post-<id></code>, <code>user-<id></code>, <code>term-<id></code>, <code>rest-<type>-collection</code>, <code>rest-comment-post-<id></code></li>
<li>Affected views: homepage, single post, any page with 404 header, any archive where post displays, author archive, term archive, REST API collection and resource endpoints</li>
</ul>
<p><strong>clean_post_cache</strong></p>
<ul>
<li>Purges surrogate keys: <code>post-<id></code>, <code>rest-post-<id></code></li>
<li>Affected views: single post, REST API resource endpoint</li>
</ul>
<p><strong>created_term / edited_term / delete_term</strong></p>
<ul>
<li>Purges surrogate keys: <code>term-<id></code>, <code>post-term-<id></code>, <code>rest-<taxonomy>-collection</code></li>
<li>Affected views: term archive, any post where the term is assigned, REST API collection and resource endpoints</li>
</ul>
<p><strong>clean_term_cache</strong></p>
<ul>
<li>Purges surrogate keys: <code>term-<id></code>, <code>rest-term-<id></code></li>
<li>Affected views: term archive, REST API resource endpoint</li>
</ul>
<p><strong>wp_insert_comment / transition_comment_status</strong></p>
<ul>
<li>Purges surrogate keys: <code>rest-comment-collection</code>, <code>rest-comment-<id></code></li>
<li>Affected views: REST API collection and resource endpoints</li>
</ul>
<p><strong>clean_comment_cache</strong></p>
<ul>
<li>Purges surrogate keys: <code>rest-comment-<id></code></li>
<li>Affected views: REST API resource endpoint</li>
</ul>
<p><strong>clean_user_cache</strong></p>
<ul>
<li>Purges surrogate keys: <code>user-<id></code>, <code>rest-user-<id></code></li>
<li>Affected views: author archive, any post where the user is the author</li>
</ul>
<p><strong>updated_option</strong></p>
<ul>
<li>Purges surrogate keys: <code>rest-setting-<name></code></li>
<li>Affected views: REST API resource endpoint</li>
</ul>
<h3>Surrogate Keys for taxonomy terms</h3>
<p>Setting surrogate keys for posts with large numbers of taxonomies (such as WooCommerce products with a large number of global attributes) can suffer from slower queries. Surrogate keys can be skipped for ‘product’ post types’ taxonomy terms (or any other criteria you see fit) with the following filter:</p>
<pre><code>function custom_should_add_terms($should_add_terms, $wp_query) {
    if ( $wp_query->is_singular( 'product' ) ) {
        return false;
    }
    return $should_add_terms;
}
add_filter('pantheon_should_add_terms', 'custom_should_add_terms', 10, 2);<h3>Other Filters</h3>
</code></pre>
<h4>pantheon_apc_disable_admin_notices</h4>
<p>Since 2.0.0, Pantheon Advanced Page Cache displays a number of admin notices about your current cache max age value. You can disable these notices with the <code>pantheon_apc_disable_admin_notices</code> filter.</p>
<pre><code>add_filter( 'pantheon_apc_disable_admin_notices', '__return_true' );
</code></pre>
<p>Alternately, the function callback is passed into the <code>pantheon_apc_disable_admin_notices</code> filter, allowing you to specify precisely <em>which</em> notice to disable, for example:</p>
<pre><code>add_filter( 'pantheon_apc_disable_admin_notices', function( $disable_notices, $callback ) {
    if ( $callback === '\\Pantheon_Advanced_Page_Cache\\Admin_Interface\\admin_notice_maybe_recommend_higher_max_age' ) {
        return true;
    }
    return $disable_notices;
}, 10, 2 );
</code></pre>
<p>The above example would disable <em>only</em> the admin notice recommending a higher cache max age.</p>
<h3>Plugin Integrations</h3>
<p>Pantheon Advanced Page Cache integrates with WordPress plugins, including:</p>
<ul>
<li><a href="https://wordpress.org/plugins/wp-graphql/" rel="ugc">WPGraphQL</a></li>
</ul>
<h3>Contributing</h3>
<p>See <a href="https://github.com/pantheon-systems/wp-saml-auth/blob/master/CONTRIBUTING.md" rel="nofollow ugc">CONTRIBUTING.md</a> for information on contributing.</p>


Pantheon Advanced Page Cache

Automatically clear related pages from Pantheon's Edge when you update content. High TTL. Fresh content. Visitors never wait.

Marinus Klasen

Anais Pantheor

Roshny Kunjappan

Scott Buscemi

<p><strong>The Pantheon Content Publisher plugin for WordPress enables seamless content publishing from Google Drive and Google Docs directly to WordPress sites.</strong> Perfect for editorial teams who collaborate on content within Google Docs, this plugin ensures a smooth transition from document creation to web publishing, facilitating real-time previews and direct publishing options.</p>
<h3>Features</h3>
<h4>Real-time Preview</h4>
<p>Experience seamless document previews within your WordPress environment as they would appear live on the web.</p>
<h4>One-click Publishing</h4>
<p>Enable direct publishing from Google Docs to WordPress, simplifying content management and streamlining workflows.</p>
<h4>Custom Post Type Support</h4>
<p>Publish content to any public post type registered on your WordPress site, including custom post types. Authors can also specify the target post type per document via metadata.</p>
<h4>ACF Integration</h4>
<p>Sync Content Publisher metadata fields to Advanced Custom Fields (ACF). Navigate to Settings > Pantheon Content Publisher > Integration tab to define field mappings per post type. Each tab shows ACF fields from the field groups assigned to that post type — enter the exact Content Publisher metadata field name (case-sensitive) to create a mapping. Mapped values are automatically applied on every publish. Sync errors are displayed in the Integration tab and auto-clear after one hour. Requires the ACF plugin (free or Pro) to be installed and active. Works with custom post types.</p>
<p>For more information, please check <a href="https://docs.content.pantheon.io" rel="nofollow ugc">Pantheon Content Publisher documentation</a>.</p>
<h3>Integration with Third-Party Services</h3>
<h4>Important Disclosure</h4>
<p>This plugin integrates with Google Drive and Google Docs to facilitate document publishing to WordPress.<br />
When enabled, it will access documents from these services for the purposes of rendering previews and enabling publishing functionality via the <a href="https://docs.content.pantheon.io" rel="nofollow ugc">Pantheon Content Publisher service</a>. These services are not processing any data or content originating from WordPress or the plugin itself and no other third-party service is used to process data.<br />
Pantheon Content Publisher policies and terms are available at <a href="https://legal.pantheon.io/" rel="nofollow ugc">https://legal.pantheon.io/</a></p>
<p>This plugin makes use of the Apollo open-source GraphQL Client library and references its <a href="https://chromewebstore.google.com/detail/apollo-client-devtools/jdkknkkbebbapilgoeccciglkfbmbnfm" rel="nofollow ugc">Chrome extension</a>.<br />
Google Chrome Web Store: <a href="https://ssl.gstatic.com/chrome/webstore/intl/en/gallery_tos.html" rel="nofollow ugc">Terms of Service</a>,  <a href="https://policies.google.com/privacy?hl=en" rel="nofollow ugc">Privacy Policy</a>.</p>
<p>Mozilla/FireFox:  <a href="https://www.mozilla.org/en-US/about/legal/terms/mozilla/" rel="nofollow ugc">Terms of Service</a>, <a href="https://www.mozilla.org/en-US/privacy/websites/" rel="nofollow ugc">Privacy Policy</a></p>
<p>This library only suggests the use of this tool to developers. Users don’t interact with it and no data is exchanged with this service.</p>
<p>This service is provided by <a href="https://www.apollographql.com" rel="nofollow ugc">Apollo</a>. See the <a href="https://www.apollographql.com/Apollo-Terms-of-Service.pdf" rel="nofollow ugc">Apollo Term of Service</a> and <a href="https://www.apollographql.com/Apollo-Privacy-Policy.pdf" rel="nofollow ugc">Apollo Privacy Policy</a> for details on terms.</p>
<h4>Data Handling</h4>
<p>User documents from Google Drive are accessed and processed to generate content on WordPress.<br />
No other personal data is shared with or stored on third-party services beyond this operational scope.</p>


Pantheon Content Publisher

The Pantheon Content Publisher plugin for WordPress enables seamless content publishing from Google Drive and Google Docs directly to WordPress sites.

Pantheon Advanced Page Cache vs Pantheon Content Publisher