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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.cache.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   7         <classname>Zend_Cache</classname> provides a generic way to cache any data.
   8     </para>
   9
  10     <para>
  11       Caching in Zend Framework is operated by frontends while cache records are stored through
  12       backend adapters (<emphasis>File</emphasis>, <emphasis>Sqlite</emphasis>,
  13       <emphasis>Memcache</emphasis>...) through a flexible system of IDs and tags. Using those, it
  14       is easy to delete specific types of records afterwards (for example: "delete all cache records
  15       marked with a given tag").
  16     </para>
  17
  18     <para>
  19         The core of the module (<classname>Zend_Cache_Core</classname>) is generic, flexible and
  20         configurable. Yet, for your specific needs there are cache frontends that extend
  21         <classname>Zend_Cache_Core</classname> for convenience: <emphasis>Output</emphasis>,
  22         <emphasis>File</emphasis>, <emphasis>Function</emphasis> and <emphasis>Class</emphasis>.
  23     </para>
  24
  25     <example id="zend.cache.introduction.example-1">
  26         <title>Getting a Frontend with Zend_Cache::factory()</title>
  27
  28         <para>
  29             <methodname>Zend_Cache::factory()</methodname> instantiates correct objects and ties
  30             them together. In this first example, we will use <emphasis>Core</emphasis> frontend
  31             together with <emphasis>File</emphasis> backend.
  32         </para>
  33
  34         <programlisting language="php"><![CDATA[
  35 $frontendOptions = array(
  36    'lifetime' => 7200, // cache lifetime of 2 hours
  37    'automatic_serialization' => true
  38 );
  39
  40 $backendOptions = array(
  41     'cache_dir' => './tmp/' // Directory where to put the cache files
  42 );
  43
  44 // getting a Zend_Cache_Core object
  45 $cache = Zend_Cache::factory('Core',
  46                              'File',
  47                              $frontendOptions,
  48                              $backendOptions);
  49 ]]></programlisting>
  50     </example>
  51
  52     <note>
  53         <title>Frontends and Backends Consisting of Multiple Words</title>
  54
  55         <para>
  56             Some frontends and backends are named using multiple words, such
  57             as 'ZendPlatform'. When specifying them to the factory, separate
  58             them using a word separator, such as a space (' '), hyphen
  59             ('-'), or period ('.').
  60         </para>
  61     </note>
  62
  63     <example id="zend.cache.introduction.example-2">
  64         <title>Caching a Database Query Result</title>
  65
  66         <para>
  67             Now that we have a frontend, we can cache any type of data (we turned on serialization).
  68             for example, we can cache a result from a very expensive database query. After it is
  69             cached, there is no need to even connect to the database; records are fetched from cache
  70             and unserialized.
  71         </para>
  72
  73         <programlisting language="php"><![CDATA[
  74 // $cache initialized in previous example
  75
  76 // see if a cache already exists:
  77 if(!$result = $cache->load('myresult')) {
  78
  79     // cache miss; connect to the database
  80
  81     $db = Zend_Db::factory( [...] );
  82
  83     $result = $db->fetchAll('SELECT * FROM huge_table');
  84
  85     $cache->save($result, 'myresult');
  86
  87 } else {
  88
  89     // cache hit! shout so that we know
  90     echo "This one is from cache!\n\n";
  91
  92 }
  93
  94 print_r($result);
  95 ]]></programlisting>
  96     </example>
  97
  98     <example id="zend.cache.introduction.example-3">
  99         <title>Caching Output with Zend_Cache Output Frontend</title>
 100
 101         <para>
 102             We 'mark up' sections in which we want to cache output by adding some conditional logic,
 103             encapsulating the section within <methodname>start()</methodname> and
 104             <methodname>end()</methodname> methods (this resembles the first example and is the core
 105             strategy for caching).
 106         </para>
 107
 108         <para>
 109             Inside, output your data as usual - all output will be cached when execution hits the
 110             <methodname>end()</methodname> method. On the next run, the whole section will be
 111             skipped in favor of fetching data from cache (as long as the cache record is valid).
 112         </para>
 113
 114         <programlisting language="php"><![CDATA[
 115 $frontendOptions = array(
 116    'lifetime' => 30,                   // cache lifetime of 30 seconds
 117    'automatic_serialization' => false  // this is the default anyways
 118 );
 119
 120 $backendOptions = array('cache_dir' => './tmp/');
 121
 122 $cache = Zend_Cache::factory('Output',
 123                              'File',
 124                              $frontendOptions,
 125                              $backendOptions);
 126
 127 // we pass a unique identifier to the start() method
 128 if(!$cache->start('mypage')) {
 129     // output as usual:
 130
 131     echo 'Hello world! ';
 132     echo 'This is cached ('.time().') ';
 133
 134     $cache->end(); // the output is saved and sent to the browser
 135 }
 136
 137 echo 'This is never cached ('.time().').';
 138 ]]></programlisting>
 139
 140         <para>
 141             Notice that we output the result of <methodname>time()</methodname> twice; this is
 142             something dynamic for demonstration purposes. Try running this and then refreshing
 143             several times; you will notice that the first number doesn't change while second changes
 144             as time passes. That is because the first number was output in the cached section and is
 145             saved among other output. After half a minute (we've set lifetime to 30 seconds) the
 146             numbers should match again because the cache record expired -- only to be cached again.
 147             You should try this in your browser or console.
 148         </para>
 149     </example>
 150
 151     <note>
 152         <para>
 153             When using <classname>Zend_Cache</classname>, pay attention to the important cache
 154             identifier (passed to <methodname>save()</methodname> and
 155             <methodname>start()</methodname>). It must be unique for every resource you cache,
 156             otherwise unrelated cache records may wipe each other or, even worse, be displayed in
 157             place of the other.
 158         </para>
 159     </note>
 160 </sect1>
 161 <!--
 162 vim:se ts=4 sw=4 et:
 163 -->