home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 August / PCWorld_2001-08_cd.bin / Komunikace / phptriad / phptriadsetup2-11.exe / php / pear / Cache / Container.php next >
PHP Script  |  2001-03-08  |  13KB  |  425 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. // |          Christian Stocker <chregu@nomad.ch>                         |
  18. // +----------------------------------------------------------------------+
  19. //
  20. // $Id: Container.php,v 1.9 2001/03/08 20:41:39 uw Exp $
  21.  
  22. require_once "Cache/Error.php";
  23.  
  24. /**
  25. * Common base class of all cache storage container.
  26. * 
  27. * To speed up things we do a preload you should know about, otherwise it might 
  28. * play you a trick. The Cache controller classes (Cache/Cache, Cache/Output, ...)
  29. * usually do something like is (isCached($id) && !isExpired($id)) return $container->load($id).
  30. * if you implement isCached(), isExpired() and load() straight ahead, each of this 
  31. * functions will result in a storage medium (db, file,...) access. This generates too much load. 
  32. * Now, a simple speculative preload should saves time in most cases. Whenever 
  33. * one of the mentioned methods is invoked we preload the cached dataset into class variables.
  34. * That means that we have only one storage medium access for the sequence
  35. *  (isCached($id) && !isExpired($id)) return $container->load($id).
  36. * The bad thing is that the preloaded data might be outdated meanwhile, which is 
  37. * unlikely but for you power users, be warned. If you do not want the preload 
  38. * you should switch it off by setting the class variable $preload to false. Anyway, this is 
  39. * not recommended!
  40. * 
  41. * @author   Ulf Wendel <ulf.wendel@phpdoc.de>
  42. * @version  $Id: Container.php,v 1.9 2001/03/08 20:41:39 uw Exp $
  43. * @package  Cache
  44. * @access   public
  45. * @abstract
  46. */
  47. class Cache_Container {
  48.  
  49.     /**
  50.     * Flag indicating wheter to preload datasets.
  51.     *
  52.     * See the class description for more details.
  53.     *
  54.     * @var  boolean
  55.     */
  56.     var $preload = true;
  57.  
  58.     /**
  59.     * ID of a preloaded dataset
  60.     *
  61.     * @var  string
  62.     */
  63.     var $id = "";
  64.  
  65.     /**
  66.     * Cache group of a preloaded dataset
  67.     *
  68.     * @var  string
  69.     */
  70.     var $group = "";
  71.  
  72.     /**
  73.     * Expiration timestamp of a preloaded dataset.
  74.     * 
  75.     * @var  integer 0 means never, endless
  76.     */
  77.     var $expires = 0;
  78.  
  79.     /**
  80.     * Value of a preloaded dataset.
  81.     * 
  82.     * @var  string
  83.     */
  84.     var $cachedata = "";
  85.  
  86.     /**
  87.     * Preloaded userdata field.
  88.     * 
  89.     * @var  string
  90.     */
  91.     var $userdata = "";
  92.  
  93.     /**
  94.     * Flag indicating that the dataset requested for preloading is unknown.
  95.     *  
  96.     * @var  boolean
  97.     */
  98.     var $unknown = true;
  99.  
  100.     /**
  101.     * Encoding mode for cache data: base64 or addslashes() (slash).
  102.     *
  103.     * @var  string  base64 or slash
  104.     */
  105.     var $encoding_mode = "base64";
  106.  
  107.     /**
  108.     * Loads a dataset from the cache.
  109.     * 
  110.     * @param    string  dataset ID
  111.     * @param    string  cache group
  112.     * @return   mixed   dataset value or NULL on failure
  113.     * @access   public
  114.     */
  115.     function load($id, $group) {
  116.         if ($this->preload) {
  117.             if ($this->id != $id || $this->group != $group)
  118.                 $this->preload($id, $group);
  119.  
  120.             return $this->cachedata;
  121.         } else {
  122.             list( , $data, ) = $this->fetch($id, $group);
  123.             return $data;
  124.         }
  125.     } // end func load
  126.  
  127.     /**
  128.     * Returns the userdata field of a cached data set.
  129.     *
  130.     * @param    string  dataset ID
  131.     * @param    string  cache group
  132.     * @return   string  userdata
  133.     * @access   public
  134.     */
  135.     function getUserdata($id, $group) {
  136.         if ($this->preload) {
  137.             if ($this->id != $id || $this->group != $group)
  138.                 $this->preload($id, $group);
  139.                 
  140.             return $this->userdata;
  141.         } else {
  142.             list( , , $userdata) = $this->fetch($id, $group);
  143.             return $userdata;
  144.         }
  145.     } // end func getUserdata
  146.  
  147.     /**
  148.     * Checks if a dataset is expired.
  149.     * 
  150.     * @param    string  dataset ID
  151.     * @param    string  cache group
  152.     * @param    integer maximum age timestamp
  153.     * @return   boolean 
  154.     * @access   public
  155.     */
  156.     function isExpired($id, $group, $max_age) {
  157.         if ($this->preload) {
  158.           if ($this->id != $id || $this->group != $group)
  159.             $this->preload($id, $group);
  160.           
  161.           if ($this->unknown)
  162.             return false;
  163.         } else {
  164.             // check if at all it is cached
  165.             if (!$this->isCached($id, $group))
  166.                 return false;
  167.                 
  168.             // I'm lazy...
  169.             list($this->expires, , ) = $this->fetch($id, $group);
  170.         }
  171.  
  172.         // endless
  173.         if (0 == $this->expires)
  174.             return false;
  175.  
  176.         // you feel fine, Ulf?
  177.         if ($expired  = ($this->expires <= time() || ($max_age && ($this->expires <= $max_age))) ) {
  178.  
  179.            $this->delete($id, $group);
  180.            $this->flushPreload();
  181.         }
  182.         return $expired;
  183.     } // end func isExpired
  184.  
  185.     /**
  186.     * Checks if a dataset is cached.
  187.     *
  188.     * @param    string  dataset ID
  189.     * @param    string  cache group
  190.     * @return   boolean
  191.     */
  192.     function isCached($id, $group) {
  193.         if ($this->preload) {
  194.             if ($this->id != $id || $this->group != $group)
  195.                 $this->preload($id, $group);
  196.  
  197.             return !($this->unknown);
  198.         } else {
  199.             return $this->idExists($id, $group);
  200.         }
  201.     } // end func isCached
  202.  
  203.     //
  204.     // abstract methods
  205.     //
  206.  
  207.     /**
  208.     * Fetches a dataset from the storage medium.
  209.     *
  210.     * @param    string  dataset ID
  211.     * @param    string  cache group
  212.     * @return   array   format: [expire date, cached data, user data]
  213.     * @throws   Cache_Error
  214.     * @abstract
  215.     */
  216.     function fetch($id, $group) {
  217.         return array(NULL, NULL, NULL);
  218.     } // end func fetch
  219.  
  220.     /**
  221.     * Stores a dataset.
  222.     * 
  223.     * @param    string  dataset ID
  224.     * @param    mixed   data to store
  225.     * @param    mixed   userdefined expire date
  226.     * @param    string  cache group
  227.     * @param    string  additional userdefined data
  228.     * @return   boolean
  229.     * @throws   Cache_Error
  230.     * @access   public
  231.     * @abstract
  232.     */
  233.     function save($id, $data, $expire, $group, $userdata) {
  234.         // QUESTION: Should we update the preload buffer instead?
  235.         // Don't think so as the sequence save()/load() is unlikely.
  236.         $this->flushPreload($id, $group);
  237.  
  238.         return NULL;
  239.     } // end func save
  240.  
  241.     /**
  242.     * Deletes a dataset.
  243.     * 
  244.     * @param    string  dataset ID
  245.     * @param    string  cache group
  246.     * @return   boolean  
  247.     * @access   public
  248.     * @abstract
  249.     */     
  250.     function delete($id, $group) {
  251.         $this->flushPreload($id, $group);
  252.         return NULL;
  253.     } // end func delete
  254.  
  255.     /**
  256.     * Flushes the cache - removes all caches datasets from the cache.
  257.     * 
  258.     * @param    string      If a cache group is given only the group will be flushed
  259.     * @return   integer     Number of removed datasets, -1 on failure
  260.     * @access   public
  261.     * @abstract
  262.     */
  263.     function flush($group) {
  264.         $this->flushPreload();
  265.         return NULL;
  266.     } // end func flush
  267.  
  268.     /**
  269.     * Checks if a dataset exists.
  270.     * 
  271.     * @param    string  dataset ID
  272.     * @param    string  cache group
  273.     * @return   boolean 
  274.     * @access   public
  275.     * @abstract
  276.     */
  277.     function idExists($id, $group) {
  278.         return NULL;
  279.     } // end func idExists
  280.  
  281.     /**
  282.     * Starts the garbage collection.
  283.     * 
  284.     * @access   public
  285.     * @abstract
  286.     */
  287.     function garbageCollection() {
  288.         $this->flushPreload();
  289.     } // end func garbageCollection
  290.  
  291.     /**
  292.     * Does a speculative preload of a dataset
  293.     *
  294.     * @param    string  dataset ID
  295.     * @param    string  cache group
  296.     * @return   boolean
  297.     */ 
  298.     function preload($id, $group) {
  299.         // whatever happens, remember the preloaded ID
  300.         $this->id = $id;
  301.         $this->group = $group;        
  302.  
  303.         list($this->expires, $this->cachedata, $this->userdata) = $this->fetch($id, $group);
  304.  
  305.         if (NULL === $this->expires) {
  306.             // Uuups, unknown ID
  307.             $this->flushPreload();
  308.  
  309.             return false;
  310.         }
  311.  
  312.         $this->unknown = false;
  313.  
  314.         return true;
  315.     } // end func preload
  316.  
  317.     /**
  318.     * Flushes the internal preload buffer.
  319.     *
  320.     * save(), delete() and flush() must call this method
  321.     * to preevent differences between the preloaded values and 
  322.     * the real cache contents.
  323.     *
  324.     * @param    string  dataset ID, if left out the preloaded values will be flushed. 
  325.     *                   If given the preloaded values will only be flushed if they are
  326.     *                   equal to the given id and group
  327.     * @param    string  cache group
  328.     * @see  preload()
  329.     */
  330.     function flushPreload($id = "", $group = "default") {
  331.         if (!$id || ($this->id == $id && $this->group == $group)) {
  332.             // clear the internal preload values
  333.             $this->id = "";
  334.             $this->group = "";
  335.             $this->cachedata = "";
  336.             $this->userdata = "";
  337.             $this->expires = -1;
  338.             $this->unknown = true;
  339.         }
  340.     } // end func flushPreload
  341.  
  342.     /**
  343.     * Imports the requested datafields as object variables if allowed
  344.     * 
  345.     * @param    array   List of fields to be imported as object variables
  346.     * @param    array   List of allowed datafields
  347.     */
  348.     function setOptions($requested, $allowed) {
  349.         foreach ($allowed as $k => $field)
  350.             if (isset($requested[$field]))
  351.                 $this->$field = $requested[$field];
  352.                 
  353.     } // end func setOptions
  354.  
  355.     /**
  356.     * Encodes the data for the storage container.
  357.     * 
  358.     * @var  mixed data to encode
  359.     */
  360.     function encode($data) {
  361.         if ("base64" == $this->encoding_mode) 
  362.             return base64_encode(serialize($data));
  363.         else 
  364.             return serialize($data);
  365.     } // end func encode
  366.  
  367.     
  368.     /**
  369.     * Decodes the data from the storage container.
  370.     * 
  371.     * @var  mixed
  372.     */
  373.     function decode($data) {
  374.         if ("base64" == $this->encoding_mode)
  375.             return unserialize(base64_decode($data));
  376.         else
  377.             return unserialize($data);
  378.     } // end func decode
  379.  
  380.     
  381.     /**
  382.     * Translates human readable/relative times in unixtime
  383.     *
  384.     * @param  mixed   can be in the following formats:
  385.     *               human readable          : yyyymmddhhmm[ss]] eg: 20010308095100
  386.     *               relative in seconds (1) : +xx              eg: +10
  387.     *               relative in seconds (2) : x <  946681200   eg: 10
  388.     *               absolute unixtime       : x < 2147483648   eg: 2147483648
  389.     *               see comments in code for details
  390.     * @return integer unix timestamp
  391.     */
  392.     function getExpiresAbsolute($expires)
  393.     {
  394.         if (!$expires)
  395.             return 0;
  396.         //for api-compatibility, one has not to provide a "+",
  397.         // if integer is < 946681200 (= Jan 01 2000 00:00:00)
  398.         if ('+' == $expires[0] || $expires < 946681200)
  399.         {
  400.             return(time() + $expires);
  401.         }
  402.         //if integer is < 100000000000 (= in 3140 years),
  403.         // it must be an absolut unixtime
  404.         // (since the "human readable" definition asks for a higher number)
  405.         elseif ($expires < 100000000000)
  406.         {
  407.             return $expires;
  408.         }
  409.         // else it's "human readable";
  410.         else
  411.         {
  412.             $year = substr($expires, 0, 4);
  413.             $month = substr($expires, 4, 2);
  414.             $day = substr($expires, 6, 2);
  415.             $hour = substr($expires, 8, 2);
  416.             $minute = substr($expires, 10, 2);
  417.             $second = substr($expires, 12, 2);
  418.             return mktime($hour, $minute, $second, $month, $day, $year);
  419.         }
  420.         
  421.     } // end func getExpireAbsolute
  422.     
  423. } // end class Container
  424. ?>
  425.