cache/stores/session/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * The library file for the session cache store.
  19  *
  20  * This file is part of the session cache store, it contains the API for interacting with an instance of the store.
  21  * This is used as a default cache store within the Cache API. It should never be deleted.
  22  *
  23  * @package    cachestore_session
  24  * @category   cache
  25  * @copyright  2012 Sam Hemelryk
  26  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  27  */
  28
  29 defined('MOODLE_INTERNAL') || die();
  30
  31 /**
  32  * The session data store class.
  33  *
  34  * @copyright  2012 Sam Hemelryk
  35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  36  */
  37 abstract class session_data_store extends cache_store {
  38
  39     /**
  40      * Used for the actual storage.
  41      * @var array
  42      */
  43     private static $sessionstore = null;
  44
  45     /**
  46      * Returns a static store by reference... REFERENCE SUPER IMPORTANT.
  47      *
  48      * @param string $id
  49      * @return array
  50      */
  51     protected static function &register_store_id($id) {
  52         if (is_null(self::$sessionstore)) {
  53             global $SESSION;
  54             if (!isset($SESSION->cachestore_session)) {
  55                 $SESSION->cachestore_session = array();
  56             }
  57             self::$sessionstore =& $SESSION->cachestore_session;
  58         }
  59         if (!array_key_exists($id, self::$sessionstore)) {
  60             self::$sessionstore[$id] = array();
  61         }
  62         return self::$sessionstore[$id];
  63     }
  64
  65     /**
  66      * Flushes the data belong to the given store id.
  67      * @param string $id
  68      */
  69     protected static function flush_store_by_id($id) {
  70         unset(self::$sessionstore[$id]);
  71         self::$sessionstore[$id] = array();
  72     }
  73
  74     /**
  75      * Flushes the store of all data.
  76      */
  77     protected static function flush_store() {
  78         $ids = array_keys(self::$sessionstore);
  79         unset(self::$sessionstore);
  80         self::$sessionstore = array();
  81         foreach ($ids as $id) {
  82             self::$sessionstore[$id] = array();
  83         }
  84     }
  85 }
  86
  87 /**
  88  * The Session store class.
  89  *
  90  * @copyright  2012 Sam Hemelryk
  91  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  92  */
  93 class cachestore_session extends session_data_store implements cache_is_key_aware, cache_is_searchable {
  94
  95     /**
  96      * The name of the store
  97      * @var store
  98      */
  99     protected $name;
 100
 101     /**
 102      * The store id (should be unique)
 103      * @var string
 104      */
 105     protected $storeid;
 106
 107     /**
 108      * The store we use for data.
 109      * @var array
 110      */
 111     protected $store;
 112
 113     /**
 114      * The ttl if there is one. Hopefully not.
 115      * @var int
 116      */
 117     protected $ttl = 0;
 118
 119     /**
 120      * The maximum size for the store, or false if there isn't one.
 121      * @var bool
 122      */
 123     protected $maxsize = false;
 124
 125     /**
 126      * The number of items currently being stored.
 127      * @var int
 128      */
 129     protected $storecount = 0;
 130
 131     /**
 132      * Constructs the store instance.
 133      *
 134      * Noting that this function is not an initialisation. It is used to prepare the store for use.
 135      * The store will be initialised when required and will be provided with a cache_definition at that time.
 136      *
 137      * @param string $name
 138      * @param array $configuration
 139      */
 140     public function __construct($name, array $configuration = array()) {
 141         $this->name = $name;
 142     }
 143
 144     /**
 145      * Returns the supported features as a combined int.
 146      *
 147      * @param array $configuration
 148      * @return int
 149      */
 150     public static function get_supported_features(array $configuration = array()) {
 151         return self::SUPPORTS_DATA_GUARANTEE +
 152                self::SUPPORTS_NATIVE_TTL +
 153                self::IS_SEARCHABLE;
 154     }
 155
 156     /**
 157      * Returns false as this store does not support multiple identifiers.
 158      * (This optional function is a performance optimisation; it must be
 159      * consistent with the value from get_supported_features.)
 160      *
 161      * @return bool False
 162      */
 163     public function supports_multiple_identifiers() {
 164         return false;
 165     }
 166
 167     /**
 168      * Returns the supported modes as a combined int.
 169      *
 170      * @param array $configuration
 171      * @return int
 172      */
 173     public static function get_supported_modes(array $configuration = array()) {
 174         return self::MODE_SESSION;
 175     }
 176
 177     /**
 178      * Returns true if the store requirements are met.
 179      *
 180      * @return bool
 181      */
 182     public static function are_requirements_met() {
 183         return true;
 184     }
 185
 186     /**
 187      * Returns true if the given mode is supported by this store.
 188      *
 189      * @param int $mode One of cache_store::MODE_*
 190      * @return bool
 191      */
 192     public static function is_supported_mode($mode) {
 193         return ($mode === self::MODE_SESSION);
 194     }
 195
 196     /**
 197      * Initialises the cache.
 198      *
 199      * Once this has been done the cache is all set to be used.
 200      *
 201      * @param cache_definition $definition
 202      */
 203     public function initialise(cache_definition $definition) {
 204         $this->storeid = $definition->generate_definition_hash();
 205         $this->store = &self::register_store_id($definition->get_id());
 206         $this->ttl = $definition->get_ttl();
 207         $maxsize = $definition->get_maxsize();
 208         if ($maxsize !== null) {
 209             // Must be a positive int.
 210             $this->maxsize = abs((int)$maxsize);
 211             $this->storecount = count($this->store);
 212         }
 213     }
 214
 215     /**
 216      * Returns true once this instance has been initialised.
 217      *
 218      * @return bool
 219      */
 220     public function is_initialised() {
 221         return (is_array($this->store));
 222     }
 223
 224     /**
 225      * Returns true if this store instance is ready to be used.
 226      * @return bool
 227      */
 228     public function is_ready() {
 229         return true;
 230     }
 231
 232     /**
 233      * Retrieves an item from the cache store given its key.
 234      *
 235      * @param string $key The key to retrieve
 236      * @return mixed The data that was associated with the key, or false if the key did not exist.
 237      */
 238     public function get($key) {
 239         if (isset($this->store[$key])) {
 240             if ($this->ttl == 0) {
 241                 return $this->store[$key][0];
 242             } else if ($this->store[$key][1] >= (cache::now() - $this->ttl)) {
 243                 return $this->store[$key][0];
 244             }
 245         }
 246         return false;
 247     }
 248
 249     /**
 250      * Retrieves several items from the cache store in a single transaction.
 251      *
 252      * If not all of the items are available in the cache then the data value for those that are missing will be set to false.
 253      *
 254      * @param array $keys The array of keys to retrieve
 255      * @return array An array of items from the cache. There will be an item for each key, those that were not in the store will
 256      *      be set to false.
 257      */
 258     public function get_many($keys) {
 259         $return = array();
 260         if ($this->ttl != 0) {
 261             $maxtime = cache::now() - $this->ttl;
 262         }
 263
 264         foreach ($keys as $key) {
 265             $return[$key] = false;
 266             if (isset($this->store[$key])) {
 267                 if ($this->ttl == 0) {
 268                     $return[$key] = $this->store[$key][0];
 269                 } else if ($this->store[$key][1] >= $maxtime) {
 270                     $return[$key] = $this->store[$key][0];
 271                 }
 272             }
 273         }
 274         return $return;
 275     }
 276
 277     /**
 278      * Sets an item in the cache given its key and data value.
 279      *
 280      * @param string $key The key to use.
 281      * @param mixed $data The data to set.
 282      * @param bool $testmaxsize If set to true then we test the maxsize arg and reduce if required.
 283      * @return bool True if the operation was a success false otherwise.
 284      */
 285     public function set($key, $data, $testmaxsize = true) {
 286         $testmaxsize = ($testmaxsize && $this->maxsize !== false);
 287         if ($testmaxsize) {
 288             $increment = (!isset($this->store[$key]));
 289         }
 290         if ($this->ttl == 0) {
 291             $this->store[$key][0] = $data;
 292         } else {
 293             $this->store[$key] = array($data, cache::now());
 294         }
 295         if ($testmaxsize && $increment) {
 296             $this->storecount++;
 297             if ($this->storecount > $this->maxsize) {
 298                 $this->reduce_for_maxsize();
 299             }
 300         }
 301         return true;
 302     }
 303
 304     /**
 305      * Sets many items in the cache in a single transaction.
 306      *
 307      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
 308      *      keys, 'key' and 'value'.
 309      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
 310      *      sent ... if they care that is.
 311      */
 312     public function set_many(array $keyvaluearray) {
 313         $count = 0;
 314         foreach ($keyvaluearray as $pair) {
 315             $this->set($pair['key'], $pair['value'], false);
 316             $count++;
 317         }
 318         if ($this->maxsize !== false) {
 319             $this->storecount += $count;
 320             if ($this->storecount > $this->maxsize) {
 321                 $this->reduce_for_maxsize();
 322             }
 323         }
 324         return $count;
 325     }
 326
 327     /**
 328      * Checks if the store has a record for the given key and returns true if so.
 329      *
 330      * @param string $key
 331      * @return bool
 332      */
 333     public function has($key) {
 334         if (isset($this->store[$key])) {
 335             if ($this->ttl == 0) {
 336                 return true;
 337             } else if ($this->store[$key][1] >= (cache::now() - $this->ttl)) {
 338                 return true;
 339             }
 340         }
 341         return false;
 342     }
 343
 344     /**
 345      * Returns true if the store contains records for all of the given keys.
 346      *
 347      * @param array $keys
 348      * @return bool
 349      */
 350     public function has_all(array $keys) {
 351         if ($this->ttl != 0) {
 352             $maxtime = cache::now() - $this->ttl;
 353         }
 354
 355         foreach ($keys as $key) {
 356             if (!isset($this->store[$key])) {
 357                 return false;
 358             }
 359             if ($this->ttl != 0 && $this->store[$key][1] < $maxtime) {
 360                 return false;
 361             }
 362         }
 363         return true;
 364     }
 365
 366     /**
 367      * Returns true if the store contains records for any of the given keys.
 368      *
 369      * @param array $keys
 370      * @return bool
 371      */
 372     public function has_any(array $keys) {
 373         if ($this->ttl != 0) {
 374             $maxtime = cache::now() - $this->ttl;
 375         }
 376
 377         foreach ($keys as $key) {
 378             if (isset($this->store[$key]) && ($this->ttl == 0 || $this->store[$key][1] >= $maxtime)) {
 379                 return true;
 380             }
 381         }
 382         return false;
 383     }
 384
 385     /**
 386      * Deletes an item from the cache store.
 387      *
 388      * @param string $key The key to delete.
 389      * @return bool Returns true if the operation was a success, false otherwise.
 390      */
 391     public function delete($key) {
 392         $result = isset($this->store[$key]);
 393         unset($this->store[$key]);
 394         if ($this->maxsize !== false) {
 395             $this->storecount--;
 396         }
 397         return $result;
 398     }
 399
 400     /**
 401      * Deletes several keys from the cache in a single action.
 402      *
 403      * @param array $keys The keys to delete
 404      * @return int The number of items successfully deleted.
 405      */
 406     public function delete_many(array $keys) {
 407         $count = 0;
 408         foreach ($keys as $key) {
 409             if (isset($this->store[$key])) {
 410                 $count++;
 411             }
 412             unset($this->store[$key]);
 413         }
 414         if ($this->maxsize !== false) {
 415             $this->storecount -= $count;
 416         }
 417         return $count;
 418     }
 419
 420     /**
 421      * Purges the cache deleting all items within it.
 422      *
 423      * @return boolean True on success. False otherwise.
 424      */
 425     public function purge() {
 426         $this->store = array();
 427         // Don't worry about checking if we're using max size just set it as thats as fast as the check.
 428         $this->storecount = 0;
 429         return true;
 430     }
 431
 432     /**
 433      * Reduces the size of the array if maxsize has been hit.
 434      *
 435      * This function reduces the size of the store reducing it by 10% of its maxsize.
 436      * It removes the oldest items in the store when doing this.
 437      * The reason it does this an doesn't use a least recently used system is purely the overhead such a system
 438      * requires. The current approach is focused on speed, MUC already adds enough overhead to static/session caches
 439      * and avoiding more is of benefit.
 440      *
 441      * @return int
 442      */
 443     protected function reduce_for_maxsize() {
 444         $diff = $this->storecount - $this->maxsize;
 445         if ($diff < 1) {
 446             return 0;
 447         }
 448         // Reduce it by an extra 10% to avoid calling this repetitively if we are in a loop.
 449         $diff += floor($this->maxsize / 10);
 450         $this->store = array_slice($this->store, $diff, null, true);
 451         $this->storecount -= $diff;
 452         return $diff;
 453     }
 454
 455     /**
 456      * Returns true if the user can add an instance of the store plugin.
 457      *
 458      * @return bool
 459      */
 460     public static function can_add_instance() {
 461         return false;
 462     }
 463
 464     /**
 465      * Performs any necessary clean up when the store instance is being deleted.
 466      */
 467     public function instance_deleted() {
 468         $this->purge();
 469     }
 470
 471     /**
 472      * Generates an instance of the cache store that can be used for testing.
 473      *
 474      * @param cache_definition $definition
 475      * @return cachestore_session
 476      */
 477     public static function initialise_test_instance(cache_definition $definition) {
 478         // Do something here perhaps.
 479         $cache = new cachestore_session('Session test');
 480         $cache->initialise($definition);
 481         return $cache;
 482     }
 483
 484     /**
 485      * Returns the name of this instance.
 486      * @return string
 487      */
 488     public function my_name() {
 489         return $this->name;
 490     }
 491
 492     /**
 493      * Finds all of the keys being stored in the cache store instance.
 494      *
 495      * @return array
 496      */
 497     public function find_all() {
 498         return array_keys($this->store);
 499     }
 500
 501     /**
 502      * Finds all of the keys whose keys start with the given prefix.
 503      *
 504      * @param string $prefix
 505      */
 506     public function find_by_prefix($prefix) {
 507         $return = array();
 508         foreach ($this->find_all() as $key) {
 509             if (strpos($key, $prefix) === 0) {
 510                 $return[] = $key;
 511             }
 512         }
 513         return $return;
 514     }
 515 }