Proxy Cache Purge

This plugin was originally adopted and updated for DreamHost’s DreamPress server, however it is not (and never has been) for DreamHost only.

I worked at DreamHost from 2012 to 2022, and have maintained the plugin since around 2014 or so.

As of October 2023, this plugin is NO LONGER installed by default on DreamPress.

Today, the plugin is maintained by GetPageSpeed, with a focus on advanced NGINX and proxy caching deployments and strong compatibility with the NGINX cache-purge module from the NGINX Extras collection.

No. This plugin tells your cache system when content is updated, and to delete the cached data at that time.

Speed and stability. Emptying too much of a cache on every change can slow a server down. This plugin does its best to determine what needs to be deleted and when, while providing hooks for developers to use as necessary.

It depends on the post, but in general the tool will delete cached content for:

1. The post name
2. The front page of the site
3. All first pages of related tags/categories
4. The JSON API pages
5. All related RSS feeds

Not really, but in order to prevent your site from crashing by running the same checks over and over, if you try to purge more than 50 URLs at once, the plugin will do a full purge. Normally this never happens, but there are some plugins that hook into the options to add more pages to purge on an update.

You can change this value in your settings, or via the define VHP_VARNISH_MAXPOSTS in your wp-config.php file.

Keep in mind, the count of 50 does not include category/tags, API, or RSS pages. It’s just the sheer number of individual posts/pages you’re trying to purge at once.

Yes. If your environment doesn’t cache logged-in users and you want to avoid purge noise from autosaves/drafts, you can exclude specific statuses network‑wide via wp-config.php (multisite‑friendly).

Add a define to exclude drafts:

define( 'VHP_EXCLUDED_POST_STATUSES', 'draft' );

Exclude multiple statuses (comma‑separated):

define( 'VHP_EXCLUDED_POST_STATUSES', 'draft,pending' );

Or pass an array:

define( 'VHP_EXCLUDED_POST_STATUSES', array( 'draft', 'pending' ) );

Developers can also use a filter to adjust the valid statuses programmatically:

add_filter( 'varnish_http_purge_valid_post_statuses', function( $statuses, $post_id ) {
    return array_diff( $statuses, array( 'draft' ) );
}, 10, 2 );

By default, the plugin considers these statuses for purge URL generation: publish, private, trash, pending, draft.

Yes. Click the ‘Empty Cache’ button on the “Right Now” Dashboard (see the screenshot if you can’t find it). There’s also an “Empty Cache” button on the admin toolbar.

If you don’t see a button, then your account doesn’t have the appropriate permissions. Only administrators can empty the entire cache. In the case of a subfolder multisite network, only the network admins can empty the cache for the primary site.

No. WordPress can’t detect those file changes so it can’t tell your cache what to do. You will need to use the Empty Cache buttons when you’re done editing your code.

No. Some of them have behaviours that cause them not to cache, either by accident or design. It’s incredibly hard to debug those, since many of the related issues are contextual (like if you save a page with a special setting). I’ve done my best to flag everything as possible issues with the debugger.

Yes. Full documentation can be found on Custom Filters in the wiki.

Not permanently, and remember that this plugin is not actually caching your content.

You can use development mode to have WordPress attempt to tell your proxy service not to serve cached content, but the content will still be cached by the service.

There are three ways to do this:

1. Choose ‘Pause Cache (24hrs)’ from the Cache dropdown menu in your toolbar
2. Go to Proxy Cache -> Settings and enable development mode
3. Add define( 'VHP_DEVMODE', true ); to your wp-config.php file.

The first two options will enable development mode for 24 hours. If you’re working on long term development, you should use the define.

It is not recommended you use development mode on production sites for extended periods of time, as it will slow your site down and lose all the benefits of caching in the first place.

If you’ve disabled caching via the define, then you cannot restart cache via the plugin. You would need to change define( 'VHP_DEVMODE', true ); to define( 'VHP_DEVMODE', false ); in your wp-config.php file.

Due to the damage this can cause a site, access is limited to admins only. In the case of a multisite network, only Network Admins can disable caching and they must do so via wp-config.php for security.

While development mode is on, your server will continue to cache content but the plugin will tell WordPress not to use the cached content. That means files that exist outside of WordPress (like CSS or images) may serve cached content.

The plugin does its best to add a No Cache parameter to javascript and CSS, however if a theme or plugin doesn’t use proper WordPress enqueues, then their cached content will be shown.

Because the server is still caching content.

The plugin provides a way to flush the cache for those pages, as well as anything not included in WordPress, for your convenience.

From your WordPress Dashboard, go to Proxy Cache > Check Caching. There, a page will auto-scan your front page and report back any issues found. This includes any known problematic plugins. You can use it to scan any URL on your domain.

PageSpeed likes to put in Caching headers to say not to cache. To fix this, you need to put this in your .htaccess section for PageSpeed: ModPagespeedModifyCachingHeaders off

If you’re using nginx, it’s pagespeed ModifyCachingHeaders off;

When you use CloudFlare or any other similar service, you’ve put a proxy in front of the server’s proxy. In general this isn’t a bad thing, though it can introduce some network latency (that means your site may run slower because it has to go through multiple layers to get to the content). The problem arises when WordPress tries to send the purge request to your domain name and, with a proxy, that means the proxy service and not your website.

On single-site, you can edit this via the Proxy Cache > Check Caching page. On Multisite, you’ll need to add the following to your wp-config.php file: define('VHP_VARNISH_IP','123.45.67.89');

Replace 123.45.67.89 with the IP of your Proxy Cache Server (not CloudFlare). DO NOT put http in this define. If you’re on nginx, you’ll want to use localhost instead of an IP address.

If you want to use WP-CLI, you can set an option in the database. This will not take precedence over the define, and exists for people who want to use automation tools: wp option update vhp_varnish_ip 123.45.67.89

This is usually related to CloudFlare’s APO setup.

I have an open ticket with CloudFlare trying to debug this, but basically whatever they’re doing with APO doesn’t ‘like’ the flush command and times out (or crashes).

Your IP address is incorrect. Check the IP of your server and then the setting for your proxy cache IP. If they’re not the same, that’s likely why.

Your proxy IP must be one of the IPs that the service is listening on. If you use multiple IPs, or if you’ve customized your ACLs, you’ll need to pick one that doesn’t conflict with your other settings.

For example, if you have a Varnish based cache and it’s listening on a public and private IP, you’ll want to pick the private. On the other hand, if you told Varnish to listen on 0.0.0.0 (i.e. “listen on every interface you can”) you would need to check what IP you set your purge ACL to allow (commonly 127.0.0.1 aka localhost), and use that (i.e. 127.0.0.1).

If your web host set up your service, check their documentation.

You may enter them, separated by a comma, on the settings page.

So far this plugin has been reported to successfully function on Varnish v2 through v6.5.

Yes. Set the cache backend to NGINX via the settings page (Proxy Cache > Settings > Cache Backend) or add this to your wp-config.php:

define( 'VHP_PURGE_BACKEND', 'nginx' );

When set to NGINX, the plugin uses a literal * wildcard instead of Varnish’s .* regex pattern, which is what the NGINX cache-purge module expects. You should also set your Proxy Cache IP to localhost.

This is a question beyond the support of this plugin. I do not have the resources available to offer any configuration help. Here are some basic gotchas to be aware of:

• To empty any cached data, the service will need to respect the PURGE command
• Not all cache services set up PURGE by default
• When flushing the whole cache with Varnish backend, the plugin sends a PURGE command of /.* and sets the X-Purge-Method header to regex
• When using NGINX backend, it sends /* instead (literal wildcard)
• NGINX expects the IP address to be ‘localhost’

Some providers require a control key, token, or Authorization header to accept PURGE requests. You can set a header name and value via the settings page or via the following constant:

define( 'VHP_VARNISH_EXTRA_PURGE_HEADER', 'X-Control-Key: YOUR_CONTROL_KEY_HERE' );

Alternatively, you can inject any required header via a filter.

1. Set where PURGE requests should be sent (host:port, no scheme):

   define( ‘VHP_VARNISH_IP’, ‘varnish.example.com:6081’ );

2. Add your control key/auth header via a small MU plugin so it loads on every request. Create wp-content/mu-plugins/varnish-purge-auth.php with:

   <?php
   add_filter( ‘varnish_http_purge_headers’, function( $headers ) {
   // Example: provider expects a custom key header
   $headers[‘X-Control-Key’] = ‘YOUR_CONTROL_KEY_HERE’;

   // Or use Authorization headers:
   // $headers['Authorization'] = 'Basic ' . base64_encode( 'username:password' );
   // $headers['Authorization'] = 'Bearer ' . 'YOUR_TOKEN_HERE';
   
   return $headers;
   

   } );

If your provider requires HTTPS for the purge endpoint, force the schema:

add_filter( 'varnish_http_purge_schema', function() { return 'https://'; } );

Important: This plugin sends HTTP PURGE requests to your cache service. It does not use the Varnish management interface (varnishadm/secret on port 6082).

Yes IF the service has an interface. Sadly NGINX does not. Detailed directions can be found on the debugging section on GitHub. Bear in mind, these interfaces tend to be command-line only.

It means that somewhere your server’s headers aren’t returning the data the plugin needs to see, in order to determine if the cache is working. The most common cause is that your server isn’t returning the X-Varnish header or the Age header.

You can use varnish_http_purge_x_varnish_header_name filter to customize this header name, like below to resolve this:

function change_varnish_header( $default_header ) {
    return 'My-Custom-Header'; // Replace with the desired header
}
add_filter( 'varnish_http_purge_x_varnish_header_name', 'change_varnish_header' );