MDL-35558 mod_data: Show only own entries while there are required pending.
[moodle.git] / cache / stores / mongodb / lib.php
CommitLineData
2e638e3d
SH
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 * The library file for the MongoDB store plugin.
19 *
20 * This file is part of the MongoDB store plugin, it contains the API for interacting with an instance of the store.
21 *
6fec1820 22 * @package cachestore_mongodb
2e638e3d
SH
23 * @copyright 2012 Sam Hemelryk
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27defined('MOODLE_INTERNAL') || die();
28
29/**
30 * The MongoDB Cache store.
31 *
32 * This cache store uses the MongoDB Native Driver.
33 * For installation instructions have a look at the following two links:
34 * - {@link http://www.php.net/manual/en/mongo.installation.php}
35 * - {@link http://www.mongodb.org/display/DOCS/PHP+Language+Center}
36 *
37 * @copyright 2012 Sam Hemelryk
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39 */
6fec1820 40class cachestore_mongodb implements cache_store {
2e638e3d
SH
41
42 /**
43 * The name of the store
44 * @var string
45 */
46 protected $name;
47
48 /**
49 * The server connection string. Comma separated values.
50 * @var string
51 */
52 protected $server = 'mongodb://127.0.0.1:27017';
53
54 /**
55 * The database connection options
56 * @var array
57 */
58 protected $options = array();
59
60 /**
61 * The name of the database to use.
62 * @var string
63 */
64 protected $databasename = 'mcache';
65
66 /**
67 * The Connection object
68 * @var Mongo
69 */
70 protected $connection;
71
72 /**
73 * The Database Object
74 * @var MongoDB
75 */
76 protected $database;
77
78 /**
79 * The Collection object
80 * @var MongoCollection
81 */
82 protected $collection;
83
84 /**
85 * Determines if and what safe setting is to be used.
86 * @var bool|int
87 */
88 protected $usesafe = false;
89
90 /**
91 * If set to true then multiple identifiers will be requested and used.
92 * @var bool
93 */
94 protected $extendedmode = false;
95
96 /**
97 * The definition has which is used in the construction of the collection.
98 * @var string
99 */
100 protected $definitionhash = null;
101
102 /**
103 * Constructs a new instance of the Mongo store but does not connect to it.
104 * @param string $name
105 * @param array $configuration
106 */
107 public function __construct($name, array $configuration = array()) {
108 $this->name = $name;
109
110 if (array_key_exists('server', $configuration)) {
111 $this->server = $configuration['server'];
112 }
113
114 if (array_key_exists('replicaset', $configuration)) {
115 $this->options['replicaSet'] = (string)$configuration['replicaset'];
116 }
117 if (array_key_exists('username', $configuration) && !empty($configuration['username'])) {
118 $this->options['username'] = (string)$configuration['username'];
119 }
120 if (array_key_exists('password', $configuration) && !empty($configuration['password'])) {
121 $this->options['password'] = (string)$configuration['password'];
122 }
123 if (array_key_exists('database', $configuration)) {
124 $this->databasename = (string)$configuration['database'];
125 }
126 if (array_key_exists('usesafe', $configuration)) {
127 $this->usesafe = $configuration['usesafe'];
128 }
129 if (array_key_exists('extendedmode', $configuration)) {
130 $this->extendedmode = $configuration['extendedmode'];
131 }
132
133 $this->isready = self::are_requirements_met();
134 }
135
136 /**
137 * Returns true if the requirements of this store have been met.
138 * @return bool
139 */
140 public static function are_requirements_met() {
141 return class_exists('Mongo');
142 }
143
144 /**
145 * Returns true if the user can add an instance of this store.
146 * @return bool
147 */
148 public static function can_add_instance() {
149 return true;
150 }
151
152 /**
153 * Returns the supported features.
154 * @param array $configuration
155 * @return int
156 */
157 public static function get_supported_features(array $configuration = array()) {
158 $supports = self::SUPPORTS_DATA_GUARANTEE;
159 if (array_key_exists('extendedmode', $configuration) && $configuration['extendedmode']) {
160 $supports += self::SUPPORTS_MULTIPLE_IDENTIFIERS;
161 }
162 return $supports;
163 }
164
165 /**
166 * Returns an int describing the supported modes.
167 * @param array $configuration
168 * @return int
169 */
170 public static function get_supported_modes(array $configuration = array()) {
171 return self::MODE_APPLICATION + self::MODE_SESSION;
172 }
173
174 /**
175 * Initialises the store instance for use.
176 *
177 * This function is reponsible for making the connection.
178 *
179 * @param cache_definition $definition
180 * @throws coding_exception
181 */
182 public function initialise(cache_definition $definition) {
183 if ($this->is_initialised()) {
184 throw new coding_exception('This mongodb instance has already been initialised.');
185 }
186 $this->definitionhash = $definition->generate_definition_hash();
187 $this->connection = new Mongo($this->server, $this->options);
188 $this->database = $this->connection->selectDB($this->databasename);
189 $this->collection = $this->database->selectCollection($this->definitionhash);
190 $this->collection->ensureIndex(array('key' => 1), array(
191 'safe' => $this->usesafe,
192 'name' => 'idx_key'
193 ));
194 }
195
196 /**
197 * Returns true if this store instance has been initialised.
198 * @return bool
199 */
200 public function is_initialised() {
201 return ($this->database instanceof MongoDB);
202 }
203
204 /**
205 * Returns true if this store instance is ready to use.
206 * @return bool
207 */
208 public function is_ready() {
209 return $this->isready;
210 }
211
212 /**
213 * Returns true if the given mode is supported by this store.
214 * @param int $mode
215 * @return bool
216 */
217 public static function is_supported_mode($mode) {
218 return ($mode == self::MODE_APPLICATION || $mode == self::MODE_SESSION);
219 }
220
221 /**
222 * Returns true if this store guarantees its data is there once set.
223 * @return bool
224 */
225 public function supports_data_guarantee() {
226 return true;
227 }
228
229 /**
230 * Returns true if this store is making use of multiple identifiers.
231 * @return bool
232 */
233 public function supports_multiple_indentifiers() {
234 return $this->extendedmode;
235 }
236
237 /**
238 * Returns true if this store supports native TTL.
239 * @return bool
240 */
241 public function supports_native_ttl() {
242 return false;;
243 }
244
245 /**
246 * Retrieves an item from the cache store given its key.
247 *
248 * @param string $key The key to retrieve
249 * @return mixed The data that was associated with the key, or false if the key did not exist.
250 */
251 public function get($key) {
252 if (!is_array($key)) {
253 $key = array('key' => $key);
254 }
170f821b 255
2e638e3d
SH
256 $result = $this->collection->findOne($key);
257 if ($result === null || !array_key_exists('data', $result)) {
258 return false;
259 }
260 $data = @unserialize($result['data']);
261 return $data;
262 }
263
264 /**
265 * Retrieves several items from the cache store in a single transaction.
266 *
267 * 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.
268 *
269 * @param array $keys The array of keys to retrieve
270 * @return array An array of items from the cache.
271 */
272 public function get_many($keys) {
273 if ($this->extendedmode) {
274 $query = $this->get_many_extendedmode_query($keys);
275 $keyarray = array();
276 foreach ($keys as $key) {
277 $keyarray[] = $key['key'];
278 }
279 $keys = $keyarray;
280 $query = array('key' => array('$in' => $keys));
281 } else {
282 $query = array('key' => array('$in' => $keys));
283 }
284 $cursor = $this->collection->find($query);
285 $results = array();
286 foreach ($cursor as $result) {
287 if (array_key_exists('key', $result)) {
288 $id = $result[$key];
289 } else {
290 $id = (string)$result['key'];
291 }
292 $results[$id] = unserialize($result['data']);
293 }
294 foreach ($keys as $key) {
295 if (!array_key_exists($key, $results)) {
296 $results[$key] = false;
297 }
298 }
299 return $results;
300 }
301
302 /**
303 * Sets an item in the cache given its key and data value.
304 *
305 * @param string $key The key to use.
306 * @param mixed $data The data to set.
307 * @return bool True if the operation was a success false otherwise.
308 */
309 public function set($key, $data) {
310 if (!is_array($key)) {
311 $record = array(
312 'key' => $key
313 );
314 } else {
315 $record = $key;
316 }
317 $record['data'] = serialize($data);
318 $options = array(
319 'upsert' => true,
320 'safe' => $this->usesafe
321 );
322 $this->delete($key);
323 $result = $this->collection->insert($record, $options);
324 return $result;
325 }
326
327 /**
328 * Sets many items in the cache in a single transaction.
329 *
330 * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
331 * keys, 'key' and 'value'.
332 * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
333 * sent ... if they care that is.
334 */
335 public function set_many(array $keyvaluearray) {
336 $count = 0;
337 foreach ($keyvaluearray as $pair) {
338 $result = $this->set($pair['key'], $pair['value']);
339 if ($result === true || (is_array($result)) && !empty($result['ok'])) {
340 $count++;
341 }
342 }
343 return;
344 }
345
346 /**
347 * Deletes an item from the cache store.
348 *
349 * @param string $key The key to delete.
350 * @return bool Returns true if the operation was a success, false otherwise.
351 */
352 public function delete($key) {
353 if (!is_array($key)) {
354 $criteria = array(
355 'key' => $key
356 );
357 } else {
358 $criteria = $key;
359 }
360 $options = array(
361 'justOne' => false,
362 'safe' => $this->usesafe
363 );
364 $result = $this->collection->remove($criteria, $options);
365 if ($result === false || (is_array($result) && !array_key_exists('ok', $result)) || $result === 0) {
366 return false;
367 }
368 return !empty($result['ok']);
369 }
370
371 /**
372 * Deletes several keys from the cache in a single action.
373 *
374 * @param array $keys The keys to delete
375 * @return int The number of items successfully deleted.
376 */
377 public function delete_many(array $keys) {
378 $count = 0;
379 foreach ($keys as $key) {
380 if ($this->delete($key)) {
381 $count++;
382 }
383 }
384 return $count;
385 }
386
387 /**
388 * Purges the cache deleting all items within it.
389 *
390 * @return boolean True on success. False otherwise.
391 */
392 public function purge() {
393 $this->collection->drop();
394 $this->collection = $this->database->selectCollection($this->definitionhash);
395 }
396
397 /**
398 * Takes the object from the add instance store and creates a configuration array that can be used to initialise an instance.
399 *
400 * @param stdClass $data
401 * @return array
402 */
403 public static function config_get_configuration_array($data) {
404 $return = array(
405 'server' => $data->server,
406 'database' => $data->database,
407 'extendedmode' => (!empty($data->extendedmode))
408 );
409 if (!empty($data->username)) {
410 $return['username'] = $data->username;
411 }
412 if (!empty($data->password)) {
413 $return['password'] = $data->password;
414 }
415 if (!empty($data->replicaset)) {
416 $return['replicaset'] = $data->replicaset;
417 }
418 if (!empty($data->usesafe)) {
419 $return['usesafe'] = true;
420 if (!empty($data->usesafevalue)) {
421 $return['usesafe'] = (int)$data->usesafevalue;
422 }
423 }
424 return $return;
425 }
426
427 /**
428 * Performs any necessary clean up when the store instance is being deleted.
429 */
430 public function cleanup() {
431 $this->purge();
432 }
433
434 /**
435 * Generates an instance of the cache store that can be used for testing.
436 *
437 * @param cache_definition $definition
438 * @return false
439 */
440 public static function initialise_test_instance(cache_definition $definition) {
441 if (!self::are_requirements_met()) {
442 return false;
443 }
444
6fec1820 445 $config = get_config('cachestore_mongodb');
2e638e3d
SH
446 if (empty($config->testserver)) {
447 return false;
448 }
449
450 $configuration = array();
451 $configuration['server'] = $config->testserver;
452 if (!empty($config->testreplicaset)) {
453 $configuration['replicaset'] = $config->testreplicaset;
454 }
455 if (!empty($config->testusername)) {
456 $configuration['username'] = $config->testusername;
457 }
458 if (!empty($config->testpassword)) {
459 $configuration['password'] = $config->testpassword;
460 }
461 if (!empty($config->testdatabase)) {
462 $configuration['database'] = $config->testdatabase;
463 }
464 if (!empty($config->testusesafe)) {
465 $configuration['usesafe'] = $config->testusesafe;
466 }
467 if (!empty($config->testextendedmode)) {
468 $configuration['extendedmode'] = (bool)$config->testextendedmode;
469 }
470
6fec1820 471 $store = new cachestore_mongodb('Test mongodb', $configuration);
2e638e3d
SH
472 $store->initialise($definition);
473
474 return $store;
475 }
34c84c72
SH
476
477 /**
478 * Returns the name of this instance.
479 * @return string
480 */
481 public function my_name() {
482 return $this->name;
483 }
2e638e3d 484}