Cache Basic API Guide

Introduction

This is one of a series of API guides, which aim to help you understand how to use the Joomla APIs through providing detailed explanations and sample code which you can easily install and run.

This API guide explains in basic terms how to use the Joomla Cache API, and focuses on the Callback type of CacheController and File type of CacheStorage. Other types are mentioned, but not described in detail.

At the end of the guide you can find the code for a simple Joomla module which you can use and adapt to experiment with the Cache APIs.

As a general rule, you should use cache on the Joomla site only, not on the administrator back-end, and the descriptions below relate to when you have the Global Configuration (System tab) parameter System Cache set to "On – Conservative caching" and the "System – Page Cache" plugin is disabled.

Overall Description

Joomla Cache Overview

The diagram provides an overview of how Joomla cache works and the description below relates to the circled steps in the diagram. The code in green is your code: the code in yellow is Joomla code.

Let's imagine that in the main code of our extension we have to get some data and we separate out this code into a function getData(). Typically this function will involve a database query which may take a significant amount of time.

Step 1 relates to the case where we don't use cache – we simply call getData() and store the results returned.

Steps 2 to 5 relate to the case where we use cache.

Step 2: we call $cache = Factory::getCache() with the following parameters:

• parameter 1 ($group) should be set to the name of our extension. This is so that an administrator can see which extensions are storing cache, and can clear cache for specific extensions. (Some core Joomla code passes "_system" as parameter 1). For cache stored in the file system this also relates to the subdirectory of the cache folder in which the cache files are stored.
• parameter 2 ($handler) is the type of cache controller, which is this guide is "callback". Other types which Joomla supports are "output", "page" and "view".
• parameter 3 ($storage) should really be left null, so that Joomla picks up the cache storage mechanism from Global Configuration.

What is returned into $cache is a pointer to an instance of a CacheController subclass, based on what we pass as parameter 2. When we pass "callback" we get returned an instance of CallbackController.

Step 3: we call $data = $cache->get() with 3 parameters:

• parameter 1 ($callback) is the name of the callback function, which in our case is "getData". You can also pass an anonymous function by eg

$myFunc = function() { … };
$cache->get($myFunc, …);

• parameter 2 ($args) is an array of the arguments to pass to the callback function.

• parameter 3 ($id) is an id to be associated with our cache. For file storage this will factor into the name of the file in which the cached data is stored, so if your extension caches data in several places you must use different ids for each.

Important If the data you're caching involves a database query whose results differ for different users then you should take that into account when generating this cache id. Otherwise users may see cached results which don't reflect what their privileges allow, causing possible confusion or security breaches.

If the query takes into account the Access field of a database record, then you can lump together the cache for users with the same Access rights by using:

$groups = implode(',', Factory::getUser()->getAuthorisedViewLevels());
$cacheId = $groups . "some text string";

Similarly if you have a multilingual site then you may want to incorporate the language tag (Factory::getLanguage()->getTag()) within the cache id.