Installation and Configuration

PLEASE READ

Development on the 3rd party LSCache Purge plugin for Craft CMS has been discontinued:

Per-URL cache busting is now broken in Craft 3.5 because of changes to how template caching works. You will need to nuke the whole cache on save if you are running 3.5+

This plugin is EOL. Minor patches will be issued, but not major functionality overhauls. PR's gratefully received.

We recommend using LSCache with rewrite rules via these instructions if you are using Craft CMS v3.5 or later.

There are two parts to Craft CMS LiteSpeed caching: rewrite rules to define caching behavior, and a third party plugin to facilitate on-demand purging of cache objects.

Before installing and activating the LSCache plugin, deactivate all other full-page cache plugins.

Tip

You can still use other types of cache (like object cache), but only one page cache can be used at a time, so you’ll need to disable any other page caches, if you want to use LSCache.

Server-Level Setup

Note

Please see the Overview for the server-level requirements before attempting to use LSCache.

Enable Cache for Craft CMS

LSCache is controlled through rewrite rules added to the .htaccess file found in your Craft CMS document root. To start, the file may look something like this:

<IfModule mod_rewrite.c>
      RewriteEngine On
      # Send would-be 404 requests to Craft
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteCond %{REQUEST_URI} !^/(favicon\.ico|apple-touch-icon.*\.png)$ [NC]
      RewriteRule (.+) index.php?p=$1 [QSA,L]
</IfModule>

In order to use LSCache on your site, you must place the cache-related rewrite rules above the existing rules. The following example will cache all pages for 8 hours (28800 seconds) with the exception of any /admin URLs:

########## Begin - Litespeed cache
<IfModule LiteSpeed>
  RewriteEngine On
  RewriteCond %{REQUEST_METHOD} ^HEAD|GET$
  RewriteCond %{ORG_REQ_URI} !/admin
  RewriteCond %{ORG_REQ_URI} !/index.php/admin    
  RewriteRule .* - [E=Cache-Control:max-age=28800]
</IfModule>
########## End - Litespeed cache
Feel free to modify these rules, if necessary for your site's needs.

Examples

  • If you would like to exclude some other page from cache (let's say, /mypage.php), simply add the following line to the existing rewrite conditions:
    RewriteCond %{ORG_REQ_URI} !/mypage.php
    
  • If you want to cache your site for only 4 hours, you can change the max-age. So, it would be:
    RewriteRule .* - [E=Cache-Control:max-age=14400]
    

Verify Your Site is Being Cached

You can verify a page is being served from LSCache through the following steps:

  1. From a non-logged-in browser, open the developer tools and navigate to your site. Open the Network tab.
  2. Refresh the page.
  3. Click the first resource. This should be an HTML file. For example, if your page is http://example.com/webapp/, your first resource should either be something like example.com/webapp/ or webapp/.
  4. If you see headings similar to
    X-LiteSpeed-Cache: miss
    X-LiteSpeed-Cache-Control:public,max-age=1800
    X-LiteSpeed-Tag:B1_F,B1_ 
    
    (for example), this means the page had not yet been cached, but that LiteSpeed has now stored it for future use.
  5. Reload the page and you should see X-LiteSpeed-Cache: hit in the response header. This means the page is being served by LSCache and is configured correctly.
  6. If you don't see X-LiteSpeed-Cache: hit or X-LiteSpeed-Cache: miss, then there is a problem with the LSCache configuration.

Purge Cache Plugin

When controlled purely with rewrite rules, LSCache lacks insight into Craft CMS's rules, and should only be used to cache content for a very short time.

The third party LSCache Purge plugin is the bridge between Craft CMS and the LiteSpeed Cache engine that allows you to cache your Craft CMS content for a longer period of time. The purge plugin understand Craft CMS rules, and as such can instruct the cache engine to purge content when it changes. This greatly reduces the risk of serving stale content to visitors.

You can confidently set max-age to several hours, if you know that pages will be automatically cleared from cache when they are changed in the CMS.

Our thanks to Scaramanga Agency for their work developing this plugin!

Craft CMS version 3.0.0 or later is required for this plugin. (You can use rewrite rules alone for earlier versions.)

Installation

To install the plugin, search for LiteSpeed Cache on the Craft CMS Plugin store, or install it manually as follows:

  1. Open your terminal and go to your Craft project:
    cd /path/to/project
    
  2. Tell Composer to require the plugin:
    composer require thoughtfulweb/lite-speed-cache
    
  3. In the Control Panel, go to Settings > Plugins and click the Install button for LiteSpeed Cache.

Usage

There are two ways to purge the cache. You can configure it to purge automatically when pages are saved in the CMS, or you can press a button to purge the entire cache at once. Please see the LSCache Purge Plugin's Github page for usage instructions and examples.


Last update: October 31, 2020