Why Varnish Still Matters for WordPress

Varnish Cache sits in front of your web server and intercepts HTTP requests before they reach PHP. For WordPress sites handling thousands of concurrent visitors, this single architectural decision can reduce backend load by 95% or more. A page that takes 400ms to generate through WordPress can be served from Varnish in under 5ms.

But running Varnish effectively requires more than installing it and pointing traffic at it. The Varnish Configuration Language (VCL) gives you precise control over what gets cached, how long it stays cached, and how stale content gets invalidated. A poorly written VCL will either cache too aggressively (serving logged-in users someone else’s dashboard) or too conservatively (passing everything through to the backend and providing zero benefit).

This article walks through a complete production VCL configuration for WordPress running Varnish 7.x. We will cover the VCL state machine, cookie handling, grace mode, Edge Side Includes, purge architecture, WordPress integration hooks, URL normalization, and backend health checks. Every code block is annotated and tested against real WordPress traffic patterns.

Understanding the VCL State Machine

VCL operates as a finite state machine. Each HTTP request passes through a series of subroutines, and the return action from each subroutine determines which subroutine runs next. Understanding this flow is the foundation for everything else.

The Request Flow: vcl_recv Through vcl_deliver

When a client sends a request, Varnish processes it through these subroutines in order:

1. vcl_recv — Receives the client request. You decide here whether to look up the request in cache (hash), pass it directly to the backend (pass), pipe it as a raw TCP connection (pipe), or synthesize a response (synth). This is where most of your logic lives.
2. vcl_hash — Builds the hash key used to look up the cached object. By default, Varnish hashes on the URL and the Host header. You can add additional factors (like a cookie value) to create per-user cache variants.
3. vcl_hit — Runs when the hash lookup finds a cached object. You typically return deliver to send the cached object to the client.
4. vcl_miss — Runs when no cached object matches the hash. Varnish will fetch from the backend.
5. vcl_backend_response — Processes the response from the backend before storing it in cache. You set TTLs, grace periods, and decide whether the response should be cached at all.
6. vcl_deliver — Final processing before sending the response to the client. You can add or remove headers, set debugging information, and clean up internal headers.

Here is the skeleton structure showing this flow:

vcl 4.1;

import std;

backend default {
    .host = "127.0.0.1";
    .port = "8080";
}

sub vcl_recv {
    # Decide: hash, pass, pipe, or synth
}

sub vcl_hash {
    # Build cache lookup key
}

sub vcl_hit {
    # Object found in cache
    return (deliver);
}

sub vcl_miss {
    # Object not in cache, fetch from backend
    return (fetch);
}

sub vcl_backend_response {
    # Process backend response, set TTLs
}

sub vcl_deliver {
    # Final response to client
}

Return Actions and Their Effects

Each subroutine has a limited set of valid return actions. Using the wrong one causes a VCL compilation error.

In vcl_recv, the most common return actions are:

• return (hash) — Proceed to cache lookup. This is the default for GET and HEAD requests.
• return (pass) — Skip cache lookup entirely. The request goes straight to the backend, and the response is not stored in cache.
• return (pipe) — Varnish becomes a blind TCP proxy. Use this for WebSocket connections or other protocols that cannot be cached.
• return (synth(status, reason)) — Generate a synthetic response without hitting the backend. Useful for redirects and error pages.
• return (purge) — Remove the cached object matching the current URL. Only use after verifying the client is authorized to purge.

In vcl_backend_response, the key return actions are:

• return (deliver) — Store the object in cache and deliver it.
• return (abandon) — Discard the backend response and retry or error out.
• return (retry) — Retry the backend fetch. Useful for transient errors.

The distinction between pass and pipe trips up many people. With pass, Varnish still processes the request as HTTP and can inspect headers. With pipe, Varnish hands off the raw TCP connection. Use pipe only when the protocol is not HTTP (like WebSockets after the upgrade handshake).

Cookie Handling for WordPress

Cookies are the single biggest reason Varnish fails to cache WordPress pages. By default, if a request carries any Cookie header, Varnish passes it to the backend without caching. WordPress sets several cookies, and third-party analytics tools add more. You need a disciplined cookie strategy.

Stripping Analytics and Tracking Cookies

Google Analytics, Facebook Pixel, HubSpot, and dozens of other tools set cookies that are only read by client-side JavaScript. These cookies have no effect on the server-side response, but their presence in the Cookie header prevents Varnish from caching the page.

The solution: strip these cookies from the request before the cache lookup.

sub vcl_recv {
    # Remove Google Analytics cookies
    set req.http.Cookie = regsuball(req.http.Cookie, "_ga=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "_gid=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "_gat=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "_ga_[A-Z0-9]+=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "__utma=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "__utmb=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "__utmc=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "__utmz=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "__utmt=[^;]+(; )?", "");

    # Remove Facebook tracking cookies
    set req.http.Cookie = regsuball(req.http.Cookie, "_fbp=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "_fbc=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "fr=[^;]+(; )?", "");

    # Remove HubSpot cookies
    set req.http.Cookie = regsuball(req.http.Cookie, "__hs[a-z_]+=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "hubspotutk=[^;]+(; )?", "");

    # Remove Cloudflare cookies
    set req.http.Cookie = regsuball(req.http.Cookie, "__cf_bm=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "__cfduid=[^;]+(; )?", "");

    # Remove common consent/GDPR cookies
    set req.http.Cookie = regsuball(req.http.Cookie, "cookieconsent_status=[^;]+(; )?", "");
    set req.http.Cookie = regsuball(req.http.Cookie, "cookie_notice_accepted=[^;]+(; )?", "");

    # Clean up any trailing semicolons and whitespace
    set req.http.Cookie = regsuball(req.http.Cookie, ";\\s*$", "");

    # If the cookie header is now empty, remove it entirely
    if (req.http.Cookie ~ "^\\s*$") {
        unset req.http.Cookie;
    }
}

The regsuball function performs a global regex substitution. Each line targets a specific cookie name pattern and replaces it with an empty string. After stripping all the non-essential cookies, we clean up trailing semicolons and remove the Cookie header entirely if nothing remains.

WordPress Cookie Normalization

WordPress sets several cookies that indicate a logged-in user or a commenter. These cookies must be preserved because they affect the server-side response:

• wordpress_logged_in_* — Indicates an authenticated session.
• wordpress_sec_* — Secure authentication cookie.
• wp-settings-* — User preferences for the admin panel.
• wp-postpass_* — Password-protected post access.
• comment_author_* — Commenter information for pre-filling forms.
• woocommerce_* — WooCommerce session and cart data (if applicable).

The strategy: if any of these cookies are present, pass the request to the backend. Otherwise, proceed to cache lookup.

sub vcl_recv {
    # (cookie stripping code from above runs first)

    # Pass requests from logged-in WordPress users
    if (req.http.Cookie ~ "wordpress_logged_in_"
        || req.http.Cookie ~ "wordpress_sec_"
        || req.http.Cookie ~ "wp-postpass_"
        || req.http.Cookie ~ "comment_author_") {
        return (pass);
    }

    # Pass WooCommerce sessions (items in cart)
    if (req.http.Cookie ~ "woocommerce_"
        || req.http.Cookie ~ "wp_woocommerce_session_") {
        return (pass);
    }
}

This ordering matters. Strip the analytics cookies first, then check for WordPress-specific cookies. If you check before stripping, a user with only a _ga cookie would still have a non-empty Cookie header and might get passed through unnecessarily (depending on your default behavior).

Grace Mode: Serving Stale Content During Backend Outages

Grace mode is one of Varnish’s most powerful features. When a cached object’s TTL expires and the backend is slow or unreachable, Varnish can serve the stale cached version while fetching a fresh copy in the background. This keeps your site responsive even during backend problems.

How Grace Works

Every cached object has two timers: its TTL (time to live) and its grace period. The TTL defines how long the object is considered fresh. The grace period defines how long past the TTL the object can still be served as a stale fallback.

Consider an object with a 2-minute TTL and a 24-hour grace period. For the first 2 minutes, every request gets the cached version directly. After 2 minutes, the next request triggers an asynchronous backend fetch while still receiving the stale cached version. If the backend is down, Varnish continues serving the stale version for up to 24 hours.

Configuring Grace in VCL

Grace requires configuration in two places: vcl_recv and vcl_backend_response.

sub vcl_recv {
    # Set the grace period for request handling.
    # This tells Varnish how old a stale object we are willing to accept.
    # If the backend is healthy, we accept a short grace (10 seconds).
    # If the backend is sick, we accept a long grace (24 hours).
    if (std.healthy(req.backend_hint)) {
        set req.grace = 10s;
    } else {
        set req.grace = 24h;
    }
}

sub vcl_backend_response {
    # Set the grace period on cached objects.
    # This tells Varnish how long to keep objects past their TTL.
    set beresp.grace = 24h;

    # Set a keep period so objects are available for conditional requests.
    set beresp.keep = 8s;
}

The req.grace value in vcl_recv tells Varnish the maximum staleness you will accept for this specific request. The beresp.grace value in vcl_backend_response tells Varnish how long to retain the object past its TTL.

When the backend is healthy, we set req.grace to 10 seconds. This means Varnish will serve a stale object for up to 10 seconds while asynchronously fetching a fresh copy. Users get fast responses, and the backend gets a brief overlap window.

When the backend is sick (as determined by health probes, which we will configure later), we accept up to 24 hours of staleness. This is your safety net. Your WordPress site could be completely down, but visitors still see cached pages.

Grace and the Thundering Herd

Grace mode also solves the thundering herd problem. Without grace, when a popular cached object expires, every incoming request for that URL sees a cache miss and sends a fetch to the backend simultaneously. A hundred concurrent visitors could trigger a hundred identical PHP processes.

With grace, only the first request after expiration triggers a backend fetch. All subsequent requests during that fetch receive the stale cached version. The backend processes one request, not a hundred.

This behavior is automatic when grace is configured. You do not need to add any extra logic for request coalescing. Varnish handles it internally through a mechanism called “request collapse,” where waiting requests are queued behind the first fetch.

Edge Side Includes for Partially Dynamic Pages

Most WordPress pages are 90% static and 10% dynamic. The header might show a login/logout link, the sidebar might display a user-specific widget, or a comment count might need to be current. ESI lets you cache the static portions and fetch only the dynamic fragments from the backend.

How ESI Works in Varnish

ESI uses special XML tags embedded in the HTML response. When Varnish encounters an <esi:include> tag, it makes a separate subrequest to fetch that fragment and assembles the final page from the cached parent and the fetched fragments.

First, enable ESI processing in vcl_backend_response:

sub vcl_backend_response {
    # Enable ESI processing for HTML responses
    if (beresp.http.Content-Type ~ "text/html") {
        set beresp.do_esi = true;
    }
}

In your WordPress theme, replace the dynamic fragment with an ESI tag:

<div class="user-greeting">
    <esi:include src="/esi/user-greeting/" />
</div>

Then create a lightweight WordPress endpoint that returns only the fragment:

// In your theme's functions.php or a custom plugin
add_action('init', function() {
    add_rewrite_rule(
        '^esi/user-greeting/?$',
        'index.php?esi_fragment=user-greeting',
        'top'
    );
});

add_filter('query_vars', function($vars) {
    $vars[] = 'esi_fragment';
    return $vars;
});

add_action('template_redirect', function() {
    $fragment = get_query_var('esi_fragment');
    if ($fragment === 'user-greeting') {
        if (is_user_logged_in()) {
            $user = wp_get_current_user();
            echo '<span>Welcome, ' . esc_html($user->display_name) . '</span>';
        } else {
            echo '<a href="/login/">Log in</a>';
        }
        exit;
    }
});

ESI Caching Strategies

Each ESI fragment is cached independently with its own TTL. The parent page might have a 10-minute TTL, while the user greeting fragment is passed through without caching (because it varies per user), and a “trending posts” widget fragment might be cached for 5 minutes.

In your VCL, handle ESI fragments differently based on their URL:

sub vcl_recv {
    # ESI fragments that vary per user should not be cached
    if (req.url ~ "^/esi/user-greeting/") {
        return (pass);
    }

    # ESI fragments with short TTLs
    if (req.url ~ "^/esi/trending-posts/") {
        return (hash);
    }
}

sub vcl_backend_response {
    # Set short TTL for trending posts fragment
    if (bereq.url ~ "^/esi/trending-posts/") {
        set beresp.ttl = 5m;
        set beresp.grace = 1h;
    }
}

ESI adds complexity and additional subrequests. Use it selectively. If a page has only one small dynamic section, ESI is worth it. If the page has twenty dynamic fragments, the overhead of twenty subrequests may negate the caching benefit. Profile both approaches with realistic load before committing to ESI.

Purge Architecture

Caching is only useful if you can invalidate stale content reliably. Varnish provides three purge mechanisms, each with different trade-offs: PURGE method, ban expressions, and xkey-based surrogate keys.

PURGE Method: Targeted URL Invalidation

The PURGE method removes a single cached object by its exact URL and host. It is the simplest and fastest purge mechanism.

acl purge_acl {
    "localhost";
    "127.0.0.1";
    "::1";
    # Add your application server IPs
    "10.0.0.0"/8;
    "172.16.0.0"/12;
    "192.168.0.0"/16;
}

sub vcl_recv {
    if (req.method == "PURGE") {
        if (!client.ip ~ purge_acl) {
            return (synth(405, "Purge not allowed from this IP."));
        }
        return (purge);
    }
}

To purge a URL from your application server:

curl -X PURGE -H "Host: example.com" http://127.0.0.1:6081/my-blog-post/

The limitation of PURGE is that it only removes a single URL. When you publish a WordPress post, you need to purge the post URL, the homepage, the category archive, the tag archive, the author archive, the RSS feed, and possibly more. That can mean 10+ PURGE requests for a single content change.

Ban Expressions: Pattern-Based Invalidation

Ban expressions let you invalidate objects matching a pattern. Instead of listing every URL, you can ban all objects whose URL matches a regex or whose backend response contained a specific header value.

sub vcl_recv {
    if (req.method == "BAN") {
        if (!client.ip ~ purge_acl) {
            return (synth(405, "Ban not allowed from this IP."));
        }
        # Ban by URL pattern
        if (req.http.X-Ban-Url) {
            ban("obj.http.x-url ~ " + req.http.X-Ban-Url
                + " && obj.http.x-host ~ " + req.http.X-Ban-Host);
            return (synth(200, "Ban added."));
        }
        # Ban everything for a host
        if (req.http.X-Ban-Host) {
            ban("obj.http.x-host ~ " + req.http.X-Ban-Host);
            return (synth(200, "Ban added."));
        }
        return (synth(400, "No ban expression provided."));
    }
}

sub vcl_backend_response {
    # Tag cached objects with their URL and host for ban matching
    set beresp.http.x-url = bereq.url;
    set beresp.http.x-host = bereq.http.host;
}

sub vcl_deliver {
    # Remove internal headers before sending to client
    unset resp.http.x-url;
    unset resp.http.x-host;
}

Using a ban to purge all category archive pages:

curl -X BAN \
  -H "X-Ban-Url: /category/.*" \
  -H "X-Ban-Host: example.com" \
  http://127.0.0.1:6081/

Bans are evaluated lazily. When you add a ban, Varnish does not immediately scan the cache. Instead, each subsequent cache lookup checks the object against all pending ban expressions. If the object matches a ban, it is treated as a miss. The ban lurker thread periodically walks the cache and tests objects against bans to keep the ban list short.

The performance concern with bans: if you accumulate hundreds of ban expressions, every cache lookup must test against all of them. This can slow down request processing. Keep ban expressions specific and let the ban lurker thread clean them up.

xkey Surrogate Keys: The Best of Both Worlds

The xkey VMOD provides surrogate key-based purging, similar to Fastly’s surrogate keys or Cloudflare’s cache tags. You tag each cached object with one or more keys, then purge by key. This is the most efficient and scalable purge mechanism.

vcl 4.1;

import xkey;

sub vcl_backend_response {
    # The backend sends an xkey header with space-separated tags.
    # Example: "post-123 category-7 front-page feed"
    # xkey automatically parses this header.
}

sub vcl_recv {
    if (req.method == "PURGE") {
        if (!client.ip ~ purge_acl) {
            return (synth(405, "Purge not allowed."));
        }

        # Soft purge: mark objects as stale but keep them for grace
        if (req.http.X-Xkey-Purge) {
            set req.http.n-gone = xkey.softpurge(req.http.X-Xkey-Purge);
            return (synth(200, "Soft-purged " + req.http.n-gone + " objects."));
        }

        # Hard purge: remove objects immediately
        if (req.http.X-Xkey-Hard-Purge) {
            set req.http.n-gone = xkey.purge(req.http.X-Xkey-Hard-Purge);
            return (synth(200, "Purged " + req.http.n-gone + " objects."));
        }

        return (purge);
    }
}

On the WordPress side, add surrogate key headers to responses:

// In your purge plugin or theme functions.php
add_action('send_headers', function() {
    if (is_admin() || is_user_logged_in()) {
        return;
    }

    $keys = [];

    if (is_singular()) {
        $post = get_queried_object();
        $keys[] = 'post-' . $post->ID;
        $keys[] = 'post-type-' . $post->post_type;

        // Add category keys
        $categories = get_the_category($post->ID);
        foreach ($categories as $cat) {
            $keys[] = 'category-' . $cat->term_id;
        }

        // Add tag keys
        $tags = get_the_tags($post->ID);
        if ($tags) {
            foreach ($tags as $tag) {
                $keys[] = 'tag-' . $tag->term_id;
            }
        }

        // Add author key
        $keys[] = 'author-' . $post->post_author;
    }

    if (is_front_page() || is_home()) {
        $keys[] = 'front-page';
    }

    if (is_category()) {
        $term = get_queried_object();
        $keys[] = 'category-' . $term->term_id;
        $keys[] = 'category-archive';
    }

    if (is_tag()) {
        $term = get_queried_object();
        $keys[] = 'tag-' . $term->term_id;
        $keys[] = 'tag-archive';
    }

    if (is_author()) {
        $author = get_queried_object();
        $keys[] = 'author-' . $author->ID;
        $keys[] = 'author-archive';
    }

    if (is_feed()) {
        $keys[] = 'feed';
    }

    if (!empty($keys)) {
        header('xkey: ' . implode(' ', $keys));
    }
});

Now purging all content related to category 7:

curl -X PURGE \
  -H "X-Xkey-Purge: category-7" \
  http://127.0.0.1:6081/

This single request purges every cached object tagged with category-7, whether it is the category archive page, individual posts in that category, or the homepage that features posts from that category. No need to enumerate URLs.

The soft purge variant (xkey.softpurge) marks objects as expired but keeps them available for grace. This is the recommended approach for content updates: the next request triggers a background fetch, but users still get the (slightly stale) cached version instantly.

WordPress Purge Integration

The best VCL configuration is useless if WordPress does not trigger purges at the right time. You need PHP-side hooks that fire purge requests whenever content changes.

Purging on Post Publish and Update

WordPress fires the transition_post_status hook whenever a post’s status changes. This covers publishing, updating, unpublishing, and deleting posts.

class Varnish_Purge_Manager {

    private $varnish_host = '127.0.0.1';
    private $varnish_port = 6081;
    private $queued_purges = [];

    public function __construct() {
        // Post changes
        add_action('transition_post_status', [$this, 'on_post_status_change'], 10, 3);
        add_action('edit_post', [$this, 'on_post_edit'], 10, 2);

        // Term changes
        add_action('edited_term', [$this, 'on_term_edit'], 10, 3);
        add_action('delete_term', [$this, 'on_term_delete'], 10, 4);

        // Comment changes
        add_action('wp_set_comment_status', [$this, 'on_comment_status_change'], 10, 2);
        add_action('comment_post', [$this, 'on_new_comment'], 10, 3);

        // Option changes (menus, widgets, theme settings)
        add_action('updated_option', [$this, 'on_option_update'], 10, 3);

        // Fire all queued purges at shutdown to avoid duplicate requests
        add_action('shutdown', [$this, 'execute_purges']);
    }

    public function on_post_status_change($new_status, $old_status, $post) {
        // Only purge for public post types
        if (!in_array($new_status, ['publish', 'trash']) 
            && !in_array($old_status, ['publish'])) {
            return;
        }

        $post_type = get_post_type($post);
        if (!is_post_type_viewable($post_type)) {
            return;
        }

        // Queue surrogate key purges
        $this->queue_xkey_purge('post-' . $post->ID);
        $this->queue_xkey_purge('post-type-' . $post_type);
        $this->queue_xkey_purge('front-page');
        $this->queue_xkey_purge('feed');

        // Purge related taxonomy archives
        $taxonomies = get_object_taxonomies($post_type);
        foreach ($taxonomies as $taxonomy) {
            $terms = get_the_terms($post->ID, $taxonomy);
            if ($terms && !is_wp_error($terms)) {
                foreach ($terms as $term) {
                    $this->queue_xkey_purge($taxonomy . '-' . $term->term_id);
                }
            }
        }

        // Purge author archive
        $this->queue_xkey_purge('author-' . $post->post_author);
    }

    public function on_post_edit($post_id, $post) {
        if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
            return;
        }
        if ($post->post_status === 'publish') {
            $this->queue_xkey_purge('post-' . $post_id);
        }
    }

    public function on_term_edit($term_id, $tt_id, $taxonomy) {
        $this->queue_xkey_purge($taxonomy . '-' . $term_id);
        $this->queue_xkey_purge($taxonomy . '-archive');
        $this->queue_xkey_purge('front-page');
    }

    public function on_term_delete($term_id, $tt_id, $taxonomy, $deleted_term) {
        $this->queue_xkey_purge($taxonomy . '-' . $term_id);
        $this->queue_xkey_purge($taxonomy . '-archive');
        $this->queue_xkey_purge('front-page');
    }

    public function on_comment_status_change($comment_id, $status) {
        $comment = get_comment($comment_id);
        if ($comment) {
            $this->queue_xkey_purge('post-' . $comment->comment_post_ID);
        }
    }

    public function on_new_comment($comment_id, $approved, $commentdata) {
        if ($approved === 1) {
            $this->queue_xkey_purge('post-' . $commentdata['comment_post_ID']);
        }
    }

    public function on_option_update($option, $old_value, $new_value) {
        // These options affect site-wide display
        $global_options = [
            'sidebars_widgets',
            'widget_text',
            'widget_categories',
            'widget_recent-posts',
            'nav_menu_options',
            'theme_mods_' . get_stylesheet(),
            'blogname',
            'blogdescription',
        ];

        if (in_array($option, $global_options)) {
            $this->queue_xkey_purge('front-page');
            // For truly global changes, consider a full purge
            if (in_array($option, ['blogname', 'blogdescription'])) {
                $this->queue_ban_all();
            }
        }
    }

    private function queue_xkey_purge($key) {
        $this->queued_purges['xkey'][$key] = true;
    }

    private function queue_ban_all() {
        $this->queued_purges['ban_all'] = true;
    }

    public function execute_purges() {
        if (empty($this->queued_purges)) {
            return;
        }

        // If a full ban is queued, just do that
        if (!empty($this->queued_purges['ban_all'])) {
            $this->send_ban('.*', $_SERVER['HTTP_HOST'] ?? '');
            return;
        }

        // Batch xkey purges into a single request
        if (!empty($this->queued_purges['xkey'])) {
            $keys = array_keys($this->queued_purges['xkey']);
            // xkey supports space-separated keys in a single purge
            $key_string = implode(' ', $keys);
            $this->send_xkey_purge($key_string);
        }
    }

    private function send_xkey_purge($keys) {
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => "http://{$this->varnish_host}:{$this->varnish_port}/",
            CURLOPT_CUSTOMREQUEST => 'PURGE',
            CURLOPT_HTTPHEADER => [
                'X-Xkey-Purge: ' . $keys,
                'Host: ' . ($_SERVER['HTTP_HOST'] ?? ''),
            ],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
        ]);
        $response = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($status !== 200) {
            error_log("Varnish xkey purge failed: HTTP $status for keys: $keys");
        }
    }

    private function send_ban($url_pattern, $host) {
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => "http://{$this->varnish_host}:{$this->varnish_port}/",
            CURLOPT_CUSTOMREQUEST => 'BAN',
            CURLOPT_HTTPHEADER => [
                'X-Ban-Url: ' . $url_pattern,
                'X-Ban-Host: ' . $host,
            ],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
        ]);
        curl_exec($ch);
        curl_close($ch);
    }
}

// Initialize the purge manager
new Varnish_Purge_Manager();

Batching Purge Requests

Notice the execute_purges method fires on the shutdown hook. This is intentional. When WordPress saves a post, it fires multiple hooks in sequence: transition_post_status, save_post, edit_post, and others. If we sent a purge request inside each hook callback, we would send multiple redundant purge requests for the same content change.

By queuing purge keys into an array and deduplicating them (using array keys), we consolidate everything into a single HTTP request at the end of the PHP process. With xkey, we can purge dozens of tags in one request by space-separating them.

This batching approach reduces network overhead and prevents Varnish from doing redundant work. It also prevents a subtle race condition where a purge fires before WordPress has finished writing all the associated data (like post meta, term relationships, and thumbnail assignments).

Purging on Menu and Widget Updates

WordPress menus and widgets present a special purge challenge. When someone reorders a menu, every page that displays that menu has stale content. There is no direct relationship between a menu and the pages that render it.

The updated_option hook catches these changes because WordPress stores menu and widget configurations as serialized options. When sidebars_widgets or nav_menu_options changes, we purge the front page. For critical global changes like the site title or tagline, we issue a full ban to invalidate everything.

You could be more surgical here by tagging pages with their menu locations (e.g., menu-primary, menu-footer) and purging only those tags. But menus and widgets change infrequently enough that a broader purge is acceptable.

URL Normalization

URL normalization ensures that requests for the same content share the same cache entry. Without normalization, /page/?utm_source=twitter&utm_medium=social and /page/?utm_medium=social&utm_source=twitter are treated as separate cache entries, even though they produce identical responses.

Stripping Marketing Parameters

UTM parameters, Facebook click IDs, and other tracking parameters do not affect the server-side response. They are read by client-side JavaScript analytics. Strip them in vcl_recv:

import std;

sub vcl_recv {
    # Strip common marketing and tracking query parameters
    if (req.url ~ "(\?|&)(utm_source|utm_medium|utm_campaign|utm_content|utm_term|gclid|gclsrc|fbclid|mc_cid|mc_eid|msclkid|_ga|_gl|_hsenc|_hsmi|hsa_cam|hsa_grp|hsa_mt|hsa_src|hsa_ad|hsa_acc|hsa_net|hsa_ver|hsa_kw)=") {

        # Use a regex to strip these parameters
        set req.url = regsuball(req.url, "([\?&])(utm_source|utm_medium|utm_campaign|utm_content|utm_term|gclid|gclsrc|fbclid|mc_cid|mc_eid|msclkid|_ga|_gl|_hsenc|_hsmi|hsa_cam|hsa_grp|hsa_mt|hsa_src|hsa_ad|hsa_acc|hsa_net|hsa_ver|hsa_kw)=[^&]*", "\1");

        # Clean up resulting URL artifacts
        # Remove trailing ? or &
        set req.url = regsuball(req.url, "(\?|&)+$", "");
        # Replace ?& with ?
        set req.url = regsuball(req.url, "\?&", "?");
        # Replace && with &
        set req.url = regsuball(req.url, "&&+", "&");
    }
}

Query String Sorting

Varnish 7.x includes the std.querysort() function that alphabetically sorts query string parameters. This ensures that ?b=2&a=1 and ?a=1&b=2 hit the same cache entry:

sub vcl_recv {
    # Sort query string parameters for consistent cache keys
    set req.url = std.querysort(req.url);
}

Call std.querysort() after stripping marketing parameters but before the cache lookup. The order of operations in vcl_recv should be: strip marketing parameters, sort remaining parameters, strip cookies, check for WordPress cookies, then proceed to hash or pass.

Normalizing Common URL Variations

Several other URL variations can fragment your cache:

sub vcl_recv {
    # Remove trailing slashes inconsistency (WordPress usually has trailing slashes)
    # Uncomment only if your WordPress uses no-trailing-slash permalink structure
    # set req.url = regsub(req.url, "([^/])/$", "\1");

    # Remove port from Host header (normalize Host)
    set req.http.Host = regsub(req.http.Host, ":[0-9]+$", "");

    # Lowercase the Host header for consistent hashing
    set req.http.Host = std.tolower(req.http.Host);

    # Remove anchors (browsers should not send these, but some tools do)
    set req.url = regsub(req.url, "#.*$", "");

    # Normalize double slashes to single (except after protocol)
    set req.url = regsuball(req.url, "(?

backend default {
    .host = "127.0.0.1";
    .port = "8080";
    .probe = {
        .request =
            "GET /wp-admin/admin-ajax.php?action=health_check HTTP/1.1"
            "Host: example.com"
            "Connection: close";
        .interval = 5s;      # Check every 5 seconds
        .timeout = 2s;       # Consider it failed after 2 seconds
        .window = 5;         # Keep track of the last 5 checks
        .threshold = 3;      # Require 3 out of 5 to be healthy
    };
}

add_action('wp_ajax_nopriv_health_check', function() {
    // Quick database check
    global $wpdb;
    $result = $wpdb->get_var("SELECT 1");

    if ($result == 1) {
        wp_send_json(['status' => 'ok'], 200);
    } else {
        wp_send_json(['status' => 'db_error'], 503);
    }
});

vcl 4.1;

import directors;

backend web1 {
    .host = "10.0.1.10";
    .port = "80";
    .probe = {
        .request =
            "GET /wp-admin/admin-ajax.php?action=health_check HTTP/1.1"
            "Host: example.com"
            "Connection: close";
        .interval = 5s;
        .timeout = 2s;
        .window = 5;
        .threshold = 3;
    };
}

backend web2 {
    .host = "10.0.1.11";
    .port = "80";
    .probe = {
        .request =
            "GET /wp-admin/admin-ajax.php?action=health_check HTTP/1.1"
            "Host: example.com"
            "Connection: close";
        .interval = 5s;
        .timeout = 2s;
        .window = 5;
        .threshold = 3;
    };
}

sub vcl_init {
    new cluster = directors.round_robin();
    cluster.add_backend(web1);
    cluster.add_backend(web2);
}

sub vcl_recv {
    set req.backend_hint = cluster.backend();
}

vcl 4.1;

import cookie;

sub vcl_recv {
    if (req.http.Cookie) {
        cookie.parse(req.http.Cookie);

        # Keep only WordPress-functional cookies
        cookie.keep("wordpress_logged_in_,wordpress_sec_,wp-postpass_,comment_author_,woocommerce_,wp_woocommerce_session_");

        # Rebuild the cookie header with only the kept cookies
        set req.http.Cookie = cookie.get_string();

        # If no functional cookies remain, remove the header
        if (req.http.Cookie == "") {
            unset req.http.Cookie;
        }
    }
}

#
# WordPress Production VCL for Varnish 7.x
# -------------------------------------------
# Tested with Varnish Cache 7.3 and WordPress 6.2+
# Requires: varnish-modules (for xkey)
#

vcl 4.1;

import std;
import cookie;
import xkey;
import directors;

# -------------------------------------------------------
# Backend definitions with health probes
# -------------------------------------------------------
backend web1 {
    .host = "10.0.1.10";
    .port = "80";
    .first_byte_timeout = 60s;
    .connect_timeout = 5s;
    .between_bytes_timeout = 10s;
    .probe = {
        .request =
            "GET /wp-admin/admin-ajax.php?action=health_check HTTP/1.1"
            "Host: example.com"
            "Connection: close";
        .interval = 5s;
        .timeout = 2s;
        .window = 5;
        .threshold = 3;
    };
}

backend web2 {
    .host = "10.0.1.11";
    .port = "80";
    .first_byte_timeout = 60s;
    .connect_timeout = 5s;
    .between_bytes_timeout = 10s;
    .probe = {
        .request =
            "GET /wp-admin/admin-ajax.php?action=health_check HTTP/1.1"
            "Host: example.com"
            "Connection: close";
        .interval = 5s;
        .timeout = 2s;
        .window = 5;
        .threshold = 3;
    };
}

# -------------------------------------------------------
# ACL: IPs allowed to issue PURGE and BAN requests
# -------------------------------------------------------
acl purge_acl {
    "localhost";
    "127.0.0.1";
    "::1";
    "10.0.1.0"/24;
}

# -------------------------------------------------------
# Initialize the backend director
# -------------------------------------------------------
sub vcl_init {
    new cluster = directors.round_robin();
    cluster.add_backend(web1);
    cluster.add_backend(web2);
}

# -------------------------------------------------------
# vcl_recv: Request processing and cache decision logic
# -------------------------------------------------------
sub vcl_recv {
    # Assign the backend director
    set req.backend_hint = cluster.backend();

    # ------ Purge and Ban handling ------
    if (req.method == "PURGE") {
        if (!client.ip ~ purge_acl) {
            return (synth(405, "Purge not allowed from this IP."));
        }
        # xkey soft purge (preferred for content updates)
        if (req.http.X-Xkey-Purge) {
            set req.http.n-gone = xkey.softpurge(req.http.X-Xkey-Purge);
            return (synth(200, "Soft-purged " + req.http.n-gone + " objects."));
        }
        # xkey hard purge
        if (req.http.X-Xkey-Hard-Purge) {
            set req.http.n-gone = xkey.purge(req.http.X-Xkey-Hard-Purge);
            return (synth(200, "Purged " + req.http.n-gone + " objects."));
        }
        # Standard single-URL purge
        return (purge);
    }

    if (req.method == "BAN") {
        if (!client.ip ~ purge_acl) {
            return (synth(405, "Ban not allowed from this IP."));
        }
        if (req.http.X-Ban-Url) {
            ban("obj.http.x-url ~ " + req.http.X-Ban-Url
                + " && obj.http.x-host ~ " + req.http.X-Ban-Host);
            return (synth(200, "Ban added."));
        }
        return (synth(400, "No ban expression provided."));
    }

    # ------ Pipe WebSocket connections ------
    if (req.http.Upgrade ~ "(?i)websocket") {
        return (pipe);
    }

    # ------ Only cache GET and HEAD ------
    if (req.method != "GET" && req.method != "HEAD") {
        return (pass);
    }

    # ------ WordPress admin and login: never cache ------
    if (req.url ~ "^/wp-(admin|login|cron)" 
        || req.url ~ "^/xmlrpc\.php"
        || req.url ~ "^/wp-json/"
        || req.url ~ "\?wc-api="
        || req.url ~ "preview=true"
        || req.url ~ "admin-ajax\.php") {
        return (pass);
    }

    # ------ URL Normalization ------
    # Strip marketing and tracking query parameters
    set req.url = regsuball(req.url,
        "([\?&])(utm_source|utm_medium|utm_campaign|utm_content|utm_term|gclid|gclsrc|fbclid|mc_cid|mc_eid|msclkid|_ga|_gl|_hsenc|_hsmi)=[^&]*", "\1");
    set req.url = regsuball(req.url, "(\?|&)+$", "");
    set req.url = regsuball(req.url, "\?&", "?");
    set req.url = regsuball(req.url, "&&+", "&");

    # Sort remaining query parameters
    set req.url = std.querysort(req.url);

    # Normalize the Host header
    set req.http.Host = std.tolower(regsub(req.http.Host, ":[0-9]+$", ""));

    # ------ Cookie handling using cookie VMOD ------
    if (req.http.Cookie) {
        cookie.parse(req.http.Cookie);

        # Keep only cookies that WordPress actually reads server-side
        cookie.keep("wordpress_logged_in_,wordpress_sec_,wp-postpass_,comment_author_,woocommerce_,wp_woocommerce_session_");

        set req.http.Cookie = cookie.get_string();

        if (req.http.Cookie == "") {
            unset req.http.Cookie;
        }
    }

    # ------ Pass logged-in users ------
    if (req.http.Cookie ~ "wordpress_logged_in_"
        || req.http.Cookie ~ "wordpress_sec_"
        || req.http.Cookie ~ "wp-postpass_"
        || req.http.Cookie ~ "comment_author_"
        || req.http.Cookie ~ "woocommerce_"
        || req.http.Cookie ~ "wp_woocommerce_session_") {
        return (pass);
    }

    # ------ Grace mode ------
    if (std.healthy(req.backend_hint)) {
        set req.grace = 10s;
    } else {
        set req.grace = 24h;
    }

    # ------ Static files: strip all cookies ------
    if (req.url ~ "\.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot|webp|avif|mp4|webm)(\?.*)?$") {
        unset req.http.Cookie;
    }

    return (hash);
}

# -------------------------------------------------------
# vcl_hash: Build cache key
# -------------------------------------------------------
sub vcl_hash {
    hash_data(req.url);

    if (req.http.Host) {
        hash_data(req.http.Host);
    } else {
        hash_data(server.ip);
    }

    # Vary cache by protocol for HSTS compliance
    if (req.http.X-Forwarded-Proto) {
        hash_data(req.http.X-Forwarded-Proto);
    }

    return (lookup);
}

# -------------------------------------------------------
# vcl_hit: Cache hit handling
# -------------------------------------------------------
sub vcl_hit {
    return (deliver);
}

# -------------------------------------------------------
# vcl_miss: Cache miss handling
# -------------------------------------------------------
sub vcl_miss {
    return (fetch);
}

# -------------------------------------------------------
# vcl_backend_response: Process response from WordPress
# -------------------------------------------------------
sub vcl_backend_response {
    # Tag objects with URL and host for ban expressions
    set beresp.http.x-url = bereq.url;
    set beresp.http.x-host = bereq.http.host;

    # ------ Do not cache WordPress admin or login responses ------
    if (bereq.url ~ "^/wp-(admin|login|cron)"
        || bereq.url ~ "^/xmlrpc\.php"
        || bereq.url ~ "admin-ajax\.php") {
        set beresp.uncacheable = true;
        set beresp.ttl = 120s;
        return (deliver);
    }

    # ------ Do not cache responses with Set-Cookie ------
    # WordPress sends Set-Cookie for logged-in users, comments, etc.
    if (beresp.http.Set-Cookie) {
        set beresp.uncacheable = true;
        set beresp.ttl = 120s;
        return (deliver);
    }

    # ------ Do not cache 5xx errors ------
    if (beresp.status >= 500) {
        set beresp.uncacheable = true;
        set beresp.ttl = 5s;
        return (deliver);
    }

    # ------ Do not cache 404s for long ------
    if (beresp.status == 404) {
        set beresp.ttl = 60s;
        set beresp.grace = 5m;
        return (deliver);
    }

    # ------ Static files: long TTL ------
    if (bereq.url ~ "\.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot|webp|avif|mp4|webm)(\?.*)?$") {
        set beresp.ttl = 7d;
        set beresp.grace = 24h;
        unset beresp.http.Set-Cookie;
        return (deliver);
    }

    # ------ RSS and Atom feeds ------
    if (bereq.url ~ "/feed(/)?") {
        set beresp.ttl = 15m;
        set beresp.grace = 1h;
        return (deliver);
    }

    # ------ HTML pages: default TTL ------
    if (beresp.http.Content-Type ~ "text/html") {
        set beresp.ttl = 10m;
        set beresp.grace = 24h;

        # Enable ESI processing for HTML
        set beresp.do_esi = true;

        return (deliver);
    }

    # ------ Default TTL for everything else ------
    set beresp.ttl = 1h;
    set beresp.grace = 24h;

    return (deliver);
}

# -------------------------------------------------------
# vcl_deliver: Final response to client
# -------------------------------------------------------
sub vcl_deliver {
    # ------ Remove internal headers ------
    unset resp.http.x-url;
    unset resp.http.x-host;
    unset resp.http.X-Varnish;
    unset resp.http.Via;

    # ------ Debug headers (disable in production) ------
    if (req.http.X-Varnish-Debug) {
        if (obj.hits > 0) {
            set resp.http.X-Cache = "HIT";
            set resp.http.X-Cache-Hits = obj.hits;
        } else {
            set resp.http.X-Cache = "MISS";
        }
        set resp.http.X-Cache-TTL = obj.ttl;
        set resp.http.X-Cache-Grace = obj.grace;
    }

    return (deliver);
}

# -------------------------------------------------------
# vcl_synth: Synthetic responses (errors, redirects)
# -------------------------------------------------------
sub vcl_synth {
    # Handle redirects
    if (resp.status == 301 || resp.status == 302) {
        set resp.http.Location = resp.reason;
        set resp.reason = "Moved";
        return (deliver);
    }

    # Error page
    set resp.http.Content-Type = "text/html; charset=utf-8";
    set resp.http.Retry-After = "5";
    synthetic({"



Error "} + resp.status + {"
"} + resp.reason + {"
Please try again in a few moments.

"});
    return (deliver);
}

# -------------------------------------------------------
# vcl_pipe: Handle piped connections (WebSockets)
# -------------------------------------------------------
sub vcl_pipe {
    if (req.http.Upgrade) {
        set bereq.http.Upgrade = req.http.Upgrade;
        set bereq.http.Connection = req.http.Connection;
    }
    return (pipe);
}

# -------------------------------------------------------
# vcl_backend_error: Handle backend fetch failures
# -------------------------------------------------------
sub vcl_backend_error {
    set beresp.http.Content-Type = "text/html; charset=utf-8";
    set beresp.http.Retry-After = "5";
    synthetic({"



Service Temporarily Unavailable
The server is temporarily unable to handle your request.
Please try again shortly.

"});
    return (deliver);
}

# Show all requests to a specific URL
varnishlog -q "ReqURL eq '/my-problem-page/'"

# Show all cache misses
varnishlog -q "VCL_call eq 'MISS'"

# Show all requests that were passed (not cached)
varnishlog -q "VCL_call eq 'PASS'"

# Show backend fetch times
varnishlog -q "Timestamp:Beresp[3] > 1.0" -i Timestamp,BereqURL

varnishd -a :6081 -f /etc/varnish/wordpress.vcl -s malloc,2G

# In /etc/varnish/varnish.params or as varnishd arguments
-p thread_pool_min=50
-p thread_pool_max=4000
-p thread_pool_timeout=120

sub vcl_recv {
    # Only allow methods that WordPress needs
    if (req.method != "GET"
        && req.method != "HEAD"
        && req.method != "POST"
        && req.method != "PURGE"
        && req.method != "BAN"
        && req.method != "OPTIONS") {
        return (synth(405, "Method not allowed."));
    }
}

sub vcl_recv {
    # Block access to sensitive WordPress files
    if (req.url ~ "^/wp-config\.php"
        || req.url ~ "^/wp-includes/.*\.php$"
        || req.url ~ "^/\.htaccess"
        || req.url ~ "^/readme\.html"
        || req.url ~ "^/license\.txt"
        || req.url ~ "/\.git"
        || req.url ~ "/\.svn"
        || req.url ~ "/\.env") {
        return (synth(403, "Forbidden"));
    }

    # Block common exploit paths
    if (req.url ~ "eval\("
        || req.url ~ "base64_"
        || req.url ~ "GLOBALS\["
        || req.url ~ "_REQUEST\[") {
        return (synth(403, "Forbidden"));
    }
}

# As varnishd parameters
-p http_req_hdr_len=16k
-p http_req_size=32k
-p http_resp_hdr_len=32k
-p http_resp_size=64k

# Check syntax without loading
varnishd -C -f /etc/varnish/wordpress.vcl

# test_wordpress.vtc
varnishtest "WordPress VCL: anonymous users get cached responses"

server s1 {
    rxreq
    txresp -status 200 -hdr "Content-Type: text/html" -body "Hello World"
} -start

varnish v1 -vcl+backend {
    # Include your production VCL here or inline the relevant parts
    sub vcl_recv {
        if (req.http.Cookie ~ "wordpress_logged_in_") {
            return (pass);
        }
        return (hash);
    }
} -start

# First request: cache miss
client c1 {
    txreq -url "/" -hdr "Host: example.com"
    rxresp
    expect resp.status == 200
} -run

# Second request: cache hit (backend should not receive a second request)
client c1 {
    txreq -url "/" -hdr "Host: example.com"
    rxresp
    expect resp.status == 200
} -run

# Request with WordPress cookie: should pass through
client c1 {
    txreq -url "/" -hdr "Host: example.com" \
        -hdr "Cookie: wordpress_logged_in_abc=user"
    rxresp
    expect resp.status == 200
} -run

varnishtest test_wordpress.vtc

# Fetch all URLs from the sitemap and warm the cache
wget --quiet -O - https://example.com/sitemap.xml \
  | grep -oP '<loc>\K[^<]+' \
  | xargs -I {} -P 10 curl -s -o /dev/null -w "%{http_code} %{url_effective}\n" {}

# In wp-config.php
define('DISABLE_WP_CRON', true);

# System crontab
*/5 * * * * curl -s https://example.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

// In wp-config.php
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) 
    && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
    $_SERVER['HTTPS'] = 'on';
}

add_action('switch_theme', function() {
    // Full site ban
    wp_remote_request('http://127.0.0.1:6081/', [
        'method' => 'BAN',
        'headers' => [
            'X-Ban-Url' => '.*',
            'X-Ban-Host' => $_SERVER['HTTP_HOST'],
        ],
    ]);
});

add_action('upgrader_process_complete', function($upgrader, $options) {
    if ($options['type'] === 'theme') {
        // Same full ban as above
        wp_remote_request('http://127.0.0.1:6081/', [
            'method' => 'BAN',
            'headers' => [
                'X-Ban-Url' => '.*',
                'X-Ban-Host' => $_SERVER['HTTP_HOST'],
            ],
        ]);
    }
}, 10, 2);

sub vcl_backend_response {
    # Keep only Accept-Encoding in Vary (Varnish handles this internally)
    if (beresp.http.Vary) {
        set beresp.http.Vary = "Accept-Encoding";
    }
}