[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 store - base class
  19   *
  20   * This file is part of Moodle's cache API, affectionately called MUC.
  21   * It contains the components that are required 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   * Cache store interface.
  33   *
  34   * This interface defines the static methods that must be implemented by every cache store plugin.
  35   * To ensure plugins implement this class the abstract cache_store class implements this interface.
  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  interface cache_store_interface {
  43      /**
  44       * Static method to check if the store requirements are met.
  45       *
  46       * @return bool True if the stores software/hardware requirements have been met and it can be used. False otherwise.
  47       */
  48      public static function are_requirements_met();
  49  
  50      /**
  51       * Static method to check if a store is usable with the given mode.
  52       *
  53       * @param int $mode One of cache_store::MODE_*
  54       */
  55      public static function is_supported_mode($mode);
  56  
  57      /**
  58       * Returns the supported features as a binary flag.
  59       *
  60       * @param array $configuration The configuration of a store to consider specifically.
  61       * @return int The supported features.
  62       */
  63      public static function get_supported_features(array $configuration = array());
  64  
  65      /**
  66       * Returns the supported modes as a binary flag.
  67       *
  68       * @param array $configuration The configuration of a store to consider specifically.
  69       * @return int The supported modes.
  70       */
  71      public static function get_supported_modes(array $configuration = array());
  72  
  73      /**
  74       * Generates an instance of the cache store that can be used for testing.
  75       *
  76       * Returns an instance of the cache store, or false if one cannot be created.
  77       *
  78       * @param cache_definition $definition
  79       * @return cache_store|false
  80       */
  81      public static function initialise_test_instance(cache_definition $definition);
  82  
  83      /**
  84       * Initialises a test instance for unit tests.
  85       *
  86       * This differs from initialise_test_instance in that it doesn't rely on interacting with the config table.
  87       *
  88       * @since 2.8
  89       * @param cache_definition $definition
  90       * @return cache_store|false
  91       */
  92      public static function initialise_unit_test_instance(cache_definition $definition);
  93  }
  94  
  95  /**
  96   * Abstract cache store class.
  97   *
  98   * All cache store plugins must extend this base class.
  99   * It lays down the foundation for what is required of a cache store plugin.
 100   *
 101   * @since Moodle 2.4
 102   * @package    core
 103   * @category   cache
 104   * @copyright  2012 Sam Hemelryk
 105   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 106   */
 107  abstract class cache_store implements cache_store_interface {
 108  
 109      // Constants for features a cache store can support
 110  
 111      /**
 112       * Supports multi-part keys
 113       */
 114      const SUPPORTS_MULTIPLE_IDENTIFIERS = 1;
 115      /**
 116       * Ensures data remains in the cache once set.
 117       */
 118      const SUPPORTS_DATA_GUARANTEE = 2;
 119      /**
 120       * Supports a native ttl system.
 121       */
 122      const SUPPORTS_NATIVE_TTL = 4;
 123  
 124      /**
 125       * The cache is searchable by key.
 126       */
 127      const IS_SEARCHABLE = 8;
 128  
 129      // Constants for the modes of a cache store
 130  
 131      /**
 132       * Application caches. These are shared caches.
 133       */
 134      const MODE_APPLICATION = 1;
 135      /**
 136       * Session caches. Just access to the PHP session.
 137       */
 138      const MODE_SESSION = 2;
 139      /**
 140       * Request caches. Static caches really.
 141       */
 142      const MODE_REQUEST = 4;
 143  
 144      /**
 145       * Constructs an instance of the cache store.
 146       *
 147       * The constructor should be responsible for creating anything needed by the store that is not
 148       * specific to a definition.
 149       * Tasks such as opening a connection to check it is available are best done here.
 150       * Tasks that are definition specific such as creating a storage area for the definition data
 151       * or creating key tables and indexs are best done within the initialise method.
 152       *
 153       * Once a store has been constructed the cache API will check it is ready to be intialised with
 154       * a definition by called $this->is_ready().
 155       * If the setup of the store failed (connection could not be established for example) then
 156       * that method should return false so that the store instance is not selected for use.
 157       *
 158       * @param string $name The name of the cache store
 159       * @param array $configuration The configuration for this store instance.
 160       */
 161      abstract public function __construct($name, array $configuration = array());
 162  
 163      /**
 164       * Returns the name of this store instance.
 165       * @return string
 166       */
 167      abstract public function my_name();
 168  
 169      /**
 170       * Initialises a new instance of the cache store given the definition the instance is to be used for.
 171       *
 172       * This function should be used to run any definition specific setup the store instance requires.
 173       * Tasks such as creating storage areas, or creating indexes are best done here.
 174       *
 175       * Its important to note that the initialise method is expected to always succeed.
 176       * If there are setup tasks that may fail they should be done within the __construct method
 177       * and should they fail is_ready should return false.
 178       *
 179       * @param cache_definition $definition
 180       */
 181      abstract public function initialise(cache_definition $definition);
 182  
 183      /**
 184       * Returns true if this cache store instance has been initialised.
 185       * @return bool
 186       */
 187      abstract public function is_initialised();
 188  
 189      /**
 190       * Returns true if this cache store instance is ready to use.
 191       * @return bool
 192       */
 193      public function is_ready() {
 194          return forward_static_call(array($this, 'are_requirements_met'));
 195      }
 196  
 197      /**
 198       * Retrieves an item from the cache store given its key.
 199       *
 200       * @param string $key The key to retrieve
 201       * @return mixed The data that was associated with the key, or false if the key did not exist.
 202       */
 203      abstract public function get($key);
 204  
 205      /**
 206       * Retrieves several items from the cache store in a single transaction.
 207       *
 208       * 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.
 209       *
 210       * @param array $keys The array of keys to retrieve
 211       * @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
 212       *      be set to false.
 213       */
 214      abstract public function get_many($keys);
 215  
 216      /**
 217       * Sets an item in the cache given its key and data value.
 218       *
 219       * @param string $key The key to use.
 220       * @param mixed $data The data to set.
 221       * @return bool True if the operation was a success false otherwise.
 222       */
 223      abstract public function set($key, $data);
 224  
 225      /**
 226       * Sets many items in the cache in a single transaction.
 227       *
 228       * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
 229       *      keys, 'key' and 'value'.
 230       * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
 231       *      sent ... if they care that is.
 232       */
 233      abstract public function set_many(array $keyvaluearray);
 234  
 235      /**
 236       * Deletes an item from the cache store.
 237       *
 238       * @param string $key The key to delete.
 239       * @return bool Returns true if the operation was a success, false otherwise.
 240       */
 241      abstract public function delete($key);
 242  
 243      /**
 244       * Deletes several keys from the cache in a single action.
 245       *
 246       * @param array $keys The keys to delete
 247       * @return int The number of items successfully deleted.
 248       */
 249      abstract public function delete_many(array $keys);
 250  
 251      /**
 252       * Purges the cache deleting all items within it.
 253       *
 254       * @return boolean True on success. False otherwise.
 255       */
 256      abstract public function purge();
 257  
 258      /**
 259       * Performs any necessary clean up when the store instance is being deleted.
 260       *
 261       * @deprecated since 2.5
 262       */
 263      public function cleanup() {
 264          debugging('This function has been renamed to instance_deleted. Please update your calls.', DEBUG_DEVELOPER);
 265      }
 266  
 267      /**
 268       * Performs any necessary operation when the store instance has been created.
 269       *
 270       * @since Moodle 2.5
 271       */
 272      public function instance_created() {
 273          // By default, do nothing.
 274      }
 275  
 276      /**
 277       * Performs any necessary operation when the store instance is being deleted.
 278       *
 279       * This method may be called before the store has been initialised.
 280       *
 281       * @since Moodle 2.5
 282       * @see cleanup()
 283       */
 284      public function instance_deleted() {
 285          if (method_exists($this, 'cleanup')) {
 286              // There used to be a legacy function called cleanup, it was renamed to instance delete.
 287              // To be removed in 2.6.
 288              $this->cleanup();
 289          }
 290      }
 291  
 292      /**
 293       * Returns true if the user can add an instance of the store plugin.
 294       *
 295       * @return bool
 296       */
 297      public static function can_add_instance() {
 298          return true;
 299      }
 300  
 301      /**
 302       * Returns true if the store instance guarantees data.
 303       *
 304       * @return bool
 305       */
 306      public function supports_data_guarantee() {
 307          return $this::get_supported_features() & self::SUPPORTS_DATA_GUARANTEE;
 308      }
 309  
 310      /**
 311       * Returns true if the store instance supports multiple identifiers.
 312       *
 313       * @return bool
 314       */
 315      public function supports_multiple_identifiers() {
 316          return $this::get_supported_features() & self::SUPPORTS_MULTIPLE_IDENTIFIERS;
 317      }
 318  
 319      /**
 320       * Returns true if the store instance supports native ttl.
 321       *
 322       * @return bool
 323       */
 324      public function supports_native_ttl() {
 325          return $this::get_supported_features() & self::SUPPORTS_NATIVE_TTL;
 326      }
 327  
 328      /**
 329       * Returns true if the store instance is searchable.
 330       *
 331       * @return bool
 332       */
 333      public function is_searchable() {
 334          return in_array('cache_is_searchable', class_implements($this));
 335      }
 336  
 337      /**
 338       * Creates a clone of this store instance ready to be initialised.
 339       *
 340       * This method is used so that a cache store needs only be constructed once.
 341       * Future requests for an instance of the store will be given a cloned instance.
 342       *
 343       * If you are writing a cache store that isn't compatible with the clone operation
 344       * you can override this method to handle any situations you want before cloning.
 345       *
 346       * @param array $details An array containing the details of the store from the cache config.
 347       * @return cache_store
 348       */
 349      public function create_clone(array $details = array()) {
 350          // By default we just run clone.
 351          // Any stores that have an issue with this will need to override the create_clone method.
 352          return clone($this);
 353      }
 354  
 355      /**
 356       * Initialises a test instance for unit tests.
 357       *
 358       * This differs from initialise_test_instance in that it doesn't rely on interacting with the config table.
 359       * By default however it calls initialise_test_instance to support backwards compatibility.
 360       *
 361       * @since 2.8
 362       * @param cache_definition $definition
 363       * @return cache_store|false
 364       */
 365      public static function initialise_unit_test_instance(cache_definition $definition) {
 366          return static::initialise_test_instance($definition);
 367      }
 368  
 369      /**
 370       * Can be overridden to return any warnings this store instance should make to the admin.
 371       *
 372       * This should be used to notify things like configuration conflicts etc.
 373       * The warnings returned here will be displayed on the cache configuration screen.
 374       *
 375       * @return string[] An array of warning strings from the store instance.
 376       */
 377      public function get_warnings() {
 378          return array();
 379      }
 380  }