Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
  • Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Cache store - base class
 *
 * This file is part of Moodle's cache API, affectionately called MUC.
 * It contains the components that are required in order to use caching.
 *
 * @package    core
 * @category   cache
 * @copyright  2012 Sam Hemelryk
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

defined('MOODLE_INTERNAL') || die();

/**
 * Cache store interface.
 *
 * This interface defines the static methods that must be implemented by every cache store plugin.
 * To ensure plugins implement this class the abstract cache_store class implements this interface.
 *
 * @package    core
 * @category   cache
 * @copyright  2012 Sam Hemelryk
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
interface cache_store_interface {
    /**
     * Static method to check if the store requirements are met.
     *
     * @return bool True if the stores software/hardware requirements have been met and it can be used. False otherwise.
     */
    public static function are_requirements_met();

    /**
     * Static method to check if a store is usable with the given mode.
     *
     * @param int $mode One of cache_store::MODE_*
     */
    public static function is_supported_mode($mode);

    /**
     * Returns the supported features as a binary flag.
     *
     * @param array $configuration The configuration of a store to consider specifically.
     * @return int The supported features.
     */
    public static function get_supported_features(array $configuration = array());

    /**
     * Returns the supported modes as a binary flag.
     *
     * @param array $configuration The configuration of a store to consider specifically.
     * @return int The supported modes.
     */
    public static function get_supported_modes(array $configuration = array());

    /**
     * Generates an instance of the cache store that can be used for testing.
     *
     * Returns an instance of the cache store, or false if one cannot be created.
     *
     * @param cache_definition $definition
     * @return cache_store|false
     */
    public static function initialise_test_instance(cache_definition $definition);

    /**
     * Generates the appropriate configuration required for unit testing.
     *
     * @return array Array of unit test configuration data to be used by initialise().
     */
    public static function unit_test_configuration();
}

/**
 * Abstract cache store class.
 *
 * All cache store plugins must extend this base class.
 * It lays down the foundation for what is required of a cache store plugin.
 *
 * @since Moodle 2.4
 * @package    core
 * @category   cache
 * @copyright  2012 Sam Hemelryk
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class cache_store implements cache_store_interface {

    // Constants for features a cache store can support

    /**
     * Supports multi-part keys
     */
    const SUPPORTS_MULTIPLE_IDENTIFIERS = 1;
    /**
     * Ensures data remains in the cache once set.
     */
    const SUPPORTS_DATA_GUARANTEE = 2;
    /**
     * Supports a native ttl system.
     */
    const SUPPORTS_NATIVE_TTL = 4;

    /**
     * The cache is searchable by key.
     */
    const IS_SEARCHABLE = 8;

    /**
     * The cache store dereferences objects.
     *
     * When set, loaders will assume that all data coming from this store has already had all references
     * resolved.  So even for complex object structures it will not try to remove references again.
     */
    const DEREFERENCES_OBJECTS = 16;

    // Constants for the modes of a cache store

    /**
     * Application caches. These are shared caches.
     */
    const MODE_APPLICATION = 1;
    /**
     * Session caches. Just access to the PHP session.
     */
    const MODE_SESSION = 2;
    /**
     * Request caches. Static caches really.
     */
    const MODE_REQUEST = 4;
    /**
     * Static caches.
     */
    const STATIC_ACCEL = '** static accel. **';

    /**
> * Returned from get_last_io_bytes if this cache store doesn't support counting bytes read/sent. * Constructs an instance of the cache store. > */ * > const IO_BYTES_NOT_SUPPORTED = -1; * The constructor should be responsible for creating anything needed by the store that is not > * specific to a definition. > /**
* Tasks such as opening a connection to check it is available are best done here. * Tasks that are definition specific such as creating a storage area for the definition data * or creating key tables and indexs are best done within the initialise method. * * Once a store has been constructed the cache API will check it is ready to be intialised with * a definition by called $this->is_ready(). * If the setup of the store failed (connection could not be established for example) then * that method should return false so that the store instance is not selected for use. * * @param string $name The name of the cache store * @param array $configuration The configuration for this store instance. */ abstract public function __construct($name, array $configuration = array()); /** * Returns the name of this store instance. * @return string */ abstract public function my_name(); /** * Initialises a new instance of the cache store given the definition the instance is to be used for. * * This function should be used to run any definition specific setup the store instance requires. * Tasks such as creating storage areas, or creating indexes are best done here. * * Its important to note that the initialise method is expected to always succeed. * If there are setup tasks that may fail they should be done within the __construct method * and should they fail is_ready should return false. * * @param cache_definition $definition */ abstract public function initialise(cache_definition $definition); /** * Returns true if this cache store instance has been initialised. * @return bool */ abstract public function is_initialised(); /** * Returns true if this cache store instance is ready to use. * @return bool */ public function is_ready() { return forward_static_call(array($this, 'are_requirements_met')); } /** * Retrieves an item from the cache store given its key. * * @param string $key The key to retrieve * @return mixed The data that was associated with the key, or false if the key did not exist. */ abstract public function get($key); /** * Retrieves several items from the cache store in a single transaction. * * 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. * * @param array $keys The array of keys to retrieve * @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 * be set to false. */ abstract public function get_many($keys); /** * Sets an item in the cache given its key and data value. * * @param string $key The key to use. * @param mixed $data The data to set. * @return bool True if the operation was a success false otherwise. */ abstract public function set($key, $data); /** * Sets many items in the cache in a single transaction. * * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two * keys, 'key' and 'value'. * @return int The number of items successfully set. It is up to the developer to check this matches the number of items * sent ... if they care that is. */ abstract public function set_many(array $keyvaluearray); /** * Deletes an item from the cache store. * * @param string $key The key to delete. * @return bool Returns true if the operation was a success, false otherwise. */ abstract public function delete($key); /** * Deletes several keys from the cache in a single action. * * @param array $keys The keys to delete * @return int The number of items successfully deleted. */ abstract public function delete_many(array $keys); /** * Purges the cache deleting all items within it. * * @return boolean True on success. False otherwise. */ abstract public function purge(); /** * @deprecated since 2.5 * @see \cache_store::instance_deleted() */ public function cleanup() { throw new coding_exception('cache_store::cleanup() can not be used anymore.' . ' Please use cache_store::instance_deleted() instead.'); } /** * Performs any necessary operation when the store instance has been created. * * @since Moodle 2.5 */ public function instance_created() { // By default, do nothing. } /** * Performs any necessary operation when the store instance is being deleted. * * This method may be called before the store has been initialised. * * @since Moodle 2.5 * @see cleanup() */ public function instance_deleted() { if (method_exists($this, 'cleanup')) { // There used to be a legacy function called cleanup, it was renamed to instance delete. // To be removed in 2.6. $this->cleanup(); } } /** * Returns true if the user can add an instance of the store plugin. * * @return bool */ public static function can_add_instance() { return true; } /** * Returns true if the store instance guarantees data. * * @return bool */ public function supports_data_guarantee() { return $this::get_supported_features() & self::SUPPORTS_DATA_GUARANTEE; } /** * Returns true if the store instance supports multiple identifiers. * * @return bool */ public function supports_multiple_identifiers() { return $this::get_supported_features() & self::SUPPORTS_MULTIPLE_IDENTIFIERS; } /** * Returns true if the store instance supports native ttl. * * @return bool */ public function supports_native_ttl() { return $this::get_supported_features() & self::SUPPORTS_NATIVE_TTL; } /** * Returns true if the store instance is searchable. * * @return bool */ public function is_searchable() { return in_array('cache_is_searchable', class_implements($this)); } /** * Returns true if the store automatically dereferences objects. * * @return bool */ public function supports_dereferencing_objects() { return $this::get_supported_features() & self::DEREFERENCES_OBJECTS; } /** * Creates a clone of this store instance ready to be initialised. * * This method is used so that a cache store needs only be constructed once. * Future requests for an instance of the store will be given a cloned instance. * * If you are writing a cache store that isn't compatible with the clone operation * you can override this method to handle any situations you want before cloning. * * @param array $details An array containing the details of the store from the cache config. * @return cache_store */ public function create_clone(array $details = array()) { // By default we just run clone. // Any stores that have an issue with this will need to override the create_clone method. return clone($this); } /** * Can be overridden to return any warnings this store instance should make to the admin. * * This should be used to notify things like configuration conflicts etc. * The warnings returned here will be displayed on the cache configuration screen. * * @return string[] An array of warning strings from the store instance. */ public function get_warnings() { return array(); } /**
> * Estimates the storage size used within this cache if the given value is stored with the * Returns true if this cache store instance is both suitable for testing, and ready for testing. > * given key. * > * * Cache stores that support being used as the default store for unit and acceptance testing should > * This function is not exactly accurate; it does not necessarily take into account all the * override this function and return true if there requirements have been met. > * overheads involved. It is only intended to give a good idea of the relative size of * > * different caches. * @return bool > * */ > * The default implementation serializes both key and value and sums the lengths (as a rough public static function ready_to_be_used_for_testing() { > * estimate which is probably good enough for everything unless the cache offers compression). return false; > * } > * @param mixed $key Key } > * @param mixed $value Value > * @return int Size in bytes > */ > public function estimate_stored_size($key, $value): int { > return strlen(serialize($key)) + strlen(serialize($value)); > } > > /** > * Gets the amount of memory/storage currently used by this cache store if known. > * > * This value should be obtained quickly from the store itself, if available. > * > * This is the total memory usage of the entire store, not for ther specific cache in question. > * > * Where not supported (default), will always return null. > * > * @return int|null Amount of memory used in bytes or null > */ > public function store_total_size(): ?int { > return null; > } > > /** > * Gets the amount of memory used by this specific cache within the store, if known. > * > * This function may be slow and should not be called in normal usage, only for administration > * pages. The value is usually an estimate, and may not be available at all. > * > * When estimating, a number of sample items will be used for the estimate. If set to 50 > * (default), then this function will retrieve 50 random items and use that to estimate the > * total size. > * > * The return value has the following fields: > * - supported (true if any other values are completed) > * - items (number of items) > * - mean (mean size of one item in bytes) > * - sd (standard deviation of item size in bytes, based on sample) > * - margin (95% confidence margin for mean - will be 0 if exactly computed) > * > * @param int $samplekeys Number of samples to use > * @return stdClass Object with information about the store size > */ > public function cache_size_details(int $samplekeys = 50): stdClass { > $result = (object)[ > 'supported' => false, > 'items' => 0, > 'mean' => 0, > 'sd' => 0, > 'margin' => 0 > ]; > > // If this cache isn't searchable, we don't know the answer. > if (!$this->is_searchable()) { > return $result; > } > $result->supported = true; > > // Get all the keys for the cache. > $keys = $this->find_all(); > $result->items = count($keys); > > // Don't do anything else if there are no items. > if ($result->items === 0) { > return $result; > } > > // Select N random keys. > $exact = false; > if ($result->items <= $samplekeys) { > $samples = $keys; > $exact = true; > } else { > $indexes = array_rand($keys, $samplekeys); > $samples = []; > foreach ($indexes as $index) { > $samples[] = $keys[$index]; > } > } > > // Get the random items from cache and estimate the size of each. > $sizes = []; > foreach ($samples as $samplekey) { > $value = $this->get($samplekey); > $sizes[] = $this->estimate_stored_size($samplekey, $value); > } > $number = count($sizes); > > // Calculate the mean and standard deviation. > $result->mean = array_sum($sizes) / $number; > $squarediff = 0; > foreach ($sizes as $size) { > $squarediff += ($size - $result->mean) ** 2; > } > $squarediff /= $number; > $result->sd = sqrt($squarediff); > > // If it's not exact, also calculate the confidence interval. > if (!$exact) { > // 95% confidence has a Z value of 1.96. > $result->margin = (1.96 * $result->sd) / sqrt($number); > } > > return $result; > } > > /**
> } > > /** > * Gets the number of bytes read from or written to cache as a result of the last action. > * > * This includes calls to the functions get(), get_many(), set(), and set_many(). The number > * is reset by calling any of these functions. > * > * This should be the actual number of bytes of the value read from or written to cache, > * giving an impression of the network or other load. It will not be exactly the same amount > * as netowrk traffic because of protocol overhead, key text, etc. > * > * If not supported, returns IO_BYTES_NOT_SUPPORTED. > * > * @return int Bytes read (or 0 if none/not supported) > * @since Moodle 4.0 > */ > public function get_last_io_bytes(): int { > return self::IO_BYTES_NOT_SUPPORTED;