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