Differences

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

--- litespeed_wiki:cache:no-plugin-advanced:esi-support [2019/02/04 10:28]
qtwrk [Response Headers]
+++ litespeed_wiki:cache:no-plugin-advanced:esi-support [2020/12/10 14:36] (current)
Lisa Clarke
@@ Line 1: / Line 1: @@
-===== LSCache ESI Support =====
+~~REDIRECT>https://docs.litespeedtech.com/lscache/devguide/advanced/~~
-It is assumed that you have a general knowledge of LSCache Web Development and ESI use cases. Please visit [[litespeed_wiki:cache:developer_guide|our Developer Guide]] and [[https://blog.litespeedtech.com/2014/02/19/lsws-5-0-lscaches-esi-support-will-speed-up-web-applications/|our blog post introducing ESI]] to ensure a basic understanding of these topics before proceeding.
-LiteSpeed can parse the standard ESI tags as well as some LiteSpeed-specific(LSS) tags. The LiteSpeed-specific tags may be used in cases where minifying applications or PageSpeed modules are not built to parse the standard ESI tags. In addition to HTML tags, LiteSpeed also has LSS attributes to assist cache lookup and storage.
-=====Available HTML Tags=====
-====<esi:inline> or <esi_inline> (LSS)====
-The ''inline'' block may be used to cache a section of code separately.  It requires an opening and closing tag.
-Attributes:
-  * ''src'' - The resource url.
-  * ''cache-tag'' - Used to classify content for cache storage.
-  * ''cache-control'' - Used to determine whether content should be cached and how to store it, as with a traditional ''cache-control'' header.
-====<esi:include> or <esi_include> (LSS)====
-This tag generates a second request that is loaded after the main page is loaded. The ''esi:include'' response headers should contain the various cache headers that are needed to determine how the content is to be cached. It does not require a closing tag.
-Attributes:
-  * ''src'' - The resource url.
-  * ''cache-tag'' - Used for private shared cache lookups. Generally, it should be unique.
-  * ''cache-control'' - Used for cache lookups. May specify ''no-vary'' and either ''public'' or ''private''.
-  * ''as-var'' - Setting this value will store the HTML output during parsing. This is useful if the ESI block needs to be included again later in the main file. Using this attribute will reuse the HTML rather than going back to the backend to regenerate it.
-  * ''test'' - Test against a condition before doing the ESI include. If the condition is met, parse the ESI request. Else do not output.
-  * ''combined'' - Value is either ''parent'' or ''sub''. A combined ESI include will parse the rest of the main request for any other ESI includes with the ''combined=sub'' attribute. After parsing, a POST request is sent to the backend. The post body will include the list of ESI includes to parse, so everything is returned in a single response. The post should have the cache control values ''no-cache'' and ''esi=on''. Each individual ESI include block should be wrapped with an ESI inline.
-====<esi:remove> or <esi_remove> (LSS)====
-Cannot have a nested ESI tag within. Used as a backup in case there is no ESI processor. Placed after another ESI tag (e.g. ''esi:include''). If there is an ESI processor, anything inside the ''esi:remove'' tag is ignored. Else, the ESI tags will be ignored, so anything inside this tag will be processed normally.
-====<esi:choose> | <esi:when> | <esi:otherwise> or <esi_choose> | <esi_when> | <esi_otherwise> (LSS)====
-Works like an ESI ''if''/''else if''/''else'' statement. It must have an opening and closing tag.
-A list of usable variables and expressions are listed [[https://www.w3.org/TR/esi-lang|at w3.org]].
-====<esi:try> | <esi:attempt> | <esi:except> or <esi_try> | <esi_attempt> | <esi_except> (LSS)====
-Works like an ESI ''try''/''catch''. Only ''esi:attempt'' and ''esi:except'' tags are allowed immediately inside ''esi:try''.
-====<esi:comment> or <esi_comment> (LSS)====
-This tag may be used to comment ESI logic. It is useful if a developer wishes to leave a comment on an HTML page without it showing up in the processed HTML.
-====<esi:vars> or <esi_vars> (LSS)====
-Enables the usage of ESI variables (listed [[https://www.w3.org/TR/esi-lang|at w3.org]])
-===== Enabling ESI Support =====
-The server needs to know when to parse for ESI tags in the response body. There are two ways to enable ESI, via rewrite rules and via response header.
-Multiple levels of ESI includes are permitted. The maximum number of levels is 10.
-<code>
-<IfModule LiteSpeed>
-RewriteEngine on
-CacheLookup on
-</IfModule>
-</code>
-The above code in ''.htaccess'' is must-have code in order to activate cache, regardless of which method you use to enable ESI.
-==== Response Headers ====
-Response Headers can be used on a more narrow scope, on a page by page basis. The ''X-LiteSpeed-Cache-Control'' response header needs to include ''esi=on''.
-This notifies the server to parse the response for ESI tags. Upon finding an ESI tag, the server will use the attributes to search for a cache entry and if not found, make the ESI request. If the ''no-vary'' cache control attribute is set, the varies will not be used to locate or store in the cache.
-The ESI resource needs to set response headers in order to be cached correctly. ''X-LiteSpeed-Cache-Control'' needs to be set like a normal cache entry (i.e. ''public''/''private''/''shared''/''no-cache, max-age'')
-  <?php
-  header('X-LiteSpeed-Cache-Control: public, max-age=120, esi=on');
-  ...
-  ...
-  ...
-  ?>
-==== Rewrite Rules ====
-Rewrite rules can be used for broader requirements if many pages need to check for ESI.
-  RewriteRule .? - [E=esi_on:1]
-The above rewrite rule would activate ESI support for all pages. If you only have ESI on a specific page, you might want to only enable ESI for that page:
-  RewriteRule PAGE_URI - [E=esi_on:1]
-===== Example =====
-You have page with 3 lines of content. Line 1 and line 3 are cache friendly, but line 2 is not.
-<code><?php
-echo 'line 1 - cache friendly';
-echo "line 2 - cache unfriendly, generate a random number: " . rand(1,999);
-echo 'line 3 - cache friendly';
-?></code>
-With ESI we can cache this page while punching a hole for line 2 and leaving that content uncached.
-Add the following code to ''.htaccess'' to enable ESI:
-<code><IfModule LiteSpeed>
-RewriteEngine on
-CacheLookup on
-RewriteRule PAGE_URI - [E=esi_on:1]
-RewriteRule PAGE_URI - [E=cache-control:max-age=120]
-</IfModule></code>
-Note: ''max-age=120'' indicates that the content should be cached for 120 seconds.
-Create the main PHP file:
-<code><?php
-echo 'line 1 - cache friendly';
-echo '<esi:include src="/second.php" cache-control="no-cache"/>';
-echo 'line 3 - cache friendly';
-?></code>
-Create a second PHP file which contains the code that is not cache-friendly:
-<code><?php
-echo "line 2 - cache unfriendly, generate a random number: " . rand(1,999);
-?></code>
-When you access this page, you will see the ''x-litespeed-cache: hit'' header, but with each refresh, you will see a //new// random number. This is proof that line 2 has not been cached.
-You can also do this by using PHP to send the cache header.
-Create ''.htaccess'' with the following code:
-<code><IfModule LiteSpeed>
-RewriteEngine on
-CacheLookup on
-</IfModule></code>
-Create the main PHP file:
-<code><?php
-header('X-LiteSpeed-Cache-Control: public, max-age=120, esi=on');
-echo 'line 1 - cache friendly';
-echo '<esi:include src="/second.php" cache-control="no-cache"/>';
-echo 'line 3 - cache friendly';
-?></code>