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

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

    <sect2 id="zend.cache.frontends.core">
        <title>Zend_Cache_Core</title>
        <sect3 id="zend.cache.frontends.core.introduction">
            <title>Introduction</title>
            <para>
                <classname>Zend_Cache_Core</classname> is a special frontend because it is the core
                of the module. It is a generic cache frontend and is extended by other classes.
            </para>
            <note><para>
                All frontends inherit from <classname>Zend_Cache_Core</classname> so that its
                methods and options (described below) would also be available in other frontends,
                therefore they won't be documented there.
            </para></note>
        </sect3>
        <sect3 id="zend.cache.frontends.core.options">
            <title>Available options</title>
            <para>
                These options are passed to the factory method as demonstrated in previous examples.
            </para>
            <table id="zend.cache.frontends.core.options.table">
                <title>Core Frontend Options</title>
                <tgroup cols="4">
                     <thead>
                          <row>
                            <entry>Option</entry>
                            <entry>Data Type</entry>
                            <entry>Default Value</entry>
                            <entry>Description</entry>
                        </row>
                     </thead>
                     <tbody>
                          <row>
                              <entry><emphasis>caching</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>TRUE</constant></entry>
                              <entry>
                                  enable / disable caching (can be very useful for the debug of
                                  cached scripts)
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>cache_id_prefix</emphasis></entry>
                              <entry><type>String</type></entry>
                              <entry><constant>NULL</constant></entry>
                              <entry>
                                A prefix for all cache ids, if set to <constant>NULL</constant>, no
                                cache id prefix will be used. The cache id prefix essentially
                                creates a namespace in the cache, allowing multiple applications or
                                websites to use a shared cache. Each application or website can use
                                a different cache id prefix so specific cache ids can be used more
                                than once.
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>lifetime</emphasis></entry>
                              <entry><type>Integer</type></entry>
                              <entry>3600</entry>
                              <entry>
                                cache lifetime (in seconds), if set to <constant>NULL</constant>,
                                the cache is valid forever.
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>logging</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>FALSE</constant></entry>
                              <entry>
                                if set to <constant>TRUE</constant>, logging through
                                <classname>Zend_Log</classname> is
                                activated (but the system is slower)
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>write_control</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>TRUE</constant></entry>
                              <entry>
                                Enable / disable write control (the cache is read just
                                after writing to detect corrupt entries), enabling write_control
                                will lightly slow the cache writing but not the cache reading (it
                                can detect some corrupt cache files but it's not a perfect control)
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>automatic_serialization</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>FALSE</constant></entry>
                              <entry>
                                Enable / disable automatic serialization, it can be used to save
                                directly datas which aren't strings (but it's slower)
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>automatic_cleaning_factor</emphasis></entry>
                              <entry><type>Integer</type></entry>
                              <entry>10</entry>
                              <entry>
                                Disable / Tune the automatic cleaning process (garbage collector):
                                0 means no automatic cache cleaning, 1 means systematic cache
                                cleaning and x &gt; 1 means automatic random cleaning 1 times in x
                                write operations.
                              </entry>
                          </row>
                          <row>
                              <entry><emphasis>ignore_user_abort</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>FALSE</constant></entry>
                              <entry>
                                if set to <constant>TRUE</constant>, the core will set the
                                ignore_user_abort <acronym>PHP</acronym> flag inside the
                                <methodname>save()</methodname> method to avoid cache
                                corruptions in some cases
                              </entry>
                          </row>
                      </tbody>
                  </tgroup>
              </table>
        </sect3>

        <sect3 id="zend.cache.core.examples">
            <title>Examples</title>
            <para>
                An example is given in the manual at the very beginning.
            </para>
            <para>
                If you store only strings into cache (because with "automatic_serialization" option,
                it's possible to store some booleans), you can use a more compact construction like:
            </para>
            <programlisting language="php"><![CDATA[
// we assume you already have $cache

$id = 'myBigLoop'; // cache id of "what we want to cache"

if (!($data = $cache->load($id))) {
    // cache miss

    $data = '';
    for ($i = 0; $i < 10000; $i++) {
        $data = $data . $i;
    }

    $cache->save($data);

}

// [...] do something with $data (echo it, pass it on etc.)
]]></programlisting>
            <para>
                If you want to cache multiple blocks or data instances, the idea is the same:
            </para>
            <programlisting language="php"><![CDATA[
// make sure you use unique identifiers:
$id1 = 'foo';
$id2 = 'bar';

// block 1
if (!($data = $cache->load($id1))) {
    // cache missed

    $data = '';
    for ($i=0;$i<10000;$i++) {
        $data = $data . $i;
    }

    $cache->save($data);

}
echo($data);

// this isn't affected by caching
echo('NEVER CACHED! ');

// block 2
if (!($data = $cache->load($id2))) {
    // cache missed

    $data = '';
    for ($i=0;$i<10000;$i++) {
        $data = $data . '!';
    }

    $cache->save($data);

}
echo($data);
]]></programlisting>
            <para>
                If you want to cache special values (boolean with "automatic_serialization" option)
                or empty strings you can't use the compact construction given above. You have to
                test formally the cache record.
            </para>
            <programlisting language="php"><![CDATA[
// the compact construction
// (not good if you cache empty strings and/or booleans)
if (!($data = $cache->load($id))) {

    // cache missed

    // [...] we make $data

    $cache->save($data);

}

// we do something with $data

// [...]

// the complete construction (works in any case)
if (!($cache->test($id))) {

    // cache missed

    // [...] we make $data

    $cache->save($data);

} else {

    // cache hit

    $data = $cache->load($id);

}

// we do something with $data
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.cache.frontends.output">
        <title>Zend_Cache_Frontend_Output</title>
        <sect3 id="zend.cache.frontends.output.introduction">
            <title>Introduction</title>
            <para>
                <classname>Zend_Cache_Frontend_Output</classname> is an output-capturing frontend.
                It utilizes output buffering in <acronym>PHP</acronym> to capture everything
                between its <methodname>start()</methodname> and <methodname>end()</methodname>
                methods.
            </para>
        </sect3>
        <sect3 id="zend.cache.frontends.output.options">
            <title>Available Options</title>
            <para>
                This frontend doesn't have any specific options other than those of
                <classname>Zend_Cache_Core</classname>.
            </para>
        </sect3>

        <sect3 id="zend.cache.frontends.output.examples">
            <title>Examples</title>
            <para>
                An example is given in the manual at the very beginning. Here it is with minor
                changes:
            </para>
            <programlisting language="php"><![CDATA[
// if it is a cache miss, output buffering is triggered
if (!($cache->start('mypage'))) {

    // output everything as usual
    echo 'Hello world! ';
    echo 'This is cached ('.time().') ';

    $cache->end(); // output buffering ends

}

echo 'This is never cached ('.time().').';
]]></programlisting>
            <para>
                Using this form it is fairly easy to set up output caching in your already working
                project with little or no code refactoring.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.cache.frontends.function">
        <title>Zend_Cache_Frontend_Function</title>
        <sect3 id="zend.cache.frontends.function.introduction">
            <title>Introduction</title>
            <para>
                <classname>Zend_Cache_Frontend_Function</classname> caches the results of function
                calls. It has a single main method named <methodname>call()</methodname> which takes
                a function name and parameters for the call in an array.
            </para>
        </sect3>
        <sect3 id="zend.cache.frontends.function.options">
            <title>Available Options</title>
            <table id="zend.cache.frontends.function.options.table">
                <title>Function Frontend Options</title>
                <tgroup cols="4">
                     <thead>
                          <row>
                            <entry>Option</entry>
                            <entry>Data Type</entry>
                            <entry>Default Value</entry>
                            <entry>Description</entry>
                        </row>
                     </thead>
                     <tbody>
                          <row>
                              <entry><emphasis>cache_by_default</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>TRUE</constant></entry>
                              <entry>
                                  if <constant>TRUE</constant>, function calls will be cached by
                                  default
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>cached_functions</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry></entry>
                              <entry>
                                  function names which will always be cached
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>non_cached_functions</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry></entry>
                              <entry>
                                  function names which must never be cached
                              </entry>
                         </row>
                      </tbody>
                  </tgroup>
              </table>
        </sect3>

        <sect3 id="zend.cache.frontends.function.examples">
            <title>Examples</title>
            <para>
                Using the <methodname>call()</methodname> function is the same as using
                <methodname>call_user_func_array()</methodname> in <acronym>PHP</acronym>:
            </para>
            <programlisting language="php"><![CDATA[
$cache->call('veryExpensiveFunc', $params);

// $params is an array
// For example to call veryExpensiveFunc(1, 'foo', 'bar') with
// caching, you can use
// $cache->call('veryExpensiveFunc', array(1, 'foo', 'bar'))
]]></programlisting>
            <para>
                <classname>Zend_Cache_Frontend_Function</classname> is smart enough to cache both
                the return value of the function and its internal output.
            </para>
            <note><para>
                You can pass any built in or user defined function with the exception of
                <methodname>array()</methodname>, <methodname>echo()</methodname>,
                <methodname>empty()</methodname>, <methodname>eval()</methodname>,
                <methodname>exit()</methodname>, <methodname>isset()</methodname>,
                <methodname>list()</methodname>, <methodname>print()</methodname> and
                <methodname>unset()</methodname>.
            </para></note>
        </sect3>
    </sect2>

    <sect2 id="zend.cache.frontends.class">
        <title>Zend_Cache_Frontend_Class</title>
        <sect3 id="zend.cache.frontends.class.introduction">
            <title>Introduction</title>
            <para>
                <classname>Zend_Cache_Frontend_Class</classname> is different from
                <classname>Zend_Cache_Frontend_Function</classname> because it allows caching of
                object and static method calls.
            </para>
        </sect3>
        <sect3 id="zend.cache.frontends.class.options">
            <title>Available Options</title>
            <table id="zend.cache.frontends.class.options.table">
                <title>Class Frontend Options</title>
                <tgroup cols="4">
                     <thead>
                          <row>
                            <entry>Option</entry>
                            <entry>Data Type</entry>
                            <entry>Default Value</entry>
                            <entry>Description</entry>
                        </row>
                     </thead>
                     <tbody>
                          <row>
                              <entry><emphasis>cached_entity</emphasis> (required)</entry>
                              <entry><type>Mixed</type></entry>
                              <entry></entry>
                              <entry>
                                  if set to a class name, we will cache an abstract class and will
                                  use only static calls; if set to an object, we will cache this
                                  object methods
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>cache_by_default</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>TRUE</constant></entry>
                              <entry>
                                  if <constant>TRUE</constant>, calls will be cached by default
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>cached_methods</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry></entry>
                              <entry>
                                  method names which will always be cached
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>non_cached_methods</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry></entry>
                              <entry>
                                  method names which must never be cached
                              </entry>
                         </row>
                      </tbody>
                  </tgroup>
              </table>
        </sect3>

        <sect3 id="zend.cache.frontends.class.examples">
            <title>Examples</title>
            <para>
                For example, to cache static calls :
            </para>
            <programlisting language="php"><![CDATA[
class Test {

    // Static method
    public static function foobar($param1, $param2) {
        echo "foobar_output($param1, $param2)";
        return "foobar_return($param1, $param2)";
    }

}

// [...]
$frontendOptions = array(
    'cached_entity' => 'Test' // The name of the class
);
// [...]

// The cached call
$result = $cache->foobar('1', '2');
]]></programlisting>
            <para>
                To cache classic method calls :
            </para>
            <programlisting language="php"><![CDATA[
class Test {

    private $_string = 'hello !';

    public function foobar2($param1, $param2) {
        echo($this->_string);
        echo "foobar2_output($param1, $param2)";
        return "foobar2_return($param1, $param2)";
    }

}

// [...]
$frontendOptions = array(
    'cached_entity' => new Test() // An instance of the class
);
// [...]

// The cached call
$result = $cache->foobar2('1', '2');
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.cache.frontends.file">
        <title>Zend_Cache_Frontend_File</title>
        <sect3 id="zend.cache.frontends.file.introduction">
            <title>Introduction</title>
            <para>
                <classname>Zend_Cache_Frontend_File</classname> is a frontend driven by the
                modification time of a "master file". It's really interesting for examples
                in configuration or templates issues. It's also possible to use multiple
                master files.
            </para>
            <para>
                For instance, you have an <acronym>XML</acronym> configuration file which is parsed
                by a function which returns a "config object" (like with
                <classname>Zend_Config</classname>). With
                <classname>Zend_Cache_Frontend_File</classname>, you can store the "config object"
                into cache (to avoid the parsing of the <acronym>XML</acronym> config file at each
                time) but with a sort of strong dependency on the "master file". So, if the
                <acronym>XML</acronym> config file is modified, the cache is immediately
                invalidated.
            </para>
        </sect3>
        <sect3 id="zend.cache.frontends.file.options">
            <title>Available Options</title>
            <table id="zend.cache.frontends.file.options.table">
                <title>File Frontend Options</title>
                <tgroup cols="4">
                     <thead>
                          <row>
                            <entry>Option</entry>
                            <entry>Data Type</entry>
                            <entry>Default Value</entry>
                            <entry>Description</entry>
                        </row>
                     </thead>
                     <tbody>
                          <row>
                              <entry><emphasis>master_file (deprecated)</emphasis></entry>
                              <entry><type>String</type></entry>
                              <entry>''</entry>
                              <entry>
                                  the complete path and name of the master file
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>master_files</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry><methodname>array()</methodname></entry>
                              <entry>
                                  an array of complete path of master files
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>master_files_mode</emphasis></entry>
                              <entry><type>String</type></entry>
                              <entry>
                                  <constant>Zend_Cache_Frontend_File::MODE_OR</constant>
                              </entry>
                              <entry>
                                  <constant>Zend_Cache_Frontend_File::MODE_AND</constant> or
                                  <constant>Zend_Cache_Frontend_File::MODE_OR</constant> ; if
                                  <constant>MODE_AND</constant>, then all master files have to be
                                  touched to get a cache invalidation if
                                  <constant>MODE_OR</constant>, then a single touched master file is
                                  enough to get a cache invalidation
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>ignore_missing_master_files</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>FALSE</constant></entry>
                              <entry>
                                  if <constant>TRUE</constant>, missing master files are ignored
                                  silently (an exception is raised else)
                              </entry>
                         </row>
                      </tbody>
                  </tgroup>
              </table>
        </sect3>
        <sect3 id="zend.cache.frontends.file.examples">
            <title>Examples</title>
            <para>
                Use of this frontend is the same than of <classname>Zend_Cache_Core</classname>.
                There is no need of a specific example - the only thing to do is to
                define the <emphasis>master_file</emphasis> when using the factory.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.cache.frontends.page">
        <title>Zend_Cache_Frontend_Page</title>
        <sect3 id="zend.cache.frontends.page.introduction">
            <title>Introduction</title>
            <para>
                <classname>Zend_Cache_Frontend_Page</classname> is like
                <classname>Zend_Cache_Frontend_Output</classname> but designed for a complete page.
                It's impossible to use <classname>Zend_Cache_Frontend_Page</classname> for caching
                only a single block.
            </para>
            <para>
                On the other hand, the "cache id" is calculated automatically with
                <varname>$_SERVER['REQUEST_URI']</varname> and (depending on options)
                <varname>$_GET</varname>, <varname>$_POST</varname>, <varname>$_SESSION</varname>,
                <varname>$_COOKIE</varname>, <varname>$_FILES</varname>. More over, you have only
                one method to call (<methodname>start()</methodname>) because the
                <methodname>end()</methodname> call is fully automatic when the page is ended.
            </para>
            <para>
                For the moment, it's not implemented but we plan to add a <acronym>HTTP</acronym>
                conditional system to save bandwidth (the system will send a
                <acronym>HTTP</acronym> 304 Not Modified if the cache is hit and if the browser
                has already the good version).
            </para>
        </sect3>
        <sect3 id="zend.cache.frontends.page.options">
            <title>Available Options</title>
            <table id="zend.cache.frontends.page.options.table">
                <title>Page Frontend Options</title>
                <tgroup cols="4">
                     <thead>
                          <row>
                            <entry>Option</entry>
                            <entry>Data Type</entry>
                            <entry>Default Value</entry>
                            <entry>Description</entry>
                        </row>
                     </thead>
                     <tbody>
                          <row>
                              <entry><emphasis>http_conditional</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>FALSE</constant></entry>
                              <entry>
                                  use the http_conditional system (not implemented for the moment)
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>debug_header</emphasis></entry>
                              <entry><type>Boolean</type></entry>
                              <entry><constant>FALSE</constant></entry>
                              <entry>
                                  if <constant>TRUE</constant>, a debug text is added before each
                                  cached pages
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>default_options</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry><methodname>array(...see below...)</methodname></entry>
                              <entry>
                                  an associative array of default options:
                                  <itemizedlist>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>TRUE</constant> by
                                                  default) cache</emphasis>: cache is on if
                                              <constant>TRUE</constant>
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>FALSE</constant> by
                                                  default) cache_with_get_variables</emphasis>: if
                                              <constant>TRUE</constant>,
                                              cache is still on even if there are some variables in
                                              <varname>$_GET</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>FALSE</constant> by
                                                  default) cache_with_post_variables</emphasis>: if
                                              <constant>TRUE</constant>,
                                              cache is still on even if there are some variables in
                                              <varname>$_POST</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>FALSE</constant> by
                                                  default) cache_with_session_variables</emphasis>:
                                              if <constant>TRUE</constant>,
                                              cache is still on even if there are some variables in
                                              <varname>$_SESSION</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>FALSE</constant> by
                                                  default) cache_with_files_variables</emphasis>:
                                              if <constant>TRUE</constant>,
                                              cache is still on even if there are some variables in
                                              <varname>$_FILES</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>FALSE</constant> by
                                                  default) cache_with_cookie_variables</emphasis>:
                                              if <constant>TRUE</constant>,
                                              cache is still on even if there are some variables in
                                              <varname>$_COOKIE</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>TRUE</constant> by
                                                  default) make_id_with_get_variables</emphasis>:
                                              if <constant>TRUE</constant>,
                                              the cache id will be dependent of the content of the
                                              <varname>$_GET</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>TRUE</constant> by
                                                  default) make_id_with_post_variables</emphasis>:
                                              if <constant>TRUE</constant>,
                                              the cache id will be dependent of the content of the
                                              <varname>$_POST</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>TRUE</constant> by
                                                  default)
                                                  make_id_with_session_variables</emphasis>: if
                                              <constant>TRUE</constant>,
                                              the cache id will be dependent of the content of
                                              the <varname>$_SESSION</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>TRUE</constant> by
                                                  default) make_id_with_files_variables</emphasis>:
                                              if <constant>TRUE</constant>,
                                              the cache id will be dependent of the content of the
                                              <varname>$_FILES</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(boolean, <constant>TRUE</constant> by
                                                  default)
                                                  make_id_with_cookie_variables</emphasis>: if
                                              <constant>TRUE</constant>,
                                              the cache id will be dependent of the content of
                                              the <varname>$_COOKIE</varname> array
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(int, <constant>FALSE</constant> by
                                                  default) specific_lifetime</emphasis>: if not
                                              <constant>FALSE</constant>, the
                                              given lifetime will be used for the choosen regexp
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(array, <methodname>array()</methodname> by
                                                  default) tags</emphasis>: tags for the cache
                                              record
                                          </para>
                                      </listitem>
                                      <listitem>
                                          <para>
                                              <emphasis>(int, <constant>NULL</constant> by default)
                                                  priority</emphasis>: priority (if the backend
                                              supports it)
                                          </para>
                                      </listitem>
                                  </itemizedlist>
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>regexps</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry><methodname>array()</methodname></entry>
                              <entry>
                                  an associative array to set options only for some
                                  <constant>REQUEST_URI</constant>, keys are
                                  (<acronym>PCRE</acronym>) regexps, values are associative arrays
                                  with specific options to set if the regexp matchs on
                                  <varname>$_SERVER['REQUEST_URI']</varname> (see default_options
                                  for the list of available options); if several regexps match the
                                  <varname>$_SERVER['REQUEST_URI']</varname>, only the last one
                                  will be used
                              </entry>
                         </row>
                         <row>
                              <entry><emphasis>memorize_headers</emphasis></entry>
                              <entry><type>Array</type></entry>
                              <entry><methodname>array()</methodname></entry>
                              <entry>
                                   an array of strings corresponding to some
                                   <acronym>HTTP</acronym> headers name. Listed headers will be
                                   stored with cache datas and "replayed" when the cache is hit
                              </entry>
                         </row>
                      </tbody>
                  </tgroup>
              </table>
        </sect3>
        <sect3 id="zend.cache.frontends.page.examples">
            <title>Examples</title>
            <para>
                Use of <classname>Zend_Cache_Frontend_Page</classname> is really trivial:
            </para>
            <programlisting language="php"><![CDATA[
// [...] // require, configuration and factory

$cache->start();
// if the cache is hit, the result is sent to the browser
// and the script stop here

// rest of the page ...
]]></programlisting>
            <para>
                a more complex example which shows a way to get a centralized cache management in a
                bootstrap file (for using with <classname>Zend_Controller</classname> for example)
            </para>
            <programlisting language="php"><![CDATA[
/*
 * You should avoid putting too many lines before the cache section.
 * For example, for optimal performances, "require_once" or
 * "Zend_Loader::loadClass" should be after the cache section.
 */

$frontendOptions = array(
   'lifetime' => 7200,
   'debug_header' => true, // for debugging
   'regexps' => array(
       // cache the whole IndexController
       '^/$' => array('cache' => true),

       // cache the whole IndexController
       '^/index/' => array('cache' => true),

       // we don't cache the ArticleController...
       '^/article/' => array('cache' => false),

       // ... but we cache the "view" action of this ArticleController
       '^/article/view/' => array(
           'cache' => true,

           // and we cache even there are some variables in $_POST
           'cache_with_post_variables' => true,

           // but the cache will be dependent on the $_POST array
           'make_id_with_post_variables' => true
       )
   )
);

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

// getting a Zend_Cache_Frontend_Page object
$cache = Zend_Cache::factory('Page',
                             'File',
                             $frontendOptions,
                             $backendOptions);

$cache->start();
// if the cache is hit, the result is sent to the browser and the
// script stop here

// [...] the end of the bootstrap file
// these lines won't be executed if the cache is hit
]]></programlisting>
        </sect3>
        <sect3 id="zend.cache.frontends.page.cancel">
            <title>The Specific Cancel Method</title>
            <para>
                Because of design issues, in some cases (for example when using non
                <acronym>HTTP</acronym> 200 return codes), you could need to cancel the current
                cache process. So we introduce for this particular frontend, the
                <methodname>cancel()</methodname> method.
            </para>
            <programlisting language="php"><![CDATA[
// [...] // require, configuration and factory

$cache->start();

// [...]

if ($someTest) {
    $cache->cancel();
    // [...]
}

// [...]
]]></programlisting>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->