git.sur5r.net Git - bacula/bacula/blob - gui/baculum/framework/I18N/core/TCache_Lite.php

   1 <?php
   2
   3 /**
   4  * TCache_Lite class file.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the BSD License.
   8  *
   9  * Copyright(c) 2004 by Qiang Xue. All rights reserved.
  10  *
  11  * To contact the author write to {@link mailto:qiang.xue@gmail.com Qiang Xue}
  12  * The latest version of PRADO can be obtained from:
  13  * {@link http://prado.sourceforge.net/}
  14  *
  15  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>
  16  * @version $Revision: 1.3 $  $Date: 2005/10/09 10:24:12 $
  17  * @package System.I18N.core
  18  */
  19
  20 /**
  21 * Fast, light and safe Cache Class
  22 *
  23 * TCache_Lite is a fast, light and safe cache system. It's optimized
  24 * for file containers. It is fast and safe (because it uses file
  25 * locking and/or anti-corruption tests).
  26 *
  27 * There are some examples in the 'docs/examples' file
  28 * Technical choices are described in the 'docs/technical' file
  29 *
  30 * A tutorial is available in english at this url :
  31 * http://www.pearfr.org/index.php/en/article/cache_lite
  32 * (big thanks to Pierre-Alain Joye for the translation)
  33 *
  34 * The same tutorial is also available in french at this url :
  35 * http://www.pearfr.org/index.php/fr/article/cache_lite
  36 *
  37 * Memory Caching is from an original idea of
  38 * Mike BENOIT <ipso@snappymail.ca>
  39 *
  40 * @package System.I18N.core
  41 * @author Fabien MARTY <fab@php.net>
  42 * @copyright  1997-2005 The PHP Group
  43 * @license    http://www.gnu.org/copyleft/lesser.html GNU LGPL
  44 * @link       http://pear.php.net/package/Cache_Lite
  45 */
  46 class TCache_Lite
  47 {
  48
  49     // --- Private properties ---
  50
  51     /**
  52     * Directory where to put the cache files
  53     * (make sure to add a trailing slash)
  54     *
  55     * @var string $_cacheDir
  56     */
  57     protected $_cacheDir = '/tmp/';
  58
  59     /**
  60     * Enable / disable caching
  61     *
  62     * (can be very usefull for the debug of cached scripts)
  63     *
  64     * @var boolean $_caching
  65     */
  66     protected $_caching = true;
  67
  68     /**
  69     * Cache lifetime (in seconds)
  70     *
  71     * @var int $_lifeTime
  72     */
  73     protected $_lifeTime = 3600;
  74
  75     /**
  76     * Enable / disable fileLocking
  77     *
  78     * (can avoid cache corruption under bad circumstances)
  79     *
  80     * @var boolean $_fileLocking
  81     */
  82     protected $_fileLocking = true;
  83
  84     /**
  85     * Timestamp of the last valid cache
  86     *
  87     * @var int $_refreshTime
  88     */
  89     protected $_refreshTime;
  90
  91     /**
  92     * File name (with path)
  93     *
  94     * @var string $_file
  95     */
  96     protected $_file;
  97
  98     /**
  99     * Enable / disable write control (the cache is read just after writing
 100     * to detect corrupt entries)
 101     *
 102     * Enable write control will lightly slow the cache writing but not the
 103     * cache reading. Write control can detect some corrupt cache files but
 104     * maybe it's not a perfect control
 105     *
 106     * @var boolean $_writeControl
 107     */
 108     protected $_writeControl = true;
 109
 110     /**
 111     * Enable / disable read control
 112     *
 113     * If enabled, a control key is embeded in cache file and this key is
 114     * compared with the one calculated after the reading.
 115     *
 116     * @var boolean $_writeControl
 117     */
 118     protected $_readControl = true;
 119
 120     /**
 121     * Type of read control (only if read control is enabled)
 122     *
 123     * Available values are :
 124     * 'md5' for a md5 hash control (best but slowest)
 125     * 'crc32' for a crc32 hash control (lightly less safe but faster,
 126     * better choice)
 127     * 'strlen' for a length only test (fastest)
 128     *
 129     * @var boolean $_readControlType
 130     */
 131     protected $_readControlType = 'crc32';
 132
 133     /**
 134     * Current cache id
 135     *
 136     * @var string $_id
 137     */
 138     protected $_id;
 139
 140     /**
 141     * Current cache group
 142     *
 143     * @var string $_group
 144     */
 145     protected $_group;
 146
 147     /**
 148     * Enable / Disable "Memory Caching"
 149     *
 150     * NB : There is no lifetime for memory caching !
 151     *
 152     * @var boolean $_memoryCaching
 153     */
 154     protected $_memoryCaching = false;
 155
 156     /**
 157     * Enable / Disable "Only Memory Caching"
 158     * (be carefull, memory caching is "beta quality")
 159     *
 160     * @var boolean $_onlyMemoryCaching
 161     */
 162     protected $_onlyMemoryCaching = false;
 163
 164     /**
 165     * Memory caching array
 166     *
 167     * @var array $_memoryCachingArray
 168     */
 169     protected $_memoryCachingArray = array();
 170
 171     /**
 172     * Memory caching counter
 173     *
 174     * @var int $memoryCachingCounter
 175     */
 176     protected $_memoryCachingCounter = 0;
 177
 178     /**
 179     * Memory caching limit
 180     *
 181     * @var int $memoryCachingLimit
 182     */
 183     protected $_memoryCachingLimit = 1000;
 184
 185     /**
 186     * File Name protection
 187     *
 188     * if set to true, you can use any cache id or group name
 189     * if set to false, it can be faster but cache ids and group names
 190     * will be used directly in cache file names so be carefull with
 191     * special characters...
 192     *
 193     * @var boolean $fileNameProtection
 194     */
 195     protected $_fileNameProtection = true;
 196
 197     /**
 198     * Enable / disable automatic serialization
 199     *
 200     * it can be used to save directly datas which aren't strings
 201     * (but it's slower)
 202     *
 203     * @var boolean $_serialize
 204     */
 205     protected $_automaticSerialization = false;
 206
 207     // --- Public methods ---
 208
 209     /**
 210     * Constructor
 211     *
 212     * $options is an assoc. Available options are :
 213     * $options = array(
 214     * 'cacheDir' => directory where to put the cache files (string),
 215     * 'caching' => enable / disable caching (boolean),
 216     * 'lifeTime' => cache lifetime in seconds (int),
 217     * 'fileLocking' => enable / disable fileLocking (boolean),
 218     * 'writeControl' => enable / disable write control (boolean),
 219     * 'readControl' => enable / disable read control (boolean),
 220     * 'readControlType' => type of read control 'crc32', 'md5', 'strlen',
 221     * 'memoryCaching' => enable / disable memory caching (boolean),
 222     * 'onlyMemoryCaching' => enable / disable only memory caching (boolean),
 223     * 'memoryCachingLimit' => max nbr of records in memory caching (int),
 224     * 'fileNameProtection' => enable / disable file name protection (boolean),
 225     * 'automaticSerialization' => enable / disable serialization (boolean)
 226     * );
 227     *
 228     * @param array $options options
 229     * @access public
 230     */
 231     function TCache_Lite($options = array(null))
 232     {
 233         $availableOptions = array(      'automaticSerialization',
 234                                                                 'fileNameProtection',
 235                                                                 'memoryCaching',
 236                                                                 'onlyMemoryCaching',
 237                                                                 'memoryCachingLimit',
 238                                                                 'cacheDir',
 239                                                                 'caching',
 240                                                                 'lifeTime',
 241                                                                 'fileLocking',
 242                                                                 'writeControl',
 243                                                                 'readControl',
 244                                                                 'readControlType');
 245         foreach($options as $key => $value) {
 246             if(in_array($key, $availableOptions)) {
 247                 $property = '_'.$key;
 248                 $this->$property = $value;
 249             }
 250         }
 251         $this->_refreshTime = time() - $this->_lifeTime;
 252         }
 253
 254     /**
 255     * Test if a cache is available and (if yes) return it
 256     *
 257     * @param string $id cache id
 258     * @param string $group name of the cache group
 259     * @param boolean $doNotTestCacheValidity if set to true, the cache
 260     * validity won't be tested
 261     * @return string data of the cache (or false if no cache available)
 262     * @access public
 263     */
 264     function get($id, $group = 'default', $doNotTestCacheValidity = false)
 265     {
 266         $this->_id = $id;
 267         $this->_group = $group;
 268         $data = false;
 269         if ($this->_caching) {
 270             $this->_setFileName($id, $group);
 271             if ($this->_memoryCaching) {
 272                 if (isset($this->_memoryCachingArray[$this->_file])) {
 273                     if ($this->_automaticSerialization) {
 274                         return unserialize(
 275                                                 $this->_memoryCachingArray[$this->_file]);
 276                     } else {
 277                         return $this->_memoryCachingArray[$this->_file];
 278                     }
 279                 } else {
 280                     if ($this->_onlyMemoryCaching) {
 281                         return false;
 282                     }
 283                 }
 284             }
 285             if ($doNotTestCacheValidity) {
 286                 if (file_exists($this->_file)) {
 287                     $data = $this->_read();
 288                 }
 289             } else {
 290                 if (@filemtime($this->_file) > $this->_refreshTime) {
 291                     $data = $this->_read();
 292                 }
 293             }
 294             if (($data) and ($this->_memoryCaching)) {
 295                 $this->_memoryCacheAdd($this->_file, $data);
 296             }
 297             if ($this->_automaticSerialization && is_string($data)) {
 298                 $data = unserialize($data);
 299             }
 300             return $data;
 301         }
 302         return false;
 303     }
 304
 305     /**
 306     * Save some data in a cache file
 307     *
 308     * @param string $data data to put in cache (can be another type than strings
 309     * if automaticSerialization is on)
 310     * @param string $id cache id
 311     * @param string $group name of the cache group
 312     * @return boolean true if no problem
 313     * @access public
 314     */
 315     function save($data, $id = null, $group = 'default')
 316     {
 317         if ($this->_caching) {
 318             if ($this->_automaticSerialization) {
 319                 $data = serialize($data);
 320             }
 321             if (isset($id)) {
 322                 $this->_setFileName($id, $group);
 323             }
 324             if ($this->_memoryCaching) {
 325                 $this->_memoryCacheAdd($this->_file, $data);
 326                 if ($this->_onlyMemoryCaching) {
 327                     return true;
 328                 }
 329             }
 330             if ($this->_writeControl) {
 331                 if (!$this->_writeAndControl($data)) {
 332                     @touch($this->_file, time() - 2*abs($this->_lifeTime));
 333                     return false;
 334                 } else {
 335                     return true;
 336                 }
 337             } else {
 338                 return $this->_write($data);
 339             }
 340         }
 341         return false;
 342     }
 343
 344     /**
 345     * Remove a cache file
 346     *
 347     * @param string $id cache id
 348     * @param string $group name of the cache group
 349     * @return boolean true if no problem
 350     * @access public
 351     */
 352     function remove($id, $group = 'default')
 353     {
 354         $this->_setFileName($id, $group);
 355         if (!@unlink($this->_file)) {
 356             $this->raiseError('TCache_Lite : Unable to remove cache !', -3);
 357             return false;
 358         }
 359         return true;
 360     }
 361
 362     /**
 363     * Clean the cache
 364     *
 365     * if no group is specified all cache files will be destroyed
 366     * else only cache files of the specified group will be destroyed
 367     *
 368     * @param string $group name of the cache group
 369     * @return boolean true if no problem
 370     * @access public
 371     */
 372     function clean($group = false)
 373     {
 374         if ($this->_fileNameProtection) {
 375             $motif = ($group) ? 'cache_'.md5($group).'_' : 'cache_';
 376         } else {
 377             $motif = ($group) ? 'cache_'.$group.'_' : 'cache_';
 378         }
 379         if ($this->_memoryCaching) {
 380             while (list($key, $value) = each($this->_memoryCaching)) {
 381                 if (strpos($key, $motif, 0)) {
 382                     unset($this->_memoryCaching[$key]);
 383                     $this->_memoryCachingCounter =
 384                                 $this->_memoryCachingCounter - 1;
 385                 }
 386             }
 387             if ($this->_onlyMemoryCaching) {
 388                 return true;
 389             }
 390         }
 391         if (!($dh = opendir($this->_cacheDir))) {
 392             $this->raiseError('TCache_Lite : Unable to open cache directory !');
 393             return false;
 394         }
 395         while ($file = readdir($dh)) {
 396             if (($file != '.') && ($file != '..')) {
 397                 $file = $this->_cacheDir . $file;
 398                 if (is_file($file)) {
 399                     if (strpos($file, $motif, 0)) {
 400                         if (!@unlink($file)) {
 401              $this->raiseError('Cache_Lite : Unable to remove cache !', -3);
 402                             return false;
 403                         }
 404                     }
 405                 }
 406             }
 407         }
 408         return true;
 409     }
 410
 411             /**
 412     * Set a new life time
 413     *
 414     * @param int $newLifeTime new life time (in seconds)
 415     * @access public
 416     */
 417     function setLifeTime($newLifeTime)
 418     {
 419         $this->_lifeTime = $newLifeTime;
 420         $this->_refreshTime = time() - $newLifeTime;
 421     }
 422
 423     /**
 424     *
 425     * @access public
 426     */
 427     function saveMemoryCachingState($id, $group = 'default')
 428     {
 429         if ($this->_caching) {
 430             $array = array(
 431                 'counter' => $this->_memoryCachingCounter,
 432                 'array' => $this->_memoryCachingState
 433             );
 434             $data = serialize($array);
 435             $this->save($data, $id, $group);
 436         }
 437     }
 438
 439     /**
 440     *
 441     * @access public
 442     */
 443     function getMemoryCachingState($id, $group = 'default',
 444                                                                 $doNotTestCacheValidity = false)
 445     {
 446         if ($this->_caching) {
 447             if ($data = $this->get($id, $group, $doNotTestCacheValidity))
 448             {
 449                 $array = unserialize($data);
 450                 $this->_memoryCachingCounter = $array['counter'];
 451                 $this->_memoryCachingArray = $array['array'];
 452             }
 453         }
 454     }
 455
 456     /**
 457     * Return the cache last modification time
 458     *
 459     * BE CAREFUL : THIS METHOD IS FOR HACKING ONLY !
 460     *
 461     * @return int last modification time
 462     */
 463     function lastModified() {
 464         return filemtime($this->cache->_file);
 465     }
 466
 467     /**
 468     * Trigger a PEAR error
 469     *
 470     * To improve performances, the PEAR.php file is included dynamically.
 471     * The file is so included only when an error is triggered. So, in most
 472     * cases, the file isn't included and perfs are much better.
 473     *
 474     * @param string $msg error message
 475     * @param int $code error code
 476     * @access public
 477     */
 478     function raiseError($msg, $code)
 479     {
 480        throw new Exception($msg);
 481     }
 482
 483     // --- Private methods ---
 484
 485     /**
 486     *
 487     * @access private
 488     */
 489     function _memoryCacheAdd($id, $data)
 490     {
 491         $this->_memoryCachingArray[$this->_file] = $data;
 492         if ($this->_memoryCachingCounter >= $this->_memoryCachingLimit) {
 493             list($key, $value) = each($this->_memoryCachingArray);
 494             unset($this->_memoryCachingArray[$key]);
 495         } else {
 496             $this->_memoryCachingCounter = $this->_memoryCachingCounter + 1;
 497         }
 498     }
 499
 500     /**
 501     * Make a file name (with path)
 502     *
 503     * @param string $id cache id
 504     * @param string $group name of the group
 505     * @access private
 506     */
 507     function _setFileName($id, $group)
 508     {
 509         if ($this->_fileNameProtection) {
 510             $this->_file = ($this->_cacheDir.'cache_'.md5($group).'_'
 511                                                         .md5($id));
 512         } else {
 513             $this->_file = $this->_cacheDir.'cache_'.$group.'_'.$id;
 514         }
 515     }
 516
 517     function getCacheFile()
 518     {
 519         return $this->_file;
 520     }
 521
 522     /**
 523     * Read the cache file and return the content
 524     *
 525     * @return string content of the cache file
 526     * @access private
 527     */
 528     function _read()
 529     {
 530         $fp = @fopen($this->_file, "rb");
 531         if ($this->_fileLocking) @flock($fp, LOCK_SH);
 532         if ($fp) {
 533                 // because the filesize can be cached by PHP itself...
 534             clearstatcache();
 535             $length = @filesize($this->_file);
 536                         if(version_compare(PHP_VERSION, '5.3.0', 'lt'))
 537                         {
 538                     $mqr = get_magic_quotes_runtime();
 539                 set_magic_quotes_runtime(0);
 540                         }
 541             if ($this->_readControl) {
 542                 $hashControl = @fread($fp, 32);
 543                 $length = $length - 32;
 544             }
 545             $data = @fread($fp, $length);
 546                         if(isset($mqr))
 547                     set_magic_quotes_runtime($mqr);
 548             if ($this->_fileLocking) @flock($fp, LOCK_UN);
 549             @fclose($fp);
 550             if ($this->_readControl) {
 551                 $hashData = $this->_hash($data, $this->_readControlType);
 552                 if ($hashData != $hashControl) {
 553                     @touch($this->_file, time() - 2*abs($this->_lifeTime));
 554                     return false;
 555                 }
 556             }
 557             return $data;
 558         }
 559         $this->raiseError('Cache_Lite : Unable to read cache !', -2);
 560         return false;
 561     }
 562
 563     /**
 564     * Write the given data in the cache file
 565     *
 566     * @param string $data data to put in cache
 567     * @return boolean true if ok
 568     * @access private
 569     */
 570     function _write($data)
 571     {
 572         $fp = @fopen($this->_file, "wb");
 573         if ($fp) {
 574             if ($this->_fileLocking) @flock($fp, LOCK_EX);
 575             if ($this->_readControl) {
 576                 @fwrite($fp, $this->_hash($data, $this->_readControlType), 32);
 577             }
 578             $len = strlen($data);
 579             @fwrite($fp, $data, $len);
 580             if ($this->_fileLocking) @flock($fp, LOCK_UN);
 581             @fclose($fp);
 582             return true;
 583         }
 584         $this->raiseError('Cache_Lite : Unable to write cache !', -1);
 585         return false;
 586     }
 587
 588     /**
 589     * Write the given data in the cache file and control it just after to avoid
 590     * corrupted cache entries
 591     *
 592     * @param string $data data to put in cache
 593     * @return boolean true if the test is ok
 594     * @access private
 595     */
 596     function _writeAndControl($data)
 597     {
 598         $this->_write($data);
 599         $dataRead = $this->_read($data);
 600         return ($dataRead==$data);
 601     }
 602
 603     /**
 604     * Make a control key with the string containing datas
 605     *
 606     * @param string $data data
 607     * @param string $controlType type of control 'md5', 'crc32' or 'strlen'
 608     * @return string control key
 609     * @access private
 610     */
 611     function _hash($data, $controlType)
 612     {
 613         switch ($controlType) {
 614         case 'md5':
 615             return md5($data);
 616         case 'crc32':
 617             return sprintf('% 32d', crc32($data));
 618         case 'strlen':
 619             return sprintf('% 32d', strlen($data));
 620         default:
 621             $this->raiseError('Unknown controlType ! '.
 622             '(available values are only \'md5\', \'crc32\', \'strlen\')', -5);
 623         }
 624     }
 625
 626 }
 627