Using Filters to Customize Cache Parameters in Jetpack Boost

In this guide, you’ll learn how to customize Jetpack Boost’s cache behavior using filters to improve site performance and reduce cache fragmentation.

Understanding the Page Cache in Jetpack Boost

Jetpack Boost’s Page Cache feature generates and stores static versions of dynamic WordPress pages. The URL of a page and the browser cookies of the visitor are what we use to identify a page.

A person who visits a page with no cookies in their browser is described as an “anonymous user” because they have no data to identify them. The cache file generated for them can potentially be used for many other visitors. To maximize speed, these cached pages are served before WordPress fully initializes, which means most WordPress functionalities are unavailable at this stage.

For developers who need to execute code early in the page-serving process, Jetpack Boost provides the Extra Code Loader. This tool enables the execution of custom code before two critical points in a WordPress request:

1. When a cached page is served.
2. When the output buffer is created to cache a new page.

This functionality allows developers to implement necessary operations or modifications even when working with cached pages, ensuring both speed and customization capabilities.

Customizing cache behavior with filters

To modify cache parameters, you can create a file named wp-content/boost-cache-extra.php. Jetpack Boost will load it and execute it like any other PHP script. The file must have an opening <?php tag.

This script will execute very early in the process of serving a page, and this means that most WordPress functionality will not be available. However, filters and actions can be used.

Image may be NSFW.
Clik here to view. Important: Ensure the file contains valid PHP code to avoid issues that could disrupt your site. It’s highly recommended to test any changes on a staging environment before applying them live.

Available filters

Jetpack Boost provides several filters for cache customization:

• jetpack_boost_ignore_cookies: Accepts one parameter, an array of cookie names. These cookie names are ignored and removed from the list of cookies that go to identify a cache file. Regular expressions can be used in the cookie names. The default list of cookie names includes the Cloudflare cookies described here, a regular expression matching any cookie starting with sbsj_ and the tk_ai and tk_qs cookies. This means that a visitor with any of these cookies in their browser will see the cache file created for anonymous visitors to the site, instead of getting a custom cache file.
• jetpack_boost_ignore_get_parameters: Accepts one parameter, an array of GET parameter names. These parameters are ignored by the cache in the same way the filter above works. The default list of parameters includes some of the “utm_” parameters used for marketing purposes.
• jetpack_boost_cache_parameters: Accepts one parameter, an array. This is similar to the filters above, but it contains both the cookies and get information. It runs earlier in the request than the filters above, but it’s recommended to use the other filters instead of this one. The filters above use this one.
• jetpack_boost_cache_bypass_patterns: Accepts one parameter, an array of regular expressions. It allows the site owner to modify the list of patterns to match against URLs that bypass caching. These are the URLs listed in the Exceptions form of the settings page.
• jetpack_boost_cache_request_cacheable: Accepts one parameter, a boolean. Return true to make the current page cacheable.
• jetpack_boost_cache_accept_headers: Accepts one parameter, an array of accept headers that the plugin will not cache. The default list includes various JSON header types.

In the list of cookies used by Boost, the Jetpack Cookie Banner eucookielaw and personalized-ads-consent cookie values are set to 1 so visitors who click the Accept button on the cookie banner will all be served the same cache file (if all other cookies are the same), to improve the efficiency of the cache. The cookies themselves are not modified, and a new cache file will be created for visitors who click Accept on the cookie banner.

If your site has a cookie with a value that changes on every page load, but the value itself isn’t used by any PHP code, it may be stopping your site from caching effectively. Use the jetpack_boost_cache_parameters filter to modify the value so it’s a consistent value on every page load.

Why ignore certain cookies?

Cookies play a crucial role in identifying website visitors. When a user logs in, a cookie is placed on their browser, but cookies serve various tracking purposes beyond just modifying page content. For first-time visitors and bots who view an “anonymous” version of the website, a frequently used cached page is typically served, as these types of visitors often outnumber those who have interacted with the site. Once a cookie is set, a new cache file is created for the page, and subsequent visitors with that cookie will be served that specific cache file. This process is essential because the cookie’s presence identifies the visitor in some manner.

However, if JavaScript on the website sets a cookie that doesn’t influence the site’s appearance through PHP, it may be safe to disregard that cookie. It’s important to note that certain cookies, such as WordPress login cookies, cannot be ignored due to their critical functionality.

Examples of modifying cache behavior with filters

Ignore a cookie

To ignore a cookie, such as one set by a cookie banner, use the jetpack_boost_ignore_cookies filter. This example demonstrates how to ignore the cookie_banner_settings cookie in a hypothetical cookie banner plugin that uses it. Any code that relies on this cookie has to be in JavaScript, running in the browser. If PHP on the server used it, to decide whether to display the banner, or perform other functionality, the cookie cannot be ignored.

<?php
// Ignore the 'cookie_banner_settings' cookie.
function ignore_banner_cookie( $cookies ) {
        $cookies[] = 'cookie_banner_settings';

        return $cookies;
}
add_filter( 'jetpack_boost_ignore_cookies', 'add_test_cookie' );

This code ensures that the cookie_banner_settings cookie is ignored, allowing a single cache file to be served to anonymous visitors.

Ignore a GET parameter

To exclude a specific GET parameter like test from cache identification, use the jetpack_boost_ignore_get_parameters filter. This example ensures URLs with the ?test parameter serve the same cache file as the base URL:

<?php
// ignore the 'test' GET parameter in the URL.
function ignore_test_get( $get) {
        $get[] = "test";
        return $get;
}
add_filter( 'jetpack_boost_ignore_get_parameters', 'ignore_test_get' );

This code removes the test parameter from cache identification, ensuring pages like yourjetpack.blog/?test=123 serve the same cached file as yourjetpack.blog/.

Pages that will now share the same cache file:

• yourjetpack.blog/
• yourjetpack.blog/?test=1
• yourjetpack.blog/?test=testing
• yourjetpack.blog/?test=123

Fix a constantly changing cookie value

This is an example where a hypothetical page counter cookie is set to 1 in the cache parameters. We can only do this when JavaScript displays the counter, not PHP. This allows the WordPress page to be cached and used by more visitors, while the counter displays how many pages they have visited.

<?php
// Fix the "page_counter" cookie
function fix_page_counter( $parameters ) {
        if ( isset( $parameters['cookies']['page_counter'] ) ) {
                $parameters['cookies']['page_counter'] = 1;
        }

        return $parameters;
}
add_filter( 'jetpack_boost_cache_parameters', 'fix_page_counter' );

Customizing your cache behavior with Jetpack Boost’s filters allows you to optimize performance and ensure a seamless experience for your site visitors. By ignoring unnecessary cookies and GET parameters, you can serve more efficient cached pages and reduce server load.

Disable caching under particular conditions

If you would like a certain page on your site to be shown without caching, but only to particular visitors, you can use the jetpack_boost_cache_request_cacheable filter. In this example, any visitor using the IP address 192.168.1.1, and has the cookie “source=vip” will be able to access an uncached /about/ page.

<?php

function uncacheable_vips( $cacheable ) {
        if (
                isset( $_SERVER['REQUEST_URI'] ) && $_SERVER['REQUEST_URI'] === '/about/' &&
                isset( $_COOKIE['source'] ) && $_COOKIE['source'] === 'vip' &&
                isset( $_SERVER['REMOTE_ADDR'] ) && $_SERVER['REMOTE_ADDR'] === '192.168.1.1'
        ) {
                return false;
        } else {
                return true;
        }
}
add_filter( 'jetpack_boost_cache_request_cacheable', 'uncacheable_vips' );

Still need help?

Please contact support. We’re happy to advise.