[Summary view] [Print] [Text view]

   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   * Cache helper class
  19   *
  20   * This file is part of Moodle's cache API, affectionately called MUC.
  21   * It contains the components that are requried in order to use caching.
  22   *
  23   * @package    core
  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 cache helper class.
  33   *
  34   * The cache helper class provides common functionality to the cache API and is useful to developers within to interact with
  35   * the cache API in a general way.
  36   *
  37   * @package    core
  38   * @category   cache
  39   * @copyright  2012 Sam Hemelryk
  40   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41   */
  42  class cache_helper {
  43  
  44      /**
  45       * Statistics gathered by the cache API during its operation will be used here.
  46       * @static
  47       * @var array
  48       */
  49      protected static $stats = array();
  50  
  51      /**
  52       * The instance of the cache helper.
  53       * @var cache_helper
  54       */
  55      protected static $instance;
  56  
  57      /**
  58       * The site identifier used by the cache.
  59       * Set the first time get_site_identifier is called.
  60       * @var string
  61       */
  62      protected static $siteidentifier = null;
  63  
  64      /**
  65       * Returns true if the cache API can be initialised before Moodle has finished initialising itself.
  66       *
  67       * This check is essential when trying to cache the likes of configuration information. It checks to make sure that the cache
  68       * configuration file has been created which allows use to set up caching when ever is required.
  69       *
  70       * @return bool
  71       */
  72      public static function ready_for_early_init() {
  73          return cache_config::config_file_exists();
  74      }
  75  
  76      /**
  77       * Returns an instance of the cache_helper.
  78       *
  79       * This is designed for internal use only and acts as a static store.
  80       * @staticvar null $instance
  81       * @return cache_helper
  82       */
  83      protected static function instance() {
  84          if (is_null(self::$instance)) {
  85              self::$instance = new cache_helper();
  86          }
  87          return self::$instance;
  88      }
  89  
  90      /**
  91       * Constructs an instance of the cache_helper class. Again for internal use only.
  92       */
  93      protected function __construct() {
  94          // Nothing to do here, just making sure you can't get an instance of this.
  95      }
  96  
  97      /**
  98       * Used as a data store for initialised definitions.
  99       * @var array
 100       */
 101      protected $definitions = array();
 102  
 103      /**
 104       * Used as a data store for initialised cache stores
 105       * We use this because we want to avoid establishing multiple instances of a single store.
 106       * @var array
 107       */
 108      protected $stores = array();
 109  
 110      /**
 111       * Returns the class for use as a cache loader for the given mode.
 112       *
 113       * @param int $mode One of cache_store::MODE_
 114       * @return string
 115       * @throws coding_exception
 116       */
 117      public static function get_class_for_mode($mode) {
 118          switch ($mode) {
 119              case cache_store::MODE_APPLICATION :
 120                  return 'cache_application';
 121              case cache_store::MODE_REQUEST :
 122                  return 'cache_request';
 123              case cache_store::MODE_SESSION :
 124                  return 'cache_session';
 125          }
 126          throw new coding_exception('Unknown cache mode passed. Must be one of cache_store::MODE_*');
 127      }
 128  
 129      /**
 130       * Returns the cache stores to be used with the given definition.
 131       * @param cache_definition $definition
 132       * @return array
 133       */
 134      public static function get_cache_stores(cache_definition $definition) {
 135          $instance = cache_config::instance();
 136          $stores = $instance->get_stores_for_definition($definition);
 137          $stores = self::initialise_cachestore_instances($stores, $definition);
 138          return $stores;
 139      }
 140  
 141      /**
 142       * Internal function for initialising an array of stores against a given cache definition.
 143       *
 144       * @param array $stores
 145       * @param cache_definition $definition
 146       * @return cache_store[]
 147       */
 148      protected static function initialise_cachestore_instances(array $stores, cache_definition $definition) {
 149          $return = array();
 150          $factory = cache_factory::instance();
 151          foreach ($stores as $name => $details) {
 152              $store = $factory->create_store_from_config($name, $details, $definition);
 153              if ($store !== false) {
 154                  $return[] = $store;
 155              }
 156          }
 157          return $return;
 158      }
 159  
 160      /**
 161       * Returns a cache_lock instance suitable for use with the store.
 162       *
 163       * @param cache_store $store
 164       * @return cache_lock_interface
 165       */
 166      public static function get_cachelock_for_store(cache_store $store) {
 167          $instance = cache_config::instance();
 168          $lockconf = $instance->get_lock_for_store($store->my_name());
 169          $factory = cache_factory::instance();
 170          return $factory->create_lock_instance($lockconf);
 171      }
 172  
 173      /**
 174       * Returns an array of plugins without using core methods.
 175       *
 176       * This function explicitly does NOT use core functions as it will in some circumstances be called before Moodle has
 177       * finished initialising. This happens when loading configuration for instance.
 178       *
 179       * @return string
 180       */
 181      public static function early_get_cache_plugins() {
 182          global $CFG;
 183          $result = array();
 184          $ignored = array('CVS', '_vti_cnf', 'simpletest', 'db', 'yui', 'tests');
 185          $fulldir = $CFG->dirroot.'/cache/stores';
 186          $items = new DirectoryIterator($fulldir);
 187          foreach ($items as $item) {
 188              if ($item->isDot() or !$item->isDir()) {
 189                  continue;
 190              }
 191              $pluginname = $item->getFilename();
 192              if (in_array($pluginname, $ignored)) {
 193                  continue;
 194              }
 195              if (!is_valid_plugin_name($pluginname)) {
 196                  // Better ignore plugins with problematic names here.
 197                  continue;
 198              }
 199              $result[$pluginname] = $fulldir.'/'.$pluginname;
 200              unset($item);
 201          }
 202          unset($items);
 203          return $result;
 204      }
 205  
 206      /**
 207       * Invalidates a given set of keys from a given definition.
 208       *
 209       * @todo Invalidating by definition should also add to the event cache so that sessions can be invalidated (when required).
 210       *
 211       * @param string $component
 212       * @param string $area
 213       * @param array $identifiers
 214       * @param array $keys
 215       * @return boolean
 216       */
 217      public static function invalidate_by_definition($component, $area, array $identifiers = array(), $keys = array()) {
 218          $cache = cache::make($component, $area, $identifiers);
 219          if (is_array($keys)) {
 220              $cache->delete_many($keys);
 221          } else if (is_scalar($keys)) {
 222              $cache->delete($keys);
 223          } else {
 224              throw new coding_exception('cache_helper::invalidate_by_definition only accepts $keys as array, or scalar.');
 225          }
 226          return true;
 227      }
 228  
 229      /**
 230       * Invalidates a given set of keys by means of an event.
 231       *
 232       * @todo add support for identifiers to be supplied and utilised.
 233       *
 234       * @param string $event
 235       * @param array $keys
 236       */
 237      public static function invalidate_by_event($event, array $keys) {
 238          $instance = cache_config::instance();
 239          $invalidationeventset = false;
 240          $factory = cache_factory::instance();
 241          $inuse = $factory->get_caches_in_use();
 242          foreach ($instance->get_definitions() as $name => $definitionarr) {
 243              $definition = cache_definition::load($name, $definitionarr);
 244              if ($definition->invalidates_on_event($event)) {
 245                  // First up check if there is a cache loader for this definition already.
 246                  // If there is we need to invalidate the keys from there.
 247                  $definitionkey = $definition->get_component().'/'.$definition->get_area();
 248                  if (isset($inuse[$definitionkey])) {
 249                      $inuse[$definitionkey]->delete_many($keys);
 250                  }
 251  
 252                  // We should only log events for application and session caches.
 253                  // Request caches shouldn't have events as all data is lost at the end of the request.
 254                  // Events should only be logged once of course and likely several definitions are watching so we
 255                  // track its logging with $invalidationeventset.
 256                  $logevent = ($invalidationeventset === false && $definition->get_mode() !== cache_store::MODE_REQUEST);
 257  
 258                  if ($logevent) {
 259                      // Get the event invalidation cache.
 260                      $cache = cache::make('core', 'eventinvalidation');
 261                      // Get any existing invalidated keys for this cache.
 262                      $data = $cache->get($event);
 263                      if ($data === false) {
 264                          // There are none.
 265                          $data = array();
 266                      }
 267                      // Add our keys to them with the current cache timestamp.
 268                      foreach ($keys as $key) {
 269                          $data[$key] = cache::now();
 270                      }
 271                      // Set that data back to the cache.
 272                      $cache->set($event, $data);
 273                      // This only needs to occur once.
 274                      $invalidationeventset = true;
 275                  }
 276              }
 277          }
 278      }
 279  
 280      /**
 281       * Purges the cache for a specific definition.
 282       *
 283       * @param string $component
 284       * @param string $area
 285       * @param array $identifiers
 286       * @return bool
 287       */
 288      public static function purge_by_definition($component, $area, array $identifiers = array()) {
 289          // Create the cache.
 290          $cache = cache::make($component, $area, $identifiers);
 291          // Initialise, in case of a store.
 292          if ($cache instanceof cache_store) {
 293              $factory = cache_factory::instance();
 294              $definition = $factory->create_definition($component, $area, null);
 295              $definition->set_identifiers($identifiers);
 296              $cache->initialise($definition);
 297          }
 298          // Purge baby, purge.
 299          $cache->purge();
 300          return true;
 301      }
 302  
 303      /**
 304       * Purges a cache of all information on a given event.
 305       *
 306       * @param string $event
 307       */
 308      public static function purge_by_event($event) {
 309          $instance = cache_config::instance();
 310          $invalidationeventset = false;
 311          $factory = cache_factory::instance();
 312          $inuse = $factory->get_caches_in_use();
 313          foreach ($instance->get_definitions() as $name => $definitionarr) {
 314              $definition = cache_definition::load($name, $definitionarr);
 315              if ($definition->invalidates_on_event($event)) {
 316                  // First up check if there is a cache loader for this definition already.
 317                  // If there is we need to invalidate the keys from there.
 318                  $definitionkey = $definition->get_component().'/'.$definition->get_area();
 319                  if (isset($inuse[$definitionkey])) {
 320                      $inuse[$definitionkey]->purge();
 321                  } else {
 322                      cache::make($definition->get_component(), $definition->get_area())->purge();
 323                  }
 324  
 325                  // We should only log events for application and session caches.
 326                  // Request caches shouldn't have events as all data is lost at the end of the request.
 327                  // Events should only be logged once of course and likely several definitions are watching so we
 328                  // track its logging with $invalidationeventset.
 329                  $logevent = ($invalidationeventset === false && $definition->get_mode() !== cache_store::MODE_REQUEST);
 330  
 331                  // We need to flag the event in the "Event invalidation" cache if it hasn't already happened.
 332                  if ($logevent && $invalidationeventset === false) {
 333                      // Get the event invalidation cache.
 334                      $cache = cache::make('core', 'eventinvalidation');
 335                      // Create a key to invalidate all.
 336                      $data = array(
 337                          'purged' => cache::now()
 338                      );
 339                      // Set that data back to the cache.
 340                      $cache->set($event, $data);
 341                      // This only needs to occur once.
 342                      $invalidationeventset = true;
 343                  }
 344              }
 345          }
 346      }
 347  
 348      /**
 349       * Ensure that the stats array is ready to collect information for the given store and definition.
 350       * @param string $store
 351       * @param string $definition A string that identifies the definition.
 352       * @param int $mode One of cache_store::MODE_*. Since 2.9.
 353       */
 354      protected static function ensure_ready_for_stats($store, $definition, $mode = cache_store::MODE_APPLICATION) {
 355          // This function is performance-sensitive, so exit as quickly as possible
 356          // if we do not need to do anything.
 357          if (isset(self::$stats[$definition]['stores'][$store])) {
 358              return;
 359          }
 360          if (!array_key_exists($definition, self::$stats)) {
 361              self::$stats[$definition] = array(
 362                  'mode' => $mode,
 363                  'stores' => array(
 364                      $store => array(
 365                          'hits' => 0,
 366                          'misses' => 0,
 367                          'sets' => 0,
 368                      )
 369                  )
 370              );
 371          } else if (!array_key_exists($store, self::$stats[$definition]['stores'])) {
 372              self::$stats[$definition]['stores'][$store] = array(
 373                  'hits' => 0,
 374                  'misses' => 0,
 375                  'sets' => 0,
 376              );
 377          }
 378      }
 379  
 380      /**
 381       * Returns a string to describe the definition.
 382       *
 383       * This method supports the definition as a string due to legacy requirements.
 384       * It is backwards compatible when a string is passed but is not accurate.
 385       *
 386       * @since 2.9
 387       * @param cache_definition|string $definition
 388       * @return string
 389       */
 390      protected static function get_definition_stat_id_and_mode($definition) {
 391          if (!($definition instanceof cache_definition)) {
 392              // All core calls to this method have been updated, this is the legacy state.
 393              // We'll use application as the default as that is the most common, really this is not accurate of course but
 394              // at this point we can only guess and as it only affects calls to cache stat outside of core (of which there should
 395              // be none) I think that is fine.
 396              debugging('Please update you cache stat calls to pass the definition rather than just its ID.', DEBUG_DEVELOPER);
 397              return array((string)$definition, cache_store::MODE_APPLICATION);
 398          }
 399          return array($definition->get_id(), $definition->get_mode());
 400      }
 401  
 402      /**
 403       * Record a cache hit in the stats for the given store and definition.
 404       *
 405       * In Moodle 2.9 the $definition argument changed from accepting only a string to accepting a string or a
 406       * cache_definition instance. It is preferable to pass a cache definition instance.
 407       *
 408       * @internal
 409       * @param cache_definition $store
 410       * @param cache_definition $definition You used to be able to pass a string here, however that is deprecated please pass the
 411       *      actual cache_definition object now.
 412       * @param int $hits The number of hits to record (by default 1)
 413       */
 414      public static function record_cache_hit($store, $definition, $hits = 1) {
 415          list($definitionstr, $mode) = self::get_definition_stat_id_and_mode($definition);
 416          self::ensure_ready_for_stats($store, $definitionstr, $mode);
 417          self::$stats[$definitionstr]['stores'][$store]['hits'] += $hits;
 418      }
 419  
 420      /**
 421       * Record a cache miss in the stats for the given store and definition.
 422       *
 423       * In Moodle 2.9 the $definition argument changed from accepting only a string to accepting a string or a
 424       * cache_definition instance. It is preferable to pass a cache definition instance.
 425       *
 426       * @internal
 427       * @param string $store
 428       * @param cache_definition $definition You used to be able to pass a string here, however that is deprecated please pass the
 429       *      actual cache_definition object now.
 430       * @param int $misses The number of misses to record (by default 1)
 431       */
 432      public static function record_cache_miss($store, $definition, $misses = 1) {
 433          list($definitionstr, $mode) = self::get_definition_stat_id_and_mode($definition);
 434          self::ensure_ready_for_stats($store, $definitionstr, $mode);
 435          self::$stats[$definitionstr]['stores'][$store]['misses'] += $misses;
 436      }
 437  
 438      /**
 439       * Record a cache set in the stats for the given store and definition.
 440       *
 441       * In Moodle 2.9 the $definition argument changed from accepting only a string to accepting a string or a
 442       * cache_definition instance. It is preferable to pass a cache definition instance.
 443       *
 444       * @internal
 445       * @param string $store
 446       * @param cache_definition $definition You used to be able to pass a string here, however that is deprecated please pass the
 447       *      actual cache_definition object now.
 448       * @param int $sets The number of sets to record (by default 1)
 449       */
 450      public static function record_cache_set($store, $definition, $sets = 1) {
 451          list($definitionstr, $mode) = self::get_definition_stat_id_and_mode($definition);
 452          self::ensure_ready_for_stats($store, $definitionstr, $mode);
 453          self::$stats[$definitionstr]['stores'][$store]['sets'] += $sets;
 454      }
 455  
 456      /**
 457       * Return the stats collected so far.
 458       * @return array
 459       */
 460      public static function get_stats() {
 461          return self::$stats;
 462      }
 463  
 464      /**
 465       * Purge all of the cache stores of all of their data.
 466       *
 467       * Think twice before calling this method. It will purge **ALL** caches regardless of whether they have been used recently or
 468       * anything. This will involve full setup of the cache + the purge operation. On a site using caching heavily this WILL be
 469       * painful.
 470       *
 471       * @param bool $usewriter If set to true the cache_config_writer class is used. This class is special as it avoids
 472       *      it is still usable when caches have been disabled.
 473       *      Please use this option only if you really must. It's purpose is to allow the cache to be purged when it would be
 474       *      otherwise impossible.
 475       */
 476      public static function purge_all($usewriter = false) {
 477          $factory = cache_factory::instance();
 478          $config = $factory->create_config_instance($usewriter);
 479          foreach ($config->get_all_stores() as $store) {
 480              self::purge_store($store['name'], $config);
 481          }
 482      }
 483  
 484      /**
 485       * Purges a store given its name.
 486       *
 487       * @param string $storename
 488       * @param cache_config $config
 489       * @return bool
 490       */
 491      public static function purge_store($storename, cache_config $config = null) {
 492          if ($config === null) {
 493              $config = cache_config::instance();
 494          }
 495  
 496          $stores = $config->get_all_stores();
 497          if (!array_key_exists($storename, $stores)) {
 498              // The store does not exist.
 499              return false;
 500          }
 501  
 502          $store = $stores[$storename];
 503          $class = $store['class'];
 504  
 505          // Found the store: is it ready?
 506          /* @var cache_store $instance */
 507          $instance = new $class($store['name'], $store['configuration']);
 508          // We check are_requirements_met although we expect is_ready is going to check as well.
 509          if (!$instance::are_requirements_met() || !$instance->is_ready()) {
 510              unset($instance);
 511              return false;
 512          }
 513  
 514          foreach ($config->get_definitions_by_store($storename) as $id => $definition) {
 515              $definition = cache_definition::load($id, $definition);
 516              $definitioninstance = clone($instance);
 517              $definitioninstance->initialise($definition);
 518              $definitioninstance->purge();
 519              unset($definitioninstance);
 520          }
 521  
 522          return true;
 523      }
 524  
 525      /**
 526       * Purges all of the stores used by a definition.
 527       *
 528       * Unlike cache_helper::purge_by_definition this purges all of the data from the stores not
 529       * just the data relating to the definition.
 530       * This function is useful when you must purge a definition that requires setup but you don't
 531       * want to set it up.
 532       *
 533       * @param string $component
 534       * @param string $area
 535       */
 536      public static function purge_stores_used_by_definition($component, $area) {
 537          $factory = cache_factory::instance();
 538          $config = $factory->create_config_instance();
 539          $definition = $factory->create_definition($component, $area);
 540          $stores = $config->get_stores_for_definition($definition);
 541          foreach ($stores as $store) {
 542              self::purge_store($store['name']);
 543          }
 544      }
 545  
 546      /**
 547       * Returns the translated name of the definition.
 548       *
 549       * @param cache_definition $definition
 550       * @return lang_string
 551       */
 552      public static function get_definition_name($definition) {
 553          if ($definition instanceof cache_definition) {
 554              return $definition->get_name();
 555          }
 556          $identifier = 'cachedef_'.clean_param($definition['area'], PARAM_STRINGID);
 557          $component = $definition['component'];
 558          if ($component === 'core') {
 559              $component = 'cache';
 560          }
 561          return new lang_string($identifier, $component);
 562      }
 563  
 564      /**
 565       * Hashes a descriptive key to make it shorter and still unique.
 566       * @param string|int $key
 567       * @param cache_definition $definition
 568       * @return string
 569       */
 570      public static function hash_key($key, cache_definition $definition) {
 571          if ($definition->uses_simple_keys()) {
 572              if (debugging() && preg_match('#[^a-zA-Z0-9_]#', $key)) {
 573                  throw new coding_exception('Cache definition '.$definition->get_id().' requires simple keys. Invalid key provided.', $key);
 574              }
 575              // We put the key first so that we can be sure the start of the key changes.
 576              return (string)$key . '-' . $definition->generate_single_key_prefix();
 577          }
 578          $key = $definition->generate_single_key_prefix() . '-' . $key;
 579          return sha1($key);
 580      }
 581  
 582      /**
 583       * Finds all definitions and updates them within the cache config file.
 584       *
 585       * @param bool $coreonly If set to true only core definitions will be updated.
 586       */
 587      public static function update_definitions($coreonly = false) {
 588          global $CFG;
 589          // Include locallib.
 590          require_once($CFG->dirroot.'/cache/locallib.php');
 591          // First update definitions
 592          cache_config_writer::update_definitions($coreonly);
 593          // Second reset anything we have already initialised to ensure we're all up to date.
 594          cache_factory::reset();
 595      }
 596  
 597      /**
 598       * Update the site identifier stored by the cache API.
 599       *
 600       * @param string $siteidentifier
 601       * @return string The new site identifier.
 602       */
 603      public static function update_site_identifier($siteidentifier) {
 604          global $CFG;
 605          // Include locallib.
 606          require_once($CFG->dirroot.'/cache/locallib.php');
 607          $factory = cache_factory::instance();
 608          $factory->updating_started();
 609          $config = $factory->create_config_instance(true);
 610          $siteidentifier = $config->update_site_identifier($siteidentifier);
 611          $factory->updating_finished();
 612          cache_factory::reset();
 613          return $siteidentifier;
 614      }
 615  
 616      /**
 617       * Returns the site identifier.
 618       *
 619       * @return string
 620       */
 621      public static function get_site_identifier() {
 622          global $CFG;
 623          if (!is_null(self::$siteidentifier)) {
 624              return self::$siteidentifier;
 625          }
 626          // If site identifier hasn't been collected yet attempt to get it from the cache config.
 627          $factory = cache_factory::instance();
 628          // If the factory is initialising then we don't want to try to get it from the config or we risk
 629          // causing the cache to enter an infinite initialisation loop.
 630          if (!$factory->is_initialising()) {
 631              $config = $factory->create_config_instance();
 632              self::$siteidentifier = $config->get_site_identifier();
 633          }
 634          if (is_null(self::$siteidentifier)) {
 635              // If the site identifier is still null then config isn't aware of it yet.
 636              // We'll see if the CFG is loaded, and if not we will just use unknown.
 637              // It's very important here that we don't use get_config. We don't want an endless cache loop!
 638              if (!empty($CFG->siteidentifier)) {
 639                  self::$siteidentifier = self::update_site_identifier($CFG->siteidentifier);
 640              } else {
 641                  // It's not being recorded in MUC's config and the config data hasn't been loaded yet.
 642                  // Likely we are initialising.
 643                  return 'unknown';
 644              }
 645          }
 646          return self::$siteidentifier;
 647      }
 648  
 649      /**
 650       * Returns the site version.
 651       *
 652       * @return string
 653       */
 654      public static function get_site_version() {
 655          global $CFG;
 656          return (string)$CFG->version;
 657      }
 658  
 659      /**
 660       * Runs cron routines for MUC.
 661       */
 662      public static function cron() {
 663          self::clean_old_session_data(true);
 664      }
 665  
 666      /**
 667       * Cleans old session data from cache stores used for session based definitions.
 668       *
 669       * @param bool $output If set to true output will be given.
 670       */
 671      public static function clean_old_session_data($output = false) {
 672          global $CFG;
 673          if ($output) {
 674              mtrace('Cleaning up stale session data from cache stores.');
 675          }
 676          $factory = cache_factory::instance();
 677          $config = $factory->create_config_instance();
 678          $definitions = $config->get_definitions();
 679          $purgetime = time() - $CFG->sessiontimeout;
 680          foreach ($definitions as $definitionarray) {
 681              // We are only interested in session caches.
 682              if (!($definitionarray['mode'] & cache_store::MODE_SESSION)) {
 683                  continue;
 684              }
 685              $definition = $factory->create_definition($definitionarray['component'], $definitionarray['area']);
 686              $stores = $config->get_stores_for_definition($definition);
 687              // Turn them into store instances.
 688              $stores = self::initialise_cachestore_instances($stores, $definition);
 689              // Initialise all of the stores used for that definition.
 690              foreach ($stores as $store) {
 691                  // If the store doesn't support searching we can skip it.
 692                  if (!($store instanceof cache_is_searchable)) {
 693                      debugging('Cache stores used for session definitions should ideally be searchable.', DEBUG_DEVELOPER);
 694                      continue;
 695                  }
 696                  // Get all of the keys.
 697                  $keys = $store->find_by_prefix(cache_session::KEY_PREFIX);
 698                  $todelete = array();
 699                  foreach ($store->get_many($keys) as $key => $value) {
 700                      if (strpos($key, cache_session::KEY_PREFIX) !== 0 || !is_array($value) || !isset($value['lastaccess'])) {
 701                          continue;
 702                      }
 703                      if ((int)$value['lastaccess'] < $purgetime || true) {
 704                          $todelete[] = $key;
 705                      }
 706                  }
 707                  if (count($todelete)) {
 708                      $outcome = (int)$store->delete_many($todelete);
 709                      if ($output) {
 710                          $strdef = s($definition->get_id());
 711                          $strstore = s($store->my_name());
 712                          mtrace("- Removed {$outcome} old {$strdef} sessions from the '{$strstore}' cache store.");
 713                      }
 714                  }
 715              }
 716          }
 717      }
 718  
 719      /**
 720       * Returns an array of stores that would meet the requirements for every definition.
 721       *
 722       * These stores would be 100% suitable to map as defaults for cache modes.
 723       *
 724       * @return array[] An array of stores, keys are the store names.
 725       */
 726      public static function get_stores_suitable_for_mode_default() {
 727          $factory = cache_factory::instance();
 728          $config = $factory->create_config_instance();
 729          $requirements = 0;
 730          foreach ($config->get_definitions() as $definition) {
 731              $definition = cache_definition::load($definition['component'].'/'.$definition['area'], $definition);
 732              $requirements = $requirements | $definition->get_requirements_bin();
 733          }
 734          $stores = array();
 735          foreach ($config->get_all_stores() as $name => $store) {
 736              if (!empty($store['features']) && ($store['features'] & $requirements)) {
 737                  $stores[$name] = $store;
 738              }
 739          }
 740          return $stores;
 741      }
 742  
 743      /**
 744       * Returns stores suitable for use with a given definition.
 745       *
 746       * @param cache_definition $definition
 747       * @return cache_store[]
 748       */
 749      public static function get_stores_suitable_for_definition(cache_definition $definition) {
 750          $factory = cache_factory::instance();
 751          $stores = array();
 752          if ($factory->is_initialising() || $factory->stores_disabled()) {
 753              // No suitable stores here.
 754              return $stores;
 755          } else {
 756              $stores = self::get_cache_stores($definition);
 757              // If mappingsonly is set, having 0 stores is ok.
 758              if ((count($stores) === 0) && (!$definition->is_for_mappings_only())) {
 759                  // No suitable stores we found for the definition. We need to come up with a sensible default.
 760                  // If this has happened we can be sure that the user has mapped custom stores to either the
 761                  // mode of the definition. The first alternative to try is the system default for the mode.
 762                  // e.g. the default file store instance for application definitions.
 763                  $config = $factory->create_config_instance();
 764                  foreach ($config->get_stores($definition->get_mode()) as $name => $details) {
 765                      if (!empty($details['default'])) {
 766                          $stores[] = $factory->create_store_from_config($name, $details, $definition);
 767                          break;
 768                      }
 769                  }
 770              }
 771          }
 772          return $stores;
 773      }
 774  
 775      /**
 776       * Returns an array of warnings from the cache API.
 777       *
 778       * The warning returned here are for things like conflicting store instance configurations etc.
 779       * These get shown on the admin notifications page for example.
 780       *
 781       * @param array|null $stores An array of stores to get warnings for, or null for all.
 782       * @return string[]
 783       */
 784      public static function warnings(array $stores = null) {
 785          global $CFG;
 786          if ($stores === null) {
 787              require_once($CFG->dirroot.'/cache/locallib.php');
 788              $stores = cache_administration_helper::get_store_instance_summaries();
 789          }
 790          $warnings = array();
 791          foreach ($stores as $store) {
 792              if (!empty($store['warnings'])) {
 793                  $warnings = array_merge($warnings, $store['warnings']);
 794              }
 795          }
 796          return $warnings;
 797      }
 798  }