repo_zf1/documentation/manual/en/module_specs/Zend_Cache-Introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.cache.introduction">
    <title>Introduction</title>

    <para>
        <classname>Zend_Cache</classname> provides a generic way to cache any data.
    </para>

    <para>
      Caching in Zend Framework is operated by frontends while cache records are stored through
      backend adapters (<emphasis>File</emphasis>, <emphasis>Sqlite</emphasis>,
      <emphasis>Memcache</emphasis>...) through a flexible system of IDs and tags. Using those, it
      is easy to delete specific types of records afterwards (for example: "delete all cache records
      marked with a given tag").
    </para>

    <para>
        The core of the module (<classname>Zend_Cache_Core</classname>) is generic, flexible and
        configurable. Yet, for your specific needs there are cache frontends that extend
        <classname>Zend_Cache_Core</classname> for convenience: <emphasis>Output</emphasis>,
        <emphasis>File</emphasis>, <emphasis>Function</emphasis> and <emphasis>Class</emphasis>.
    </para>

    <example id="zend.cache.introduction.example-1">
        <title>Getting a Frontend with Zend_Cache::factory()</title>

        <para>
            <methodname>Zend_Cache::factory()</methodname> instantiates correct objects and ties
            them together. In this first example, we will use <emphasis>Core</emphasis> frontend
            together with <emphasis>File</emphasis> backend.
        </para>

        <programlisting language="php"><![CDATA[
$frontendOptions = array(
   'lifetime' => 7200, // cache lifetime of 2 hours
   'automatic_serialization' => true
);

$backendOptions = array(
    'cache_dir' => './tmp/' // Directory where to put the cache files
);

// getting a Zend_Cache_Core object
$cache = Zend_Cache::factory('Core',
                             'File',
                             $frontendOptions,
                             $backendOptions);
]]></programlisting>
    </example>

    <note>
        <title>Frontends and Backends Consisting of Multiple Words</title>

        <para>
            Some frontends and backends are named using multiple words, such
            as 'ZendPlatform'. When specifying them to the factory, separate
            them using a word separator, such as a space (' '), hyphen
            ('-'), or period ('.').
        </para>
    </note>

    <example id="zend.cache.introduction.example-2">
        <title>Caching a Database Query Result</title>

        <para>
            Now that we have a frontend, we can cache any type of data (we turned on serialization).
            for example, we can cache a result from a very expensive database query. After it is
            cached, there is no need to even connect to the database; records are fetched from cache
            and unserialized.
        </para>

        <programlisting language="php"><![CDATA[
// $cache initialized in previous example

// see if a cache already exists:
if( ($result = $cache->load('myresult')) === false ) {

    // cache miss; connect to the database

    $db = Zend_Db::factory( [...] );

    $result = $db->fetchAll('SELECT * FROM huge_table');

    $cache->save($result, 'myresult');

} else {

    // cache hit! shout so that we know
    echo "This one is from cache!\n\n";

}

print_r($result);
]]></programlisting>
    </example>

    <example id="zend.cache.introduction.example-3">
        <title>Caching Output with Zend_Cache Output Frontend</title>

        <para>
            We 'mark up' sections in which we want to cache output by adding some conditional logic,
            encapsulating the section within <methodname>start()</methodname> and
            <methodname>end()</methodname> methods (this resembles the first example and is the core
            strategy for caching).
        </para>

        <para>
            Inside, output your data as usual - all output will be cached when execution hits the
            <methodname>end()</methodname> method. On the next run, the whole section will be
            skipped in favor of fetching data from cache (as long as the cache record is valid).
        </para>

        <programlisting language="php"><![CDATA[
$frontendOptions = array(
   'lifetime' => 30,                   // cache lifetime of 30 seconds
   'automatic_serialization' => false  // this is the default anyways
);

$backendOptions = array('cache_dir' => './tmp/');

$cache = Zend_Cache::factory('Output',
                             'File',
                             $frontendOptions,
                             $backendOptions);

// we pass a unique identifier to the start() method
if(!$cache->start('mypage')) {
    // output as usual:

    echo 'Hello world! ';
    echo 'This is cached ('.time().') ';

    $cache->end(); // the output is saved and sent to the browser
}

echo 'This is never cached ('.time().').';
]]></programlisting>

        <para>
            Notice that we output the result of <methodname>time()</methodname> twice; this is
            something dynamic for demonstration purposes. Try running this and then refreshing
            several times; you will notice that the first number doesn't change while second changes
            as time passes. That is because the first number was output in the cached section and is
            saved among other output. After half a minute (we've set lifetime to 30 seconds) the
            numbers should match again because the cache record expired -- only to be cached again.
            You should try this in your browser or console.
        </para>
    </example>

    <note>
        <para>
            When using <classname>Zend_Cache</classname>, pay attention to the important cache
            identifier (passed to <methodname>save()</methodname> and
            <methodname>start()</methodname>). It must be unique for every resource you cache,
            otherwise unrelated cache records may wipe each other or, even worse, be displayed in
            place of the other.
        </para>
    </note>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->