Proyectos de Subversion Moodle

<?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/>.

/**

 * This file contains the cache factory class.

 *

 * This file is part of Moodle's cache API, affectionately called MUC.

 * It contains the components that are requried 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();

/**

 * The cache factory class.

 *

 * This factory class is important because it stores instances of objects used by the cache API and returns them upon requests.

 * This allows us to both reuse objects saving on overhead, and gives us an easy place to "reset" the cache API in situations that

 * we need such as unit testing.

 *

 * @copyright  2012 Sam Hemelryk

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class cache_factory {

    /** The cache has not been initialised yet. */

    const STATE_UNINITIALISED = 0;

    /** The cache is in the process of initialising itself. */

    const STATE_INITIALISING = 1;

    /** The cache is in the process of saving its configuration file. */

    const STATE_SAVING = 2;

    /** The cache is ready to use. */

    const STATE_READY = 3;

    /** The cache is currently updating itself */

    const STATE_UPDATING = 4;

    /** The cache encountered an error while initialising. */

    const STATE_ERROR_INITIALISING = 9;

    /** The cache has been disabled. */

    const STATE_DISABLED = 10;

    /** The cache stores have been disabled */

    const STATE_STORES_DISABLED = 11;

    /**

     * An instance of the cache_factory class created upon the first request.

     * @var cache_factory

     */

    protected static $instance;

    /**

     * An array containing caches created for definitions

     * @var array

     */

    protected $cachesfromdefinitions = array();

    /**

     * Array of caches created by parameters, ad-hoc definitions will have been used.

     * @var array

     */

    protected $cachesfromparams = array();

    /**

     * An array of stores organised by definitions.

     * @var array

     */

    protected $definitionstores = array();

    /**

     * An array of instantiated stores.

     * @var array

     */

    protected $stores = array();

    /**

     * An array of configuration instances

     * @var array

     */

    protected $configs = array();

    /**

     * An array of initialised definitions

     * @var array

     */

    protected $definitions = array();

    /**

     * An array of lock plugins.

     * @var array

     */

    protected $lockplugins = array();

    /**

     * The current state of the cache API.

     * @var int

     */

    protected $state = 0;

    /**

     * The current cache display helper.

     * @var core_cache\local\administration_display_helper

     */

    protected static $displayhelper = null;

    /**

     * Returns an instance of the cache_factory class.

     *

     * @param bool $forcereload If set to true a new cache_factory instance will be created and used.

     * @return cache_factory

     */

    public static function instance($forcereload = false) {

        global $CFG;

        if ($forcereload || self::$instance === null) {

            // Initialise a new factory to facilitate our needs.

            if (defined('CACHE_DISABLE_ALL') && CACHE_DISABLE_ALL !== false) {

                // The cache has been disabled. Load disabledlib and start using the factory designed to handle this

                // situation. It will use disabled alternatives where available.

                require_once($CFG->dirroot.'/cache/disabledlib.php');

                self::$instance = new cache_factory_disabled();

            } else if ((defined('PHPUNIT_TEST') && PHPUNIT_TEST) || defined('BEHAT_SITE_RUNNING')) {

                // We're using the test factory.

                require_once($CFG->dirroot.'/cache/tests/fixtures/lib.php');

                self::$instance = new cache_phpunit_factory();

                if (defined('CACHE_DISABLE_STORES') && CACHE_DISABLE_STORES !== false) {

                    // The cache stores have been disabled.

                    self::$instance->set_state(self::STATE_STORES_DISABLED);

                }

            } else if (!empty($CFG->alternative_cache_factory_class)) {

                $factoryclass = $CFG->alternative_cache_factory_class;

                self::$instance = new $factoryclass();

            } else {

                // We're using the regular factory.

                self::$instance = new cache_factory();

                if (defined('CACHE_DISABLE_STORES') && CACHE_DISABLE_STORES !== false) {

                    // The cache stores have been disabled.

                    self::$instance->set_state(self::STATE_STORES_DISABLED);

                }

            }

        }

        return self::$instance;

    }

    /**

     * Protected constructor, please use the static instance method.

     */

    protected function __construct() {

        // Nothing to do here.

    }

    /**

     * Resets the arrays containing instantiated caches, stores, and config instances.

     */

    public static function reset() {

        $factory = self::instance();

        $factory->reset_cache_instances();

        $factory->configs = array();

        $factory->definitions = array();

        $factory->definitionstores = array();

        $factory->lockplugins = array(); // MUST be null in order to force its regeneration.

        // Reset the state to uninitialised.

        $factory->state = self::STATE_UNINITIALISED;

    }

    /**

     * Resets the stores, clearing the array of created stores.

     *

     * Cache objects still held onto by the code that initialised them will remain as is

     * however all future requests for a cache/store will lead to a new instance being re-initialised.

     */

    public function reset_cache_instances() {

        $this->cachesfromdefinitions = array();

        $this->cachesfromparams = array();

        $this->stores = array();

    }

    /**

     * Creates a cache object given the parameters for a definition.

     *

     * If a cache has already been created for the given definition then that cache instance will be returned.

     *

     * @param string $component

     * @param string $area

     * @param array $identifiers

     * @param string $unused Used to be data source aggregate however that was removed and this is now unused.

     * @return cache_application|cache_session|cache_request

     */

    public function create_cache_from_definition($component, $area, array $identifiers = array(), $unused = null) {

        $identifierstring = empty($identifiers) ? '' : '/'.http_build_query($identifiers);

        $definitionname = $component.'/'.$area.$identifierstring;

        if (isset($this->cachesfromdefinitions[$definitionname])) {

            $cache = $this->cachesfromdefinitions[$definitionname];

            return $cache;

        }

        $definition = $this->create_definition($component, $area);

        // Identifiers are cached as part of the cache creation, so we store a cloned version of the cache.

        $cacheddefinition = clone($definition);

        $cacheddefinition->set_identifiers($identifiers);

        $cache = $this->create_cache($cacheddefinition);

        // Loaders are always held onto to speed up subsequent requests.

        $this->cachesfromdefinitions[$definitionname] = $cache;

        return $cache;

    }

    /**

     * Creates an ad-hoc cache from the given param.

     *

     * If a cache has already been created using the same params then that cache instance will be returned.

     *

     * @param int $mode

     * @param string $component

     * @param string $area

     * @param array $identifiers

     * @param array $options An array of options, available options are:

     *   - simplekeys : Set to true if the keys you will use are a-zA-Z0-9_

     *   - simpledata : Set to true if the type of the data you are going to store is scalar, or an array of scalar vars

     *   - staticacceleration : If set to true the cache will hold onto data passing through it.

     *   - staticaccelerationsize : The maximum number of items to hold onto for acceleration purposes.

     * @return cache_application|cache_session|cache_request

     */

    public function create_cache_from_params($mode, $component, $area, array $identifiers = array(), array $options = array()) {

        $identifierstring = empty($identifiers) ? '' : '_'.http_build_query($identifiers);

        $key = "{$mode}_{$component}_{$area}{$identifierstring}";

        if (isset($this->cachesfromparams[$key])) {

            return $this->cachesfromparams[$key];

        }

        // Regular cache definitions are cached inside create_definition().  This is not the case for Adhoc definitions

        // using load_adhoc().  They are built as a new object on each call.

        // We do not need to clone the definition because we know it's new.

        $definition = cache_definition::load_adhoc($mode, $component, $area, $options);

        $definition->set_identifiers($identifiers);

        $cache = $this->create_cache($definition);

        $this->cachesfromparams[$key] = $cache;

        return $cache;

    }

    /**

     * Common public method to create a cache instance given a definition.

     *

     * This is used by the static make methods.

     *

     * @param cache_definition $definition

     * @return cache_application|cache_session|cache_store

     * @throws coding_exception

     */

    public function create_cache(cache_definition $definition) {

        $class = $definition->get_cache_class();

        $stores = cache_helper::get_stores_suitable_for_definition($definition);

        foreach ($stores as $key => $store) {

            if (!$store::are_requirements_met()) {

                unset($stores[$key]);

            }

        }

        if (count($stores) === 0) {

            // Hmm still no stores, better provide a dummy store to mimic functionality. The dev will be none the wiser.

            $stores[] = $this->create_dummy_store($definition);

        }

        $loader = null;

        if ($definition->has_data_source()) {

            $loader = $definition->get_data_source();

        }

        while (($store = array_pop($stores)) !== null) {

            $loader = new $class($definition, $store, $loader);

        }

        return $loader;

    }

    /**

     * Creates a store instance given its name and configuration.

     *

     * If the store has already been instantiated then the original object will be returned. (reused)

     *

     * @param string $name The name of the store (must be unique remember)

     * @param array $details

     * @param cache_definition $definition The definition to instantiate it for.

     * @return boolean|cache_store

     */

    public function create_store_from_config($name, array $details, cache_definition $definition) {

        if (!array_key_exists($name, $this->stores)) {

            // Properties: name, plugin, configuration, class.

            $class = $details['class'];

            if (!$class::are_requirements_met()) {

                return false;

            }

            $store = new $class($details['name'], $details['configuration']);

            $this->stores[$name] = $store;

        }

        /* @var cache_store $store */

        $store = $this->stores[$name];

        // We check are_requirements_met although we expect is_ready is going to check as well.

        if (!$store::are_requirements_met() || !$store->is_ready() || !$store->is_supported_mode($definition->get_mode())) {

            return false;

        }

        // We always create a clone of the original store.

        // If we were to clone a store that had already been initialised with a definition then

        // we'd run into a myriad of issues.

        // We use a method of the store to create a clone rather than just creating it ourselves

        // so that if any store out there doesn't handle cloning they can override this method in

        // order to address the issues.

        $store = $this->stores[$name]->create_clone($details);

        $store->initialise($definition);

        $definitionid = $definition->get_id();

        if (!isset($this->definitionstores[$definitionid])) {

            $this->definitionstores[$definitionid] = array();

        }

        $this->definitionstores[$definitionid][] = $store;

        return $store;

    }

    /**

     * Returns an array of cache stores that have been initialised for use in definitions.

     * @param cache_definition $definition

     * @return array

     */

    public function get_store_instances_in_use(cache_definition $definition) {

        $id = $definition->get_id();

        if (!isset($this->definitionstores[$id])) {

            return array();

        }

        return $this->definitionstores[$id];

    }

    /**

     * Returns the cache instances that have been used within this request.

     * @since Moodle 2.6

     * @return array

     */

    public function get_caches_in_use() {

        return $this->cachesfromdefinitions;

    }

    /**

     * Gets all adhoc caches that have been used within this request.

     *

     * @return cache_store[] Caches currently in use

     */

    public function get_adhoc_caches_in_use() {

        return $this->cachesfromparams;

    }

    /**

     * Creates a cache config instance with the ability to write if required.

     *

     * @param bool $writer If set to true an instance that can update the configuration will be returned.

     * @return cache_config|cache_config_writer

     */

    public function create_config_instance($writer = false) {

        global $CFG;

        // The class to use.

        $class = 'cache_config';

        // Are we running tests of some form?

        $testing = (defined('PHPUNIT_TEST') && PHPUNIT_TEST) || defined('BEHAT_SITE_RUNNING');

        // Check if this is a PHPUnit test and redirect to the phpunit config classes if it is.

        if ($testing) {

            require_once($CFG->dirroot.'/cache/locallib.php');

            require_once($CFG->dirroot.'/cache/tests/fixtures/lib.php');

            // We have just a single class for PHP unit tests. We don't care enough about its

            // performance to do otherwise and having a single method allows us to inject things into it

            // while testing.

            $class = 'cache_config_testing';

        }

        // Check if we need to create a config file with defaults.

        $needtocreate = !$class::config_file_exists();

        if ($writer || $needtocreate) {

            require_once($CFG->dirroot.'/cache/locallib.php');

            if (!$testing) {

                $class .= '_writer';

            }

        }

        $error = false;

        if ($needtocreate) {

            // Create the default configuration.

            // Update the state, we are now initialising the cache.

            self::set_state(self::STATE_INITIALISING);

            /** @var cache_config_writer $class */

            $configuration = $class::create_default_configuration();

            if ($configuration !== true) {

                // Failed to create the default configuration. Disable the cache stores and update the state.

                self::set_state(self::STATE_ERROR_INITIALISING);

                $this->configs[$class] = new $class;

                $this->configs[$class]->load($configuration);

                $error = true;

            }

        }

        if (!array_key_exists($class, $this->configs)) {

            // Create a new instance and call it to load it.

            $this->configs[$class] = new $class;

            $this->configs[$class]->load();

        }

        if (!$error) {

            // The cache is now ready to use. Update the state.

            self::set_state(self::STATE_READY);

        }

        // Return the instance.

        return $this->configs[$class];

    }

    /**

     * Creates a definition instance or returns the existing one if it has already been created.

     * @param string $component

     * @param string $area

     * @param string $unused This used to be data source aggregate - however that functionality has been removed and

     *        this argument is now unused.

     * @return cache_definition

     * @throws coding_exception If the definition cannot be found.

     */

    public function create_definition($component, $area, $unused = null) {

        $id = $component.'/'.$area;

        if (!isset($this->definitions[$id])) {

            // This is the first time this definition has been requested.

            if ($this->is_initialising()) {

                // We're initialising the cache right now. Don't try to create another config instance.

                // We'll just use an ad-hoc cache for the time being.

                $definition = cache_definition::load_adhoc(cache_store::MODE_REQUEST, $component, $area);

            } else {

                // Load all the known definitions and find the desired one.

                $instance = $this->create_config_instance();

                $definition = $instance->get_definition_by_id($id);

                if (!$definition) {

                    // Oh-oh the definition doesn't exist.

                    // There are several things that could be going on here.

                    // We may be installing/upgrading a site and have hit a definition that hasn't been used before.

                    // Of the developer may be trying to use a newly created definition.

                    if ($this->is_updating()) {

                        // The cache is presently initialising and the requested cache definition has not been found.

                        // This means that the cache initialisation has requested something from a cache (I had recursive nightmares about this).

                        // To serve this purpose and avoid errors we are going to make use of an ad-hoc cache rather than

                        // search for the definition which would possibly cause an infitite loop trying to initialise the cache.

                        $definition = cache_definition::load_adhoc(cache_store::MODE_REQUEST, $component, $area);

                    } else {

                        // Either a typo of the developer has just created the definition and is using it for the first time.

                        $this->reset();

                        $instance = $this->create_config_instance(true);

                        $instance->update_definitions();

                        $definition = $instance->get_definition_by_id($id);

                        if (!$definition) {

                            throw new coding_exception('The requested cache definition does not exist.'. $id, $id);

                        }

                        if (!$this->is_disabled()) {

                            debugging('Cache definitions reparsed causing cache reset in order to locate definition.

                                You should bump the version number to ensure definitions are reprocessed.', DEBUG_DEVELOPER);

                        }

                        $definition = cache_definition::load($id, $definition);

                    }

                } else {

                    $definition = cache_definition::load($id, $definition);

                }

            }

            $this->definitions[$id] = $definition;

        }

        return $this->definitions[$id];

    }

    /**

     * Creates a dummy store object for use when a loader has no potential stores to use.

     *

     * @param cache_definition $definition

     * @return cachestore_dummy

     */

    protected function create_dummy_store(cache_definition $definition) {

        global $CFG;

        require_once($CFG->dirroot.'/cache/classes/dummystore.php');

        $store = new cachestore_dummy();

        $store->initialise($definition);

        return $store;

    }

    /**

     * Returns a lock instance ready for use.

     *

     * @param array $config

     * @return cache_lock_interface

     */

    public function create_lock_instance(array $config) {

        global $CFG;

        if (!array_key_exists('name', $config) || !array_key_exists('type', $config)) {

            throw new coding_exception('Invalid cache lock instance provided');

        }

        $name = $config['name'];

        $type = $config['type'];

        unset($config['name']);

        unset($config['type']);

        if (!isset($this->lockplugins[$type])) {

            $pluginname = substr($type, 10);

            $file = $CFG->dirroot."/cache/locks/{$pluginname}/lib.php";

            if (file_exists($file) && is_readable($file)) {

                require_once($file);

            }

            if (!class_exists($type)) {

                throw new coding_exception('Invalid lock plugin requested.');

            }

            $this->lockplugins[$type] = $type;

        }

        if (!array_key_exists($type, $this->lockplugins)) {

            throw new coding_exception('Invalid cache lock type.');

        }

        $class = $this->lockplugins[$type];

        return new $class($name, $config);

    }

    /**

     * Returns the current state of the cache API.

     *

     * @return int

     */

    public function get_state() {

        return $this->state;

    }

    /**

     * Updates the state fo the cache API.

     *

     * @param int $state

     * @return bool

     */

    public function set_state($state) {

        if ($state <= $this->state) {

            return false;

        }

        $this->state = $state;

        return true;

    }

    /**

     * Informs the factory that the cache is currently updating itself.

     *

     * This forces the state to upgrading and can only be called once the cache is ready to use.

     * Calling it ensure we don't try to reinstantite things when requesting cache definitions that don't exist yet.

     */

    public function updating_started() {

        if ($this->state !== self::STATE_READY) {

            return false;

        }

        $this->state = self::STATE_UPDATING;

        return true;

    }

    /**

     * Informs the factory that the upgrading has finished.

     *

     * This forces the state back to ready.

     */

    public function updating_finished() {

        $this->state = self::STATE_READY;

    }

    /**

     * Returns true if the cache API has been disabled.

     *

     * @return bool

     */

    public function is_disabled() {

        return $this->state === self::STATE_DISABLED;

    }

    /**

     * Returns true if the cache is currently initialising itself.

     *

     * This includes both initialisation and saving the cache config file as part of that initialisation.

     *

     * @return bool

     */

    public function is_initialising() {

        return $this->state === self::STATE_INITIALISING || $this->state === self::STATE_SAVING;

    }

    /**

     * Returns true if the cache is currently updating itself.

     *

     * @return bool

     */

    public function is_updating() {

        return $this->state === self::STATE_UPDATING;

    }

    /**

     * Disables as much of the cache API as possible.

     *

     * All of the magic associated with the disabled cache is wrapped into this function.

     * In switching out the factory for the disabled factory it gains full control over the initialisation of objects

     * and can use all of the disabled alternatives.

     * Simple!

     *

     * This function has been marked as protected so that it cannot be abused through the public API presently.

     * Perhaps in the future we will allow this, however as per the build up to the first release containing

     * MUC it was decided that this was just to risky and abusable.

     */

    protected static function disable() {

        global $CFG;

        require_once($CFG->dirroot.'/cache/disabledlib.php');

        self::$instance = new cache_factory_disabled();

    }

    /**

     * Returns true if the cache stores have been disabled.

     *

     * @return bool

     */

    public function stores_disabled() {

        return $this->state === self::STATE_STORES_DISABLED || $this->is_disabled();

    }

    /**

     * Disables cache stores.

     *

     * The cache API will continue to function however none of the actual stores will be used.

     * Instead the dummy store will be provided for all cache requests.

     * This is useful in situations where you cannot be sure any stores are working.

     *

     * In order to re-enable the cache you must call the cache factories static reset method:

     * <code>

     * // Disable the cache factory.

     * cache_factory::disable_stores();

     * // Re-enable the cache factory by resetting it.

     * cache_factory::reset();

     * </code>

     */

    public static function disable_stores() {

        // First reset to clear any static acceleration array.

        $factory = self::instance();

        $factory->reset_cache_instances();

        $factory->set_state(self::STATE_STORES_DISABLED);

    }

    /**

     * Returns an instance of the current display_helper.

     *

     * @return core_cache\administration_helper

     */

    public static function get_administration_display_helper(): core_cache\administration_helper {

        if (is_null(self::$displayhelper)) {

            self::$displayhelper = new \core_cache\local\administration_display_helper();

        }

        return self::$displayhelper;

    }

    /**

     * Gets the cache_config_writer to use when caching is disabled.

     * This should only be called from cache_factory_disabled.

     *

     * @return cache_config_writer

     */

    public static function get_disabled_writer(): cache_config_writer {

        global $CFG;

        // Figure out if we are in a recursive loop using late static binding.

        // This happens when get_disabled_writer is not overridden. We just want the default.

        $loop = false;

        if (!empty($CFG->alternative_cache_factory_class)) {

            $loop = get_called_class() === $CFG->alternative_cache_factory_class;

        }

        if (!$loop && !empty($CFG->alternative_cache_factory_class)) {

            // Get the class to use from the alternative factory.

            $factoryinstance = new $CFG->alternative_cache_factory_class();

            return $factoryinstance::get_disabled_writer();

        } else {

            // We got here from cache_factory_disabled.

            // We should use the default writer here.

            // Make sure we have a default config if needed.

            if (!cache_config::config_file_exists()) {

                cache_config_writer::create_default_configuration(true);

            }

            return new cache_config_writer();

        }

    }

}