Caching

Caching for Pages is critical to make it run fast. Without caching enabled, Pages might feel slow and sluggish, especially if there is a lot going on to render a single page.

PHP caching is critical. You should run a PHP opcache and usercache in order to get the best performance out of Pages. Pages requires PHP7 and makes full use of the built-in Opcode cache.

A key consideration in the design of Pages has been to implement different caching techniques on different levels. There are 3 types of caching happening in Pages:

Table of contents

• Object caching
• Template caching
• Http caching
• Asset versioning

1. Object caching

Pages will transform page frontmatter, structured data files and remote collections into PHP arrays and cache them on the file system and in the opcode cache. Making them blazingly fast.

Page caching

The page cache can be configured by adding a config.php file to the /joomlatools-pages root folder with the following config options:

<?php
  return array(
     'page_cache'       => JDEBUG ? false : true,
     'page_cache_time'  => 60*60*24, // 1 day 
     'page_cache_path'  => JPATH_ROOT.'/joomlatools-pages/cache'
);

See also: Page

Data caching

The data cache can be configured by adding a config.php file to the /joomlatools-pages root folder with the following config options:

<?php
  return array(
     'data_cache'       => JDEBUG ? false : true,
     'data_cache_time'  => 60*60*24, // 1 day 
     'data_cache_path'  => JPATH_ROOT.'/joomlatools-pages/cache'
);

See also: Data

Remote caching

The remote cache can be configured by adding a config.php file to the /joomlatools-pages root folder with the following config options:

<?php
  return array(
     'remote_cache'       => JDEBUG ? false : true,
     'remote_cache_time'  => 60*60*24, // 1 day 
     'remote_cache_path'  => JPATH_ROOT.'/joomlatools-pages/cache'
);

See also: Page > Collections > Webservice

2. Template caching

Pages will parse all templates and cache them as PHP files. This means that the next time they are loaded they don't need to be parsed again. By caching pages as PHP, Pages also makes use of the built-in PHP opcode cache.

<?php
  return array(
     'template_cache'       => JDEBUG ? false : true,
     'template_cache_path'  => JPATH_ROOT.'/joomlatools-pages/cache'
);

See also: Templates

3. Http caching

Pages supports http caching using weak Etag based cache validation. Depending on the cache setting Pages can be cached on the server, in a proxy (CDN) or in the browser.

Cache key

The cache key is based on the URL, user and format. By not using the contents of the page, Pages can return the response from cache for subsequent requests for the same resource. The longer the http_cache_time, the longer the page will remain valid in the cache.

Invalidation

Pages uses a passive cache cleanup mechanism. Files are stored on disk for a maximum of 1 week. After which, they are garbage collected. This ensures that local cache is cleared for URLs that are not requested, or no longer exist.

Configuration

Configuration is provided at two levels:

1. Global

The cache can be globally configured by adding a config.php file to the /joomlatools-pages root folder with the following config options:

<?php
  return array(
     'http_cache'             => true,
     'http_cache_time'        => 60*15, (15min)   //browser cache time
     'http_cache_time_proxy'  => 60*60*24,(1 day) //proxy cache time
);

If you set the http_cache_time to 0 the page will still be cached but it will be re-validated on each request. Only if the page has changed it will be sent back. This is slightly faster, but still requires Pages to re-render the page.

http_cache_time

The http_cache_time defines the time a page can be cached by a proxy server (CDN) or by a browser and it allows you to define the max-age cache directive. This accepts values in seconds. The default cache time is set to 15 minutes.

The max-age directive states the maximum amount of time in seconds that fetched responses are allowed to be used again (from the time when a request is made). For instance, "max-age=900" indicates that an asset can be reused (remains in the browser cache) for the next 900 seconds.

Example:

<?php
    return array(
        'http_cache_time' => 900 // equivalent to 15 minutes 
    );
?>

http_cache_time_proxy

In case you want to use a longer cache time for the proxy server you can specify this using http_cache_time_proxy. This setting allows you to define the s-maxage cache directive which is only used by the proxy server. This accepts values in seconds. The default proxy cache time is set to 120 minutes or 2 hours.

The “s-” stands for shared as in "shared cache". This directive is explicitly for CDNs among other intermediary caches. This directive overrides the max-age directive and expires header field when present.

Example:

<?php
    return array(
        'http_cache_time_proxy' => 7200 // equivalent to 120 minutes or 2 hours.
    );
?>

Note: If the http_cache_time_proxy < http_cache_time it will not be used.

2. Page Frontmatter

The http cache can be disabled per page and the cache time can also be set. The frontmatter property is:

process:
     cache: [true, false,  time]

The time is specified in seconds.

4. Asset versioning

Pages also has an easy asset versioning filter for theme:// and media:// assets.

The filter will calculate a content based version hash and add it to the asset url as version=[hash].

To use it simply include the filter in a page or layout as follows:

---
@layout: template://pages/document.html
@process:
	filters:
		- image
---

The filter will match any of the following:

<ktml:style src="theme://[path]" />
<ktml:style src="media://[path]" />
<ktml:script src="theme://[path]" />
<ktml:script src="media://[path]" />