smarty/docs/en/programmers/caching/caching-setting-up.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <sect1 id="caching.setting.up">
   <title>Setting Up Caching</title>
   <para>
    The first thing to do is enable caching by setting <link
    linkend="variable.caching">
    <parameter>$caching</parameter></link><literal> = 1 (or 2)</literal>.
   </para>
   <example>
    <title>Enabling caching</title>
    <programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = 1;

$smarty->display('index.tpl');
?>
]]>
    </programlisting>
   </example>
   <para>
    With caching enabled, the function call to
    <literal>display('index.tpl')</literal> 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"><parameter>$cache_dir</parameter></link>.
    On the next call to <literal>display('index.tpl')</literal>, the cached copy
    will be used instead of rendering the template again.
   </para>
   <note>
    <title>Technical Note</title>
    <para>
     The files in the
     <link linkend="variable.cache.dir"><parameter>$cache_dir</parameter></link>
     are named similar to the template name.
     Although they end in the <filename>.php</filename> extention, they are not
     intended to be directly executable. Do not edit these files!
    </para>
   </note>
   <para>
    Each cached page has a limited lifetime determined by <link
    linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>.
    The default value is 3600 seconds ie an hour. After that time expires, the
    cache is regenerated. It is possible to give individual caches their own
    expiration time by setting
    <link linkend="variable.caching"><parameter>$caching</parameter></link><literal>=2</literal>.
    See <link
    linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>
    for more 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">
    <parameter>$compile_check</parameter></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, set
    <link linkend="variable.compile.check"><parameter>$compile_check</parameter>
    </link> to &false;.
   </para>
   <example>
    <title>Enabling $compile_check</title>
    <programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;

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

$smarty->display('index.tpl');
?>
]]>
    </programlisting>
   </example>
   <para>
    If <link linkend="variable.force.compile">
    <parameter>$force_compile</parameter></link> is enabled,
    the cache files will always be regenerated. This effectively turns off
    caching.
    <link linkend="variable.force.compile"><parameter>$force_compile</parameter>
    </link> is usually for
    <link linkend="chapter.debugging.console">debugging</link>
    purposes only, a more  efficient way of disabling caching is to set <link
    linkend="variable.caching"><parameter>$caching</parameter>
    </link><literal> = 0</literal>.
   </para>
   <para>
    The <link linkend="api.is.cached"><varname>is_cached()</varname></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 = 1;

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"><varname>{insert}</varname></link>
    template function. Let's
    say the whole page can be cached except for a banner that is displayed down
    the side of the page. By using the
    <link linkend="language.function.insert"><varname>{insert}</varname></link>
    function for the banner, you
    can keep this element dynamic within the cached content. See the
    documentation on
    <link linkend="language.function.insert"><varname>{insert}</varname></link>
    for more details and examples.
   </para>
   <para>
    You can clear all the cache files with the <link
    linkend="api.clear.all.cache"><varname>clear_all_cache()</varname></link>
    function, or
    individual cache files
    <link linkend="caching.groups">and groups</link>
    with the <link
    linkend="api.clear.cache"><varname>clear_cache()</varname></link> function.
   </para>
   <example>
    <title>Clearing the cache</title>
    <programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty->caching = 1;

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

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

$smarty->display('index.tpl');
?>
]]>
    </programlisting>
   </example>

  </sect1>

<!-- 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
-->