WpW: LSCache and your plugin – perfect together
Welcome to another installment of WordPress Wednesday!
Disclaimer: The information contained in this post is accurate for LSCWP v1.4. If you are using a newer version of the plugin, some details may have changed. Please refer to our wiki for the latest!
In most of our previous posts we’ve talked to site owners and hosting providers. Today, we’d like to address our fellow plugin developers. Let’s talk about how to ensure your plugin is compatible with LiteSpeed Cache for WordPress. And for those of you who are developers and would like to help make someone else’s plugin work well with LSCache, you’ll want to check out “What if it’s not your plugin?” below.
To know if your plugin is compatible with LSCache, it helps to understand a bit about caching in general, as well as LiteSpeed Cache in particular. For that, we recommend you have a look at our Caching 101 series.
Are we compatible?
If your plugin doesn’t generate site content, or do anything out of the ordinary with existing front-end content, then chances are it is 100% compatible with LiteSpeed Cache for WordPress already. The vast majority of plugins will fall into this “already compatible” category. If, however, you have a plugin that makes changes to front-end-displayed content, and it does so in a non-traditional way, you’ll want to read on.
LSCWP purges pages from the cache when certain events are triggered. If your plugin generates content that triggers those same events, then we’re already compatible in that area.
LSCWP follows a set of rules to determine whether a page is cacheable. If your plugin generates content that also abides by those same rules, then we’re already compatible in that area as well.
Even if your plugin generates cacheable content that doesn’t trigger the standard events, or it generates non-cacheable content that doesn’t abide by the same rules that we do, we can still get along. You may just need to invoke our API first.
First, let’s look at purging rules and exclude rules to understand what is possible, and then we can look at the API functions that allow you to realize those possibilities.
LSCache will automatically purge a page from the cache if any of the following events are triggered:
LSCache’s “smart purge” feature works by assigning tags to each cacheable page, and then using those tags to intelligently group together a collection of pages to be purged later.
In its most basic form, each page is tagged with its Post ID, and then sent to the server to be cached. When one of the above events is triggered for the page, that request will notify the server to purge all of the cache’s items that are also tagged with that page’s Post ID. Depending on the purge rules that have been defined by the site owner, this could include related category pages, tag pages, and monthly archives, among other things.
If your plugin makes modifications that trigger those same events, then you should be good. If, however, you have an application that changes what appears on a page without triggering any of those events, then you will need to inform LiteSpeed Cache that a purge is necessary.
Our API gives you the ability to customize the notifications sent to the server. As the page is stored in the cache, you can assign your own tags to the page so that later, it may be purged as part of a custom group. Multiple tags can be set on a single page, and a single tag may be used on multiple pages. This many-to-many mapping provides a flexible system enabling you to group pages in a variety of useful ways.
- Page #1 is tagged with
MTPP_F.1, MTPP_G.4, MTPP_S.wyoming(because the page is in forum 1, group 4, and related to the state of Wyoming).
- Page #2 is tagged with
MTPP_F.1, MTPP_G.2, MTPP_S.iowa(because the page is in forum 1, group 2, and related to the state of Iowa).
If a change is made where all pages tagged
MTPP_F.1 need to be purged, the tag system enables the server to easily purge both Page #1 and Page #2. If a request is sent to the server indicating that pages tagged
MTPP_S.wyoming need to be purged, then the tagging system knows to only purge Page #1.
For this functionality, you’ll want to pay special attention to the API functions
TIP: When defining tags, it is a good idea to give them a prefix that is unique to your application, that way you avoid stepping on anyone else’s tags. In this example, we’ve used
MTPP_ for “my third-party plugin.”
As of v1.4, LSCache considers a page to be non-cacheable if
- It is an Admin page
- It is a post request
- No theme is used
- The URI is found in the Do Not Cache URIs List
- The post 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
If your plugin generates content that is non-cacheable but doesn’t fall into one of the above categories, you will need to inform LiteSpeed Cache that the content cannot be cached. Our API gives you the ability to do so via the
set_nocache API hook and function.
LiteSpeed Cache for WordPress’ API provides functions and hooks that allow you to customize the aspects of cache management that we discussed above. Listed below are eight useful API functions and hooks. There is more to our API, though, and you can get all of the latest details and available functions on our wiki.
These functions are defined in
plugins/litespeed-cache/includes/litespeed-cache-api.class.php and may be used in any hook point prior to the
shutdown hook point.
Use these functions to implement your own purge rules, as in our forum/group/state example above.
When a page is created or edited, use this function to add a single cache tag (or group of cache tags) to the list of cache tags associated with the current page. These tags are appended the list of built-in tags generated by LSCWP.
When you need to purge a page and its related pages, use this function to add a single purge tag (or group of purge tags) to the list of tags to be purged with the request.
If you plugin generates content that should not be cached, use these functions to implement your own exclude rules.
Use this function to mark the current page as non-cacheable.
Specify a hook for cache control with this filter. The hook will be triggered when the cache plugin is checking whether the current page is cacheable. This filter will not trigger on admin pages nor any page that has previously been marked as non-cacheable.
Customized Admin Handling
If your plugin makes adjustments to content through WordPress Admin (for example, you change a product description and then need to purge that product) these are the functions to use.
Purge a single post by id with this function.
This hook is called at the end of every cacheable request, and gives you the ability to add purge tags to the current request.
If you’d like to use ESI blocks in your plugin, you’ll want to employ the following functions:
LiteSpeed_Cache_API::esi_url($block_id, $wrapper, $params = array(), $control = 'private,no-vary')
Creates a new ESI block. Use this if you wish to punch a hole for differently-cached content (i.e. a privately-cached individualized greeting on a publicly-cached page).
Use this hook to display an ESI block.
For some detailed ESI examples, visit our wiki.
What if it’s not your plugin?
Not every plugin author is interested in modifying their plugin for LSCache compatibility, and that’s ok. You don’t have to be the author of the plugin to make sure it is compatible with LiteSpeed Cache. In fact, we’ve been adding support for well-known plugins ourselves since the beginning.
If you are currently using an incompatible plugin, and you have some PHP skills, you can contribute to our project. Take a look at our plugin source code, and you’ll see a
thirdparty directory where you’ll find our current integrations. Use these examples to help you write up some code that will make your own favorite plugin compatible with LSCache.
And then get in touch! We’d love to integrate your working solution into our plugin so that everyone may benefit.
The majority of plugins get along just fine with LSCache, and those that don’t generally just need a line or two of code to make them compatible. If the advice we’ve shared today doesn’t help you with your particular application, or you’d like to discuss any of these ideas in more depth, feel free to get in touch with us! Visit the WordPress support forum for LSCache, or go through our ticket system. We’d be happy to help.
Have some of your own ideas for future WordPress Wednesday topics? Leave us a comment!
Don’t forget to meet us back here next week for the next installment. In the meantime, here are a few other things you can do:
- Subscribe to the WordPress Wednesday RSS feed
- Download LiteSpeed Cache for WordPress plugin
- Learn more about the plugin on our website