cvs: peardoc /en/package/caching/cache-lite constants.xml intro.xml

From:	Fabien MARTY	Date:	Sun, 23 May 2004 19:28:49 +0000
Subject:	cvs: peardoc /en/package/caching/cache-lite constants.xml intro.xml
Groups:	php.pear.doc
Request:	Send a blank email to pear-doc+get-4079@lists.php.net to get a copy of this message

fab Sun May 23 15:28:49 2004 EDT Added files: /peardoc/en/package/caching/cache-lite constants.xml intro.xml Log: first commit

http://cvs.php.net/co.php/peardoc/en/package/caching/cache-lite/constants.xml?r=1.1&p=1 Index: peardoc/en/package/caching/cache-lite/constants.xml +++ peardoc/en/package/caching/cache-lite/constants.xml  <refentry id="package.default.cache-lite.constants"> <refnamediv> <refname>Package Cache_Lite Constants</refname> <refpurpose>Constants defined in and used by Cache_Lite</refpurpose> </refnamediv> <refsect1 id="package.default.cache-lite.constants.details"> <title>All Constants</title> <refsect2 id="package.default.cache-lite.constants.details.lite---php"> <title> Constants defined in Lite.php </title> <para> <table> <title>Constants defined in Lite.php</title> <tgroup cols="3"> <thead> <row> <entry>Name</entry> <entry>Value</entry> <entry>Line Number</entry> </row> </thead> <tbody> <row> <entry>CACHE_LITE_ERROR_DIE</entry> <entry>8</entry> <entry>30</entry> </row> <row> <entry>CACHE_LITE_ERROR_RETURN</entry> <entry>1</entry> <entry>29</entry> </row> </tbody> </tgroup> </table> </para> </refsect2> </refsect1> </refentry>   http://cvs.php.net/co.php/peardoc/en/package/caching/cache-lite/intro.xml?r=1.1&p=1 Index: peardoc/en/package/caching/cache-lite/intro.xml +++ peardoc/en/package/caching/cache-lite/intro.xml <?xml version="1.0" encoding="iso-8859-1" ?>  <refentry id="package.caching.cache-lite.intro"> <refnamediv> <refname>Introduction</refname> <refpurpose>Introduction to Cache_Lite</refpurpose> </refnamediv> <refsect1 id="package.caching.cache-lite.intro.desc"> &title.desc; <para> PEAR::Cache_Lite is a little cache system. It's optimized for high traffic websites so it is really fast and safe (because it uses file locking and/or anti-corruption tests). </para> </refsect1> <refsect1 id="package.caching.cache-lite.intro.technical"> <title>Goals and technical details</title> <refsect2 id="package.caching.cache-lite.intro.technical.speed"> <title>speed</title> <para> Before all, PEAR::Cache_Lite has to be extremely fast. That returns the use of PEAR possible on sites with high traffic without falling in hi-level hardware solutions. </para> <para> You can find more details about cache_lite technical choices on the <ulink url="http://www.pearfr.org/index.php/fr/article/cache_lite">this document</ulink>. but the main idea is to include PEAR.php file <emphasis>ONLY</emphasis> when an error occurs (very rare). </para> </refsect2> <refsect2 id="package.caching.cache-lite.intro.technical.simplicity"> <title>simplicity</title> <para> Because the cache system is often embedded in the application layer, PEAR::Cache_Lite kernel has to be small and flexible with an adapted licence (LGPL). Advanced functionnalities are then seconded to files that extends the core. </para> </refsect2> <refsect2> <title>security</title> <para> On high traffic websites, the cache system has to be really protected against cache files corruptions (because of competior accesses in read/write mode). Very few cache systems offer a protection against this problem. </para> <para> File locking is not a perfect solution because it is useless with NFS or multithreaded servers. So in addition to it, PEAR::Cache_Lite offers two fully transparent mechanisms (based on hash keys) to guarantee the security of the datas in all circumstances. Just have a look at the link given in a previous paragraph for more details. </para> </refsect2> </refsect1> <refsect1 id="package.caching.cache-lite.intro.usage"> <title>Usage</title> <refsect2 id="package.caching.cache-lite.intro.usage.general"> <title>general usage</title> <para> Every module of Cache_Lite follows the same philophy. </para> <para> Parameters (others than default ones) are passed to the constructor by using an associative array. </para> <para> A cache file is identified by a cache ID (and eventually a group). For obvious flexibility reasons, the logic of IDs choice is left to the developer. </para> </refsect2> <refsect2 id="package.caching.cache-lite.intro.usage.core"> <title>core</title> <para> Let's start with a simple example : the page is built then recovered in an unique variable (string): <programlisting role="php"> <![CDATA[ <?php // Include the package require_once('Cache/Lite.php'); // Set a id for this cache $id = '123'; // Set a few options $options = array( 'cacheDir' => '/tmp/', 'lifeTime' => 3600 ); // Create a Cache_Lite object $Cache_Lite = new Cache_Lite($options); // Test if thereis a valide cache for this id if ($data = $Cache_Lite->get($id)) { // Cache hit ! // Content is in $data // (...) } else { // No valid cache found (you have to make the page) // Cache miss ! // Put in $data datas to put in cache // (...) $Cache_Lite->save($data); } ?> ]]> </programlisting> </para> <para> If you wish use a cache per block and not a global cache, take as example the following script: <programlisting role="php"> <![CDATA[ <?php require_once('Cache/Lite.php'); $options = array( 'cacheDir' => '/tmp/', 'lifeTime' => 3600 ); // Create a Cache_Lite object $Cache_Lite = new Cache_Lite($options); if ($data = $Cache_Lite->get('block1')) { echo($data); } else { $data = 'Data of the block 1'; $Cache_Lite->save($data); } echo('<br><br>Non cached line !<br><br>'); if ($data = $Cache_Lite->get('block2')) { echo($data); } else { $data = 'Data of the block 2'; $Cache_Lite->save($data); } ?> ]]> </programlisting> </para> </refsect2> <refsect2 id="package.caching.cache-lite.intro.usage.output"> <title>core</title> <para> However, it is not always possible to recover all the contents of a page in a single string variable. Thus Cache_Lite_Output comes to our help : <programlisting role="php"> <![CDATA[ <?php require_once('Cache/Lite/Output.php'); $options = array( 'cacheDir' => '/tmp/', 'lifeTime' => 10 ); $cache = new Cache_Lite_Output($options); if (!($cache->start('123'))) { // Cache missed... for($i=0;$i<1000;$i++) { // Making of the page... echo('0123456789'); } $cache->end(); } ?> ]]> </programlisting> </para> <para> The idea is the same for a per block usage : <programlisting role="php"> <![CDATA[ <?php require_once('Cache/Lite/Output.php'); $options = array( 'cacheDir' => '/tmp/', 'lifeTime' => 10 ); $cache = new Cache_Lite_Output($options); if (!($cache->start('block1'))) { // Cache missed... echo('Data of the block 1 !'); $cache->end(); } echo('Non cached line !'); if (!($cache->start('block2'))) { // Cache missed... echo('Data of the block 2 !'); $cache->end(); } ?> ]]> </programlisting> </para> </refsect2> <refsect2 id="package.caching.cache-lite.intro.usage.important"> <title>very important comment</title> <para> For a maximum efficiency with Cache_Lite, do not include systematically any others packages in your page. Load the modules which you have need <emphasis>ONLY </emphasis>when the page is not in the cache (and has to be recomputed) by using a conditionnal inclusion. </para> <para> The <emphasis>BAD</emphasis> way : <programlisting role="php"> <![CDATA[ <?php require_once("Cache/Lite.php"); require_once("...") require_once("...") // (...) $cache = new Cache_Lite(); if ($data = $Cache_Lite->get($id)) { // cache hit ! echo($data); } else { // page has to be (re)constructed in $data // (...) $Cache_Lite->save($data); } ?> ]]> </programlisting> </para> <para> Here is the good way (often more than two times faster) : <programlisting role="php"> <![CDATA[ <?php require_once("Cache/Lite.php"); // (...) $cache = new Cache_Lite(); if ($data = $Cache_Lite->get($id)) { // cache hit ! echo($data); } else { // page has to be (re)constructed in $data require_once("...") require_once("...") // (...) $Cache_Lite->save($data); } ?> ]]> </programlisting> </para> </refsect2> </refsect1> <refsect1 id="package.caching.cache-lite.intro.conclusion"> <title>Conclusion</title> <para> To go more far with Cache_Lite, just have a look at examples and technical details given with the package. </para> </refsect1> </refentry>