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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.cache.theory">
   4     <title>The Theory of Caching</title>
   5
   6     <para>
   7         There are three key concepts in <classname>Zend_Cache</classname>. One is the unique
   8         identifier (a string) that is used to identify cache records. The second one is the
   9         <emphasis>'lifetime'</emphasis> directive as seen in the examples; it defines for how long
  10         the cached resource is considered 'fresh'. The third key concept is conditional execution so
  11         that parts of your code can be skipped entirely, boosting performance. The main frontend
  12         function (e.g. <methodname>Zend_Cache_Core::get()</methodname>) is always designed to return
  13         <constant>FALSE</constant> for a cache miss if that makes sense for the nature of a
  14         frontend. That enables
  15         end-users to wrap parts of the code they would like to cache (and skip) in
  16         <emphasis><methodname>if()</methodname>{ ... }</emphasis> statements where the condition is
  17         a <classname>Zend_Cache</classname> method itself. On the end if these blocks you must save
  18         what you've generated, however (e.g. <methodname>Zend_Cache_Core::save()</methodname>).
  19     </para>
  20
  21     <note>
  22         <para>
  23             The conditional execution design of your generating code is not necessary in some
  24             frontends (<emphasis>Function</emphasis>, for an example) when the whole logic is
  25             implemented inside the frontend.
  26         </para>
  27     </note>
  28
  29     <note>
  30         <para>
  31             'Cache hit' is a term for a condition when a cache record is found, is valid and is
  32             'fresh' (in other words hasn't expired yet). 'Cache miss' is everything else. When a
  33             cache miss happens, you must generate your data (as you would normally do) and have it
  34             cached. When you have a cache hit, on the other hand, the backend automatically fetches
  35             the record from cache transparently.
  36         </para>
  37     </note>
  38
  39     <sect2 id="zend.cache.factory">
  40         <title>The Zend_Cache Factory Method</title>
  41
  42         <para>
  43             A good way to build a usable instance of a <classname>Zend_Cache</classname> Frontend is
  44             given in the following example :
  45         </para>
  46
  47         <programlisting language="php"><![CDATA[
  48 // We choose a backend (for example 'File' or 'Sqlite'...)
  49 $backendName = '[...]';
  50
  51 // We choose a frontend (for example 'Core', 'Output', 'Page'...)
  52 $frontendName = '[...]';
  53
  54 // We set an array of options for the chosen frontend
  55 $frontendOptions = array([...]);
  56
  57 // We set an array of options for the chosen backend
  58 $backendOptions = array([...]);
  59
  60 // We create an instance of Zend_Cache
  61 // (of course, the two last arguments are optional)
  62 $cache = Zend_Cache::factory($frontendName,
  63                              $backendName,
  64                              $frontendOptions,
  65                              $backendOptions);
  66 ]]></programlisting>
  67
  68         <para>
  69             In the following examples we will assume that the <varname>$cache</varname> variable
  70             holds a valid, instantiated frontend as shown and that you understand how to pass
  71             parameters to your chosen backends.
  72         </para>
  73
  74         <note>
  75             <para>
  76                 Always use <methodname>Zend_Cache::factory()</methodname> to get frontend instances.
  77                 Instantiating frontends and backends yourself will not work as expected.
  78             </para>
  79         </note>
  80     </sect2>
  81
  82     <sect2 id="zend.cache.tags">
  83         <title>Tagging Records</title>
  84
  85         <para>
  86             Tags are a way to categorize cache records. When you save a cache with the
  87             <methodname>save()</methodname> method, you can set an array of tags to apply for this
  88             record. Then you will be able to clean all cache records tagged with a given tag (or
  89             tags):
  90         </para>
  91
  92         <programlisting language="php"><![CDATA[
  93 $cache->save($huge_data, 'myUniqueID', array('tagA', 'tagB', 'tagC'));
  94 ]]></programlisting>
  95
  96         <note>
  97             <para>
  98                 note than the <methodname>save()</methodname> method accepts an optional fourth
  99                 argument: <varname>$specificLifetime</varname> (if != <constant>FALSE</constant>,
 100                 it sets a specific lifetime for this particular cache record)
 101             </para>
 102         </note>
 103     </sect2>
 104
 105     <sect2 id="zend.cache.clean">
 106         <title>Cleaning the Cache</title>
 107
 108         <para>
 109             To remove or invalidate in particular cache id, you can use the
 110             <methodname>remove()</methodname> method :
 111         </para>
 112
 113         <programlisting language="php"><![CDATA[
 114 $cache->remove('idToRemove');
 115 ]]></programlisting>
 116
 117         <para>
 118             To remove or invalidate several cache ids in one operation, you can use the
 119             <methodname>clean()</methodname> method. For example to remove all cache records :
 120         </para>
 121
 122         <programlisting language="php"><![CDATA[
 123 // clean all records
 124 $cache->clean(Zend_Cache::CLEANING_MODE_ALL);
 125
 126 // clean only outdated
 127 $cache->clean(Zend_Cache::CLEANING_MODE_OLD);
 128 ]]></programlisting>
 129
 130         <para>
 131             If you want to remove cache entries matching the tags 'tagA' and 'tagC':
 132         </para>
 133
 134         <programlisting language="php"><![CDATA[
 135 $cache->clean(
 136     Zend_Cache::CLEANING_MODE_MATCHING_TAG,
 137     array('tagA', 'tagC')
 138 );
 139 ]]></programlisting>
 140
 141         <para>
 142             If you want to remove cache entries not matching the tags 'tagA' or 'tagC':
 143         </para>
 144
 145         <programlisting language="php"><![CDATA[
 146 $cache->clean(
 147     Zend_Cache::CLEANING_MODE_NOT_MATCHING_TAG,
 148     array('tagA', 'tagC')
 149 );
 150 ]]></programlisting>
 151
 152         <para>
 153             If you want to remove cache entries matching the tags 'tagA' or 'tagC':
 154         </para>
 155
 156         <programlisting language="php"><![CDATA[
 157 $cache->clean(
 158     Zend_Cache::CLEANING_MODE_MATCHING_ANY_TAG,
 159     array('tagA', 'tagC')
 160 );
 161 ]]></programlisting>
 162
 163         <para>
 164             Available cleaning modes are: <constant>CLEANING_MODE_ALL</constant>,
 165             <constant>CLEANING_MODE_OLD</constant>, <constant>CLEANING_MODE_MATCHING_TAG</constant>,
 166             <constant>CLEANING_MODE_NOT_MATCHING_TAG</constant> and
 167             <constant>CLEANING_MODE_MATCHING_ANY_TAG</constant>. The latter are, as their names
 168             suggest, combined with an array of tags in cleaning operations.
 169         </para>
 170     </sect2>
 171 </sect1>
 172 <!--
 173 vim:se ts=4 sw=4 et:
 174 -->