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.

Nonce Issues

The WordPress nonce makes caching difficult with most plugins, however the LiteSpeed API (described below in more detail) includes a work-around.

Anywhere in your code that you would have used

wp_create_nonce( 'example' )

you should instead use

method_exists( 'LiteSpeed_Cache_API', 'nonce' ) ? LiteSpeed_Cache_API::nonce( 'example' ) : wp_create_nonce( 'example' )

NOTE: Replace example with your own string.

This new code checks to see that LiteSpeed is available, and if it is, the LiteSpeed API function is used in place of the built-in WP function.

LiteSpeed's function simply creates an ESI block and then runs the WP function inside of that block. ESI ensures the nonce is cached for only 12 hours, separate from the TTL of the page that it is on.

Potential for Customization

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

Customized Smart Purging

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.

Customized Do-Not-Cache Rules

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.

Constants

LSCACHE_NO_CACHE

define('LSCACHE_NO_CACHE', true);

indicates that the current page is not cacheable.

LITESPEED_ON

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

LITESPEED_WP_REALPATH

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

API

Functions

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.

LiteSpeed_Cache_API::v($v)

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

LiteSpeed_Cache_API::set_nocache()

Marks the current page as noncacheable.

LiteSpeed_Cache_API::not_cacheable()

Checks if the current page is noncacheable.

LiteSpeed_Cache_API::set_cacheable($reason)

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

LiteSpeed_Cache_API::set_force_cacheable($reason)

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

LiteSpeed_Cache_API::esi_enabled()

Checks to see whether ESI has been enabled.

LiteSpeed_Cache_API::cache_enabled()

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

LiteSpeed_Cache_API::set_mobile()

Mark the current page as mobile.

LiteSpeed_Cache_API::set_cache_private()

Set to private cache.

LiteSpeed_Cache_API::set_cache_no_vary()

Do not create a cache vary for the current page.

LiteSpeed_Cache_API::set_use_frontpage_ttl()

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

LiteSpeed_Cache_API::get_ttl()

Get the TTL of the current page.

LiteSpeed_Cache_API::add_private($tags)

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

LiteSpeed_Cache_API::force_vary()

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

LiteSpeed_Cache_API::purge_private_all()

Purge all private cache.

LiteSpeed_Cache_API::purge_private($tags)

Purge private cache for a particular tag.

LiteSpeed_Cache_API::build_switch($id)

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

LiteSpeed_Cache_API::parse_onoff($input, $id)

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

LiteSpeed_Cache_API::debug2($info)

Log debugging info in Advanced Mode.

LiteSpeed_Cache_API::purge_post($id)

Purges a single post by id.

LiteSpeed_Cache_API::purge_all()

Purges all existing caches.

LiteSpeed_Cache_API::tag_add($tag)

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.

LiteSpeed_Cache_API::vary_add($tag)

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.

LiteSpeed_Cache_API::purge($tag)

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.

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

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

LiteSpeed_Cache_API::set_ttl($val)

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

LiteSpeed_Cache_API::debug($info)

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

LiteSpeed_Cache_API::config($field)

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

LiteSpeed_Cache_API::register($classname)

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.

LiteSpeed_Cache_API::nonce($string)

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.

LiteSpeed_Cache_API::vary($vary_name, $vary_value, $default_value)

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.

Hooks

LiteSpeed_Cache_API::hook_control($hook)

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.

LiteSpeed_Cache_API::hook_tag($hook)

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.

LiteSpeed_Cache_API::hook_vary_add($hook)

Enables a new vary cookie to be added.

LiteSpeed_Cache_API::hook_vary($hook)

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.

LiteSpeed_Cache_API::hook_vary_finalize($hook)

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.

LiteSpeed_Cache_API::hook_purge($hook)

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

LiteSpeed_Cache_API::hook_purge_post($hook)

Hook purge post action to purge.

LiteSpeed_Cache_API::hook_tpl_not_esi($hook)

Hook not ESI template.

LiteSpeed_Cache_API::hook_tpl_esi($block, $hook)

Use this hook to display an ESI block.

LiteSpeed_Cache_API::hook_esi_param($block, $hook)

Hook ESI parameters.

LiteSpeed_Cache_API::hook_setting_tab($hook)

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

LiteSpeed_Cache_API::hook_setting_save($hook)

The hook to LSCWP's setting saving process.

LiteSpeed_Cache_API::hook_widget_default_options($hook)

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

LiteSpeed_Cache_API::hook_get_options($hook)

The hook to LSCWP's options initialization process.

About ESI

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

Deprecated

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

 
litespeed_wiki/cache/lscwp/api.txt · Last modified: 2018/09/24 20:17 by Lisa Clarke