Revert "MDL-38555 forms: Prevent same data submission multiple times."
[moodle.git] / cache / classes / loaders.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 loaders
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  * The main cache class.
33  *
34  * This class if the first class that any end developer will interact with.
35  * In order to create an instance of a cache that they can work with they must call one of the static make methods belonging
36  * to this class.
37  *
38  * @package    core
39  * @category   cache
40  * @copyright  2012 Sam Hemelryk
41  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42  */
43 class cache implements cache_loader {
45     /**
46      * We need a timestamp to use within the cache API.
47      * This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with
48      * timing issues.
49      * @var int
50      */
51     protected static $now;
53     /**
54      * The definition used when loading this cache if there was one.
55      * @var cache_definition
56      */
57     private $definition = false;
59     /**
60      * The cache store that this loader will make use of.
61      * @var cache_store
62      */
63     private $store;
65     /**
66      * The next cache loader in the chain if there is one.
67      * If a cache request misses for the store belonging to this loader then the loader
68      * stored here will be checked next.
69      * If there is a loader here then $datasource must be false.
70      * @var cache_loader|false
71      */
72     private $loader = false;
74     /**
75      * The data source to use if we need to load data (because if doesn't exist in the cache store).
76      * If there is a data source here then $loader above must be false.
77      * @var cache_data_source|false
78      */
79     private $datasource = false;
81     /**
82      * Used to quickly check if the store supports key awareness.
83      * This is set when the cache is initialised and is used to speed up processing.
84      * @var bool
85      */
86     private $supportskeyawareness = null;
88     /**
89      * Used to quickly check if the store supports ttl natively.
90      * This is set when the cache is initialised and is used to speed up processing.
91      * @var bool
92      */
93     private $supportsnativettl = null;
95     /**
96      * Gets set to true if the cache is going to be using the build in static "persist" cache.
97      * The persist cache statically caches items used during the lifetime of the request. This greatly speeds up interaction
98      * with the cache in areas where it will be repetitively hit for the same information such as with strings.
99      * There are several other variables to control how this persist cache works.
100      * @var bool
101      */
102     private $persist = false;
104     /**
105      * The persist cache itself.
106      * Items will be stored in this cache as they were provided. This ensure there is no unnecessary processing taking place.
107      * @var array
108      */
109     private $persistcache = array();
111     /**
112      * The number of items in the persist cache. Avoids count calls like you wouldn't believe.
113      * @var int
114      */
115     private $persistcount = 0;
117     /**
118      * An array containing just the keys being used in the persist cache.
119      * This seems redundant perhaps but is used when managing the size of the persist cache.
120      * @var array
121      */
122     private $persistkeys = array();
124     /**
125      * The maximum size of the persist cache. If set to false there is no max size.
126      * Caches that make use of the persist cache should seriously consider setting this to something reasonably small, but
127      * still large enough to offset repetitive calls.
128      * @var int|false
129      */
130     private $persistmaxsize = false;
132     /**
133      * Gets set to true during initialisation if the definition is making use of a ttl.
134      * Used to speed up processing.
135      * @var bool
136      */
137     private $hasattl = false;
139     /**
140      * Gets set to the class name of the store during initialisation. This is used several times in the cache class internally
141      * and having it here helps speed up processing.
142      * @var strubg
143      */
144     protected $storetype = 'unknown';
146     /**
147      * Gets set to true if we want to collect performance information about the cache API.
148      * @var bool
149      */
150     protected $perfdebug = false;
152     /**
153      * Determines if this loader is a sub loader, not the top of the chain.
154      * @var bool
155      */
156     protected $subloader = false;
158     /**
159      * Creates a new cache instance for a pre-defined definition.
160      *
161      * @param string $component The component for the definition
162      * @param string $area The area for the definition
163      * @param array $identifiers Any additional identifiers that should be provided to the definition.
164      * @param string $aggregate Super advanced feature. More docs later.
165      * @return cache_application|cache_session|cache_store
166      */
167     public static function make($component, $area, array $identifiers = array(), $aggregate = null) {
168         $factory = cache_factory::instance();
169         return $factory->create_cache_from_definition($component, $area, $identifiers, $aggregate);
170     }
172     /**
173      * Creates a new cache instance based upon the given params.
174      *
175      * @param int $mode One of cache_store::MODE_*
176      * @param string $component The component this cache relates to.
177      * @param string $area The area this cache relates to.
178      * @param array $identifiers Any additional identifiers that should be provided to the definition.
179      * @param array $options An array of options, available options are:
180      *   - simplekeys : Set to true if the keys you will use are a-zA-Z0-9_
181      *   - simpledata : Set to true if the type of the data you are going to store is scalar, or an array of scalar vars
182      *   - persistent : If set to true the cache will persist construction requests.
183      * @return cache_application|cache_session|cache_store
184      */
185     public static function make_from_params($mode, $component, $area, array $identifiers = array(), array $options = array()) {
186         $factory = cache_factory::instance();
187         return $factory->create_cache_from_params($mode, $component, $area, $identifiers, $options);
188     }
190     /**
191      * Constructs a new cache instance.
192      *
193      * You should not call this method from your code, instead you should use the cache::make methods.
194      *
195      * This method is public so that the cache_factory is able to instantiate cache instances.
196      * Ideally we would make this method protected and expose its construction to the factory method internally somehow.
197      * The factory class is responsible for this in order to centralise the storage of instances once created. This way if needed
198      * we can force a reset of the cache API (used during unit testing).
199      *
200      * @param cache_definition $definition The definition for the cache instance.
201      * @param cache_store $store The store that cache should use.
202      * @param cache_loader|cache_data_source $loader The next loader in the chain or the data source if there is one and there
203      *      are no other cache_loaders in the chain.
204      */
205     public function __construct(cache_definition $definition, cache_store $store, $loader = null) {
206         global $CFG;
207         $this->definition = $definition;
208         $this->store = $store;
209         $this->storetype = get_class($store);
210         $this->perfdebug = !empty($CFG->perfdebug);
211         if ($loader instanceof cache_loader) {
212             $this->loader = $loader;
213             // Mark the loader as a sub (chained) loader.
214             $this->loader->set_is_sub_loader(true);
215         } else if ($loader instanceof cache_data_source) {
216             $this->datasource = $loader;
217         }
218         $this->definition->generate_definition_hash();
219         $this->persist = $this->definition->should_be_persistent();
220         if ($this->persist) {
221             $this->persistmaxsize = $this->definition->get_persistent_max_size();
222         }
223         $this->hasattl = ($this->definition->get_ttl() > 0);
224     }
226     /**
227      * Used to inform the loader of its state as a sub loader, or as the top of the chain.
228      *
229      * This is important as it ensures that we do not have more than one loader keeping persistent data.
230      * Subloaders need to be "pure" loaders in the sense that they are used to store and retrieve information from stores or the
231      * next loader/data source in the chain.
232      * Nothing fancy, nothing flash.
233      *
234      * @param bool $setting
235      */
236     protected function set_is_sub_loader($setting = true) {
237         if ($setting) {
238             $this->subloader = true;
239             // Subloaders should not keep persistent data.
240             $this->persist = false;
241             $this->persistmaxsize = false;
242         } else {
243             $this->subloader = true;
244             $this->persist = $this->definition->should_be_persistent();
245             if ($this->persist) {
246                 $this->persistmaxsize = $this->definition->get_persistent_max_size();
247             }
248         }
249     }
251     /**
252      * Alters the identifiers that have been provided to the definition.
253      *
254      * This is an advanced method and should not be used unless really needed.
255      * It allows the developer to slightly alter the definition without having to re-establish the cache.
256      * It will cause more processing as the definition will need to clear and reprepare some of its properties.
257      *
258      * @param array $identifiers
259      */
260     public function set_identifiers(array $identifiers) {
261         $this->definition->set_identifiers($identifiers);
262     }
264     /**
265      * Retrieves the value for the given key from the cache.
266      *
267      * @param string|int $key The key for the data being requested.
268      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
269      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
270      * @param int $strictness One of IGNORE_MISSING | MUST_EXIST
271      * @return mixed|false The data from the cache or false if the key did not exist within the cache.
272      * @throws moodle_exception
273      */
274     public function get($key, $strictness = IGNORE_MISSING) {
275         // 1. Parse the key.
276         $parsedkey = $this->parse_key($key);
277         // 2. Get it from the persist cache if we can (only when persist is enabled and it has already been requested/set).
278         $result = false;
279         if ($this->is_using_persist_cache()) {
280             $result = $this->get_from_persist_cache($parsedkey);
281         }
282         if ($result !== false) {
283             if (!is_scalar($result)) {
284                 // If data is an object it will be a reference.
285                 // If data is an array if may contain references.
286                 // We want to break references so that the cache cannot be modified outside of itself.
287                 // Call the function to unreference it (in the best way possible).
288                 $result = $this->unref($result);
289             }
290             return $result;
291         }
292         // 3. Get it from the store. Obviously wasn't in the persist cache.
293         $result = $this->store->get($parsedkey);
294         if ($result !== false) {
295             if ($result instanceof cache_ttl_wrapper) {
296                 if ($result->has_expired()) {
297                     $this->store->delete($parsedkey);
298                     $result = false;
299                 } else {
300                     $result = $result->data;
301                 }
302             }
303             if ($result instanceof cache_cached_object) {
304                 $result = $result->restore_object();
305             }
306             if ($this->is_using_persist_cache()) {
307                 $this->set_in_persist_cache($parsedkey, $result);
308             }
309         }
310         // 4. Load if from the loader/datasource if we don't already have it.
311         $setaftervalidation = false;
312         if ($result === false) {
313             if ($this->perfdebug) {
314                 cache_helper::record_cache_miss($this->storetype, $this->definition->get_id());
315             }
316             if ($this->loader !== false) {
317                 // We must pass the original (unparsed) key to the next loader in the chain.
318                 // The next loader will parse the key as it sees fit. It may be parsed differently
319                 // depending upon the capabilities of the store associated with the loader.
320                 $result = $this->loader->get($key);
321             } else if ($this->datasource !== false) {
322                 $result = $this->datasource->load_for_cache($key);
323             }
324             $setaftervalidation = ($result !== false);
325         } else if ($this->perfdebug) {
326             cache_helper::record_cache_hit($this->storetype, $this->definition->get_id());
327         }
328         // 5. Validate strictness.
329         if ($strictness === MUST_EXIST && $result === false) {
330             throw new moodle_exception('Requested key did not exist in any cache stores and could not be loaded.');
331         }
332         // 6. Set it to the store if we got it from the loader/datasource.
333         if ($setaftervalidation) {
334             $this->set($key, $result);
335         }
336         // 7. Make sure we don't pass back anything that could be a reference.
337         //    We don't want people modifying the data in the cache.
338         if (!is_scalar($result)) {
339             // If data is an object it will be a reference.
340             // If data is an array if may contain references.
341             // We want to break references so that the cache cannot be modified outside of itself.
342             // Call the function to unreference it (in the best way possible).
343             $result = $this->unref($result);
344         }
345         return $result;
346     }
348     /**
349      * Retrieves an array of values for an array of keys.
350      *
351      * Using this function comes with potential performance implications.
352      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
353      * the equivalent singular method for each item provided.
354      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
355      * does support it, but you should be aware of this fact.
356      *
357      * @param array $keys The keys of the data being requested.
358      *      Each key can be any structure although using a scalar string or int is recommended in the interests of performance.
359      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
360      * @param int $strictness One of IGNORE_MISSING or MUST_EXIST.
361      * @return array An array of key value pairs for the items that could be retrieved from the cache.
362      *      If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown.
363      *      Otherwise any key that did not exist will have a data value of false within the results.
364      * @throws moodle_exception
365      */
366     public function get_many(array $keys, $strictness = IGNORE_MISSING) {
368         $keysparsed = array();
369         $parsedkeys = array();
370         $resultpersist = array();
371         $resultstore = array();
372         $keystofind = array();
374         // First up check the persist cache for each key.
375         $isusingpersist = $this->is_using_persist_cache();
376         foreach ($keys as $key) {
377             $pkey = $this->parse_key($key);
378             $keysparsed[$key] = $pkey;
379             $parsedkeys[$pkey] = $key;
380             $keystofind[$pkey] = $key;
381             if ($isusingpersist) {
382                 $value = $this->get_from_persist_cache($pkey);
383                 if ($value !== false) {
384                     $resultpersist[$pkey] = $value;
385                     unset($keystofind[$pkey]);
386                 }
387             }
388         }
390         // Next assuming we didn't find all of the keys in the persist cache try loading them from the store.
391         if (count($keystofind)) {
392             $resultstore = $this->store->get_many(array_keys($keystofind));
393             // Process each item in the result to "unwrap" it.
394             foreach ($resultstore as $key => $value) {
395                 if ($value instanceof cache_ttl_wrapper) {
396                     if ($value->has_expired()) {
397                         $value = false;
398                     } else {
399                         $value = $value->data;
400                     }
401                 }
402                 if ($value instanceof cache_cached_object) {
403                     $value = $value->restore_object();
404                 }
405                 $resultstore[$key] = $value;
406             }
407         }
409         // Merge the result from the persis cache with the results from the store load.
410         $result = $resultpersist + $resultstore;
411         unset($resultpersist);
412         unset($resultstore);
414         // Next we need to find any missing values and load them from the loader/datasource next in the chain.
415         $usingloader = ($this->loader !== false);
416         $usingsource = (!$usingloader && ($this->datasource !== false));
417         if ($usingloader || $usingsource) {
418             $missingkeys = array();
419             foreach ($result as $key => $value) {
420                 if ($value === false) {
421                     $missingkeys[] = ($usingloader) ? $key : $parsedkeys[$key];
422                 }
423             }
424             if (!empty($missingkeys)) {
425                 if ($usingloader) {
426                     $resultmissing = $this->loader->get_many($missingkeys);
427                 } else {
428                     $resultmissing = $this->datasource->load_many_for_cache($missingkeys);
429                 }
430                 foreach ($resultmissing as $key => $value) {
431                     $pkey = ($usingloader) ? $key : $keysparsed[$key];
432                     $realkey = ($usingloader) ? $parsedkeys[$key] : $key;
433                     $result[$pkey] = $value;
434                     if ($value !== false) {
435                         $this->set($realkey, $value);
436                     }
437                 }
438                 unset($resultmissing);
439             }
440             unset($missingkeys);
441         }
443         // Create an array with the original keys and the found values. This will be what we return.
444         $fullresult = array();
445         foreach ($result as $key => $value) {
446             $fullresult[$parsedkeys[$key]] = $value;
447         }
448         unset($result);
450         // Final step is to check strictness.
451         if ($strictness === MUST_EXIST) {
452             foreach ($keys as $key) {
453                 if (!array_key_exists($key, $fullresult)) {
454                     throw new moodle_exception('Not all the requested keys existed within the cache stores.');
455                 }
456             }
457         }
459         // Return the result. Phew!
460         return $fullresult;
461     }
463     /**
464      * Sends a key => value pair to the cache.
465      *
466      * <code>
467      * // This code will add four entries to the cache, one for each url.
468      * $cache->set('main', 'http://moodle.org');
469      * $cache->set('docs', 'http://docs.moodle.org');
470      * $cache->set('tracker', 'http://tracker.moodle.org');
471      * $cache->set('qa', 'http://qa.moodle.net');
472      * </code>
473      *
474      * @param string|int $key The key for the data being requested.
475      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
476      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
477      * @param mixed $data The data to set against the key.
478      * @return bool True on success, false otherwise.
479      */
480     public function set($key, $data) {
481         if ($this->perfdebug) {
482             cache_helper::record_cache_set($this->storetype, $this->definition->get_id());
483         }
484         if (is_object($data) && $data instanceof cacheable_object) {
485             $data = new cache_cached_object($data);
486         } else if (!is_scalar($data)) {
487             // If data is an object it will be a reference.
488             // If data is an array if may contain references.
489             // We want to break references so that the cache cannot be modified outside of itself.
490             // Call the function to unreference it (in the best way possible).
491             $data = $this->unref($data);
492         }
493         if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) {
494             $data = new cache_ttl_wrapper($data, $this->definition->get_ttl());
495         }
496         $parsedkey = $this->parse_key($key);
497         if ($this->is_using_persist_cache()) {
498             $this->set_in_persist_cache($parsedkey, $data);
499         }
500         return $this->store->set($parsedkey, $data);
501     }
503     /**
504      * Removes references where required.
505      *
506      * @param stdClass|array $data
507      */
508     protected function unref($data) {
509         if ($this->definition->uses_simple_data()) {
510             return $data;
511         }
512         // Check if it requires serialisation in order to produce a reference free copy.
513         if ($this->requires_serialisation($data)) {
514             // Damn, its going to have to be serialise.
515             $data = serialize($data);
516             // We unserialise immediately so that we don't have to do it every time on get.
517             $data = unserialize($data);
518         } else if (!is_scalar($data)) {
519             // Its safe to clone, lets do it, its going to beat the pants of serialisation.
520             $data = $this->deep_clone($data);
521         }
522         return $data;
523     }
525     /**
526      * Checks to see if a var requires serialisation.
527      *
528      * @param mixed $value The value to check.
529      * @param int $depth Used to ensure we don't enter an endless loop (think recursion).
530      * @return bool Returns true if the value is going to require serialisation in order to ensure a reference free copy
531      *      or false if its safe to clone.
532      */
533     protected function requires_serialisation($value, $depth = 1) {
534         if (is_scalar($value)) {
535             return false;
536         } else if (is_array($value) || $value instanceof stdClass || $value instanceof Traversable) {
537             if ($depth > 5) {
538                 // Skrew it, mega-deep object, developer you suck, we're just going to serialise.
539                 return true;
540             }
541             foreach ($value as $key => $subvalue) {
542                 if ($this->requires_serialisation($subvalue, $depth++)) {
543                     return true;
544                 }
545             }
546         }
547         // Its not scalar, array, or stdClass so we'll need to serialise.
548         return true;
549     }
551     /**
552      * Creates a reference free clone of the given value.
553      *
554      * @param mixed $value
555      * @return mixed
556      */
557     protected function deep_clone($value) {
558         if (is_object($value)) {
559             // Objects must be cloned to begin with.
560             $value = clone $value;
561         }
562         if (is_array($value) || is_object($value)) {
563             foreach ($value as $key => $subvalue) {
564                 $value[$key] = $this->deep_clone($subvalue);
565             }
566         }
567         return $value;
568     }
570     /**
571      * Sends several key => value pairs to the cache.
572      *
573      * Using this function comes with potential performance implications.
574      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
575      * the equivalent singular method for each item provided.
576      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
577      * does support it, but you should be aware of this fact.
578      *
579      * <code>
580      * // This code will add four entries to the cache, one for each url.
581      * $cache->set_many(array(
582      *     'main' => 'http://moodle.org',
583      *     'docs' => 'http://docs.moodle.org',
584      *     'tracker' => 'http://tracker.moodle.org',
585      *     'qa' => ''http://qa.moodle.net'
586      * ));
587      * </code>
588      *
589      * @param array $keyvaluearray An array of key => value pairs to send to the cache.
590      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.
591      *      ... if they care that is.
592      */
593     public function set_many(array $keyvaluearray) {
594         $data = array();
595         $simulatettl = $this->has_a_ttl() && !$this->store_supports_native_ttl();
596         $usepersistcache = $this->is_using_persist_cache();
597         foreach ($keyvaluearray as $key => $value) {
598             if (is_object($value) && $value instanceof cacheable_object) {
599                 $value = new cache_cached_object($value);
600             } else if (!is_scalar($value)) {
601                 // If data is an object it will be a reference.
602                 // If data is an array if may contain references.
603                 // We want to break references so that the cache cannot be modified outside of itself.
604                 // Call the function to unreference it (in the best way possible).
605                 $value = $this->unref($value);
606             }
607             if ($simulatettl) {
608                 $value = new cache_ttl_wrapper($value, $this->definition->get_ttl());
609             }
610             $data[$key] = array(
611                 'key' => $this->parse_key($key),
612                 'value' => $value
613             );
614             if ($usepersistcache) {
615                 $this->set_in_persist_cache($data[$key]['key'], $value);
616             }
617         }
618         if ($this->perfdebug) {
619             cache_helper::record_cache_set($this->storetype, $this->definition->get_id());
620         }
621         return $this->store->set_many($data);
622     }
624     /**
625      * Test is a cache has a key.
626      *
627      * The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the
628      * test and any subsequent action (get, set, delete etc).
629      * Instead it is recommended to write your code in such a way they it performs the following steps:
630      * <ol>
631      * <li>Attempt to retrieve the information.</li>
632      * <li>Generate the information.</li>
633      * <li>Attempt to set the information</li>
634      * </ol>
635      *
636      * Its also worth mentioning that not all stores support key tests.
637      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
638      * Just one more reason you should not use these methods unless you have a very good reason to do so.
639      *
640      * @param string|int $key
641      * @param bool $tryloadifpossible If set to true, the cache doesn't contain the key, and there is another cache loader or
642      *      data source then the code will try load the key value from the next item in the chain.
643      * @return bool True if the cache has the requested key, false otherwise.
644      */
645     public function has($key, $tryloadifpossible = false) {
646         $parsedkey = $this->parse_key($key);
647         if ($this->is_in_persist_cache($parsedkey)) {
648             // Hoorah, that was easy. It exists in the persist cache so we definitely have it.
649             return true;
650         }
651         if ($this->has_a_ttl() && !$this->store_supports_native_ttl()) {
652             // The data has a TTL and the store doesn't support it natively.
653             // We must fetch the data and expect a ttl wrapper.
654             $data = $this->store->get($parsedkey);
655             $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
656         } else if (!$this->store_supports_key_awareness()) {
657             // The store doesn't support key awareness, get the data and check it manually... puke.
658             // Either no TTL is set of the store supports its handling natively.
659             $data = $this->store->get($parsedkey);
660             $has = ($data !== false);
661         } else {
662             // The store supports key awareness, this is easy!
663             // Either no TTL is set of the store supports its handling natively.
664             $has = $this->store->has($parsedkey);
665         }
666         if (!$has && $tryloadifpossible) {
667             if ($this->loader !== false) {
668                 $result = $this->loader->get($parsedkey);
669             } else if ($this->datasource !== null) {
670                 $result = $this->datasource->load_for_cache($key);
671             }
672             $has = ($result !== null);
673             if ($has) {
674                 $this->set($key, $result);
675             }
676         }
677         return $has;
678     }
680     /**
681      * Test is a cache has all of the given keys.
682      *
683      * It is strongly recommended to avoid the use of this function if not absolutely required.
684      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
685      *
686      * Its also worth mentioning that not all stores support key tests.
687      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
688      * Just one more reason you should not use these methods unless you have a very good reason to do so.
689      *
690      * @param array $keys
691      * @return bool True if the cache has all of the given keys, false otherwise.
692      */
693     public function has_all(array $keys) {
694         if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) {
695             foreach ($keys as $key) {
696                 if (!$this->has($key)) {
697                     return false;
698                 }
699             }
700             return true;
701         }
702         $parsedkeys = array_map(array($this, 'parse_key'), $keys);
703         return $this->store->has_all($parsedkeys);
704     }
706     /**
707      * Test if a cache has at least one of the given keys.
708      *
709      * It is strongly recommended to avoid the use of this function if not absolutely required.
710      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
711      *
712      * Its also worth mentioning that not all stores support key tests.
713      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
714      * Just one more reason you should not use these methods unless you have a very good reason to do so.
715      *
716      * @param array $keys
717      * @return bool True if the cache has at least one of the given keys
718      */
719     public function has_any(array $keys) {
720         if (($this->has_a_ttl() && !$this->store_supports_native_ttl()) || !$this->store_supports_key_awareness()) {
721             foreach ($keys as $key) {
722                 if ($this->has($key)) {
723                     return true;
724                 }
725             }
726             return false;
727         }
729         if ($this->is_using_persist_cache()) {
730             $parsedkeys = array();
731             foreach ($keys as $id => $key) {
732                 $parsedkey = $this->parse_key($key);
733                 if ($this->is_in_persist_cache($parsedkey)) {
734                     return true;
735                 }
736                 $parsedkeys[] = $parsedkey;
737             }
738         } else {
739             $parsedkeys = array_map(array($this, 'parse_key'), $keys);
740         }
741         return $this->store->has_any($parsedkeys);
742     }
744     /**
745      * Delete the given key from the cache.
746      *
747      * @param string|int $key The key to delete.
748      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
749      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
750      * @return bool True of success, false otherwise.
751      */
752     public function delete($key, $recurse = true) {
753         $parsedkey = $this->parse_key($key);
754         $this->delete_from_persist_cache($parsedkey);
755         if ($recurse && $this->loader !== false) {
756             // Delete from the bottom of the stack first.
757             $this->loader->delete($key, $recurse);
758         }
759         return $this->store->delete($parsedkey);
760     }
762     /**
763      * Delete all of the given keys from the cache.
764      *
765      * @param array $keys The key to delete.
766      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
767      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
768      * @return int The number of items successfully deleted.
769      */
770     public function delete_many(array $keys, $recurse = true) {
771         $parsedkeys = array_map(array($this, 'parse_key'), $keys);
772         if ($this->is_using_persist_cache()) {
773             foreach ($parsedkeys as $parsedkey) {
774                 $this->delete_from_persist_cache($parsedkey);
775             }
776         }
777         if ($recurse && $this->loader !== false) {
778             // Delete from the bottom of the stack first.
779             $this->loader->delete_many($keys, $recurse);
780         }
781         return $this->store->delete_many($parsedkeys);
782     }
784     /**
785      * Purges the cache store, and loader if there is one.
786      *
787      * @return bool True on success, false otherwise
788      */
789     public function purge() {
790         // 1. Purge the persist cache.
791         $this->persistcache = array();
792         // 2. Purge the store.
793         $this->store->purge();
794         // 3. Optionally pruge any stacked loaders.
795         if ($this->loader) {
796             $this->loader->purge();
797         }
798         return true;
799     }
801     /**
802      * Parses the key turning it into a string (or array is required) suitable to be passed to the cache store.
803      *
804      * @param string|int $key As passed to get|set|delete etc.
805      * @return string|array String unless the store supports multi-identifiers in which case an array if returned.
806      */
807     protected function parse_key($key) {
808         // First up if the store supports multiple keys we'll go with that.
809         if ($this->store->supports_multiple_identifiers()) {
810             $result = $this->definition->generate_multi_key_parts();
811             $result['key'] = $key;
812             return $result;
813         }
814         // If not we need to generate a hash and to for that we use the cache_helper.
815         return cache_helper::hash_key($key, $this->definition);
816     }
818     /**
819      * Returns true if the cache is making use of a ttl.
820      * @return bool
821      */
822     protected function has_a_ttl() {
823         return $this->hasattl;
824     }
826     /**
827      * Returns true if the cache store supports native ttl.
828      * @return bool
829      */
830     protected function store_supports_native_ttl() {
831         if ($this->supportsnativettl === null) {
832             $this->supportsnativettl = ($this->store->supports_native_ttl());
833         }
834         return $this->supportsnativettl;
835     }
837     /**
838      * Returns the cache definition.
839      *
840      * @return cache_definition
841      */
842     protected function get_definition() {
843         return $this->definition;
844     }
846     /**
847      * Returns the cache store
848      *
849      * @return cache_store
850      */
851     protected function get_store() {
852         return $this->store;
853     }
855     /**
856      * Returns the loader associated with this instance.
857      *
858      * @since 2.4.4
859      * @return cache_loader|false
860      */
861     protected function get_loader() {
862         return $this->loader;
863     }
865     /**
866      * Returns the data source associated with this cache.
867      *
868      * @since 2.4.4
869      * @return cache_data_source|false
870      */
871     protected function get_datasource() {
872         return $this->datasource;
873     }
875     /**
876      * Returns true if the store supports key awareness.
877      *
878      * @return bool
879      */
880     protected function store_supports_key_awareness() {
881         if ($this->supportskeyawareness === null) {
882             $this->supportskeyawareness = ($this->store instanceof cache_is_key_aware);
883         }
884         return $this->supportskeyawareness;
885     }
887     /**
888      * Returns true if the store natively supports locking.
889      *
890      * @return bool
891      */
892     protected function store_supports_native_locking() {
893         if ($this->nativelocking === null) {
894             $this->nativelocking = ($this->store instanceof cache_is_lockable);
895         }
896         return $this->nativelocking;
897     }
899     /**
900      * Returns true if this cache is making use of the persist cache.
901      *
902      * @return bool
903      */
904     protected function is_using_persist_cache() {
905         return $this->persist;
906     }
908     /**
909      * Returns true if the requested key exists within the persist cache.
910      *
911      * @param string $key The parsed key
912      * @return bool
913      */
914     protected function is_in_persist_cache($key) {
915         if (is_array($key)) {
916             $key = $key['key'];
917         }
918         // This could be written as a single line, however it has been split because the ttl check is faster than the instanceof
919         // and has_expired calls.
920         if (!$this->persist || !array_key_exists($key, $this->persistcache)) {
921             return false;
922         }
923         if ($this->has_a_ttl() && $this->store_supports_native_ttl()) {
924              return !($this->persistcache[$key] instanceof cache_ttl_wrapper && $this->persistcache[$key]->has_expired());
925         }
926         return true;
927     }
929     /**
930      * Returns the item from the persist cache if it exists there.
931      *
932      * @param string $key The parsed key
933      * @return mixed|false The data from the persist cache or false if it wasn't there.
934      */
935     protected function get_from_persist_cache($key) {
936         if (is_array($key)) {
937             $key = $key['key'];
938         }
939         if (!$this->persist || !array_key_exists($key, $this->persistcache)) {
940             $result = false;
941         } else {
942             $data = $this->persistcache[$key];
943             if (!$this->has_a_ttl() || !$data instanceof cache_ttl_wrapper) {
944                 if ($data instanceof cache_cached_object) {
945                     $data = $data->restore_object();
946                 }
947                 $result = $data;
948             } else if ($data->has_expired()) {
949                 $this->delete_from_persist_cache($key);
950                 $result = false;
951             } else {
952                 if ($data instanceof cache_cached_object) {
953                     $data = $data->restore_object();
954                 }
955                 $result = $data->data;
956             }
957         }
958         if ($result) {
959             if ($this->perfdebug) {
960                 cache_helper::record_cache_hit('** static persist **', $this->definition->get_id());
961             }
962             return $result;
963         } else {
964             if ($this->perfdebug) {
965                 cache_helper::record_cache_miss('** static persist **', $this->definition->get_id());
966             }
967             return false;
968         }
969     }
971     /**
972      * Sets a key value pair into the persist cache.
973      *
974      * @param string $key The parsed key
975      * @param mixed $data
976      * @return bool
977      */
978     protected function set_in_persist_cache($key, $data) {
979         if (is_array($key)) {
980             $key = $key['key'];
981         }
982         $this->persistcache[$key] = $data;
983         if ($this->persistmaxsize !== false) {
984             $this->persistcount++;
985             if ($this->persistcount > $this->persistmaxsize) {
986                 $dropkey = array_shift($this->persistkeys);
987                 unset($this->persistcache[$dropkey]);
988                 $this->persistcount--;
989             }
990         }
991         return true;
992     }
994     /**
995      * Deletes an item from the persist cache.
996      *
997      * @param string|int $key As given to get|set|delete
998      * @return bool True on success, false otherwise.
999      */
1000     protected function delete_from_persist_cache($key) {
1001         unset($this->persistcache[$key]);
1002         if ($this->persistmaxsize !== false) {
1003             $dropkey = array_search($key, $this->persistkeys);
1004             if ($dropkey) {
1005                 unset($this->persistkeys[$dropkey]);
1006                 $this->persistcount--;
1007             }
1008         }
1009         return true;
1010     }
1012     /**
1013      * Returns the timestamp from the first request for the time from the cache API.
1014      *
1015      * This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with
1016      * timing issues.
1017      *
1018      * @return int
1019      */
1020     public static function now() {
1021         if (self::$now === null) {
1022             self::$now = time();
1023         }
1024         return self::$now;
1025     }
1028 /**
1029  * An application cache.
1030  *
1031  * This class is used for application caches returned by the cache::make methods.
1032  * On top of the standard functionality it also allows locking to be required and or manually operated.
1033  *
1034  * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.
1035  * It is technically possible to call those methods through this class however there is no guarantee that you will get an
1036  * instance of this class back again.
1037  *
1038  * @internal don't use me directly.
1039  *
1040  * @package    core
1041  * @category   cache
1042  * @copyright  2012 Sam Hemelryk
1043  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1044  */
1045 class cache_application extends cache implements cache_loader_with_locking {
1047     /**
1048      * Lock identifier.
1049      * This is used to ensure the lock belongs to the cache instance + definition + user.
1050      * @var string
1051      */
1052     protected $lockidentifier;
1054     /**
1055      * Gets set to true if the cache's primary store natively supports locking.
1056      * If it does then we use that, otherwise we need to instantiate a second store to use for locking.
1057      * @var cache_store
1058      */
1059     protected $nativelocking = null;
1061     /**
1062      * Gets set to true if the cache is going to be using locking.
1063      * This isn't a requirement, it doesn't need to use locking (most won't) and this bool is used to quickly check things.
1064      * If required then locking will be forced for the get|set|delete operation.
1065      * @var bool
1066      */
1067     protected $requirelocking = false;
1069     /**
1070      * Gets set to true if the cache must use read locking (get|has).
1071      * @var bool
1072      */
1073     protected $requirelockingread = false;
1075     /**
1076      * Gets set to true if the cache must use write locking (set|delete)
1077      * @var bool
1078      */
1079     protected $requirelockingwrite = false;
1081     /**
1082      * Gets set to a cache_store to use for locking if the caches primary store doesn't support locking natively.
1083      * @var cache_lock_interface
1084      */
1085     protected $cachelockinstance;
1087     /**
1088      * Overrides the cache construct method.
1089      *
1090      * You should not call this method from your code, instead you should use the cache::make methods.
1091      *
1092      * @param cache_definition $definition
1093      * @param cache_store $store
1094      * @param cache_loader|cache_data_source $loader
1095      */
1096     public function __construct(cache_definition $definition, cache_store $store, $loader = null) {
1097         parent::__construct($definition, $store, $loader);
1098         $this->nativelocking = $this->store_supports_native_locking();
1099         if ($definition->require_locking()) {
1100             $this->requirelocking = true;
1101             $this->requirelockingread = $definition->require_locking_read();
1102             $this->requirelockingwrite = $definition->require_locking_write();
1103         }
1105         if ($definition->has_invalidation_events()) {
1106             $lastinvalidation = $this->get('lastinvalidation');
1107             if ($lastinvalidation === false) {
1108                 // This is a new session, there won't be anything to invalidate. Set the time of the last invalidation and
1109                 // move on.
1110                 $this->set('lastinvalidation', cache::now());
1111                 return;
1112             } else if ($lastinvalidation == cache::now()) {
1113                 // We've already invalidated during this request.
1114                 return;
1115             }
1117             // Get the event invalidation cache.
1118             $cache = cache::make('core', 'eventinvalidation');
1119             $events = $cache->get_many($definition->get_invalidation_events());
1120             $todelete = array();
1121             $purgeall = false;
1122             // Iterate the returned data for the events.
1123             foreach ($events as $event => $keys) {
1124                 if ($keys === false) {
1125                     // No data to be invalidated yet.
1126                     continue;
1127                 }
1128                 // Look at each key and check the timestamp.
1129                 foreach ($keys as $key => $timestamp) {
1130                     // If the timestamp of the event is more than or equal to the last invalidation (happened between the last
1131                     // invalidation and now)then we need to invaliate the key.
1132                     if ($timestamp >= $lastinvalidation) {
1133                         if ($key === 'purged') {
1134                             $purgeall = true;
1135                             break;
1136                         } else {
1137                             $todelete[] = $key;
1138                         }
1139                     }
1140                 }
1141             }
1142             if ($purgeall) {
1143                 $this->purge();
1144             } else if (!empty($todelete)) {
1145                 $todelete = array_unique($todelete);
1146                 $this->delete_many($todelete);
1147             }
1148             // Set the time of the last invalidation.
1149             $this->set('lastinvalidation', cache::now());
1150         }
1151     }
1153     /**
1154      * Returns the identifier to use
1155      *
1156      * @staticvar int $instances Counts the number of instances. Used as part of the lock identifier.
1157      * @return string
1158      */
1159     public function get_identifier() {
1160         static $instances = 0;
1161         if ($this->lockidentifier === null) {
1162             $this->lockidentifier = md5(
1163                 $this->get_definition()->generate_definition_hash() .
1164                 sesskey() .
1165                 $instances++ .
1166                 'cache_application'
1167             );
1168         }
1169         return $this->lockidentifier;
1170     }
1172     /**
1173      * Fixes the instance up after a clone.
1174      */
1175     public function __clone() {
1176         // Force a new idenfitier.
1177         $this->lockidentifier = null;
1178     }
1180     /**
1181      * Acquires a lock on the given key.
1182      *
1183      * This is done automatically if the definition requires it.
1184      * It is recommended to use a definition if you want to have locking although it is possible to do locking without having
1185      * it required by the definition.
1186      * The problem with such an approach is that you cannot ensure that code will consistently use locking. You will need to
1187      * rely on the integrators review skills.
1188      *
1189      * @param string|int $key The key as given to get|set|delete
1190      * @return bool Returns true if the lock could be acquired, false otherwise.
1191      */
1192     public function acquire_lock($key) {
1193         $key = $this->parse_key($key);
1194         if ($this->nativelocking) {
1195             return $this->get_store()->acquire_lock($key, $this->get_identifier());
1196         } else {
1197             $this->ensure_cachelock_available();
1198             return $this->cachelockinstance->lock($key, $this->get_identifier());
1199         }
1200     }
1202     /**
1203      * Checks if this cache has a lock on the given key.
1204      *
1205      * @param string|int $key The key as given to get|set|delete
1206      * @return bool|null Returns true if there is a lock and this cache has it, null if no one has a lock on that key, false if
1207      *      someone else has the lock.
1208      */
1209     public function check_lock_state($key) {
1210         $key = $this->parse_key($key);
1211         if ($this->nativelocking) {
1212             return $this->get_store()->check_lock_state($key, $this->get_identifier());
1213         } else {
1214             $this->ensure_cachelock_available();
1215             return $this->cachelockinstance->check_state($key, $this->get_identifier());
1216         }
1217     }
1219     /**
1220      * Releases the lock this cache has on the given key
1221      *
1222      * @param string|int $key
1223      * @return bool True if the operation succeeded, false otherwise.
1224      */
1225     public function release_lock($key) {
1226         $key = $this->parse_key($key);
1227         if ($this->nativelocking) {
1228             return $this->get_store()->release_lock($key, $this->get_identifier());
1229         } else {
1230             $this->ensure_cachelock_available();
1231             return $this->cachelockinstance->unlock($key, $this->get_identifier());
1232         }
1233     }
1235     /**
1236      * Ensure that the dedicated lock store is ready to go.
1237      *
1238      * This should only happen if the cache store doesn't natively support it.
1239      */
1240     protected function ensure_cachelock_available() {
1241         if ($this->cachelockinstance === null) {
1242             $this->cachelockinstance = cache_helper::get_cachelock_for_store($this->get_store());
1243         }
1244     }
1246     /**
1247      * Sends a key => value pair to the cache.
1248      *
1249      * <code>
1250      * // This code will add four entries to the cache, one for each url.
1251      * $cache->set('main', 'http://moodle.org');
1252      * $cache->set('docs', 'http://docs.moodle.org');
1253      * $cache->set('tracker', 'http://tracker.moodle.org');
1254      * $cache->set('qa', 'http://qa.moodle.net');
1255      * </code>
1256      *
1257      * @param string|int $key The key for the data being requested.
1258      * @param mixed $data The data to set against the key.
1259      * @return bool True on success, false otherwise.
1260      */
1261     public function set($key, $data) {
1262         if ($this->requirelockingwrite && !$this->acquire_lock($key)) {
1263             return false;
1264         }
1265         $result = parent::set($key, $data);
1266         if ($this->requirelockingwrite && !$this->release_lock($key)) {
1267             debugging('Failed to release cache lock on set operation... this should not happen.', DEBUG_DEVELOPER);
1268         }
1269         return $result;
1270     }
1272     /**
1273      * Sends several key => value pairs to the cache.
1274      *
1275      * Using this function comes with potential performance implications.
1276      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1277      * the equivalent singular method for each item provided.
1278      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1279      * does support it, but you should be aware of this fact.
1280      *
1281      * <code>
1282      * // This code will add four entries to the cache, one for each url.
1283      * $cache->set_many(array(
1284      *     'main' => 'http://moodle.org',
1285      *     'docs' => 'http://docs.moodle.org',
1286      *     'tracker' => 'http://tracker.moodle.org',
1287      *     'qa' => ''http://qa.moodle.net'
1288      * ));
1289      * </code>
1290      *
1291      * @param array $keyvaluearray An array of key => value pairs to send to the cache.
1292      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.
1293      *      ... if they care that is.
1294      */
1295     public function set_many(array $keyvaluearray) {
1296         if ($this->requirelockingwrite) {
1297             $locks = array();
1298             foreach ($keyvaluearray as $id => $pair) {
1299                 $key = $pair['key'];
1300                 if ($this->acquire_lock($key)) {
1301                     $locks[] = $key;
1302                 } else {
1303                     unset($keyvaluearray[$id]);
1304                 }
1305             }
1306         }
1307         $result = parent::set_many($keyvaluearray);
1308         if ($this->requirelockingwrite) {
1309             foreach ($locks as $key) {
1310                 if ($this->release_lock($key)) {
1311                     debugging('Failed to release cache lock on set_many operation... this should not happen.', DEBUG_DEVELOPER);
1312                 }
1313             }
1314         }
1315         return $result;
1316     }
1318     /**
1319      * Retrieves the value for the given key from the cache.
1320      *
1321      * @param string|int $key The key for the data being requested.
1322      * @param int $strictness One of IGNORE_MISSING | MUST_EXIST
1323      * @return mixed|false The data from the cache or false if the key did not exist within the cache.
1324      * @throws moodle_exception
1325      */
1326     public function get($key, $strictness = IGNORE_MISSING) {
1327         if ($this->requirelockingread && $this->check_lock_state($key) === false) {
1328             // Read locking required and someone else has the read lock.
1329             return false;
1330         }
1331         return parent::get($key, $strictness);
1332     }
1334     /**
1335      * Retrieves an array of values for an array of keys.
1336      *
1337      * Using this function comes with potential performance implications.
1338      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1339      * the equivalent singular method for each item provided.
1340      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1341      * does support it, but you should be aware of this fact.
1342      *
1343      * @param array $keys The keys of the data being requested.
1344      * @param int $strictness One of IGNORE_MISSING or MUST_EXIST.
1345      * @return array An array of key value pairs for the items that could be retrieved from the cache.
1346      *      If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown.
1347      *      Otherwise any key that did not exist will have a data value of false within the results.
1348      * @throws moodle_exception
1349      */
1350     public function get_many(array $keys, $strictness = IGNORE_MISSING) {
1351         if ($this->requirelockingread) {
1352             foreach ($keys as $id => $key) {
1353                 $lock =$this->acquire_lock($key);
1354                 if (!$lock) {
1355                     if ($strictness === MUST_EXIST) {
1356                         throw new coding_exception('Could not acquire read locks for all of the items being requested.');
1357                     } else {
1358                         // Can't return this as we couldn't get a read lock.
1359                         unset($keys[$id]);
1360                     }
1361                 }
1363             }
1364         }
1365         return parent::get_many($keys, $strictness);
1366     }
1368     /**
1369      * Delete the given key from the cache.
1370      *
1371      * @param string|int $key The key to delete.
1372      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1373      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1374      * @return bool True of success, false otherwise.
1375      */
1376     public function delete($key, $recurse = true) {
1377         if ($this->requirelockingwrite && !$this->acquire_lock($key)) {
1378             return false;
1379         }
1380         $result = parent::delete($key, $recurse);
1381         if ($this->requirelockingwrite && !$this->release_lock($key)) {
1382             debugging('Failed to release cache lock on delete operation... this should not happen.', DEBUG_DEVELOPER);
1383         }
1384         return $result;
1385     }
1387     /**
1388      * Delete all of the given keys from the cache.
1389      *
1390      * @param array $keys The key to delete.
1391      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1392      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1393      * @return int The number of items successfully deleted.
1394      */
1395     public function delete_many(array $keys, $recurse = true) {
1396         if ($this->requirelockingwrite) {
1397             $locks = array();
1398             foreach ($keys as $id => $key) {
1399                 if ($this->acquire_lock($key)) {
1400                     $locks[] = $key;
1401                 } else {
1402                     unset($keys[$id]);
1403                 }
1404             }
1405         }
1406         $result = parent::delete_many($keys, $recurse);
1407         if ($this->requirelockingwrite) {
1408             foreach ($locks as $key) {
1409                 if ($this->release_lock($key)) {
1410                     debugging('Failed to release cache lock on delete_many operation... this should not happen.', DEBUG_DEVELOPER);
1411                 }
1412             }
1413         }
1414         return $result;
1415     }
1418 /**
1419  * A session cache.
1420  *
1421  * This class is used for session caches returned by the cache::make methods.
1422  *
1423  * It differs from the application loader in a couple of noteable ways:
1424  *    1. Sessions are always expected to be persistent.
1425  *       Because of this we don't ever use the persist cache and instead a session array
1426  *       containing all of the data is maintained by this object.
1427  *    2. Session data for a loader instance (store + definition) is consolidate into a
1428  *       single array for storage within the store.
1429  *       Along with this we embed a lastaccessed time with the data. This way we can
1430  *       check sessions for a last access time.
1431  *    3. Session stores are required to support key searching and must
1432  *       implement cache_is_searchable. This ensures stores used for the cache can be
1433  *       targetted for garbage collection of session data.
1434  *
1435  * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.
1436  * It is technically possible to call those methods through this class however there is no guarantee that you will get an
1437  * instance of this class back again.
1438  *
1439  * @todo we should support locking in the session as well. Should be pretty simple to set up.
1440  *
1441  * @internal don't use me directly.
1442  *
1443  * @package    core
1444  * @category   cache
1445  * @copyright  2012 Sam Hemelryk
1446  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1447  */
1448 class cache_session extends cache {
1449     /**
1450      * The user the session has been established for.
1451      * @var int
1452      */
1453     protected static $loadeduserid = null;
1455     /**
1456      * The userid this cache is currently using.
1457      * @var int
1458      */
1459     protected $currentuserid = null;
1461     /**
1462      * The session id we are currently using.
1463      * @var array
1464      */
1465     protected $sessionid = null;
1467     /**
1468      * The session data for the above session id.
1469      * @var array
1470      */
1471     protected $session = null;
1473     /**
1474      * Constant used to prefix keys.
1475      */
1476     const KEY_PREFIX = 'sess_';
1478     /**
1479      * Override the cache::construct method.
1480      *
1481      * This function gets overriden so that we can process any invalidation events if need be.
1482      * If the definition doesn't have any invalidation events then this occurs exactly as it would for the cache class.
1483      * Otherwise we look at the last invalidation time and then check the invalidation data for events that have occured
1484      * between then now.
1485      *
1486      * You should not call this method from your code, instead you should use the cache::make methods.
1487      *
1488      * @param cache_definition $definition
1489      * @param cache_store $store
1490      * @param cache_loader|cache_data_source $loader
1491      * @return void
1492      */
1493     public function __construct(cache_definition $definition, cache_store $store, $loader = null) {
1494         // First up copy the loadeduserid to the current user id.
1495         $this->currentuserid = self::$loadeduserid;
1496         parent::__construct($definition, $store, $loader);
1497         if ($definition->has_invalidation_events()) {
1498             $lastinvalidation = $this->get('lastsessioninvalidation');
1499             if ($lastinvalidation === false) {
1500                 // This is a new session, there won't be anything to invalidate. Set the time of the last invalidation and
1501                 // move on.
1502                 $this->set('lastsessioninvalidation', cache::now());
1503                 return;
1504             } else if ($lastinvalidation == cache::now()) {
1505                 // We've already invalidated during this request.
1506                 return;
1507             }
1509             // Get the event invalidation cache.
1510             $cache = cache::make('core', 'eventinvalidation');
1511             $events = $cache->get_many($definition->get_invalidation_events());
1512             $todelete = array();
1513             $purgeall = false;
1514             // Iterate the returned data for the events.
1515             foreach ($events as $event => $keys) {
1516                 if ($keys === false) {
1517                     // No data to be invalidated yet.
1518                     continue;
1519                 }
1520                 // Look at each key and check the timestamp.
1521                 foreach ($keys as $key => $timestamp) {
1522                     // If the timestamp of the event is more than or equal to the last invalidation (happened between the last
1523                     // invalidation and now)then we need to invaliate the key.
1524                     if ($timestamp >= $lastinvalidation) {
1525                         if ($key === 'purged') {
1526                             $purgeall = true;
1527                             break;
1528                         } else {
1529                             $todelete[] = $key;
1530                         }
1531                     }
1532                 }
1533             }
1534             if ($purgeall) {
1535                 $this->purge();
1536             } else if (!empty($todelete)) {
1537                 $todelete = array_unique($todelete);
1538                 $this->delete_many($todelete);
1539             }
1540             // Set the time of the last invalidation.
1541             $this->set('lastsessioninvalidation', cache::now());
1542         }
1543     }
1545     /**
1546      * Parses the key turning it into a string (or array is required) suitable to be passed to the cache store.
1547      *
1548      * This function is called for every operation that uses keys. For this reason we use this function to also check
1549      * that the current user is the same as the user who last used this cache.
1550      *
1551      * On top of that if prepends the string 'sess_' to the start of all keys. The _ ensures things are easily identifiable.
1552      *
1553      * @param string|int $key As passed to get|set|delete etc.
1554      * @return string|array String unless the store supports multi-identifiers in which case an array if returned.
1555      */
1556     protected function parse_key($key) {
1557         if ($key === 'lastaccess') {
1558             $key = '__lastaccess__';
1559         }
1560         return 'sess_'.parent::parse_key($key);
1561     }
1563     /**
1564      * Check that this cache instance is tracking the current user.
1565      */
1566     protected function check_tracked_user() {
1567         if (isset($_SESSION['USER']->id)) {
1568             // Get the id of the current user.
1569             $new = $_SESSION['USER']->id;
1570         } else {
1571             // No user set up yet.
1572             $new = 0;
1573         }
1574         if ($new !== self::$loadeduserid) {
1575             // The current user doesn't match the tracked userid for this request.
1576             if (!is_null(self::$loadeduserid)) {
1577                 // Purge the data we have for the old user.
1578                 // This way we don't bloat the session.
1579                 $this->purge();
1580                 // Update the session id just in case!
1581                 $this->sessionid = session_id();
1582             }
1583             self::$loadeduserid = $new;
1584             $this->currentuserid = $new;
1585         } else if ($new !== $this->currentuserid) {
1586             // The current user matches the loaded user but not the user last used by this cache.
1587             $this->purge();
1588             $this->currentuserid = $new;
1589             // Update the session id just in case!
1590             $this->sessionid = session_id();
1591         }
1592     }
1594     /**
1595      * Gets the session data.
1596      *
1597      * @param bool $force If true the session data will be loaded from the store again.
1598      * @return array An array of session data.
1599      */
1600     protected function get_session_data($force = false) {
1601         if ($this->sessionid === null) {
1602             $this->sessionid = session_id();
1603         }
1604         if (is_array($this->session) && !$force) {
1605             return $this->session;
1606         }
1607         $session = parent::get($this->sessionid);
1608         if ($session === false) {
1609             $session = array();
1610         }
1611         // We have to write here to ensure that the lastaccess time is recorded.
1612         // And also in order to ensure the session entry exists as when we save it on __destruct
1613         // $CFG is likely to have already been destroyed.
1614         $this->save_session($session);
1615         return $this->session;
1616     }
1618     /**
1619      * Saves the session data.
1620      *
1621      * This function also updates the last access time.
1622      *
1623      * @param array $session
1624      * @return bool
1625      */
1626     protected function save_session(array $session) {
1627         $session['lastaccess'] = time();
1628         $this->session = $session;
1629         return parent::set($this->sessionid, $this->session);
1630     }
1632     /**
1633      * Retrieves the value for the given key from the cache.
1634      *
1635      * @param string|int $key The key for the data being requested.
1636      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
1637      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
1638      * @param int $strictness One of IGNORE_MISSING | MUST_EXIST
1639      * @return mixed|false The data from the cache or false if the key did not exist within the cache.
1640      * @throws moodle_exception
1641      */
1642     public function get($key, $strictness = IGNORE_MISSING) {
1643         // Check the tracked user.
1644         $this->check_tracked_user();
1645         // 2. Parse the key.
1646         $parsedkey = $this->parse_key($key);
1647         // 3. Get it from the store.
1648         $result = false;
1649         $session = $this->get_session_data();
1650         if (array_key_exists($parsedkey, $session)) {
1651             $result = $session[$parsedkey];
1652             if ($result instanceof cache_ttl_wrapper) {
1653                 if ($result->has_expired()) {
1654                     $this->get_store()->delete($parsedkey);
1655                     $result = false;
1656                 } else {
1657                     $result = $result->data;
1658                 }
1659             }
1660             if ($result instanceof cache_cached_object) {
1661                 $result = $result->restore_object();
1662             }
1663         }
1664         // 4. Load if from the loader/datasource if we don't already have it.
1665         $setaftervalidation = false;
1666         if ($result === false) {
1667             if ($this->perfdebug) {
1668                 cache_helper::record_cache_miss('**static session**', $this->get_definition()->get_id());
1669             }
1670             if ($this->get_loader() !== false) {
1671                 // We must pass the original (unparsed) key to the next loader in the chain.
1672                 // The next loader will parse the key as it sees fit. It may be parsed differently
1673                 // depending upon the capabilities of the store associated with the loader.
1674                 $result = $this->get_loader()->get($key);
1675             } else if ($this->get_datasource() !== false) {
1676                 $result = $this->get_datasource()->load_for_cache($key);
1677             }
1678             $setaftervalidation = ($result !== false);
1679         } else if ($this->perfdebug) {
1680             cache_helper::record_cache_hit('**static session**', $this->get_definition()->get_id());
1681         }
1682         // 5. Validate strictness.
1683         if ($strictness === MUST_EXIST && $result === false) {
1684             throw new moodle_exception('Requested key did not exist in any cache stores and could not be loaded.');
1685         }
1686         // 6. Set it to the store if we got it from the loader/datasource.
1687         if ($setaftervalidation) {
1688             $this->set($key, $result);
1689         }
1690         // 7. Make sure we don't pass back anything that could be a reference.
1691         //    We don't want people modifying the data in the cache.
1692         if (!is_scalar($result)) {
1693             // If data is an object it will be a reference.
1694             // If data is an array if may contain references.
1695             // We want to break references so that the cache cannot be modified outside of itself.
1696             // Call the function to unreference it (in the best way possible).
1697             $result = $this->unref($result);
1698         }
1699         return $result;
1700     }
1702     /**
1703      * Sends a key => value pair to the cache.
1704      *
1705      * <code>
1706      * // This code will add four entries to the cache, one for each url.
1707      * $cache->set('main', 'http://moodle.org');
1708      * $cache->set('docs', 'http://docs.moodle.org');
1709      * $cache->set('tracker', 'http://tracker.moodle.org');
1710      * $cache->set('qa', 'http://qa.moodle.net');
1711      * </code>
1712      *
1713      * @param string|int $key The key for the data being requested.
1714      *      It can be any structure although using a scalar string or int is recommended in the interests of performance.
1715      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
1716      * @param mixed $data The data to set against the key.
1717      * @return bool True on success, false otherwise.
1718      */
1719     public function set($key, $data) {
1720         $this->check_tracked_user();
1721         if ($this->perfdebug) {
1722             cache_helper::record_cache_set('**static session**', $this->get_definition()->get_id());
1723         }
1724         if (is_object($data) && $data instanceof cacheable_object) {
1725             $data = new cache_cached_object($data);
1726         } else if (!is_scalar($data)) {
1727             // If data is an object it will be a reference.
1728             // If data is an array if may contain references.
1729             // We want to break references so that the cache cannot be modified outside of itself.
1730             // Call the function to unreference it (in the best way possible).
1731             $data = $this->unref($data);
1732         }
1733         // We dont' support native TTL here as we consolidate data for sessions.
1734         if ($this->has_a_ttl()) {
1735             $data = new cache_ttl_wrapper($data, $this->get_definition()->get_ttl());
1736         }
1737         $session = $this->get_session_data();
1738         $session[$this->parse_key($key)] = $data;
1739         return $this->save_session($session);
1740     }
1742     /**
1743      * Delete the given key from the cache.
1744      *
1745      * @param string|int $key The key to delete.
1746      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1747      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1748      * @return bool True of success, false otherwise.
1749      */
1750     public function delete($key, $recurse = true) {
1751         $this->check_tracked_user();
1752         $parsedkey = $this->parse_key($key);
1753         if ($recurse && $this->get_loader() !== false) {
1754             // Delete from the bottom of the stack first.
1755             $this->get_loader()->delete($key, $recurse);
1756         }
1757         $session = $this->get_session_data();
1758         unset($session[$parsedkey]);
1759         return $this->save_session($session);
1760     }
1762     /**
1763      * Retrieves an array of values for an array of keys.
1764      *
1765      * Using this function comes with potential performance implications.
1766      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1767      * the equivalent singular method for each item provided.
1768      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1769      * does support it, but you should be aware of this fact.
1770      *
1771      * @param array $keys The keys of the data being requested.
1772      *      Each key can be any structure although using a scalar string or int is recommended in the interests of performance.
1773      *      In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
1774      * @param int $strictness One of IGNORE_MISSING or MUST_EXIST.
1775      * @return array An array of key value pairs for the items that could be retrieved from the cache.
1776      *      If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown.
1777      *      Otherwise any key that did not exist will have a data value of false within the results.
1778      * @throws moodle_exception
1779      */
1780     public function get_many(array $keys, $strictness = IGNORE_MISSING) {
1781         $this->check_tracked_user();
1782         $return = array();
1783         foreach ($keys as $key) {
1784             $return[$key] = $this->get($key, $strictness);
1785         }
1786         return $return;
1787     }
1789     /**
1790      * Delete all of the given keys from the cache.
1791      *
1792      * @param array $keys The key to delete.
1793      * @param bool $recurse When set to true the key will also be deleted from all stacked cache loaders and their stores.
1794      *     This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.
1795      * @return int The number of items successfully deleted.
1796      */
1797     public function delete_many(array $keys, $recurse = true) {
1798         $this->check_tracked_user();
1799         $parsedkeys = array_map(array($this, 'parse_key'), $keys);
1800         if ($recurse && $this->get_loader() !== false) {
1801             // Delete from the bottom of the stack first.
1802             $this->get_loader()->delete_many($keys, $recurse);
1803         }
1804         $session = $this->get_session_data();
1805         foreach ($parsedkeys as $parsedkey) {
1806             unset($session[$parsedkey]);
1807         }
1808         $this->save_session($session);
1809         return count($keys);
1810     }
1812     /**
1813      * Sends several key => value pairs to the cache.
1814      *
1815      * Using this function comes with potential performance implications.
1816      * Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call
1817      * the equivalent singular method for each item provided.
1818      * This should not deter you from using this function as there is a performance benefit in situations where the cache store
1819      * does support it, but you should be aware of this fact.
1820      *
1821      * <code>
1822      * // This code will add four entries to the cache, one for each url.
1823      * $cache->set_many(array(
1824      *     'main' => 'http://moodle.org',
1825      *     'docs' => 'http://docs.moodle.org',
1826      *     'tracker' => 'http://tracker.moodle.org',
1827      *     'qa' => ''http://qa.moodle.net'
1828      * ));
1829      * </code>
1830      *
1831      * @param array $keyvaluearray An array of key => value pairs to send to the cache.
1832      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items.
1833      *      ... if they care that is.
1834      */
1835     public function set_many(array $keyvaluearray) {
1836         $this->check_tracked_user();
1837         $session = $this->get_session_data();
1838         $simulatettl = $this->has_a_ttl();
1839         foreach ($keyvaluearray as $key => $value) {
1840             if (is_object($value) && $value instanceof cacheable_object) {
1841                 $value = new cache_cached_object($value);
1842             } else if (!is_scalar($value)) {
1843                 // If data is an object it will be a reference.
1844                 // If data is an array if may contain references.
1845                 // We want to break references so that the cache cannot be modified outside of itself.
1846                 // Call the function to unreference it (in the best way possible).
1847                 $value = $this->unref($value);
1848             }
1849             if ($simulatettl) {
1850                 $value = new cache_ttl_wrapper($value, $this->get_definition()->get_ttl());
1851             }
1852             $parsedkey = $this->parse_key($key);
1853             $session[$parsedkey] = $value;
1854         }
1855         if ($this->perfdebug) {
1856             cache_helper::record_cache_set($this->storetype, $this->get_definition()->get_id());
1857         }
1858         $this->save_session($session);
1859         return count($keyvaluearray);
1860     }
1862     /**
1863      * Purges the cache store, and loader if there is one.
1864      *
1865      * @return bool True on success, false otherwise
1866      */
1867     public function purge() {
1868         // 1. Purge the session object.
1869         $this->session = array();
1870         // 2. Delete the record for this users session from the store.
1871         $this->get_store()->delete($this->sessionid);
1872         // 3. Optionally purge any stacked loaders in the same way.
1873         if ($this->get_loader()) {
1874             $this->get_loader()->delete($this->sessionid);
1875         }
1876         return true;
1877     }
1879     /**
1880      * Test is a cache has a key.
1881      *
1882      * The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the
1883      * test and any subsequent action (get, set, delete etc).
1884      * Instead it is recommended to write your code in such a way they it performs the following steps:
1885      * <ol>
1886      * <li>Attempt to retrieve the information.</li>
1887      * <li>Generate the information.</li>
1888      * <li>Attempt to set the information</li>
1889      * </ol>
1890      *
1891      * Its also worth mentioning that not all stores support key tests.
1892      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
1893      * Just one more reason you should not use these methods unless you have a very good reason to do so.
1894      *
1895      * @param string|int $key
1896      * @param bool $tryloadifpossible If set to true, the cache doesn't contain the key, and there is another cache loader or
1897      *      data source then the code will try load the key value from the next item in the chain.
1898      * @return bool True if the cache has the requested key, false otherwise.
1899      */
1900     public function has($key, $tryloadifpossible = false) {
1901         $this->check_tracked_user();
1902         $parsedkey = $this->parse_key($key);
1903         $session = $this->get_session_data();
1904         $has = false;
1905         if ($this->has_a_ttl()) {
1906             // The data has a TTL and the store doesn't support it natively.
1907             // We must fetch the data and expect a ttl wrapper.
1908             if (array_key_exists($parsedkey, $session)) {
1909                 $data = $session[$parsedkey];
1910                 $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
1911             }
1912         } else {
1913             $has = array_key_exists($parsedkey, $session);
1914         }
1915         if (!$has && $tryloadifpossible) {
1916             if ($this->get_loader() !== false) {
1917                 $result = $this->get_loader()->get($key);
1918             } else if ($this->get_datasource() !== null) {
1919                 $result = $this->get_datasource()->load_for_cache($key);
1920             }
1921             $has = ($result !== null);
1922             if ($has) {
1923                 $this->set($key, $result);
1924             }
1925         }
1926         return $has;
1927     }
1929     /**
1930      * Test is a cache has all of the given keys.
1931      *
1932      * It is strongly recommended to avoid the use of this function if not absolutely required.
1933      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
1934      *
1935      * Its also worth mentioning that not all stores support key tests.
1936      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
1937      * Just one more reason you should not use these methods unless you have a very good reason to do so.
1938      *
1939      * @param array $keys
1940      * @return bool True if the cache has all of the given keys, false otherwise.
1941      */
1942     public function has_all(array $keys) {
1943         $this->check_tracked_user();
1944         $session = $this->get_session_data();
1945         foreach ($keys as $key) {
1946             $has = false;
1947             $parsedkey = $this->parse_key($key);
1948             if ($this->has_a_ttl()) {
1949                 // The data has a TTL and the store doesn't support it natively.
1950                 // We must fetch the data and expect a ttl wrapper.
1951                 if (array_key_exists($parsedkey, $session)) {
1952                     $data = $session[$parsedkey];
1953                     $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
1954                 }
1955             } else {
1956                 $has = array_key_exists($parsedkey, $session);
1957             }
1958             if (!$has) {
1959                 return false;
1960             }
1961         }
1962         return true;
1963     }
1965     /**
1966      * Test if a cache has at least one of the given keys.
1967      *
1968      * It is strongly recommended to avoid the use of this function if not absolutely required.
1969      * In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).
1970      *
1971      * Its also worth mentioning that not all stores support key tests.
1972      * For stores that don't support key tests this functionality is mimicked by using the equivalent get method.
1973      * Just one more reason you should not use these methods unless you have a very good reason to do so.
1974      *
1975      * @param array $keys
1976      * @return bool True if the cache has at least one of the given keys
1977      */
1978     public function has_any(array $keys) {
1979         $this->check_tracked_user();
1980         $session = $this->get_session_data();
1981         foreach ($keys as $key) {
1982             $has = false;
1983             $parsedkey = $this->parse_key($key);
1984             if ($this->has_a_ttl()) {
1985                 // The data has a TTL and the store doesn't support it natively.
1986                 // We must fetch the data and expect a ttl wrapper.
1987                 if (array_key_exists($parsedkey, $session)) {
1988                     $data = $session[$parsedkey];
1989                     $has = ($data instanceof cache_ttl_wrapper && !$data->has_expired());
1990                 }
1991             } else {
1992                 $has = array_key_exists($parsedkey, $session);
1993             }
1994             if ($has) {
1995                 return true;
1996             }
1997         }
1998         return false;
1999     }
2001     /**
2002      * The session loader never uses the persist cache.
2003      * Instead it stores things in the static $session variable. Shared between all session loaders.
2004      *
2005      * @return bool
2006      */
2007     protected function is_using_persist_cache() {
2008         return false;
2009     }
2012 /**
2013  * An request cache.
2014  *
2015  * This class is used for request caches returned by the cache::make methods.
2016  *
2017  * This cache class should never be interacted with directly. Instead you should always use the cache::make methods.
2018  * It is technically possible to call those methods through this class however there is no guarantee that you will get an
2019  * instance of this class back again.
2020  *
2021  * @internal don't use me directly.
2022  *
2023  * @package    core
2024  * @category   cache
2025  * @copyright  2012 Sam Hemelryk
2026  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2027  */
2028 class cache_request extends cache {
2029     // This comment appeases code pre-checker ;) !