MSCache Varnish Purge

This plugin has been designed, developed, tested, and validated on the hosting infrastructure of Managed Server S.r.l. — Performance Managed Hosting (managedserver.it). The reference stack consists of Nginx (SSL termination and micro-caching) + Varnish Cache 3.x/4.x (HTTP reverse proxy) + Apache/Nginx (backend) + PHP-FPM, running on Linux. The plugin communicates with Varnish via raw TCP socket on a configurable IP address and port. Whether it works on other hosting environments depends entirely on:

• The Varnish version installed and its VCL configuration
• The IP address and port on which Varnish listens for HTTP requests
• The network topology (is Varnish on localhost? Behind a load balancer? On a separate machine?)
• The presence of additional caching layers (Nginx proxy cache, CDN, etc.)
• ACL rules in the VCL that control which IPs are authorized to send PURGE requests

Your VCL must handle PURGE requests from the WordPress server and optionally support the ms-cache: excluded header for cache exclusions. Below is the reference VCL configuration tested and validated on the Managed Server infrastructure, for Varnish 3.x. Replace 123.123.123.123 with your server's public IP address and 127.0.0.2 with your actual backend address and port. vcl_recv — PURGE handling (single URL + full domain): ` backend website { .host = "127.0.0.2"; .port = "80"; } sub vcl_recv { Set X-Forwarded-For header if (req.http.x-forwarded-for) { set req.http.X-Forwarded-For = req.http.X-Forwarded-For + ", " + client.ip; } else { set req.http.X-Forwarded-For = client.ip; } --------------------------------------------------------------- PURGE — Single URL invalidation The plugin sends: PURGE /path/ HTTP/1.0 with Host header For full cache purge: PURGE /.* HTTP/1.0 --------------------------------------------------------------- if (req.request == "PURGE") { if ((req.http.X-Forwarded-For == "123.123.123.123, 127.0.0.1") || (req.http.X-Forwarded-For == "127.0.0.1")) { ban("req.url ~ ^" + req.url + "$" + " && req.http.host == " + req.http.host); error 200 "Purged."; } else { error 405 "Not allowed."; } } --------------------------------------------------------------- PURGE with X-Purge-Domain — Full domain invalidation Invalidates all cached objects for a specific domain --------------------------------------------------------------- if ((req.request == "PURGE") && ((req.http.X-Forwarded-For == "123.123.123.123") || (req.http.X-Forwarded-For == "127.0.0.1")) && (req.http.X-Purge-Domain)) { ban("req.http.host == " + req.http.X-Purge-Domain); error 200 req.http.X-Purge-Domain + " purged."; } ... your other vcl_recv rules ... } ` vcl_fetch — Respect the ms-cache: excluded header from the plugin: ` sub vcl_fetch { --------------------------------------------------------------- MSCache exclusion header When the plugin detects that a page matches an exclusion pattern (e.g., /cart/, /checkout/, /my-account/*), it adds the response header: ms-cache: excluded This block ensures Varnish does NOT cache those responses. --------------------------------------------------------------- if (beresp.http.ms-cache == "excluded") { set beresp.ttl = 0s; set beresp.http.X-Cache = "EXCLUDED"; Optionally hide the header from end users: unset beresp.http.ms-cache; return (hit_for_pass); } ... your other vcl_fetch rules ... } `

The plugin sends an HTTP PURGE request to Varnish via a raw TCP socket connection (fsockopen). The request includes the URL path to invalidate and the correct Host header for the domain. Single URL purge — When a post is saved, the plugin sends: PURGE /2026/04/03/my-post-title/ HTTP/1.0 Host: www.example.com Connection: Close The VCL uses ban() with a regex anchored match (^/path/$) to invalidate the URL. This approach is used instead of return(purge) because most production Varnish configurations include additional keys in vcl_hash (e.g., x-ua-device for mobile/desktop variants). A ban() invalidates all variants of the URL in a single operation, regardless of the hash. Full cache purge — When "Purge Entire Cache" is clicked, the plugin sends: PURGE /.* HTTP/1.0 Host: www.example.com Connection: Close The VCL interprets /.* as a regex matching all URLs for that host, effectively invalidating the entire domain cache. Asynchronous (fire-and-forget) — The socket is closed immediately after sending the request. The plugin does NOT wait for Varnish to respond, so the purge request does not block the WordPress request. In debug mode, the plugin reads the response status line for logging purposes.

• PURGE (return(purge) in VCL) removes a single cached object matching an exact URL and hash. It is fast and frees memory immediately, but only works for the exact hash — if your vcl_hash includes device type, language, or other keys, you would need a separate PURGE for each variant.
• BAN (ban() in VCL) adds a rule to the ban list that retroactively invalidates all cached objects matching a condition. Objects are checked against the ban list when they are next requested. BAN is more flexible because it can match patterns (regex) and invalidates all variants of a URL regardless of the hash.

When a frontend request path matches one of the exclusion patterns configured in the plugin settings (e.g., /cart/*, /checkout/*, /my-account/*), the plugin adds the HTTP response header ms-cache: excluded. This header does nothing by itself — it is a signal for your caching layer to skip caching for that response. In Varnish: The vcl_fetch block shown above checks for this header and sets beresp.ttl = 0s + return(hit_for_pass), ensuring the response is never stored in cache. In Nginx proxy cache: You can use this header with proxy_no_cache to achieve the same effect. See the Nginx integration section in the plugin documentation. WooCommerce pages (Cart, Checkout, My Account) can be automatically excluded without manual pattern configuration by enabling the "Auto-Exclude WooCommerce Pages" option in the WooCommerce tab.

Yes. The plugin fully supports WordPress Multisite with a dual-layer configuration:

• Network-level settings — Varnish IP, port, socket timeout, Cloudflare CDN integration, and third-party plugin integrations are configured once in Network Admin → Settings → MSCache Network and shared across all sites in the network.
• Per-site settings — Each site in the network has its own independent configuration for auto-purge options, exclusion patterns, WooCommerce integration, permissions, and debug mode.
• Dynamic host header — The plugin automatically detects and uses the correct domain name for each site when sending PURGE requests. Sites with custom domains (domain mapping) are supported.
• Network admin dashboard — Shows all sites in the network with their host headers and plugin status (enabled/disabled) at a glance.
• WP-CLI — The wp mscache purge-network command purges the cache for all sites in the network in a single operation, iterating through each site with the correct host header.

Yes. The plugin only opens outbound TCP connections to the configured Varnish IP (default: 127.0.0.1, localhost). It does not require any special PHP extensions beyond the standard fsockopen function available in all PHP installations. It is compatible with PHP 7.0 through PHP 8.x without deprecation warnings.

The WordPress HTTP API (wp_remote_request) sends the request and waits for the full HTTP response cycle before returning control to WordPress. This adds latency to every post save. Raw sockets with fsockopen allow the plugin to:

1. Open a TCP connection to Varnish
2. Write the PURGE request
3. Close the connection immediately — without reading the response

The plugin integrates with:

• Cloudflare CDN — Synchronized cache purge via Cloudflare API v4 (per-URL or purge-everything)
• WP Rocket — Bidirectional sync (MSCache → WP Rocket and WP Rocket → MSCache)
• FlyingPress — Bidirectional sync
• W3 Total Cache — Sync purge (MSCache → W3TC)
• Autoptimize — CSS/JS cache clear on full Varnish purge
• Redis / Memcached Object Cache — Optional flush on full purge
• WooCommerce — Dedicated integration with stock, sales, reviews, coupons, attributes, orders, and auto-exclusion of dynamic pages

Many websites use Cloudflare as a CDN and security layer in front of their origin server. When Varnish is purged, the content at the origin is fresh — but Cloudflare edge nodes around the world may still serve stale cached copies to visitors for hours or days. The plugin solves this by optionally sending purge requests to the Cloudflare API v4 every time Varnish is purged. Configuration requires a Cloudflare API Token (with "Zone.Cache Purge" permission) and the Zone ID of your domain, both available from the Cloudflare dashboard. Three purge modes are available:

• Per-URL — Each individual URL purged from Varnish is also purged from Cloudflare. Precise but generates more API calls. Cloudflare free plan allows 1,000 purge API calls per day.
• Purge Everything — Any Varnish purge event triggers a full Cloudflare cache purge. Simple but clears the entire CDN cache including static assets (CSS, JS, images).
• Per-URL + full purge fallback (recommended) — Individual page purges are sent per-URL to Cloudflare. Full Varnish purge events trigger a Cloudflare "purge everything". This mode balances per-URL precision with simplicity.

WP Rocket is one of the most popular WordPress performance plugins, providing page caching, file optimization, and lazy loading. When both MSCache and WP Rocket are active, two separate caching layers exist: Varnish (server-level) and WP Rocket (application-level). If only one is purged, visitors may see inconsistent content. The integration provides bidirectional synchronization:

• MSCache → WP Rocket — When MSCache purges a URL from Varnish, it also calls rocket_clean_post() to clear that page from WP Rocket's local page cache. On a full Varnish purge, rocket_clean_domain() clears the entire WP Rocket cache.
• WP Rocket → MSCache — When a user clicks "Clear Cache" in WP Rocket (or WP Rocket clears cache automatically), MSCache listens to the after_rocket_clean_domain, after_rocket_clean_post, and after_rocket_clean_home hooks and sends corresponding PURGE requests to Varnish.

FlyingPress is a lightweight WordPress performance plugin focused on page caching and CDN. The integration works similarly to WP Rocket:

• MSCache → FlyingPress — Calls FlyingPress\Purge::purge_url() for single pages and FlyingPress\Purge::purge_everything() for full cache purge.
• FlyingPress → MSCache — Listens to the flying_press_purge_everything action. When FlyingPress clears its cache, MSCache also sends a full PURGE to Varnish.

W3 Total Cache (W3TC) is a comprehensive performance plugin with page cache, database cache, object cache, and CDN support. The integration is one-directional (MSCache → W3TC):

• When MSCache purges a single URL, it calls w3tc_flush_post() to clear that page from all W3TC cache layers.
• When MSCache performs a full purge, it calls w3tc_flush_all() to clear the entire W3TC cache.

Autoptimize aggregates and minifies CSS and JavaScript files to reduce HTTP requests and file sizes. After a theme or plugin update, the optimized asset bundles may reference outdated code. The integration is one-directional and limited to full purge only:

• When MSCache performs a full Varnish purge (e.g., after a plugin/theme update), it also calls autoptimizeCache::clearall() to regenerate all optimized CSS/JS bundles.
• Single page purges do not trigger Autoptimize clear, because regenerating all optimized assets for a single page change would be disproportionately expensive.

WordPress object cache (Redis, Memcached, APCu) stores transients, database query results, and rendered fragments in memory. When Varnish is fully purged (e.g., after a major site update), the object cache may still contain stale data that causes WordPress to render pages with outdated content — even though Varnish fetches fresh HTML from the backend. The integration is one-directional and limited to full purge only:

• When MSCache performs a full Varnish purge, it optionally calls wp_cache_flush() to clear the entire object cache.
• Single page purges do not trigger an object cache flush, because flushing the entire object cache for a single page change would degrade performance.

WooCommerce introduces unique caching challenges: product prices change with sales and coupons, stock quantities change with every order, reviews affect displayed ratings, and pages like Cart, Checkout, and My Account contain user-specific dynamic content that must never be cached. The plugin provides a dedicated WooCommerce tab with granular control over each integration point:

• Product stock changes — When a product's stock is updated (purchase, restock, manual edit), the product page, shop page, and all product category pages are purged. This prevents the common issue where a product shows "In Stock" in the cached page while it is actually sold out.
• Scheduled sales — WooCommerce uses a cron job to activate and deactivate scheduled sale prices. The plugin hooks into this cron event and purges all products currently on sale plus the shop page, ensuring that sale prices and "On Sale" badges appear and disappear instantly.
• Product reviews — When a product review is posted, approved, unapproved, or deleted, the product page and shop page are purged to reflect the updated star rating and review count.
• Coupons — When a coupon is created or modified, the shop page and home page are purged. This is relevant if your shop displays coupon-dependent promotions or pricing.
• Product attributes — When product attributes (Color, Size, Material, etc.) are renamed, added, or deleted, the shop page is purged to ensure filter/navigation labels are correct.
• Order status changes — When an order transitions to processing, completed, cancelled, or refunded, the plugin purges the product page, shop page, and product category pages for every product in that order. For example, an order with 6 products triggers purge of all 6 product pages plus their categories and the shop page, in a single deduplicated operation.
• Auto-exclusion of dynamic pages — Cart, Checkout, and My Account pages are automatically detected using WooCommerce's own wc_get_page_id() function and marked with the ms-cache: excluded header. This works regardless of custom page slugs or permalink structures, without requiring manual exclusion pattern configuration.