MDL-42839 MUC: Memcache server configuration too sensitive to whitespace
[moodle.git] / cache / stores / memcached / lib.php
CommitLineData
47d89ccf
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 memcached cache store.
19 *
20 * This file is part of the memcached cache store, it contains the API for interacting with an instance of the store.
21 *
6fec1820 22 * @package cachestore_memcached
47d89ccf
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 memcached store.
31 *
32 * (Not to be confused with the memcache store)
33 *
34 * Configuration options:
35 * servers: string: host:port:weight , ...
36 * compression: true, false
37 * serialiser: SERIALIZER_PHP, SERIALIZER_JSON, SERIALIZER_IGBINARY
38 * prefix: string: defaults to instance name
39 * hashmethod: HASH_DEFAULT, HASH_MD5, HASH_CRC, HASH_FNV1_64, HASH_FNV1A_64, HASH_FNV1_32,
40 * HASH_FNV1A_32, HASH_HSIEH, HASH_MURMUR
41 * bufferwrites: true, false
42 *
43 * @copyright 2012 Sam Hemelryk
44 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
45 */
2b274ad0 46class cachestore_memcached extends cache_store implements cache_is_configurable {
47d89ccf
SH
47 /**
48 * The name of the store
49 * @var store
50 */
51 protected $name;
52
53 /**
54 * The memcached connection
55 * @var Memcached
56 */
57 protected $connection;
58
59 /**
60 * An array of servers to use during connection
61 * @var array
62 */
63 protected $servers = array();
64
65 /**
66 * The options used when establishing the connection
67 * @var array
68 */
69 protected $options = array();
70
71 /**
72 * True when this instance is ready to be initialised.
73 * @var bool
74 */
75 protected $isready = false;
170f821b 76
65b3edc4
SH
77 /**
78 * Set to true when this store instance has been initialised.
79 * @var bool
80 */
81 protected $isinitialised = false;
82
47d89ccf
SH
83 /**
84 * The cache definition this store was initialised with.
85 * @var cache_definition
86 */
87 protected $definition;
88
89 /**
90 * Constructs the store instance.
91 *
92 * Noting that this function is not an initialisation. It is used to prepare the store for use.
93 * The store will be initialised when required and will be provided with a cache_definition at that time.
94 *
95 * @param string $name
96 * @param array $configuration
97 */
98 public function __construct($name, array $configuration = array()) {
99 $this->name = $name;
100 if (!array_key_exists('servers', $configuration) || empty($configuration['servers'])) {
101 // Nothing configured.
102 return;
103 }
42f5d164
SH
104 if (!is_array($configuration['servers'])) {
105 $configuration['servers'] = array($configuration['servers']);
106 }
47d89ccf
SH
107
108 $compression = array_key_exists('compression', $configuration) ? (bool)$configuration['compression'] : true;
170f821b
SH
109 if (array_key_exists('serialiser', $configuration)) {
110 $serialiser = (int)$configuration['serialiser'];
111 } else {
112 $serialiser = Memcached::SERIALIZER_PHP;
113 }
47d89ccf
SH
114 $prefix = (!empty($configuration['prefix'])) ? (string)$configuration['prefix'] : crc32($name);
115 $hashmethod = (array_key_exists('hash', $configuration)) ? (int)$configuration['hash'] : Memcached::HASH_DEFAULT;
116 $bufferwrites = array_key_exists('bufferwrites', $configuration) ? (bool)$configuration['bufferwrites'] : false;
117
118 foreach ($configuration['servers'] as $server) {
119 if (!is_array($server)) {
120 $server = explode(':', $server, 3);
121 }
122 if (!array_key_exists(1, $server)) {
123 $server[1] = 11211;
124 $server[2] = 100;
125 } else if (!array_key_exists(2, $server)) {
126 $server[2] = 100;
127 }
128 $this->servers[] = $server;
129 }
130 $this->options[Memcached::OPT_COMPRESSION] = $compression;
131 $this->options[Memcached::OPT_SERIALIZER] = $serialiser;
132 $this->options[Memcached::OPT_PREFIX_KEY] = $prefix;
133 $this->options[Memcached::OPT_HASH] = $hashmethod;
134 $this->options[Memcached::OPT_BUFFER_WRITES] = $bufferwrites;
135
f4cec2ec
MS
136 $this->connection = new Memcached(crc32($this->name));
137 $servers = $this->connection->getServerList();
138 if (empty($servers)) {
139 foreach ($this->options as $key => $value) {
140 $this->connection->setOption($key, $value);
141 }
142 $this->connection->addServers($this->servers);
f4cec2ec 143 }
a94bc886 144 // Test the connection to the pool of servers.
ff6f9d3a 145 $this->isready = @$this->connection->set("ping", 'ping', 1);
47d89ccf
SH
146 }
147
148 /**
149 * Initialises the cache.
150 *
151 * Once this has been done the cache is all set to be used.
152 *
153 * @param cache_definition $definition
154 */
155 public function initialise(cache_definition $definition) {
156 if ($this->is_initialised()) {
157 throw new coding_exception('This memcached instance has already been initialised.');
158 }
159 $this->definition = $definition;
65b3edc4 160 $this->isinitialised = true;
47d89ccf
SH
161 }
162
163 /**
164 * Returns true once this instance has been initialised.
165 *
166 * @return bool
167 */
168 public function is_initialised() {
65b3edc4 169 return ($this->isinitialised);
47d89ccf
SH
170 }
171
172 /**
173 * Returns true if this store instance is ready to be used.
174 * @return bool
175 */
176 public function is_ready() {
177 return $this->isready;
178 }
179
180 /**
181 * Returns true if the store requirements are met.
182 *
183 * @return bool
184 */
185 public static function are_requirements_met() {
186 return class_exists('Memcached');
187 }
188
189 /**
190 * Returns true if the given mode is supported by this store.
191 *
192 * @param int $mode One of cache_store::MODE_*
193 * @return bool
194 */
195 public static function is_supported_mode($mode) {
196 return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
197 }
198
199 /**
200 * Returns the supported features as a combined int.
201 *
202 * @param array $configuration
203 * @return int
204 */
205 public static function get_supported_features(array $configuration = array()) {
206 return self::SUPPORTS_NATIVE_TTL;
207 }
208
cb86f1eb 209 /**
210 * Returns false as this store does not support multiple identifiers.
211 * (This optional function is a performance optimisation; it must be
212 * consistent with the value from get_supported_features.)
213 *
214 * @return bool False
215 */
216 public function supports_multiple_identifiers() {
217 return false;
218 }
219
47d89ccf
SH
220 /**
221 * Returns the supported modes as a combined int.
222 *
223 * @param array $configuration
224 * @return int
225 */
226 public static function get_supported_modes(array $configuration = array()) {
227 return self::MODE_APPLICATION + self::MODE_SESSION;
228 }
229
230 /**
231 * Retrieves an item from the cache store given its key.
232 *
233 * @param string $key The key to retrieve
234 * @return mixed The data that was associated with the key, or false if the key did not exist.
235 */
236 public function get($key) {
237 return $this->connection->get($key);
238 }
239
240 /**
241 * Retrieves several items from the cache store in a single transaction.
242 *
243 * 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.
244 *
245 * @param array $keys The array of keys to retrieve
246 * @return array An array of items from the cache. There will be an item for each key, those that were not in the store will
247 * be set to false.
248 */
249 public function get_many($keys) {
250 $result = $this->connection->getMulti($keys);
251 if (!is_array($result)) {
252 $result = array();
253 }
254 foreach ($keys as $key) {
255 if (!array_key_exists($key, $result)) {
256 $result[$key] = false;
257 }
258 }
259 return $result;
260 }
261
262 /**
263 * Sets an item in the cache given its key and data value.
264 *
265 * @param string $key The key to use.
266 * @param mixed $data The data to set.
267 * @return bool True if the operation was a success false otherwise.
268 */
269 public function set($key, $data) {
270 return $this->connection->set($key, $data, $this->definition->get_ttl());
271 }
272
273 /**
274 * Sets many items in the cache in a single transaction.
275 *
276 * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
277 * keys, 'key' and 'value'.
278 * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
279 * sent ... if they care that is.
280 */
281 public function set_many(array $keyvaluearray) {
282 $pairs = array();
283 foreach ($keyvaluearray as $pair) {
284 $pairs[$pair['key']] = $pair['value'];
285 }
286 if ($this->connection->setMulti($pairs, $this->definition->get_ttl())) {
287 return count($keyvaluearray);
288 }
289 return 0;
290 }
291
292 /**
293 * Deletes an item from the cache store.
294 *
295 * @param string $key The key to delete.
296 * @return bool Returns true if the operation was a success, false otherwise.
297 */
298 public function delete($key) {
299 return $this->connection->delete($key);
300 }
301
302 /**
303 * Deletes several keys from the cache in a single action.
304 *
305 * @param array $keys The keys to delete
306 * @return int The number of items successfully deleted.
307 */
308 public function delete_many(array $keys) {
309 $count = 0;
310 foreach ($keys as $key) {
311 if ($this->connection->delete($key)) {
312 $count++;
313 }
314 }
315 return $count;
316 }
317
318 /**
319 * Purges the cache deleting all items within it.
320 *
321 * @return boolean True on success. False otherwise.
322 */
323 public function purge() {
f4cec2ec
MS
324 if ($this->isready) {
325 $this->connection->flush();
326 }
327
47d89ccf
SH
328 return true;
329 }
330
331 /**
332 * Gets an array of options to use as the serialiser.
333 * @return array
334 */
335 public static function config_get_serialiser_options() {
336 $options = array(
6fec1820 337 Memcached::SERIALIZER_PHP => get_string('serialiser_php', 'cachestore_memcached')
47d89ccf
SH
338 );
339 if (Memcached::HAVE_JSON) {
6fec1820 340 $options[Memcached::SERIALIZER_JSON] = get_string('serialiser_json', 'cachestore_memcached');
47d89ccf
SH
341 }
342 if (Memcached::HAVE_IGBINARY) {
a10d6199 343 $options[Memcached::SERIALIZER_IGBINARY] = get_string('serialiser_igbinary', 'cachestore_memcached');
47d89ccf
SH
344 }
345 return $options;
346 }
347
348 /**
349 * Gets an array of hash options available during configuration.
350 * @return array
351 */
352 public static function config_get_hash_options() {
353 $options = array(
6fec1820
SH
354 Memcached::HASH_DEFAULT => get_string('hash_default', 'cachestore_memcached'),
355 Memcached::HASH_MD5 => get_string('hash_md5', 'cachestore_memcached'),
356 Memcached::HASH_CRC => get_string('hash_crc', 'cachestore_memcached'),
357 Memcached::HASH_FNV1_64 => get_string('hash_fnv1_64', 'cachestore_memcached'),
358 Memcached::HASH_FNV1A_64 => get_string('hash_fnv1a_64', 'cachestore_memcached'),
359 Memcached::HASH_FNV1_32 => get_string('hash_fnv1_32', 'cachestore_memcached'),
360 Memcached::HASH_FNV1A_32 => get_string('hash_fnv1a_32', 'cachestore_memcached'),
361 Memcached::HASH_HSIEH => get_string('hash_hsieh', 'cachestore_memcached'),
362 Memcached::HASH_MURMUR => get_string('hash_murmur', 'cachestore_memcached'),
47d89ccf
SH
363 );
364 return $options;
365 }
366
367 /**
368 * Given the data from the add instance form this function creates a configuration array.
369 *
370 * @param stdClass $data
371 * @return array
372 */
373 public static function config_get_configuration_array($data) {
374 $lines = explode("\n", $data->servers);
375 $servers = array();
376 foreach ($lines as $line) {
5c138b25 377 // Trim surrounding colons and default whitespace.
378 $line = trim(trim($line), ":");
379 // Skip blank lines.
380 if ($line === '') {
381 continue;
382 }
47d89ccf
SH
383 $servers[] = explode(':', $line, 3);
384 }
385 return array(
386 'servers' => $servers,
387 'compression' => $data->compression,
388 'serialiser' => $data->serialiser,
389 'prefix' => $data->prefix,
390 'hash' => $data->hash,
391 'bufferwrites' => $data->bufferwrites,
392 );
393 }
394
81ede547
SH
395 /**
396 * Allows the cache store to set its data against the edit form before it is shown to the user.
397 *
398 * @param moodleform $editform
399 * @param array $config
400 */
401 public static function config_set_edit_form_data(moodleform $editform, array $config) {
402 $data = array();
403 if (!empty($config['servers'])) {
404 $servers = array();
405 foreach ($config['servers'] as $server) {
406 $servers[] = join(":", $server);
407 }
408 $data['servers'] = join("\n", $servers);
409 }
d837df0d
SH
410 if (isset($config['compression'])) {
411 $data['compression'] = (bool)$config['compression'];
81ede547
SH
412 }
413 if (!empty($config['serialiser'])) {
414 $data['serialiser'] = $config['serialiser'];
415 }
416 if (!empty($config['prefix'])) {
417 $data['prefix'] = $config['prefix'];
418 }
419 if (!empty($config['hash'])) {
420 $data['hash'] = $config['hash'];
421 }
d837df0d
SH
422 if (isset($config['bufferwrites'])) {
423 $data['bufferwrites'] = (bool)$config['bufferwrites'];
81ede547
SH
424 }
425 $editform->set_data($data);
426 }
427
47d89ccf
SH
428 /**
429 * Performs any necessary clean up when the store instance is being deleted.
430 */
59ca73ff 431 public function instance_deleted() {
a037c943
SH
432 if ($this->connection) {
433 $connection = $this->connection;
434 } else {
435 $connection = new Memcached(crc32($this->name));
436 $servers = $connection->getServerList();
437 if (empty($servers)) {
438 foreach ($this->options as $key => $value) {
439 $connection->setOption($key, $value);
440 }
441 $connection->addServers($this->servers);
442 }
443 }
bb4c3916 444 @$connection->flush();
a037c943
SH
445 unset($connection);
446 unset($this->connection);
59ca73ff
MS
447 }
448
47d89ccf
SH
449 /**
450 * Generates an instance of the cache store that can be used for testing.
451 *
452 * @param cache_definition $definition
7dfa10b0 453 * @return cachestore_memcached|false
47d89ccf
SH
454 */
455 public static function initialise_test_instance(cache_definition $definition) {
456
457 if (!self::are_requirements_met()) {
458 return false;
459 }
460
6fec1820 461 $config = get_config('cachestore_memcached');
47d89ccf
SH
462 if (empty($config->testservers)) {
463 return false;
464 }
465
466 $configuration = array();
467 $configuration['servers'] = $config->testservers;
468 if (!empty($config->testcompression)) {
469 $configuration['compression'] = $config->testcompression;
470 }
471 if (!empty($config->testserialiser)) {
472 $configuration['serialiser'] = $config->testserialiser;
473 }
474 if (!empty($config->testprefix)) {
475 $configuration['prefix'] = $config->testprefix;
476 }
477 if (!empty($config->testhash)) {
478 $configuration['hash'] = $config->testhash;
479 }
480 if (!empty($config->testbufferwrites)) {
481 $configuration['bufferwrites'] = $config->testbufferwrites;
482 }
483
6fec1820 484 $store = new cachestore_memcached('Test memcached', $configuration);
47d89ccf
SH
485 $store->initialise($definition);
486
487 return $store;
488 }
34c84c72
SH
489
490 /**
491 * Returns the name of this instance.
492 * @return string
493 */
494 public function my_name() {
495 return $this->name;
496 }
bb4c3916 497}