Cache Tag

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 }} 

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

It's worth noting that variables defined inside the cache tag won't be available outside of it.

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 }} 

<statamic:cache> 
 this will be cached 
 <statamic:nocache> this will remain dynamic </statamic:nocache> 
 this will also be cached 
</statamic: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 }} 

<statamic:cache 
 for="5 minute" 
> 
 ... 
</statamic:cache> 

Key#

By specifying a key, you can invalidate it programmatically.

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

<statamic:cache 
 key="homepage_stocks" 
> 
 ... 
</statamic: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; 
use Statamic\Events\EntrySaved; 
 
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.

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 }} 

<statamic:cache 
 scope="page" 
> 
 <statamic:nav> ... </statamic:nav> 
</statamic: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 }} 

<statamic:cache 
 scope="user" 
> 
 <statamic:nav> 
 {{ $user->name }} 
 </statamic:nav> 
</statamic: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