Caching

Caching pages

You can enable Kirby's page cache in your config.php file with the cache.pages option:

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'ignore' => fn ($page) => $page->title()->value() === 'Do not cache me'
    ]
  ]
];

Options

Excluding pages using a page model

If you need even more detailed control over which pages are cached or ignored, you can use page models with an override of the $page->isCacheable() method:

<?php

class ProjectPage extends Page
{
  public function isCacheable(): bool
  {
    // run the core checks
    if (parent::isCacheable() === false) {
      return false;
    }

    // your custom ignore rules

    // otherwise consider the page cacheable
    return true;
  }
}

Automatic cacheability detection

Not all page responses can and will be cached. Kirby automatically determines whether a response is cacheable.

• Only the base response of a page is cached. If the request matches any of the following criteria, the response is not cached:
  • If the request contains a query string, request data or a Kirby param
  • If the request uses a HTTP method other than GET and HEAD (e.g. POST, PUT or DELETE)
• If the response relies on $kirby->session(), a cookie value (Cookie::get()) or the Authorization header ($kirby->request()->auth()), Kirby protects against sharing the cache between visitors who have these values set and those who don't. In particular, Kirby behaves like this:
  • If any of the queried request headers is set, the response is considered private and never cached.
  • If the headers are not set in the current request, the response is cached but the cached response is only used for requests without these headers. This ensures that users with the cookie or authentication receive their own personalized response.
• If the page is excluded from caching via the ignore option or a page model, the page is never cached.

Cache drivers and options

Cache prefix

Each cache has its own cache prefix or namespace. The prefix ensures that different caches don't collide with each other, even if they use the same underlying cache driver.

By default, Kirby generates the cache prefix as the site's index URL and the cache's name. Here are some examples for the resulting prefixes:

If you run your site on multiple domains and want to share the cache between all domains, you can override the cache prefix like so:

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'prefix' => 'example.com/pages'
    ]
  ]
];

Using a different cache driver

The default cache driver is the file cache, which stores cached data in static files inside the site/cache directory.

You can override the cache driver with the type option. Depending on the driver, you may need to define additional options:

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'type'   => 'memcached',
      'host'   => 'localhost',
      'port'   => '11211',
      'prefix' => 'pages',
      'ignore' => fn ($page) => $page->id() === 'something'
    ]
  ]
];

You can find the list of core cache drivers in the reference.

Custom caches

Defining the cache

If you want to create your own cache instance, you can just add it to the config like this:

return [
  'cache' => [
    'api' => true
  ]
];

That's it! Now you got a new cache up and running with the id api.

This will again be a file cache instance and stores the cache files in /site/cache/api.

You have the same extended options if needed and you can combine different cache types without hassle.

Using the cache

As soon as you configured your cache in the config, you can start using it like this (for example in a controller):

return function ($kirby) {

  $apiCache = $kirby->cache('api');
  $apiData  = $apiCache->get('apiData');

  // there's nothing in the cache, so let's fetch it
  if ($apiData === null) {
    $apiData = Remote::get('https://someapi.com');
    $apiCache->set('apiData', $apiData->content());
  }

  return compact('apiData');
};

You can define how long a cache variable is valid by specifying the number of minutes until it expires in the set method:

$apiCache->set('apiData', $apiData->content(), 30);

The getter will now return null after the 30 minutes expired.

Plugin caches

Plugins can have their own namespaced caches by defining them in their options:

Kirby::plugin('superwoman/superplugin', [
  'options' => [
    'cache' => true
  ]
]);

This plugin cache instance will be available at:

$kirby->cache('superwoman.superplugin');

But you can even have multiple cache instances per plugin:

Kirby::plugin('superwoman/superplugin', [
  'options' => [
    'cache.api' => true
  ]
]);

Following the same concept, you can access it like this:

$kirby->cache('superwoman.superplugin.api');