Merge branch 'install_310_STABLE' of https://git.in.moodle.com/amosbot/moodle-install...
[moodle.git] / question / engine / bank.php
CommitLineData
d1b7e03d 1<?php
d1b7e03d
TH
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
d1b7e03d
TH
17/**
18 * More object oriented wrappers around parts of the Moodle question bank.
19 *
20 * In due course, I expect that the question bank will be converted to a
21 * fully object oriented structure, at which point this file can be a
22 * starting point.
23 *
017bc1d9 24 * @package moodlecore
d1b7e03d 25 * @subpackage questionbank
017bc1d9
TH
26 * @copyright 2009 The Open University
27 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d
TH
28 */
29
30
a17b297d
TH
31defined('MOODLE_INTERNAL') || die();
32
1fcf0ca8 33require_once(__DIR__ . '/../type/questiontypebase.php');
c468ce59 34
a17b297d 35
d1b7e03d
TH
36/**
37 * This static class provides access to the other question bank.
38 *
39 * It provides functions for managing question types and question definitions.
40 *
017bc1d9
TH
41 * @copyright 2009 The Open University
42 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d
TH
43 */
44abstract class question_bank {
63637e9d
EL
45 // TODO: This limit can be deleted if someday we move all TEXTS to BIG ones. MDL-19603
46 const MAX_SUMMARY_LENGTH = 32000;
c83ed025 47
d1b7e03d
TH
48 /** @var array question type name => question_type subclass. */
49 private static $questiontypes = array();
50
51 /** @var array question type name => 1. Records which question definitions have been loaded. */
52 private static $loadedqdefs = array();
53
d1b7e03d
TH
54 /** @var boolean nasty hack to allow unit tests to call {@link load_question()}. */
55 private static $testmode = false;
56 private static $testdata = array();
57
f9b0500f
TH
58 private static $questionconfig = null;
59
af2f98ee
TH
60 /**
61 * @var array string => string The standard set of grade options (fractions)
62 * to use when editing questions, in the range 0 to 1 inclusive. Array keys
63 * are string becuase: a) we want grades to exactly 7 d.p., and b. you can't
64 * have float array keys in PHP.
65 * Initialised by {@link ensure_grade_options_initialised()}.
66 */
67 private static $fractionoptions = null;
68 /** @var array string => string The full standard set of (fractions) -1 to 1 inclusive. */
69 private static $fractionoptionsfull = null;
70
d649fb02
TH
71 /**
72 * @param string $qtypename a question type name, e.g. 'multichoice'.
73 * @return bool whether that question type is installed in this Moodle.
74 */
75 public static function is_qtype_installed($qtypename) {
1c74b260 76 $plugindir = core_component::get_plugin_directory('qtype', $qtypename);
d649fb02
TH
77 return $plugindir && is_readable($plugindir . '/questiontype.php');
78 }
79
d1b7e03d
TH
80 /**
81 * Get the question type class for a particular question type.
82 * @param string $qtypename the question type name. For example 'multichoice' or 'shortanswer'.
f7970e3c 83 * @param bool $mustexist if false, the missing question type is returned when
d1b7e03d
TH
84 * the requested question type is not installed.
85 * @return question_type the corresponding question type class.
86 */
87 public static function get_qtype($qtypename, $mustexist = true) {
88 global $CFG;
89 if (isset(self::$questiontypes[$qtypename])) {
90 return self::$questiontypes[$qtypename];
91 }
1c74b260 92 $file = core_component::get_plugin_directory('qtype', $qtypename) . '/questiontype.php';
d1b7e03d
TH
93 if (!is_readable($file)) {
94 if ($mustexist || $qtypename == 'missingtype') {
88f0eb15 95 throw new coding_exception('Unknown question type ' . $qtypename);
d1b7e03d
TH
96 } else {
97 return self::get_qtype('missingtype');
98 }
99 }
100 include_once($file);
101 $class = 'qtype_' . $qtypename;
f29aeb5a 102 if (!class_exists($class)) {
f4fe3968 103 throw new coding_exception("Class {$class} must be defined in {$file}.");
f29aeb5a 104 }
d1b7e03d
TH
105 self::$questiontypes[$qtypename] = new $class();
106 return self::$questiontypes[$qtypename];
107 }
108
f9b0500f
TH
109 /**
110 * Load the question configuration data from config_plugins.
111 * @return object get_config('question') with caching.
112 */
fde4560d 113 public static function get_config() {
f9b0500f 114 if (is_null(self::$questionconfig)) {
fde4560d 115 self::$questionconfig = get_config('question');
f9b0500f 116 }
fde4560d 117 return self::$questionconfig;
f9b0500f
TH
118 }
119
06f8ed54
TH
120 /**
121 * @param string $qtypename the internal name of a question type. For example multichoice.
f7970e3c 122 * @return bool whether users are allowed to create questions of this type.
06f8ed54
TH
123 */
124 public static function qtype_enabled($qtypename) {
f9b0500f
TH
125 $config = self::get_config();
126 $enabledvar = $qtypename . '_disabled';
127 return self::qtype_exists($qtypename) && empty($config->$enabledvar) &&
128 self::get_qtype($qtypename)->menu_name() != '';
129 }
130
131 /**
132 * @param string $qtypename the internal name of a question type. For example multichoice.
f7970e3c 133 * @return bool whether this question type exists.
f9b0500f
TH
134 */
135 public static function qtype_exists($qtypename) {
bd3b3bba 136 return array_key_exists($qtypename, core_component::get_plugin_list('qtype'));
06f8ed54
TH
137 }
138
d1b7e03d
TH
139 /**
140 * @param $qtypename the internal name of a question type, for example multichoice.
141 * @return string the human_readable name of this question type, from the language pack.
142 */
143 public static function get_qtype_name($qtypename) {
f9b0500f 144 return self::get_qtype($qtypename)->local_name();
d1b7e03d
TH
145 }
146
147 /**
148 * @return array all the installed question types.
149 */
150 public static function get_all_qtypes() {
151 $qtypes = array();
bd3b3bba 152 foreach (core_component::get_plugin_list('qtype') as $plugin => $notused) {
f29aeb5a
TH
153 try {
154 $qtypes[$plugin] = self::get_qtype($plugin);
2daffca5
TH
155 } catch (coding_exception $e) {
156 // Catching coding_exceptions here means that incompatible
157 // question types do not cause the rest of Moodle to break.
f29aeb5a 158 }
d1b7e03d
TH
159 }
160 return $qtypes;
161 }
162
f9b0500f 163 /**
d649fb02
TH
164 * Sort an array of question types according to the order the admin set up,
165 * and then alphabetically for the rest.
166 * @param array qtype->name() => qtype->local_name().
167 * @return array sorted array.
f9b0500f 168 */
d649fb02
TH
169 public static function sort_qtype_array($qtypes, $config = null) {
170 if (is_null($config)) {
171 $config = self::get_config();
172 }
f9b0500f
TH
173
174 $sortorder = array();
175 $otherqtypes = array();
d649fb02 176 foreach ($qtypes as $name => $localname) {
f9b0500f
TH
177 $sortvar = $name . '_sortorder';
178 if (isset($config->$sortvar)) {
179 $sortorder[$config->$sortvar] = $name;
180 } else {
d649fb02 181 $otherqtypes[$name] = $localname;
f9b0500f
TH
182 }
183 }
184
185 ksort($sortorder);
2f1e464a 186 core_collator::asort($otherqtypes);
f9b0500f 187
d649fb02 188 $sortedqtypes = array();
f9b0500f 189 foreach ($sortorder as $name) {
d649fb02 190 $sortedqtypes[$name] = $qtypes[$name];
f9b0500f
TH
191 }
192 foreach ($otherqtypes as $name => $notused) {
d649fb02
TH
193 $sortedqtypes[$name] = $qtypes[$name];
194 }
195 return $sortedqtypes;
196 }
197
198 /**
199 * @return array all the question types that users are allowed to create,
200 * sorted into the preferred order set on the admin screen.
201 */
202 public static function get_creatable_qtypes() {
203 $config = self::get_config();
204 $allqtypes = self::get_all_qtypes();
205
206 $qtypenames = array();
207 foreach ($allqtypes as $name => $qtype) {
208 if (self::qtype_enabled($name)) {
209 $qtypenames[$name] = $qtype->local_name();
210 }
211 }
212
213 $qtypenames = self::sort_qtype_array($qtypenames);
214
215 $creatableqtypes = array();
216 foreach ($qtypenames as $name => $notused) {
f9b0500f
TH
217 $creatableqtypes[$name] = $allqtypes[$name];
218 }
a13d4fbd 219 return $creatableqtypes;
f9b0500f
TH
220 }
221
d1b7e03d
TH
222 /**
223 * Load the question definition class(es) belonging to a question type. That is,
224 * include_once('/question/type/' . $qtypename . '/question.php'), with a bit
225 * of checking.
226 * @param string $qtypename the question type name. For example 'multichoice' or 'shortanswer'.
227 */
228 public static function load_question_definition_classes($qtypename) {
229 global $CFG;
230 if (isset(self::$loadedqdefs[$qtypename])) {
231 return;
232 }
233 $file = $CFG->dirroot . '/question/type/' . $qtypename . '/question.php';
234 if (!is_readable($file)) {
88f0eb15 235 throw new coding_exception('Unknown question type (no definition) ' . $qtypename);
d1b7e03d
TH
236 }
237 include_once($file);
238 self::$loadedqdefs[$qtypename] = 1;
239 }
240
a560d636
TH
241 /**
242 * This method needs to be called whenever a question is edited.
243 */
244 public static function notify_question_edited($questionid) {
245 question_finder::get_instance()->uncache_question($questionid);
246 }
247
248 /**
249 * Load a question definition data from the database. The data will be
250 * returned as a plain stdClass object.
251 * @param int $questionid the id of the question to load.
252 * @return object question definition loaded from the database.
253 */
254 public static function load_question_data($questionid) {
255 return question_finder::get_instance()->load_question_data($questionid);
256 }
257
d1b7e03d
TH
258 /**
259 * Load a question definition from the database. The object returned
260 * will actually be of an appropriate {@link question_definition} subclass.
f7970e3c 261 * @param int $questionid the id of the question to load.
9c197f44
TH
262 * @param bool $allowshuffle if false, then any shuffle option on the selected
263 * quetsion is disabled.
d1b7e03d
TH
264 * @return question_definition loaded from the database.
265 */
a31689a4 266 public static function load_question($questionid, $allowshuffle = true) {
c76145d3 267
d1b7e03d 268 if (self::$testmode) {
8e93e515 269 // Evil, test code in production, but no way round it.
d1b7e03d
TH
270 return self::return_test_question_data($questionid);
271 }
272
a560d636
TH
273 $questiondata = self::load_question_data($questionid);
274
a31689a4
TH
275 if (!$allowshuffle) {
276 $questiondata->options->shuffleanswers = false;
277 }
d1b7e03d
TH
278 return self::make_question($questiondata);
279 }
280
281 /**
282 * Convert the question information loaded with {@link get_question_options()}
283 * to a question_definintion object.
284 * @param object $questiondata raw data loaded from the database.
285 * @return question_definition loaded from the database.
286 */
287 public static function make_question($questiondata) {
288 return self::get_qtype($questiondata->qtype, false)->make_question($questiondata, false);
289 }
290
291 /**
292 * @return question_finder a question finder.
293 */
294 public static function get_finder() {
a560d636 295 return question_finder::get_instance();
d1b7e03d
TH
296 }
297
298 /**
299 * Only to be called from unit tests. Allows {@link load_test_data()} to be used.
300 */
301 public static function start_unit_test() {
302 self::$testmode = true;
303 }
304
305 /**
306 * Only to be called from unit tests. Allows {@link load_test_data()} to be used.
307 */
308 public static function end_unit_test() {
309 self::$testmode = false;
310 self::$testdata = array();
311 }
312
313 private static function return_test_question_data($questionid) {
314 if (!isset(self::$testdata[$questionid])) {
88f0eb15 315 throw new coding_exception('question_bank::return_test_data(' . $questionid .
d1b7e03d
TH
316 ') called, but no matching question has been loaded by load_test_data.');
317 }
318 return self::$testdata[$questionid];
319 }
320
321 /**
322 * To be used for unit testing only. Will throw an exception if
323 * {@link start_unit_test()} has not been called first.
324 * @param object $questiondata a question data object to put in the test data store.
325 */
326 public static function load_test_question_data(question_definition $question) {
327 if (!self::$testmode) {
9c197f44
TH
328 throw new coding_exception('question_bank::load_test_data called when ' .
329 'not in test mode.');
d1b7e03d
TH
330 }
331 self::$testdata[$question->id] = $question;
332 }
af2f98ee 333
072db71c 334 protected static function ensure_fraction_options_initialised() {
af2f98ee
TH
335 if (!is_null(self::$fractionoptions)) {
336 return;
337 }
338
339 // define basic array of grades. This list comprises all fractions of the form:
340 // a. p/q for q <= 6, 0 <= p <= q
341 // b. p/10 for 0 <= p <= 10
342 // c. 1/q for 1 <= q <= 10
343 // d. 1/20
344 $rawfractions = array(
345 0.9000000,
346 0.8333333,
347 0.8000000,
348 0.7500000,
349 0.7000000,
350 0.6666667,
351 0.6000000,
352 0.5000000,
353 0.4000000,
354 0.3333333,
355 0.3000000,
356 0.2500000,
357 0.2000000,
358 0.1666667,
359 0.1428571,
360 0.1250000,
361 0.1111111,
362 0.1000000,
363 0.0500000,
364 );
365
366 // Put the None option at the top.
367 self::$fractionoptions = array(
368 '0.0' => get_string('none'),
369 '1.0' => '100%',
370 );
371 self::$fractionoptionsfull = array(
372 '0.0' => get_string('none'),
373 '1.0' => '100%',
374 );
375
376 // The the positive grades in descending order.
377 foreach ($rawfractions as $fraction) {
0a5aa9c6 378 $percentage = format_float(100 * $fraction, 5, true, true) . '%';
f4fe3968
TH
379 self::$fractionoptions["{$fraction}"] = $percentage;
380 self::$fractionoptionsfull["{$fraction}"] = $percentage;
af2f98ee
TH
381 }
382
383 // The the negative grades in descending order.
384 foreach (array_reverse($rawfractions) as $fraction) {
0a5aa9c6
TH
385 self::$fractionoptionsfull['' . (-$fraction)] =
386 format_float(-100 * $fraction, 5, true, true) . '%';
af2f98ee
TH
387 }
388
389 self::$fractionoptionsfull['-1.0'] = '-100%';
390 }
391
392 /**
393 * @return array string => string The standard set of grade options (fractions)
394 * to use when editing questions, in the range 0 to 1 inclusive. Array keys
395 * are string becuase: a) we want grades to exactly 7 d.p., and b. you can't
396 * have float array keys in PHP.
397 * Initialised by {@link ensure_grade_options_initialised()}.
398 */
399 public static function fraction_options() {
400 self::ensure_fraction_options_initialised();
401 return self::$fractionoptions;
402 }
403
404 /** @return array string => string The full standard set of (fractions) -1 to 1 inclusive. */
405 public static function fraction_options_full() {
406 self::ensure_fraction_options_initialised();
407 return self::$fractionoptionsfull;
408 }
2ec325c2 409
b6c53841
JL
410 /**
411 * Return a list of the different question types present in the given categories.
412 *
413 * @param array $categories a list of category ids
414 * @return array the list of question types in the categories
415 * @since Moodle 3.1
416 */
417 public static function get_all_question_types_in_categories($categories) {
418 global $DB;
419
420 list($categorysql, $params) = $DB->get_in_or_equal($categories);
421 $sql = "SELECT DISTINCT q.qtype
422 FROM {question} q
423 WHERE q.category $categorysql";
424
425 $qtypes = $DB->get_fieldset_sql($sql, $params);
426 return $qtypes;
427 }
d1b7e03d
TH
428}
429
f7970e3c
TH
430
431/**
432 * Class for loading questions according to various criteria.
433 *
434 * @copyright 2009 The Open University
435 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
436 */
a560d636
TH
437class question_finder implements cache_data_source {
438 /** @var question_finder the singleton instance of this class. */
439 protected static $questionfinder = null;
440
a560d636
TH
441 /**
442 * @return question_finder a question finder.
443 */
444 public static function get_instance() {
445 if (is_null(self::$questionfinder)) {
446 self::$questionfinder = new question_finder();
447 }
448 return self::$questionfinder;
449 }
450
451 /* See cache_data_source::get_instance_for_cache. */
452 public static function get_instance_for_cache(cache_definition $definition) {
453 return self::get_instance();
454 }
455
456 /**
457 * @return get the question definition cache we are using.
458 */
459 protected function get_data_cache() {
c0fa7b0d
460 // Do not double cache here because it may break cache resetting.
461 return cache::make('core', 'questiondata');
a560d636
TH
462 }
463
464 /**
465 * This method needs to be called whenever a question is edited.
466 */
467 public function uncache_question($questionid) {
468 $this->get_data_cache()->delete($questionid);
469 }
470
471 /**
472 * Load a question definition data from the database. The data will be
473 * returned as a plain stdClass object.
474 * @param int $questionid the id of the question to load.
475 * @return object question definition loaded from the database.
476 */
477 public function load_question_data($questionid) {
478 return $this->get_data_cache()->get($questionid);
479 }
480
d1b7e03d 481 /**
bb93fc24 482 * Get the ids of all the questions in a list of categories.
2daffca5 483 * @param array $categoryids either a categoryid, or a comma-separated list
d1b7e03d 484 * category ids, or an array of them.
2daffca5
TH
485 * @param string $extraconditions extra conditions to AND with the rest of
486 * the where clause. Must use named parameters.
487 * @param array $extraparams any parameters used by $extraconditions.
d1b7e03d
TH
488 * @return array questionid => questionid.
489 */
9c197f44
TH
490 public function get_questions_from_categories($categoryids, $extraconditions,
491 $extraparams = array()) {
f9b0500f
TH
492 global $DB;
493
a2ac2349 494 list($qcsql, $qcparams) = $DB->get_in_or_equal($categoryids, SQL_PARAMS_NAMED, 'qc');
d1b7e03d
TH
495
496 if ($extraconditions) {
497 $extraconditions = ' AND (' . $extraconditions . ')';
498 }
2daffca5
TH
499
500 return $DB->get_records_select_menu('question',
f4fe3968 501 "category {$qcsql}
d1b7e03d
TH
502 AND parent = 0
503 AND hidden = 0
f4fe3968 504 {$extraconditions}", $qcparams + $extraparams, '', 'id,id AS id2');
d1b7e03d 505 }
a560d636 506
bb93fc24
TH
507 /**
508 * Get the ids of all the questions in a list of categories, with the number
509 * of times they have already been used in a given set of usages.
510 *
511 * The result array is returned in order of increasing (count previous uses).
512 *
513 * @param array $categoryids an array question_category ids.
514 * @param qubaid_condition $qubaids which question_usages to count previous uses from.
515 * @param string $extraconditions extra conditions to AND with the rest of
516 * the where clause. Must use named parameters.
517 * @param array $extraparams any parameters used by $extraconditions.
518 * @return array questionid => count of number of previous uses.
519 */
520 public function get_questions_from_categories_with_usage_counts($categoryids,
521 qubaid_condition $qubaids, $extraconditions = '', $extraparams = array()) {
2adefc21
SR
522 return $this->get_questions_from_categories_and_tags_with_usage_counts(
523 $categoryids, $qubaids, $extraconditions, $extraparams);
524 }
525
526 /**
527 * Get the ids of all the questions in a list of categories that have ALL the provided tags,
528 * with the number of times they have already been used in a given set of usages.
529 *
530 * The result array is returned in order of increasing (count previous uses).
531 *
532 * @param array $categoryids an array of question_category ids.
533 * @param qubaid_condition $qubaids which question_usages to count previous uses from.
534 * @param string $extraconditions extra conditions to AND with the rest of
535 * the where clause. Must use named parameters.
536 * @param array $extraparams any parameters used by $extraconditions.
537 * @param array $tagids an array of tag ids
538 * @return array questionid => count of number of previous uses.
539 */
540 public function get_questions_from_categories_and_tags_with_usage_counts($categoryids,
541 qubaid_condition $qubaids, $extraconditions = '', $extraparams = array(), $tagids = array()) {
bb93fc24
TH
542 global $DB;
543
544 list($qcsql, $qcparams) = $DB->get_in_or_equal($categoryids, SQL_PARAMS_NAMED, 'qc');
545
2adefc21
SR
546 $select = "q.id, (SELECT COUNT(1)
547 FROM " . $qubaids->from_question_attempts('qa') . "
548 WHERE qa.questionid = q.id AND " . $qubaids->where() . "
549 ) AS previous_attempts";
550 $from = "{question} q";
551 $where = "q.category {$qcsql}
552 AND q.parent = 0
553 AND q.hidden = 0";
554 $params = $qcparams;
555
556 if (!empty($tagids)) {
557 // We treat each additional tag as an AND condition rather than
558 // an OR condition.
559 //
560 // For example, if the user filters by the tags "foo" and "bar" then
561 // we reduce the question list to questions that are tagged with both
562 // "foo" AND "bar". Any question that does not have ALL of the specified
563 // tags will be omitted.
564 list($tagsql, $tagparams) = $DB->get_in_or_equal($tagids, SQL_PARAMS_NAMED, 'ti');
565 $tagparams['tagcount'] = count($tagids);
566 $tagparams['questionitemtype'] = 'question';
567 $tagparams['questioncomponent'] = 'core_question';
568 $where .= " AND q.id IN (SELECT ti.itemid
569 FROM {tag_instance} ti
570 WHERE ti.itemtype = :questionitemtype
571 AND ti.component = :questioncomponent
572 AND ti.tagid {$tagsql}
573 GROUP BY ti.itemid
574 HAVING COUNT(itemid) = :tagcount)";
575 $params += $tagparams;
576 }
577
bb93fc24
TH
578 if ($extraconditions) {
579 $extraconditions = ' AND (' . $extraconditions . ')';
580 }
581
2adefc21
SR
582 return $DB->get_records_sql_menu("SELECT $select
583 FROM $from
584 WHERE $where $extraconditions
585 ORDER BY previous_attempts",
586 $qubaids->from_where_params() + $params + $extraparams);
bb93fc24
TH
587 }
588
a560d636
TH
589 /* See cache_data_source::load_for_cache. */
590 public function load_for_cache($questionid) {
591 global $DB;
592 $questiondata = $DB->get_record_sql('
593 SELECT q.*, qc.contextid
594 FROM {question} q
595 JOIN {question_categories} qc ON q.category = qc.id
596 WHERE q.id = :id', array('id' => $questionid), MUST_EXIST);
597 get_question_options($questiondata);
598 return $questiondata;
599 }
600
601 /* See cache_data_source::load_many_for_cache. */
602 public function load_many_for_cache(array $questionids) {
603 global $DB;
604 list($idcondition, $params) = $DB->get_in_or_equal($questionids);
605 $questiondata = $DB->get_records_sql('
606 SELECT q.*, qc.contextid
607 FROM {question} q
608 JOIN {question_categories} qc ON q.category = qc.id
609 WHERE q.id ' . $idcondition, $params);
610
611 foreach ($questionids as $id) {
471c39b3 612 if (!array_key_exists($id, $questiondata)) {
a560d636
TH
613 throw new dml_missing_record_exception('question', '', array('id' => $id));
614 }
615 get_question_options($questiondata[$id]);
616 }
617 return $questiondata;
618 }
d1b7e03d 619}