Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
litespeed_wiki:cache:lscwp:api [2020/05/04 13:55]
Shivam Saluja 		litespeed_wiki:cache:lscwp:api [2020/11/14 15:31] (current)
Lisa Clarke Redirect to new Documentation Site
Line 1: Line 1:
-====== LSCache for WP Third Party Plugin Integration Framework ====== +~~REDIRECT>​https://​docs.litespeedtech.com/​lscache/​lscwp/​api/​~~
-**Please Note**: This wiki is valid for v2.9.x and below of the LiteSpeed Cache Plugin for WordPress. If you are using v3.0 or above, please see [[https://​docs.litespeedtech.com/​lscache/​lscwp/​overview/​|the new documentation]]. +
- +
-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 [[litespeed_wiki:​cache:​lscwp:​api#api |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.) +
- +
-===== 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 ==== +
-**This is only valid for v.2 of LSCWP since with v.3 all API functions have been replaced with hooks and the previous hooks have new names. +
-For assistance with migrating from v.2 to the refactored v.3 API please refer to the comments at [[https://​github.com/​litespeedtech/​lscache_wp/​blob/​master/​src/​api.cls.php#​L51|src/​api.cls.php under the init() function]] which has side-by-side comparisons & even lists hooks registered elsewhere. +
-See the [[https://​docs.litespeedtech.com/​lscache/​lscwp/​api/​|LSCWP v3 API documentation]] if starting new. +
-** +
- +
-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) === +
-**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.  +
- +
-=== LiteSpeed_Cache_API::​nonce_action($string) === +
-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''​. +
-  +
-=== 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''​). [[litespeed_wiki:​cache:​developer_guide:​cache-vary | 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 [[https://​blog.litespeedtech.com/​2017/​09/​06/​wpw-esi-and-litespeed-cache/​|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: [[litespeed_wiki:​cache:​lscwp:​esi_sample|ESI Sample Code]] +
- +
-===== Deprecated ===== +
- +
-If you need to look up the deprecated elements of the API, please visit [[litespeed_wiki:​cache:​lscwp:​api:​deprecated|this page]].+
  • Admin
  • Last modified: 2020/05/04 13:55
  • by Shivam Saluja