home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 August / PCWorld_2001-08_cd.bin / Komunikace / phptriad / phptriadsetup2-11.exe / php / pear / Cache.php next >
PHP Script  |  2001-03-17  |  9KB  |  296 lines
  1. <?php
  2. // +----------------------------------------------------------------------+
  3. // | PHP version 4.0                                                      |
  4. // +----------------------------------------------------------------------+
  5. // | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group             |
  6. // +----------------------------------------------------------------------+
  7. // | This source file is subject to version 2.0 of the PHP license,       |
  8. // | that is bundled with this package in the file LICENSE, and is        |
  9. // | available at through the world-wide-web at                           |
  10. // | http://www.php.net/license/2_02.txt.                                 |
  11. // | If you did not receive a copy of the PHP license and are unable to   |
  12. // | obtain it through the world-wide-web, please send a note to          |
  13. // | license@php.net so we can mail you a copy immediately.               |
  14. // +----------------------------------------------------------------------+
  15. // | Authors: Ulf Wendel <ulf.wendel@phpdoc.de>                           |
  16. // |          Sebastian Bergmann <sb@sebastian-bergmann.de>               |
  17. // +----------------------------------------------------------------------+
  18. //
  19. // $Id: Cache.php,v 1.8 2001/03/17 16:06:31 chregu Exp $
  20.  
  21. require_once "Cache/Error.php";
  22.  
  23. /**
  24. * Cache is a base class for cache implementations.
  25. *
  26. * TODO: Simple usage example goes here.
  27. *
  28. * WARNING: No File/DB-Table-Row locking is implemented yet,
  29. *          it's possible, that you get corrupted data-entries under
  30. *          bad circumstances  (especially with the file container)
  31. *
  32. * @author   Ulf Wendel <ulf.wendel@phpdoc.de>
  33. * @version  $Id: Cache.php,v 1.8 2001/03/17 16:06:31 chregu Exp $
  34. * @package  Cache
  35. * @access   public
  36. */
  37. class Cache extends PEAR {
  38.  
  39.     /**
  40.     * Disables the caching.
  41.     *
  42.     * TODO: Add explanation what this is good for.
  43.     *
  44.     * @var      boolean
  45.     * @access   public
  46.     */
  47.     var $no_cache = false;
  48.  
  49.     /**
  50.     * Garbage collection: probability in seconds
  51.     *
  52.     * If set to a value above 0 a garbage collection will
  53.     * flush all cache entries older than the specified number
  54.     * of seconds.
  55.     *
  56.     * @var      integer
  57.     * @see      $gc_probability
  58.     * @access   public
  59.     */
  60.     var $gc_time  = 1;
  61.  
  62.     /**
  63.     * Garbage collection: probability in percent
  64.     *
  65.     * TODO: Add an explanation.
  66.     *
  67.     * @var      integer     0 => never
  68.     * @see      $gc_time
  69.     * @access   public
  70.     */
  71.     var $gc_probability = 1;
  72.  
  73.     /**
  74.     * Storage container object.
  75.     *
  76.     * @var  object Cache_Container
  77.     */
  78.     var $container;
  79.  
  80.     //
  81.     // public methods
  82.     //
  83.  
  84.     /**
  85.     *
  86.     * @param    string  Name of storage container class
  87.     * @param    array   Array with storage class dependend config options
  88.     */
  89.     function Cache($storage_driver, $storage_options = "")
  90.     {
  91.         $this->PEAR();
  92.         $storage_driver = strtolower($storage_driver);
  93.         $storage_class = 'Cache_Container_' . $storage_driver;
  94.         $storage_classfile = 'Cache/Container/' . $storage_driver . '.php';
  95.  
  96.         include_once $storage_classfile;
  97.         $this->container = new $storage_class($storage_options);
  98.     }
  99.  
  100.     //deconstructor
  101.     function _Cache()
  102.     {
  103.         $this->garbageCollection();
  104.     }
  105.  
  106.     /**
  107.     * Returns the requested dataset it if exists and is not expired
  108.     *
  109.     * @param    string  dataset ID
  110.     * @param    string  cache group
  111.     * @return   mixed   cached data or NULL on failure
  112.     * @access   public
  113.     */
  114.     function get($id, $group = "default") {
  115.         if ($this->no_cache)
  116.             return "";
  117.  
  118.         if ($this->isCached($id, $group) && !$this->isExpired($id, $group))
  119.             return $this->load($id, $group);
  120.  
  121.         return NULL;
  122.     } // end func get
  123.  
  124.     /**
  125.     * Stores the given data in the cache.
  126.     *
  127.     * @param    string  dataset ID used as cache identifier
  128.     * @param    mixed   data to cache
  129.     * @param    integer lifetime of the cached data in seconds - 0 for endless
  130.     * @param    string  cache group
  131.     * @return   boolean
  132.     * @access   public
  133.     */
  134.     function save($id, $data, $expires = 0, $group = "default") {
  135.         if ($this->no_cache)
  136.             return true;
  137.  
  138.         return $this->container->save($id, $data, $expires, $group, "");
  139.     } // end func save
  140.  
  141.     /**
  142.     * Stores a dataset without additional userdefined data.
  143.     *
  144.     * @param    string  dataset ID
  145.     * @param    mixed   data to store
  146.     * @param    string  additional userdefined data
  147.     * @param    mixed   userdefined expire date
  148.     * @param    string  cache group
  149.     * @return   boolean
  150.     * @throws   Cache_Error
  151.     * @access   public
  152.     * @see      getUserdata()
  153.     */
  154.     function extSave($id, $cachedata, $userdata, $expires = 0, $group = "default") {
  155.         if ($this->no_cache)
  156.             return true;
  157.  
  158.         return $this->container->save($id, $cachedata, $expires, $group, $userdata);
  159.     } // end func extSave
  160.  
  161.     /**
  162.     * Loads the given ID from the cache.
  163.     *
  164.     * @param    string  dataset ID
  165.     * @param    string  cache group
  166.     * @return   mixed   cached data or NULL on failure
  167.     * @access   public
  168.     */
  169.     function load($id, $group = "default") {
  170.         if ($this->no_cache)
  171.             return "";
  172.  
  173.         return $this->container->load($id, $group);
  174.     } // end func load
  175.  
  176.     /**
  177.     * Returns the userdata field of a cached data set.
  178.     *
  179.     * @param    string  dataset ID
  180.     * @param    string  cache group
  181.     * @return   string  userdata
  182.     * @access   public
  183.     * @see      extSave()
  184.     */
  185.     function getUserdata($id, $group = "default") {
  186.         if ($this->no_cache)
  187.             return "";
  188.  
  189.         return $this->container->getUserdata($id, $group);
  190.     } // end func getUserdata
  191.  
  192.     /**
  193.     * Removes the specified dataset from the cache.
  194.     *
  195.     * @param    string  dataset ID
  196.     * @param    string  cache group
  197.     * @return   boolean
  198.     * @access   public
  199.     */
  200.     function delete($id, $group = "default") {
  201.         if ($this->no_cache)
  202.             return true;
  203.  
  204.         return $this->container->delete($id, $group);
  205.     } // end func delete
  206.  
  207.     /**
  208.     * Flushes the cache - removes all data from it
  209.     *
  210.     * @param    string  cache group, if empty all groups will be flashed
  211.     * @return   integer number of removed datasets
  212.     */
  213.     function flush($group = "") {
  214.         if ($this->no_cache)
  215.             return true;
  216.  
  217.         return $this->container->flush($group);
  218.     } // end func flush
  219.  
  220.     /**
  221.     * Checks if a dataset exists.
  222.     *
  223.     * Note: this does not say that the cached data is not expired!
  224.     *
  225.     * @param    string  dataset ID
  226.     * @param    string  cache group
  227.     * @return   boolean
  228.     * @access   public
  229.     */
  230.     function isCached($id, $group = "default") {
  231.         if ($this->no_cache)
  232.             return false;
  233.  
  234.         return $this->container->isCached($id, $group);
  235.     } // end func isCached
  236.  
  237.     /**
  238.     * Checks if a dataset is expired
  239.     *
  240.     * @param    string  dataset ID
  241.     * @param    string  cache group
  242.     * @param    integer maximum age for the cached data in seconds - 0 for endless
  243.     *                   If the cached data is older but the given lifetime it will
  244.     *                   be removed from the cache. You don't have to provide this
  245.     *                   argument if you call isExpired(). Every dataset knows
  246.     *                   it's expire date and will be removed automatically. Use
  247.     *                   this only if you know what you're doing...
  248.     * @return   boolean
  249.     * @access   public
  250.     */
  251.     function isExpired($id, $group = "default", $max_age = 0) {
  252.         if ($this->no_cache)
  253.             return true;
  254.  
  255.         return $this->container->isExpired($id, $group, $max_age);
  256.     } // end func isExpired
  257.  
  258.     /**
  259.     * Generates a "unique" ID for the given value
  260.     *
  261.     * This is a quick but dirty hack to get a "unique" ID for a any kind of variable.
  262.     * ID clashes might occur from time to time although they are extreme unlikely!
  263.     *
  264.     * @param    mixed   variable to generate a ID for
  265.     * @return   string  "unique" ID
  266.     * @access   public
  267.     */
  268.     function generateID($variable) {
  269.         // WARNING: ID clashes are possible although unlikely
  270.         return md5(serialize($variable));
  271.     }
  272.  
  273.     /**
  274.     * Calls the garbage collector of the storage object with a certain probability
  275.     *
  276.     * @param    boolean Force a garbage collection run?
  277.     * @see  $gc_probability, $gc_time
  278.     */
  279.     function garbageCollection($force = false) {
  280.         static $last_run = 0;
  281.  
  282.         if ($this->no_cache)
  283.             return;
  284.  
  285.         srand((double) microtime() * 1000000);
  286.  
  287.         // time and probability based
  288.         if (($force) || ($last_run && $last_run < time() + $this->gc_time) || (rand(1, 100) < $this->gc_probability)) {
  289.             $this->container->garbageCollection();
  290.             $last_run = time();
  291.         }
  292.     } // end func garbageCollection
  293.  
  294. } // end class cache
  295. ?>
  296.