mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-28 10:51:37 +01:00
451 lines
14 KiB
XML
451 lines
14 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<chapter id="caching">
|
|
<title>Caching</title>
|
|
<para>
|
|
Caching is used to speed up a call to <link
|
|
linkend="api.display">display()</link> or <link
|
|
linkend="api.fetch">fetch()</link> 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<sect1 id="caching.setting.up">
|
|
<title>Setting Up Caching</title>
|
|
<para>
|
|
The first thing to do is enable caching. This is done by setting <link
|
|
linkend="variable.caching">$caching</link> = true (or 1.)
|
|
</para>
|
|
<example>
|
|
<title>enabling caching</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
$smarty->display('index.tpl');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
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 <link linkend="variable.cache.dir">$cache_dir</link>.
|
|
Upon the next call to display('index.tpl'), the cached copy will be used
|
|
instead of rendering the template again.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
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!
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Each cached page has a limited lifetime determined by <link
|
|
linkend="variable.cache.lifetime">$cache_lifetime</link>. 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 <link
|
|
linkend="variable.cache.lifetime">$cache_lifetime</link> for details.
|
|
</para>
|
|
<example>
|
|
<title>setting cache_lifetime per cache</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
If <link linkend="variable.compile.check">$compile_check</link> 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.
|
|
</para>
|
|
<example>
|
|
<title>enabling $compile_check</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
$smarty->compile_check = true;
|
|
|
|
$smarty->display('index.tpl');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
If <link linkend="variable.force.compile">$force_compile</link> 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 <link
|
|
linkend="variable.caching">$caching</link> = false (or 0.)
|
|
</para>
|
|
<para>
|
|
The <link linkend="api.is.cached">is_cached()</link> 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.
|
|
</para>
|
|
<example>
|
|
<title>using is_cached()</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
You can keep parts of a page dynamic with the <link
|
|
linkend="language.function.insert">insert</link> 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 <link linkend="language.function.insert">insert</link> for
|
|
details and examples.
|
|
</para>
|
|
<para>
|
|
You can clear all the cache files with the <link
|
|
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
|
|
individual cache files (or groups) with the <link
|
|
linkend="api.clear.cache">clear_cache()</link> function.
|
|
</para>
|
|
<example>
|
|
<title>clearing the cache</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="caching.multiple.caches">
|
|
<title>Multiple Caches Per Page</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<example>
|
|
<title>passing a cache_id to display()</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
$my_cache_id = $_GET['article_id'];
|
|
|
|
$smarty->display('index.tpl',$my_cache_id);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
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!
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Be sure to pass the same cache_id as the
|
|
second parameter to <link linkend="api.is.cached">is_cached()</link> and
|
|
<link linkend="api.clear.cache">clear_cache()</link>.
|
|
</para>
|
|
<example>
|
|
<title>passing a cache_id to is_cached()</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
You can clear all caches for a particular cache_id by passing null as the
|
|
first parameter to clear_cache().
|
|
</para>
|
|
<example>
|
|
<title>clearing all caches for a particular cache_id</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
In this manner, you can "group" your caches together by giving them the
|
|
same cache_id.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="caching.groups">
|
|
<title>Cache Groups</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<example>
|
|
<title>cache_id groups</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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");
|
|
|
|
$smarty->display('index.tpl',"sports|basketball");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
The cache grouping does NOT use the path to the template as any part of the
|
|
cache_id. For example, if you have display('themes/blue/index.tpl'), you
|
|
cannot clear the cache for everything under the "themes/blue" directory. If
|
|
you want to do that, you must group them in the cache_id, such as
|
|
display('themes/blue/index.tpl','themes|blue'); Then you can clear the
|
|
caches for the blue theme with clear_cache(null,'themes|blue');
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
|
|
<sect1 id="caching.cacheable">
|
|
<title>Controlling Cacheability of Plugins' Output</title>
|
|
<para>
|
|
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
|
|
<parameter>$cacheable</parameter> and defaults to true which is also
|
|
the behaviour of plugins in Smarty versions before 2.6.0
|
|
</para>
|
|
|
|
<para>
|
|
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 <link linkend="plugins.inserts">insert</link> function.
|
|
</para>
|
|
|
|
<para>
|
|
In contrast to <link linkend="language.function.insert">{insert}</link> the attributes to the plugins are not cached by default. They can be declared to be cached with the fourth parameter <parameter>$cache_attrs</parameter>. <parameter>$cache_attrs</parameter> 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.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Preventing a plugin's output from being cached</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
index.php:
|
|
|
|
<?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');
|
|
?>
|
|
|
|
|
|
index.tpl:
|
|
|
|
Time Remaining: {remain endtime=$obj->endtime}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</example>
|
|
|
|
|
|
<example>
|
|
<title>Preventing a whole passage of a template from being cached</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
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');
|
|
?>
|
|
|
|
|
|
index.tpl:
|
|
|
|
Page created: {"0"|date_format:"%D %H:%M:%S"}
|
|
|
|
{dynamic}
|
|
|
|
Now is: {"0"|date_format:"%D %H:%M:%S"}
|
|
|
|
... do other stuff ...
|
|
|
|
{/dynamic}
|
|
]]>
|
|
</programlisting>
|
|
|
|
</example>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
--> |