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>
            <note>
                <para>
                    This frontend operates by registering a callback function to be called
                    when the output buffering it uses is cleaned. In order for this to operate
                    correctly, it must be the final output buffer in the request. To guarantee
                    this, the output buffering used by the Dispatcher needs to be disabled by
                    calling <classname>Zend_Controller_Front<classname>'s <methodname>setParam()
                    <methodname> method, for example, $front->setParam('disableOutputBuffering',
                    true)</classname> or adding
                    "resources.frontcontroller.params.disableOutputBuffering = true"
                    to your bootstrap configuration file (assumed INI) if using
                    </classname>Zend_Application</classname>.
                </para>
            <note>
        </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:
-->