Managing Cacheability With LSCWP API

The LiteSpeed Cache plugin for WordPress includes an API that you can use to customize cache behavior. If you’re a developer, the LSCWP API will help you to achieve LiteSpeed compatibility within your plugins. If you’re a site owner who enjoys customizing every little aspect of your site, maybe you have some unique reason to use one of our API hooks in your child theme’s functions.php file.

Whatever your actual purpose is, today we’re going to look at three LSCWP API cache hooks and show you how to use them to control the cacheability of a page:

• litespeed_control_set_nocache
• litespeed_control_set_cacheable
• litespeed_control_force_cacheable

Plus, we’ll look at a couple of bonus hooks that are useful for setting cache scope:

• litespeed_control_set_private
• litespeed_control_force_public

To cache, or not to cache

First, let’s look at how LSCWP decides which pages to cache and which pages not to cache.

By default, the wp action hook is run on each page of a WordPress site, after the query has been parsed and the post has been loaded, but before template functionality is executed. (There may be exceptions to this rule, but we’ll talk about that later.)

LSCWP considers all pages that have had the wp action run on them to be cacheable. Essentially, every page is cacheable. Unless it falls into one of these categories:

• It is an admin page
• It is a POST request
• is_trackback() is true
• is_search() is true
• No theme is used

Site administrators may also set some content to be non-cacheable, so LSCWP checks the values of the settings in LiteSpeed Cache > Cache > Excludes, and considers a page non-cacheable if:

• The URI is found in the Do Not Cache URIs list
• The URL has a query string found in the Do Not Cache Query Strings list
• The post has a category found in the Do Not Cache Categories list
• The post has a tag found in the Do Not Cache Tags list
• The request has a cookie found in the Do Not Cache Cookies list
• The request has a user agent found in the Do Not Cache User Agents list
• The request is being made by a user whose role is checked in the Do Not Cache Roles list

This is enough for most admins, but maybe you have a special case that you want to handle programmatically. Or maybe you have written a plugin that generates its own pages and doesn’t follow the usual wp action hook conventions. What do you do then?

You use LSCWP’s cache control API hooks.

Cache control API hooks

Mark the current page as cacheable

If your plugin generates pages and does not invoke the wp action hook, then LSCWP may not know that the page should be cached. Use the litespeed_control_set_cacheable action with a ‘reason’ parameter, like so:

do_action(
	'litespeed_control_set_cacheable',
	'The lady doth protest too much, methinks.'
);

Note that if the page fits one of the criteria specified in the the plugin’s Cache > Excludes settings, then the page may ultimately be set as non-cacheable, despite this hook.

Mark the current page as non-cacheable

The litespeed_control_set_nocache action is the opposite of the previous one. Use it in your plugins or snippets to inform LSCWP not to cache the page.

do_action(
	'litespeed_control_set_nocache',
	'And flights of angels sing thee to thy rest!'
);

Force the current page to be cacheable

The litespeed_control_force_cacheable action informs LSCWP to cache the page, and it will override anything the user may enter in the Cache > Excludes settings.

do_action(
	'litespeed_control_force_cacheable',
	'if it be not to come, it will be now'
);

What have I done?

With all the settings and API hooks available, it can be difficult to know whether the current page is set to be cached or whether it is non-cacheable. Use the litespeed_control_cacheable filter to get a definitive answer.

apply_filters( 'litespeed_control_cacheable', false );

BONUS

Once you set a page as cacheable, you might want to further define the scope of that cache. Do you want to store the cache object in a logged-in user’s private cache, or do you want all visitors to view a publicly cached copy? By default, LSCWP caches pages publicly. Use these action hooks to explicitly define cache scope:

do_action(
	'litespeed_control_set_private',
	'Listen to many, speak to a few.'
);

do_action(
	'litespeed_control_force_public',
	'Brevity is the soul of wit.'
);

Conclusion

We hope this is helpful to you plugin developers and site tinkerers out there. If you want to learn more about LSCWP’s API hooks, take a look at our API Reference.

—
Thank you to Tynan Beatty for his numerous contributions to this post, including all of the sample code!