Radical Design Course by Jack McDade

From the creator of Statamic

Learn how to make your websites standout and be remembered.

Bought Jack McDade's course on design. Going through it now...and it is SO well done!

— Justin Jackson, Transistor.fm

Cache Tag

If you find that a particular chunk of your view logic is the cause of a performance hit — perhaps you're fetching and filtering huge amount of content, or pulling data from an API, caching that portion of your template can remove alleviate any slowdown.

Overview

After an initial render, markup inside a cache tag will be pulled from a cached, statically cached copy until invalidated.

{{ cache for="5 minutes" }}
{{ collection:stocks limit="5000" }}
<!-- probably lots of stuff happening -->
{{ /collection:stocks }}
{{ /cache }}
Hot Tip!

You can disable the {{ cache }} tag (temporarily) based on the environment. This is great for your local setup.

STATAMIC_CACHE_TAGS_ENABLED=false
return [
'cache_tags_enabled' => env('STATAMIC_CACHE_TAGS_ENABLED', true),
...
];

Exclusions

You may use the nocache tag inside a cache tag to keep that section dynamic.

{{ cache }}
this will be cached
{{ nocache }} this will remain dynamic {{ /nocache }}
this will also be cached
{{ /cache }}

Read more about the nocache tag

Invalidation

Caching is handy to speed up parts of your site, but it's not very useful unless it's able to be updated at some stage. Here's how
the tag contents can be invalidated.

Time

Using the for parameter allows you to say how long the tag pair contents should be cached in time.

{{ cache for="5 minutes" }} ... {{ /cache }}

Key

By specifying a key, you can invalidate it programmatically.

{{ cache key="homepage_stocks" }} ... {{ /cache }}

For example, you could listen for an entry in the stocks collection being saved and then bust the key.

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;
 
class EventServiceProvider
{
public function boot()
{
Event::listen(function (EntrySaved $event) {
if ($event->entry->collectionHandle() === 'stocks') {
Cache::forget('homepage_stocks');
}
});
}
}
Warning!

Invalidating by key won't work if you're using tags. In that case, you should invalidate by flushing the tag.

Tag

By specifying tags, you can invalidate it programmatically. You must be using a cache driver that supports tags, like Redis or Memcached.

{{ cache tags="stocks|home" }} ... {{ /cache }}
{{ cache tags="home" }} ... {{ /cache }}
{{ cache tags="stocks" }} ... {{ /cache }}

Similar to invalidating by a key as explained above, you can flush all keys that use the tags.

Cache::tags('home')->flush(); // invalidates first and second pair
Cache::tags('stocks')->flush(); // invalidates first and third pair
Warning!

Don't use the key and tags parameters together.

Cache clear

The contents of your cache tags are stored in the application cache. Clear that, and you'll see fresh content next visit.

You can clear your cache using the Artisan command:

php artisan cache:clear

Tag parameters and contents

It might be useful to know that if you aren't using the key parameter, a key is generated behind the scenes based on what
parameters and values you've used, along with what's between the tag pair.

So, if you change your template or parameters, you'll see a fresh version next time you visit the page.

Scope

The scope parameter allows you cache the template chunk either across the whole site (the default behavior), for the current user, or per page.

For example, you might have a "recent articles" list on the sidebar that's the same on every page. Or, your footer navigation is probably the same on every page. You can use the site scope for those.

However, your header navigation might have "active" states on it, so you'd want to make sure to cache it per page.

{{ cache scope="page" }}
{{ nav }} ... {{ /nav }}
{{ /cache }}

Or if your navigation changes depending on the current user, you want to use the user scope:

{{ cache scope="user" }}
{{ nav }} {{ user }} ... {{ /user }} {{ /nav }}
{{ /cache }}
Hot Tip!

The scope parameter has no effect if you use the key parameter.

Static Caching

You're free to use the cache tag on top of static caching.

You'll probably have static caching disabled during development so you can see your changes without having to continually clear anything.

The cache tag could be a nice compromise to speed up heavy areas for a few minutes at a time. Or, if you have some pages excluded from static caching then the cache tag could be useful there.

Of course, if you do have static caching enabled, keep in mind that you aren't going to gain anything by using both at the same time.

Parameters

for

string

The length of time to cache this section. Use plain English to specify the length, eg. 2 hours, 5 minutes, etc.

key

string

The cache key to be used, if you'd like to manually invalidate this tag pair programmatically.

tags

string|array

The cache tags this section will be using, if you'd like to invalidate this pair programmatically. If you use this, do not also use key.

scope

string

Sets the cache scope. Three possible values: site, page or user. Has no effect when using the key parameter.

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →