It is assumed that you have a general knowledge of LSCache Web Development and ESI use cases. Please visit our Developer Guide and 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.

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.

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.

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.

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 at w3.org.

Works like an ESI try/catch. Only esi:attempt and esi:except tags are allowed immediately inside esi:try.

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.

Enables the usage of ESI variables (listed at w3.org)

In addition to the ESI tags, the X-LiteSpeed-Cache-Control response header needs to include esi=on, or this can also be done by using a rewrite rule to enable ESI.

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)

Multiple levels of ESI includes are permitted. The maximum number of levels is 10.

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. Rewrite rules can be used for broader requirements if many pages need to check for ESI.

Response Headers can be used on a more narrow scope, on a page by page basis.

<IfModule LiteSpeed>
RewriteEngine on
CacheLookup on
</IfModule>

The above code in .htaccess is must-have code in order to activate cache, regardless of which method you use to enable 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]

<?php
header('X-LiteSpeed-Cache-Control: public, max-age=120, esi=on');
...
...
...
?>

You have page with 3 lines of content. Line 1 and line 3 are cache friendly, but line 2 is not.

<?php
echo 'line 1 - cache friendly';
echo "line 2 - cache unfriendly, generate a random number: " . rand(1,999);
echo 'line 3 - cache friendly';
?>

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:

<IfModule LiteSpeed>
RewriteEngine on
CacheLookup on
RewriteRule PAGE_URI - [E=esi_on:1]
RewriteRule PAGE_URI - [E=cache-control:max-age=120]
</IfModule>

Note: max-age=120 indicates that the content should be cached for 120 seconds.

Create the main PHP file:

<?php
echo 'line 1 - cache friendly';
echo '<esi:include src="/second.php" cache-control="no-cache"/>';
echo 'line 3 - cache friendly';
?>

Create a second PHP file which contains the code that is not cache-friendly:

<?php
echo "line 2 - cache unfriendly, generate a random number: " . rand(1,999);
?>

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:

<IfModule LiteSpeed>
RewriteEngine on
CacheLookup on
</IfModule>

Create the main PHP file:

<?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';
?>