Skip to content

How-to Guides

Technical References

Caching /

Cache API

Using the cache clearance API you can:

  • Set the maximum age of the cache
  • Clear the cache for a specific URL, post, or term
  • Filter the URLs being queued for clearance in a variety of ways

Set the maximum cache age

Some sample code to control cache age for feeds is below:

/**
* 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 * 60) );         
        }
    }
}
add_action( 'wp', 'wpcom_vip_cache_maxage' );

Please do not set cache age lower than 1 minute for heavily trafficked resource types. During code review we will check anywhere you are setting the maximum cache age and discuss the options with you.

Note the 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.

Clearing caches for post, term, or a specific URL

We have three functions you can call to clear particular caches:

wpcom_vip_purge_edge_cache_for_url( $url ) – purge the cache for one specific URL. Works for CSS and JS URLs as well.

wpcom_vip_purge_edge_cache_for_post( $post ) – purge the caches related to a post (see above, for which caches are associated with a post)

wpcom_vip_purge_edge_cache_for_term( $term ) – purge the caches related to a term (see above, for which caches are associated with 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 technique allows chosen users to bypass cache even if they are not logged in, meaning that their requests will always processed by the origin servers, you can personalise the response, and the response will never be cached and served to other users. This might fit the use case for a paywall, or as part of some A/B testing functionality.

Requests with the vip-go-cb cookie set with a value of 1 (it must be a value of 1) will always PASS the VIP Go cache, meaning that 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 Go application will always PASS the cache, so setting this cookie for logged in WordPress users is not necessary. If you have users logging in via some other mechanism, you can set the vip-go-cb cookie in addition to any other cookies or local storage data for some third party login system and be sure that these users will not have responses cached or see cached responses.

Filter the URLs cleared when a post is changed

Whenever a post is published, a published post is changed, or a post is un-published, a set of URLs is assembled to be purged. By default we include most URLs you would want to clear, see the list above in “Overview”, and you can add to or remove from these URLs using the wpcom_vip_cache_purge_{$post->post_type}_post_urls filter.

Example code below:

/**
 * 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;
}
add_filter( 'wpcom_vip_cache_purge_post_post_urls', 'my_cache_purge_post_urls', 10, 2 );

Filter the URLs cleared when a term is changed

Whenever a term is created, changed, or deleted, a set of URLs is assembled to be purged. By default we include most URLs you would want to clear, see the list above in “Overview”, and you can add to or remove from these URLs using the wpcom_vip_cache_purge_{$taxonomy_name}_term_urls filter.

Example code below:

<div class="wp-block-rkv-syntax-highlighting vipdocs-syntax"><pre class="line-numbers prism-large" data-start="1"><code class="lang-php">/**
 * 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 &amp;amp;amp;amp;amp;amp;&amp;amp;amp;amp;amp;amp; is_string( $term_link ) ) {
        $this-&amp;amp;amp;gt;purge_urls[] = $term_link . '/json/';
    }
    return $urls;
}
add_filter( 'wpcom_vip_cache_purge_category_term_urls', 'my_cache_purge_term_urls', 10, 2 );</code></pre><textarea aria-hidden="true" class="vipdocs-syntax__copy-textarea" tabindex="-1">/**
 * 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 &amp;amp;amp;amp;amp;amp;&amp;amp;amp;amp;amp;amp; is_string( $term_link ) ) {
        $this-&amp;amp;amp;gt;purge_urls[] = $term_link . '/json/';
    }
    return $urls;
}
add_filter( 'wpcom_vip_cache_purge_category_term_urls', 'my_cache_purge_term_urls', 10, 2 );</textarea><button class="vipdocs-syntax__copy-button" type="button"><span class="vipdocs-syntax__copy-button__before">Copy</span><span class="vipdocs-syntax__copy-button__after" aria-hidden="true">Copied</span></button></div>

Varying the cached content by User Agent class

For anonymous requests you will see an X-Mobile-Class HTTP request header (accessible via $_SERVER['HTTP_X_MOBILE_CLASS']), our page cache provides buckets for the possible values here (desktop, smart, tablet, and dumb). You can conditionally alter your output for different classes of user agent by checking this header, and have the result cached correctly.

Geo targeting on VIP Go

VIP Go allows you to differentiate visitors from different countries, tailoring the content you serve to your visitors on a country by country basis, while still keeping the benefits of our fast page caching. Read our separate documentation on this geotargeting on VIP Go.

Last updated: November 12, 2020