Skip to content

Cache API

Customizations can be made to cache control for some behaviors of Varnish and NGINX by using the VIP Cache API. These customizations can be written into a theme, plugin, or client MU plugin.

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

Three functions can be called to clear specific caches:

  • wpcom_vip_purge_edge_cache_for_url( $url ) – Purge the page cache for a specific URL, including URLs for media files, CSS, and JS.
  • wpcom_vip_purge_edge_cache_for_post( $post ) – Purge the caches related to a post.
  • wpcom_vip_purge_edge_cache_for_term( $term ) – Purge the caches related to a term.

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

Filter URLs to be cleared when a post is changed

When a post is published, a published post is changed, or a post is unpublished, a default set of URLs is assembled to be purged. URLs for additional specific posts can be included in the triggered cache purge with the wpcom_vip_cache_purge_{$post->post_type}_post_urls filter.

Example code below:

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. URLs for additional specific term IDs can be included in the triggered cache purge with thewpcom_vip_cache_purge_{$taxonomy_name}_term_urls filter.

Example code below:

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;
}

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 leveraging the vary: X-Country-Code response header.

The VIP Go Geo Uniques plugin is an IP geolocation option for WordPress sites specifically designed to work with the VIP Platform’s page cache.

Set individual users or requests to bypass the cache

This method allows selected users to bypass the cache even if they are not logged in. The origin servers will always process their requests. The response can be personalized and will never be cached and served to other users. This could be useful for sites with a paywall or as part of A/B testing functionality.

Requests with the vip-go-cb cookie set to a value of 1 (it must be a value of 1) will always PASS 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.

Logged-in WordPress users accessing a VIP Platform application will always PASS the cache, so 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.

Set the maximum cache age

The default cache-control header value max-age=300 returned by VIP’s page cache (for responses with an HTTP Status Code of 200) can be set to a custom value.

Do not set cache age less than 1 minute for heavily trafficked resource types. 

The code example below sets the cache control for feeds to a custom value. Note that the example includes an is_user_logged_in() check, which ensures the cache TTL headers are not set for logged-in users, as this would trigger browser caching for them.

add_action( 'wp', 'my_cache_maxage' );
/**
 * Hooks the wp action to insert some cache control
 * max-age headers.
 *
 * @param Object wp The WP object, passed by reference
 * @return void
 */
function my_cache_maxage( $wp ) {
    if ( is_feed() ) {
        // Set the max age for feeds to 5 minutes.
        if ( ! is_user_logged_in() ) {
            header( 'Cache-Control: max-age=' . ( 5 * MINUTE_IN_SECONDS ) );         
        }
    }
}

The Vary HTTP response header

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

Vary cached content by User-Agent class

The X-Mobile-Class HTTP request header (accessible via $_SERVER['HTTP_X_MOBILE_CLASS']) will be seen by anonymous requests. The page cache automatically provides buckets for the possible values: desktop, smart, tablet, and dumb. Output can be conditionally altered for different classes of User-Agent by checking this header and having the result cached correctly.

Last updated: May 04, 2023

Relevant to

  • Node.js
  • WordPress