Documentation
Static Caching
In order to get the very best performance from your project, it's worth considering the use of static caching to dramatically accelerate the speed of most requests.
Static caching captures a snapshot of your project's response HTML and stores it in a cache. The next request for the same URL will return the pre-rendered HTML from the cache rather than forwarding the request to PHP for it to build a whole new response.
This strategy can work very well for websites which serve the same content to all users, but can cause issues for projects which rely on user logins or detection of a user's country in order to tailor the content that is displayed. However, the benefits are huge so if you're not sure whether it'll work for you, just give it a try in your staging environment and see how it goes!
Enabling static caching on Servd is easy and can be fully configured via the dashboard.
Enabling/Disabling Static Caching
#
-
Navigate the the Environment > Settings page for the environment that you'd like to change
-
Find the Static Caching section on the page
-
Toggle the master enable/disable switch
-
Set your Default Cache TTL value as desired. If set to 'Use Origin Headers' make sure your project is configured to return `Cache-Control` headers in responses.
-
Click the 'Sync' button at the top of the page to deploy your change
Add Static Caching Exceptions #
Whenever you use static caching it is very important to also define exceptions to the caching mechanism.
At a minimum the Craft control panel should be excluded in its entirety. You should also add exceptions for any pages which return different content to each user.
Static caching exceptions are based on URL prefixes. Any incoming request which begins with one of these prefixes will entirely bypass Servd's static caching mechanism.
-
Navigate the the Environment > Settings page for the environment that you'd like to change
-
Find the Static Caching section on the page
-
Add, remove or edit any required URL prefixes
-
Click Save
-
Click the 'Sync' button at the top of the page to deploy your change
Automated Cache Purging #
The Servd plugin is capable of automatically purging the cached copied of pages whenever those pages are updated. You can find out more about the settings which control this functionality in the plugin settings documentation below.
Other Static Caching Options #
Default Cache TTL
The length of time that cached versions of pages are stored before automatically expiring.
If you set this to 'Use Origin Cache Headers' the value of the response's Cache-Control header will be used. If no Cache-Control headers are present, the response will not be cached.
Logged in users skip the cache
When enabled, users who are logged into Craft (the control panel or otherwise) will never be sent cached responses and the responses they generate will never be cached. This is useful if you need to show admin-only content on the site's front end.
Include GET Params in cache keys
If you do not use GET/Query String parameters in your site's URLs you should disable this in order to greatly increase the number of requests which are served from the cache.
Check Whether a Response Came From the Cache #
Once static caching has been enabled Servd will begin adding a response header called X-Cache to indicate whether or not a specific request has been served from the static cache. The header will not be present for requests which skip the cache entirely (CP logged in users or requests which match a cache exception).
You can check this header using the developer tools in your browser. It will be set to one of the following values:
- MISS - The request was not served from the cache because no cached copy of the page was available
- HIT - The request was served from the cache
Cache Stampede Protection #
Cached pages are stored for a specific length of time, as defined by the Default Cache TTL setting, or the headers returned in your project's responses.
When this time elapses the cached page will be marked as 'expired'. The following request for the same page will return the 'expired' copy, but will also trigger a new version of the page to be created in the background. This ensures that all users are able to benefit from the increased speeds of statically cached content and avoids the danger of cache stampedes.
This mechanism means that even when cached pages are purged, you'll still see cache HITs for subsequent requests. In order to determine if a page has actually been flushed from the cache, check the age header which contains the number of seconds elapsed since the cached page was generated.
Dynamic Content #
Sometimes it's useful to be able to have specific sections of a page dynamic whilst keeping the majority of the page cached. The plugin contains a twig tag which can do this on your behalf:
{% dynamicInclude 'snippets/login' with {key: 'val'} only %}
The tag matches the syntax of the standard twig {% include %} tag exactly, so you can easily switch between standard and dynamic template includes.
This mechanism relies on Craft's action URL prefix being excluded from the static cache. Servd has this in place by default, but you might need to update it if you use a non-standard action URL prefix.
Dynamic Content Context
As with the normal {% include %} tag, the vast majority of the parent template's context will be made available to the dynamically loaded template by default. You can prevent the full context from being used by specifying the only flag.
Due to the way the dynamic loading works, any simple data types (strings, numbers, arrays etc) in the parent context will be exposed publicly. This does not include any of Craft's global twig variables however. If you have sensitive content in your template context, always use the only flag and define your child template's context explicitly.
ESI (Edge Side Includes) #
The Servd platform is capable of performing other advanced functions for Enterprise projects, including ESI. Please reach out to us if you'd like to make use of this in your project.If you have ESI enabled on Servd, the plugin will automatically detect this and switch {% dynamicInclude %}s to use ESI instead of ajax requests, resulting in extremely quick page load times. No changes are required to your codebase. The implementation of ESI inclusion using this tag is... interesting, and relies on javascript being enabled on the client. If you're interested in why that's the case, we're always happy to talk tech.
More Settings in The Servd Plugin #
The Servd Plugin provides deep integration with your project's static cache by allowing brute force or intelligent cache purges to occur. You can select when the cache is purged and what strategy is used to perform the purge within the plugin settings.
Trigger - None
The cache will never be automatically purged in any way.
Trigger - Only when entries are updated via the control panel
The cache will only be purged if a Craft Entry is updated from within the control panel. This prevents purges from occurring when an end-user submits a form from the front end or makes a Commerce purchase - both of which might edit an Entry, but not from the control panel.
Trigger - When entries are updated in any way
The cache will be purged whenever an Entry is saved, no matter where the request originated from.
Strategy - Full Purge
A full purge will destroy the entire static cache immediately whenever a 'live' Craft Element is updated (not disabled or a draft). This is a brute force approach, but it ensures that any changes you have made are displayed on the front end immediately with no chance of any cached pages pages surviving.
Strategy - Automated Tag Based Purge
This purge mechanism tracks all of the Craft Elements which are loaded in order to render each URL on your site. These Element -> URL associations are stored within an efficient data structure for later retrieval.
When any 'live' Craft Element is updated, the plugin is able to determine which URLs need to be purged based on the Element -> URL associations and only these URLs are purged. This prevents sudden surges of traffic from reaching PHP due to a full cache purge, but relies on a relatively complex tagging system on the back end which might, in some edge case circumstances, result in some URLs being missed from purges.
Manual Cache Purges
As well as the built-in automatic cache purging mechanisms, the plugin also provides several ways to manually purge cached URLs:
- On the Utilities > Clear Caches page in the Craft Control Panel, you have the option to fully purge the static cache by checking the Servd Static Cache check box.
- On the edit page for any Craft Entry which has an associated URL, you will find buttons which allow you to purge the Entry's cache specifically, or purge any URLs which are associated with the Entry.
- Use the Craft CLI command ./craft clear-caches/servd-static-cache
CSRF Token Injection
By default Craft uses CSRF tokens within <form> elements. Static caching breaks this functionality by serving incorrect tokens to the majority of users. In order to prevent this you can enable CSRF token injection in the Servd Plugin settings. This will inject a small piece of javascript into all of your templated pages which checks for any CSRF tokens and replaces them with an uncached value.
JS Events #
Dynamic Includes
When {% dynamicInclude %} tags are detected in a template response, the Servd plugin will fire a handy servd.dynamicloaded JS event to allow your JavaScript code to respond to when the dynamic content has been added to the page.
document.addEventListener('servd.dynamicloaded', function (e) {
// Respond to dynamic blocks loading
// e.detail.blocks will return an array of the inserted HTML blocks
});
CSRF Token Injection
When the CSRF token injection setting is enabled, servd.csrfloaded and servd.csrffailed JS events will be emitted when the CSRF has been successfully or unsuccessfully fetched.
window.addEventListener('servd.csrfloaded', function (e) {
// Respond to a successful CSRF token injection
// e.detail.token contains the new CSRF token
});
window.addEventListener('servd.csrffailed', function (e) {
// Respond to a failed CSRF token injection
});