Customize page cache behavior

Select behavior of the VIP page cache can be controlled using VIP’s Cache API. Some of the Cache API controls are provided by VIP MU plugins and must be implemented by a WordPress application. Other controls are generic HTTP concepts that can be used by both WordPress and Node.js applications.

Custom NGINX rules cannot be added to modify the behavior of the page cache for a WordPress or Node.js application.

Filter URLs to be cleared when a post is changed

When a post is published, unpublished, or if a published post is modified, a default set of URLs are assembled to be purged. WordPress applications can use the wpcom_vip_cache_purge_{$post->post_type}_post_urls filter to specify additional URLs that should be purged.

A code example demonstrating use of the filter:

add_filter( 'wpcom_vip_cache_purge_post_post_urls', 'my_cache_purge_post_urls', 10, 2 );
/**
 * Hooks the wpcom_vip_cache_purge_post_post_urls filter to 
 * also clear a custom JSON endpoint for the post URL.
 * 
 * This targets posts of post type "post" only.
 *
 * @param array urls An array of URLs to be purged
 * @param int post_id The ID of the post for which we're purging URLs
 * @return array An array of URLs to be purged
 */
function my_cache_purge_post_urls( $urls, $post_id ) {
    $post = get_post( $post_id );
    if ( empty( $post ) ) {
        return $urls;
    }
    // Also purge the JSON format for the posts
    $urls[] = get_permalink( $post_id ) . '/json/';
    return $urls;
}

Filter URLs to be cleared when a term is changed

Whenever a term is created, changed, or deleted, a default set of URLs is assembled to be purged. WordPress applications can use the wpcom_vip_cache_purge_{$taxonomy_name}_term_urls filter to specify additional URLs that should be purged.

A code example demonstrating use of the filter:

add_filter( 'wpcom_vip_cache_purge_category_term_urls', 'my_cache_purge_term_urls', 10, 2 );
/**
 * Hooks the wpcom_vip_cache_purge_category_term_urls filter to 
 * also clear a custom JSON endpoint for the term archive
 *
 * @param array urls An array of URLs to be purged
 * @param int term_id The ID of the term for which we're purging URLs
 * @return array An array of URLs to be purged
 */
function my_cache_purge_term_urls( $urls, $term_id ) {
    $term = get_term( $term_id );
    if ( is_wp_error( $term ) || empty( $term ) ) {
        return false;
    }
    $term_link = get_term_link( $term, $taxonomy_name );
    if ( is_wp_error( $term_link ) ) {
        return false;
    }
    if ( $term_link && is_string( $term_link ) ) {
        $this->purge_urls[] = $term_link . '/json/';
    }
    return $urls;
}

Clear caches for a post, term, or a specific URL

In WordPress applications, functions are available to manually clear specific cache objects.

• wpcom_vip_purge_edge_cache_for_url( $url ): Purge the page cache for a specific URL, including URLs for media files, CSS, JS, or a URL belonging to a related Node.js application, such as a decoupled frontend.
• wpcom_vip_purge_edge_cache_for_post( $post ): Purge URLs related to a post from the page cache. The purged URLs can be controlled using the wpcom_vip_cache_purge_{$post->post_type}_post_urls filter.
• wpcom_vip_purge_edge_cache_for_term( $term ): Purge URLs related to a term from the page cache. The purged URLs can be controlled using the wpcom_vip_cache_purge_{$taxonomy_name}_term_urls filter.

Purging can take up to 10 seconds to complete across all VIP edge cache servers, though the average is around 70ms. In one analysis of 10 million requests, only 0.00252% of purge requests took longer than 200ms.

Set individual users or requests to bypass the cache

Use the vip-go-cb cookie on WordPress or Node.js applications to allow selected users to bypass the page cache. This method allows responses to be personalized, and to never be cached and served to other users.

Methods for bypassing the cache can be useful for sites with a paywall or as part of A/B testing functionality. However it should be used with caution, as requests made by users that bypass the cache will always be processed by the origin servers.

• Requests with the vip-go-cb cookie set to a value of 1 (it must be a value of 1) will always BYPASS the page cache. As a result, these requests will never be served a cached response, and the response to these requests will never be cached to be served to others.
• On WordPress applications, requests from logged-in users will always BYPASS the cache; setting this cookie for logged-in WordPress users is not necessary. If users are logging in using a different mechanism, set the vip-go-cb cookie in addition to any other cookies or local storage data for a third-party login system. Be sure that these users will not have responses cached or see cached responses.

The Vary HTTP response header

On the VIP Platform, the Vary HTTP response header is respected for these values:

• origin
• RSC
• x-vip-go-segmentation
• x-vip-go-auth
• x-country-code
• x-continent
• x-region
• x-metro-code
• x-city
• x-postal-code

Geolocation on VIP

The Vary IP geolocation response headers can be utilized by WordPress and Node.js applications to deliver variations of cached content based on an end user’s global location.

For WordPress sites, country-based IP geolocation can also be managed with the VIP Go Geo Uniques plugin. The plugin is specifically designed to work with the VIP Platform’s page cache, but is currently limited to only respect the vary: x-country-code header.

Vary cached content by User-Agent class

For all requests (except those by logged-in WordPress users), the x-mobile-class HTTP request header is populated with 1 of 4 values that correspond to VIP’s classification of the request’s User-Agent.

By inspecting the value of the x-mobile-class request header, an application can conditionally alter its response. The result will be cached correctly in its own page cache “bucket”.