Purge programmatically

Select behaviors 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 page cache clearing behavior for a WordPress or Node.js application.

Instead, the VIP Cache API should be leveraged to customize cache clearing behavior.

The VIP Cache API provides customization options such as:

• Automatically purging the cache for a url or a custom API endpoint when a change is made in the WordPress Admin dashboard.
• Clearing the cache for a specific URL, post, or term.
• Filtering the URLs that are queued for cache clearance.

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.