Smarty-Caching

Chapter 14. Caching

Caching is used to speed up a call to display() or fetch() by saving its output to a file. If a cached version of the call is available, that is displayed instead of regenerating the output. Caching can speed things up tremendously, especially templates with longer computation times. Since the output of display() or fetch() is cached, one cache file could conceivably be made up of several template files, config files, etc.

Since templates are dynamic, it is important to be careful what you are caching and for how long. For instance, if you are displaying the front page of your website that does not change its content very often, it might work well to cache this page for an hour or more. On the other hand, if you are displaying a page with a weather map containing new information by the minute, it would not make sense to cache this page.

Setting Up Caching

The first thing to do is enable caching. This is done by setting $caching = true (or 1.)

Example 14-1. enabling caching
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

$smarty->display('index.tpl');
?>

With caching enabled, the function call to display('index.tpl') will render the template as usual, but also saves a copy of its output to a file (a cached copy) in the $cache_dir. Upon the next call to display('index.tpl'), the cached copy will be used instead of rendering the template again.

Technical Note: The files in the $cache_dir are named similar to the template name. Although they end in the ".php" extention, they are not really executable php scripts. Do not edit these files!

Each cached page has a limited lifetime determined by $cache_lifetime. The default value is 3600 seconds, or 1 hour. After that time expires, the cache is regenerated. It is possible to give individual caches their own expiration time by setting $caching = 2. See the documentation on $cache_lifetime for details.

Example 14-2. setting cache_lifetime per cache
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = 2; // lifetime is per cache

// set the cache_lifetime for index.tpl to 5 minutes
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');

// set the cache_lifetime for home.tpl to 1 hour
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');

// NOTE: the following $cache_lifetime setting will not work when $caching = 2.
// The cache lifetime for home.tpl has already been set
// to 1 hour, and will no longer respect the value of $cache_lifetime.
// The home.tpl cache will still expire after 1 hour.
$smarty->cache_lifetime = 30; // 30 seconds
$smarty->display('home.tpl');
?>

If $compile_check is enabled, every template file and config file that is involved with the cache file is checked for modification. If any of the files have been modified since the cache was generated, the cache is immediately regenerated. This is a slight overhead so for optimum performance, leave $compile_check set to false.

Example 14-3. enabling $compile_check
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;
$smarty->compile_check = true;

$smarty->display('index.tpl');
?>

If $force_compile is enabled, the cache files will always be regenerated. This effectively turns off caching. $force_compile is usually for debugging purposes only, a more efficient way of disabling caching is to set $caching = false (or 0.)

The is_cached() function can be used to test if a template has a valid cache or not. If you have a cached template that requires something like a database fetch, you can use this to skip that process.

Example 14-4. using is_cached()
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

if(!$smarty->is_cached('index.tpl')) {
    // No cache available, do variable assignments here.
    $contents = get_database_contents();
    $smarty->assign($contents);
}

$smarty->display('index.tpl');
?>

You can keep parts of a page dynamic with the insert template function. Let's say the whole page can be cached except for a banner that is displayed down the right side of the page. By using an insert function for the banner, you can keep this element dynamic within the cached content. See the documentation on insert for details and examples.

You can clear all the cache files with the clear_all_cache() function, or individual cache files (or groups) with the clear_cache() function.

Example 14-5. clearing the cache
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

// clear out all cache files
$smarty->clear_all_cache();

// clear only cache for index.tpl
$smarty->clear_cache('index.tpl');

$smarty->display('index.tpl');
?>

Multiple Caches Per Page

You can have multiple cache files for a single call to display() or fetch(). Let's say that a call to display('index.tpl') may have several different output contents depending on some condition, and you want separate caches for each one. You can do this by passing a cache_id as the second parameter to the function call.

Example 14-6. passing a cache_id to display()
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

$my_cache_id = $_GET['article_id'];

$smarty->display('index.tpl',$my_cache_id);
?>

Above, we are passing the variable $my_cache_id to display() as the cache_id. For each unique value of $my_cache_id, a separate cache will be generated for index.tpl. In this example, "article_id" was passed in the URL and is used as the cache_id.

Technical Note: Be very cautious when passing values from a client (web browser) into Smarty (or any PHP application.) Although the above example of using the article_id from the URL looks handy, it could have bad consequences. The cache_id is used to create a directory on the file system, so if the user decided to pass an extremely large value for article_id, or write a script that sends random article_ids at a rapid pace, this could possibly cause problems at the server level. Be sure to sanitize any data passed in before using it. In this instance, maybe you know the article_id has a length of 10 characters and is made up of alpha-numerics only, and must be a valid article_id in the database. Check for this!

Be sure to pass the same cache_id as the second parameter to is_cached() and clear_cache().

Example 14-7. passing a cache_id to is_cached()
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

$my_cache_id = $_GET['article_id'];

if(!$smarty->is_cached('index.tpl',$my_cache_id)) {
    // No cache available, do variable assignments here.
    $contents = get_database_contents();
    $smarty->assign($contents);
}

$smarty->display('index.tpl',$my_cache_id);
?>

You can clear all caches for a particular cache_id by passing null as the first parameter to clear_cache().

Example 14-8. clearing all caches for a particular cache_id
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

// clear all caches with "sports" as the cache_id
$smarty->clear_cache(null,"sports");

$smarty->display('index.tpl',"sports");
?>

In this manner, you can "group" your caches together by giving them the same cache_id.

Cache Groups

You can do more elaborate grouping by setting up cache_id groups. This is accomplished by separating each sub-group with a vertical bar "|" in the cache_id value. You can have as many sub-groups as you like.

You can think of cache groups like a directory heirarchy. For instance, a cache group of "a|b|c" could be thought of as the directory structure "/a/b/c/". clear_cache(null,"a|b|c") would be like removing the files "/a/b/c/*". clear_cache(null,"a|b") would be like removing the files "/a/b/*". If you specify a compile_id such as clear_cache(null,"a|b","foo") it is treated as an appended cache group "/a/b/c/foo/". If you specify a template name such as clear_cache("foo.tpl","a|b|c") then Smarty will attempt to remove "/a/b/c/foo.tpl". You CANNOT remove a specified template name under multiple cache groups such as "/a/b/*/foo.tpl", the cache grouping works left-to-right ONLY. You will need to group your templates under a single cache group heirarchy to be able to clear them as a group.

Cache grouping should not be confused with your template directory heirarchy, the cache grouping has no knowledge of how your templates are structured. So for example, if you have a template structure like "themes/blue/index.tpl" and you want to be able to clear all the cache files for the "blue" theme, you will need to create a cache group structure that mimics your template file structure, such as display("themes/blue/index.tpl","themes|blue"), then clear them with clear_cache(null,"themes|blue").

Example 14-9. cache_id groups
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = true;

// clear all caches with "sports|basketball" as the first two cache_id groups
$smarty->clear_cache(null,"sports|basketball");

// clear all caches with "sports" as the first cache_id group. This would
// include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
$smarty->clear_cache(null,"sports");

// clear the foo.tpl cache file with "sports|basketball" as the cache_id
$smarty->clear_cache("foo.tpl","sports|basketball");


$smarty->display('index.tpl',"sports|basketball");
?>

Controlling Cacheability of Plugins' Output

Since Smarty-2.6.0 plugins the cacheability of plugins can be declared when registering them. The third parameter to register_block, register_compiler_function and register_function is called $cacheable and defaults to true which is also the behaviour of plugins in Smarty versions before 2.6.0

When registering a plugin with $cacheable=false the plugin is called everytime the page is displayed, even if the page comes from the cache. The plugin function behaves a little like an insert function.

In contrast to {insert} the attributes to the plugins are not cached by default. They can be declared to be cached with the fourth parameter $cache_attrs. $cache_attrs is an array of attribute-names that should be cached, so the plugin-function get value as it was the time the page was written to cache everytime it is fetched from the cache.

Example 14-10. Preventing a plugin's output from being cached
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;

function remaining_seconds($params, &$smarty) {
    $remain = $params['endtime'] - time();
    if ($remain >=0)
        return $remain . " second(s)";
    else
        return "done";
}

$smarty->register_function('remaining', 'remaining_seconds', false, array('endtime'));

if (!$smarty->is_cached('index.tpl')) {
    // fetch $obj from db and assign...
    $smarty->assign_by_ref('obj', $obj);
}

$smarty->display('index.tpl');
?>

where index.tpl is: 

Time Remaining: {remaining endtime=$obj->endtime}

The number of seconds till the endtime of $obj is reached changes on each display of the page, even if the page is cached. Since the endtime attribute is cached the object only has to be pulled from the database when page is written to the cache but not on subsequent requests of the page.

Example 14-11. Preventing a whole passage of a template from being cached
index.php:

<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;

function smarty_block_dynamic($param, $content, &$smarty) {
    return $content;
}
$smarty->register_block('dynamic', 'smarty_block_dynamic', false);

$smarty->display('index.tpl');
?>

where index.tpl is: 

Page created: {"0"|date_format:"%D %H:%M:%S"}

{dynamic}

Now is: {"0"|date_format:"%D %H:%M:%S"}

... do other stuff ...

{/dynamic}

When reloading the page you will notice that both dates differ. One is "dynamic" one is "static". You can do everything between {dynamic}...{/dynamic} and be sure it will not be cached like the rest of the page.