Skip to content

Caching

Cache API

Customizations made to cache control using the VIP Cache API can be written into a theme, plugin, or client MU plugin.

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. 

In the code example below, the cache control max-age for feeds is set 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', 'wpcom_vip_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 wpcom_vip_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) );         
        }
    }
}

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

Three functions that 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.

Setting individual users or requests to bypass cache

This method allows selected users to bypass cache even if they are not logged in. Their requests will always be processed by the origin servers. 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.

Filter URLs cleared when a post is changed

When a post is published, a published post is changed, or a post is un-published, 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 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;
}

Varying 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 have the result cached correctly.

Geo targeting on VIP

The VIP Go Geo Uniques plugin allows content to be served to visitors on a country by country basis, while still benefitting from VIP’s page caching.

Last updated: August 18, 2022