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