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.

Geolocation on VIP

Variations of cached content can be delivered based on an end user’s global location. IP geolocation on the VIP Platform can be implemented by WordPress and Node.js applications by leveraging the vary: X-Country-Code response header.

For WordPress sites, IP geolocation can be managed with the VIP Go Geo Uniques plugin specifically designed to work with the VIP Platform’s page cache.

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
• X-Country-Code
• X-VIP-Go-Segmentation
• X-VIP-Go-Auth

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:

• desktop
• smart
• tablet
• dumb

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.”

X-Mobile-Class

In WordPress applications, the X-Mobile-Class request header can be accessed via $_SERVER['HTTP_X_MOBILE_CLASS'].

Node.js applications can access the X-Mobile-Class header directly using the method recommended by their preferred framework. In Express.js, for example, it is accessible via req.headers['x-mobile-class'].