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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.cache.theory">
    <title>The Theory of Caching</title>
    <para>
        There are three key concepts in <classname>Zend_Cache</classname>. One is the unique identifier (a string) that is used
        to identify cache records. The second one is the <code>'lifetime'</code> directive as seen in the
        examples; it defines for how long the cached resource is considered 'fresh'. The third key concept
        is conditional execution so that parts of your code can be skipped entirely, boosting performance.
        The main frontend function (eg. <classname>Zend_Cache_Core::get()</classname>) is always designed to return
        false for a cache miss if that makes sense for the nature of a frontend. That enables end-users to
        wrap parts of the code they would like to cache (and skip) in <code>if(){ ... }</code> statements where
        the condition is a <classname>Zend_Cache</classname> method itself. On the end if these blocks you must save what you've
        generated, however (eg. <classname>Zend_Cache_Core::save()</classname>).
    </para>
    <note><para>
        The conditional execution design of your generating code is not necessary in some frontends
        (<code>Function</code>, for an example) when the whole logic is implemented inside the frontend.
    </para></note>
    <note><para>
        'Cache hit' is a term for a condition when a cache record is found, is valid and is 'fresh' (in other
        words hasn't expired yet). 'Cache miss' is everything else. When a cache miss happens, you must
        generate your data (as you would normally do) and have it cached. When you have a cache hit, on the
        other hand, the backend automatically fetches the record from cache transparently.
    </para></note>
    <sect2 id="zend.cache.factory">
        <title>The Zend_Cache Factory Method</title>
        <para>
            A good way to build a usable instance of a <classname>Zend_Cache</classname> Frontend is given
            in the following example :
        </para>
        <programlisting role="php"><![CDATA[
// We choose a backend (for example 'File' or 'Sqlite'...)
$backendName = '[...]';

// We choose a frontend (for example 'Core', 'Output', 'Page'...)
$frontendName = '[...]';

// We set an array of options for the choosen frontend
$frontendOptions = array([...]);

// We set an array of options for the choosen backend
$backendOptions = array([...]);

// We create an instance of Zend_Cache
// (of course, the two last arguments are optional)
$cache = Zend_Cache::factory($frontendName,
                             $backendName,
                             $frontendOptions,
                             $backendOptions);
]]></programlisting>
        <para>
            In the following examples we will assume that the <code>$cache</code> variable holds a
            valid, instantiated frontend as shown and that you understand how to pass parameters
            to your chosen backends.
        </para>
        <note><para>
            Always use <classname>Zend_Cache::factory()</classname> to get frontend instances. Instantiating
            frontends and backends yourself will not work as expected.
        </para></note>
    </sect2>

    <sect2 id="zend.cache.tags">
        <title>Tagging Records</title>
        <para>
            Tags are a way to categorize cache records. When you save a cache with the <code>save()</code>
            method, you can set an array of tags to apply for this record. Then you will be
            able to clean all cache records tagged with a given tag (or tags):
        </para>
        <programlisting role="php"><![CDATA[
$cache->save($huge_data, 'myUniqueID', array('tagA', 'tagB', 'tagC'));
]]></programlisting>
        <note><para>
            note than the <code>save()</code> method accepts an optional fourth argument : <code>$specificLifetime</code>
            (if != false, it sets a specific lifetime for this particular cache record)
        </para></note>
    </sect2>
    <sect2 id="zend.cache.clean">
        <title>Cleaning the Cache</title>
        <para>
            To remove/invalidate in particular cache id, you can use the <code>remove()</code>
            method :
        </para>
        <programlisting role="php"><![CDATA[
$cache->remove('idToRemove');
]]></programlisting>
        <para>
            To remove/invalidate several cache ids in one operation, you can use the <code>clean()</code>
            method. For example to remove all cache records :
        </para>
        <programlisting role="php"><![CDATA[
// clean all records
$cache->clean(Zend_Cache::CLEANING_MODE_ALL);

// clean only outdated
$cache->clean(Zend_Cache::CLEANING_MODE_OLD);
]]></programlisting>
        <para>
            If you want to remove cache entries matching the tags 'tagA' and 'tagC':
        </para>
        <programlisting role="php"><![CDATA[
$cache->clean(
    Zend_Cache::CLEANING_MODE_MATCHING_TAG,
    array('tagA', 'tagC')
);
]]></programlisting>
        <para>
            If you want to remove cache entries not matching the tags 'tagA' or 'tagC':
        </para>
        <programlisting role="php"><![CDATA[
$cache->clean(
    Zend_Cache::CLEANING_MODE_NOT_MATCHING_TAG,
    array('tagA', 'tagC')
);
]]></programlisting>
        <para>
            If you want to remove cache entries matching the tags 'tagA' or 'tagC':
        </para>
        <programlisting role="php"><![CDATA[
$cache->clean(
    Zend_Cache::CLEANING_MODE_MATCHING_ANY_TAG,
    array('tagA', 'tagC')
);
]]></programlisting>
        <para>
            Available cleaning modes are: <code>CLEANING_MODE_ALL</code>, <code>CLEANING_MODE_OLD</code>,
            <code>CLEANING_MODE_MATCHING_TAG</code>, <code>CLEANING_MODE_NOT_MATCHING_TAG</code> and
            <code>CLEANING_MODE_MATCHING_ANY_TAG</code>.
            The latter are, as their names suggest, combined with an array of tags in cleaning operations.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->