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>

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');
            }
        });
    }
}

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>

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