LSCache for WP Third Party Plugin Integration Framework

Any WordPress plugin that populates front-end content that can be publicly cached should work with LSCache.

However, if the plugin needs to update some data, and the cache does not automatically purge the cached page, you may be required to write an integration script to remedy this or invoke LSCWP's API.

The WordPress nonce makes caching difficult with most plugins, however the LiteSpeed API (described below in more detail) has an elegant solution.

If your plugin uses a default nonce, then LiteSpeed Cache will automatically treat that nonce as an ESI block. This ensures the nonce is cached for only 12 hours, separate from the TTL of the page that it is on. You don't have to do anything special for this to work.

If your plugin uses a custom nonce, however, you will need to register the nonce action with our API before you use it.

For example, if you have the following line in your code

wp_create_nonce( 'example' );

Then you need to call the API somewhere before that line, like so:

LiteSpeed_Cache_API::nonce_action( 'example' )

NOTE: Replace example with your own parameter.

Once registered with our API, your custom nonce will be treated as an ESI block as long as your users have ESI enabled. (If ESI is not enabled, the API will call the native WordPress nonce function.)

LSCache for WordPress provides functions and hooks that allow you to customize many aspects of cache management, well beyond the nonce issue mentioned above.

LSCache works by tagging each cacheable page. In its most basic form, each page is tagged with its Post ID, then sent to the server to be cached. When someone makes a change to the page, that request will notify the server to purge the cached items associated with that page's post id.

A post will automatically be purged if the following events are triggered:

• edit_post
• save_post
• deleted_post
• trashed_post
• delete_attachment

These cases cover most situations in which a cache purge is necessary.

If your plugin has additional situations in which a cache purge is necessary, you have 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 ways.

Example:

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.

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 of those pages at once. 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.

Below is a list of what LSCWP considers non-cacheable.

LSCache considers a page to be non-cacheable if

• It is an Admin page
• It is a post request
• is_trackback() is true
• is_search() is true
• 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
• The request is being made by a user whose role is checked in the Do Not Cache Roles List

If your plugin generates other private/transient data that cannot be cached for certain responses, you can instruct LSCWP to not cache that data.

define('LSCACHE_NO_CACHE', true);

indicates that the current page is not cacheable.

Use defined( 'LITESPEED_ON' ) to check if our cache is on or not.

If WordPress is installed in a different folder /wordpress, then uses .htaccess only in / to rewrite and visit, Please add define( 'LITESPEED_WP_REALPATH', '/wordpress' ) ; in wp-config.php to do the compatibility. (LSCWP v1.6.3+)

These functions are found in plugins/litespeed-cache/inc/api.class.php and may be used in any hook point prior to the shutdown hook point.

Version compare. Returns whether the current version of the plugin is > or = $v.

Marks the current page as noncacheable.

Checks if the current page is noncacheable.

Set cache status to cacheable (By default cacheable status will be set when called WP hook wp).

Set cache status to force cacheable (Will ignore most kinds of non-cacheable conditions).

Checks to see whether ESI has been enabled.

Checks the value of the LITESPEED_ON variable, to determine whether caching has been enabled.

Mark the current page as mobile.

Set to private cache.

Do not create a cache vary for the current page.

Set the TTL of the current page to the same value as the Front Page.

Get the TTL of the current page.

Adds private cache tags to the list of cache tags for the current page.

Force a cache vary for the current page, even if the variation is caused by an ajax call.

Purge all private cache.

Purge private cache for a particular tag.

Create an “on/off” switch like in the LiteSpeed Cache Settings pages.

Check the value of an “on/off” switch.

Log debugging info in Advanced Mode.

Purges a single post by id.

Purges all existing caches.

Adds 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 and may be used to purge by a custom tag, as described with the example earlier.

Adds a single tag (or group of tags) to the list of vary cookies associated with the current page. These tags are appended to the built-in vary cookies generated by LSCWP, and may be used to serve different cached copies of a single page, based on a visitor’s cookie values. This allows your plugin to support, for example, different currencies, or different languages, and have these properly-managed in the cache.

Adds a single purge tag (or group of purge tags) to the list of tags to be purged with the request. This is useful if you need to purge custom cache tags or associated pages.

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).

Set $control = 'no-cache' to set the ESI block as non-cacheable.

Use this function to manually set the TTL (Time to Live) for your cached object or ESI block.

Logs debugging information to wp-content/debug.log.

Gets the setting value from LiteSpeed's configuration settings. $field can be found in the LiteSpeed_Cache_Config class constants. e.g. LiteSpeed_Cache_Config::OPID_403_TTL

Registers a third-party class to LSCWP. The class should be under the thirdparty folder and include the function detect(). The detect() action may be used to check if it is necessary to add any further functionality to the current request. For example, if a user visits a shopping page, there is no need for a forum plugin to do its extra checks or add its tags because the shop page is unrelated to the forum.

Deprecated This creates an ESI block for WordPress' own “create nonce” function, assigns it a TTL of 12 hours, and then calls wp_create_nonce($string). Essentially, you can cache the nonce function independently of the page it is on. This allows you to serve fully-cached pages even when they include a nonce. Replaces wp_create_nonce($string) in your code.

Call this function before creating a custom nonce so that the new nonce will be treated as an ESI block with a TTL of 12 hours. $string should be the same as the parameter that you pass to wp_create_nonce.

Use this function to create a cache vary. Cache varies allow you to store multiple public versions of the same page in cache. So, if your application was for multiple currencies, you would use this function and pass it the name you have given the vary (i.e. myapp_currency), the currency the current visitor is using (i.e. EUR), and the default currency (i.e. USD). Learn more about cache varies.

Specifies a hook for cache control. 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 noncacheable.

This hook is called at the end of every cacheable request, and provides an access point to your plugin, giving you the ability to add cache tags to the current request.

Enables a new vary cookie to be added.

The hook to the vary cookie finalizing process. There's no need to use this hook or the one below, if using the vary() API function introduced in v2.6.

Hook vary tags to vary finalization. There's no need to use this hook or the one above, if using the vary() API function introduced in v2.6.

This hook is called at the end of every cacheable request, and gives you the ability to add purge tags to the current request.

Hook purge post action to purge.

Hook not ESI template.

Use this hook to display an ESI block.

Hook ESI parameters.

Use this hook to add a new tab after the original LiteSpeed setting tabs.

The hook to LSCWP's setting saving process.

The hook to LSCWP's widget-default-options initialization process.

The hook to LSCWP's options initialization process.

Edge Side Includes (ESI) allows you to “punch holes” in a page in order to treat certain sections of the page differently. This is useful, for example, if you want to include a private shopping cart widget in a public page. For more on ESI and how it works, see our blog post on the subject.

If you want to include ESI blocks in your plugin, we've put together a few examples that might help: ESI Sample Code

If you need to look up the deprecated elements of the API, please visit this page.