464df843d3b44526bc58e584e15b76eb8b50660c
[moodle.git] / cache / classes / store.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
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  */
29 defined('MOODLE_INTERNAL') || die();
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();
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);
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());
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());
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);
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 }
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 {
109     // Constants for features a cache store can support
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;
124     /**
125      * The cache is searchable by key.
126      */
127     const IS_SEARCHABLE = 8;
129     // Constants for the modes of a cache store
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;
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());
163     /**
164      * Returns the name of this store instance.
165      * @return string
166      */
167     abstract public function my_name();
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);
183     /**
184      * Returns true if this cache store instance has been initialised.
185      * @return bool
186      */
187     abstract public function is_initialised();
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     }
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);
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);
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);
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);
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);
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);
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();
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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 array[] Returns an array of arrays with the format:
376      *     $notifications = array(
377      *         array('This is a success message', true),
378      *         array('This is a failure message', false),
379      *     );
380      */
381     public function get_warnings() {
382         return array();
383     }