Merge branch 'MDL-62899-search-icons-master' of https://github.com/dmitriim/moodle
[moodle.git] / search / classes / base.php
CommitLineData
db48207e
DM
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 * Search base class to be extended by search areas.
19 *
20 * @package core_search
21 * @copyright 2015 David Monllao {@link http://www.davidmonllao.com}
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
8fa1810c 25namespace core_search;
db48207e
DM
26
27defined('MOODLE_INTERNAL') || die();
28
29/**
30 * Base search implementation.
31 *
6a4c2146
DM
32 * Components and plugins interested in filling the search engine with data should extend this class (or any extension of this
33 * class).
db48207e
DM
34 *
35 * @package core_search
36 * @copyright 2015 David Monllao {@link http://www.davidmonllao.com}
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 */
39abstract class base {
40
41 /**
42 * The area name as defined in the class name.
43 *
44 * @var string
45 */
46 protected $areaname = null;
47
48 /**
49 * The component frankenstyle name.
50 *
51 * @var string
52 */
53 protected $componentname = null;
54
55 /**
56 * The component type (core or the plugin type).
57 *
58 * @var string
59 */
60 protected $componenttype = null;
61
62 /**
63 * The context levels the search implementation is working on.
64 *
65 * @var array
66 */
67 protected static $levels = [CONTEXT_SYSTEM];
68
69 /**
70 * Constructor.
71 *
72 * @throws \coding_exception
73 * @return void
74 */
75 public final function __construct() {
76
77 $classname = get_class($this);
78
79 // Detect possible issues when defining the class.
80 if (strpos($classname, '\search') === false) {
81 throw new \coding_exception('Search area classes should be located in \PLUGINTYPE_PLUGINNAME\search\AREANAME.');
82 } else if (strpos($classname, '_') === false) {
83 throw new \coding_exception($classname . ' class namespace level 1 should be its component frankenstyle name');
84 }
85
86 $this->areaname = substr(strrchr($classname, '\\'), 1);
87 $this->componentname = substr($classname, 0, strpos($classname, '\\'));
88 $this->areaid = \core_search\manager::generate_areaid($this->componentname, $this->areaname);
89 $this->componenttype = substr($this->componentname, 0, strpos($this->componentname, '_'));
90 }
91
92 /**
93 * Returns context levels property.
94 *
95 * @return int
96 */
97 public static function get_levels() {
98 return static::$levels;
99 }
100
101 /**
102 * Returns the area id.
103 *
104 * @return string
105 */
106 public function get_area_id() {
107 return $this->areaid;
108 }
109
110 /**
111 * Returns the moodle component name.
112 *
113 * It might be the plugin name (whole frankenstyle name) or the core subsystem name.
114 *
115 * @return string
116 */
117 public function get_component_name() {
118 return $this->componentname;
119 }
120
121 /**
122 * Returns the component type.
123 *
124 * It might be a plugintype or 'core' for core subsystems.
125 *
126 * @return string
127 */
128 public function get_component_type() {
129 return $this->componenttype;
130 }
131
132 /**
133 * Returns the area visible name.
134 *
135 * @param bool $lazyload Usually false, unless when in admin settings.
136 * @return string
137 */
138 public function get_visible_name($lazyload = false) {
1f69cd81
DM
139
140 $component = $this->componentname;
141
142 // Core subsystem strings go to lang/XX/search.php.
e314b354 143 if ($this->componenttype === 'core') {
1f69cd81
DM
144 $component = 'search';
145 }
146 return get_string('search:' . $this->areaname, $component, null, $lazyload);
db48207e
DM
147 }
148
149 /**
150 * Returns the config var name.
151 *
152 * It depends on whether it is a moodle subsystem or a plugin as plugin-related config should remain in their own scope.
153 *
69d66020 154 * @access private
db48207e
DM
155 * @return string Config var path including the plugin (or component) and the varname
156 */
157 public function get_config_var_name() {
158
159 if ($this->componenttype === 'core') {
1f69cd81
DM
160 // Core subsystems config in core_search and setting name using only [a-zA-Z0-9_]+.
161 $parts = \core_search\manager::extract_areaid_parts($this->areaid);
162 return array('core_search', $parts[0] . '_' . $parts[1]);
db48207e
DM
163 }
164
165 // Plugins config in the plugin scope.
166 return array($this->componentname, 'search_' . $this->areaname);
167 }
168
69d66020
DM
169 /**
170 * Returns all the search area configuration.
171 *
172 * @return array
173 */
174 public function get_config() {
175 list($componentname, $varname) = $this->get_config_var_name();
176
177 $config = [];
67d64795 178 $settingnames = array('_enabled', '_indexingstart', '_indexingend', '_lastindexrun',
179 '_docsignored', '_docsprocessed', '_recordsprocessed', '_partial');
69d66020
DM
180 foreach ($settingnames as $name) {
181 $config[$varname . $name] = get_config($componentname, $varname . $name);
182 }
183
6a4c2146
DM
184 // Search areas are enabled by default.
185 if ($config[$varname . '_enabled'] === false) {
186 $config[$varname . '_enabled'] = 1;
187 }
69d66020
DM
188 return $config;
189 }
190
db48207e
DM
191 /**
192 * Is the search component enabled by the system administrator?
193 *
194 * @return bool
195 */
196 public function is_enabled() {
197 list($componentname, $varname) = $this->get_config_var_name();
6a4c2146
DM
198
199 $value = get_config($componentname, $varname . '_enabled');
200
201 // Search areas are enabled by default.
202 if ($value === false) {
203 $value = 1;
204 }
205 return (bool)$value;
db48207e
DM
206 }
207
c3a95c28
DP
208 public function set_enabled($isenabled) {
209 list($componentname, $varname) = $this->get_config_var_name();
210 return set_config($varname . '_enabled', $isenabled, $componentname);
211 }
212
67d64795 213 /**
214 * Gets the length of time spent indexing this area (the last time it was indexed).
215 *
216 * @return int|bool Time in seconds spent indexing this area last time, false if never indexed
217 */
218 public function get_last_indexing_duration() {
219 list($componentname, $varname) = $this->get_config_var_name();
220 $start = get_config($componentname, $varname . '_indexingstart');
221 $end = get_config($componentname, $varname . '_indexingend');
222 if ($start && $end) {
223 return $end - $start;
224 } else {
225 return false;
226 }
227 }
228
091973db
EM
229 /**
230 * Returns true if this area uses file indexing.
231 *
232 * @return bool
233 */
234 public function uses_file_indexing() {
235 return false;
236 }
237
db48207e
DM
238 /**
239 * Returns a recordset ordered by modification date ASC.
240 *
241 * Each record can include any data self::get_document might need but it must:
242 * - Include an 'id' field: Unique identifier (in this area's scope) of a document to index in the search engine
243 * If the indexed content field can contain embedded files, the 'id' value should match the filearea itemid.
244 * - Only return data modified since $modifiedfrom, including $modifiedform to prevent
245 * some records from not being indexed (e.g. your-timemodified-fieldname >= $modifiedfrom)
246 * - Order the returned data by time modified in ascending order, as \core_search::manager will need to store the modified time
247 * of the last indexed document.
248 *
427b7563 249 * Since Moodle 3.4, subclasses should instead implement get_document_recordset, which has
250 * an additional context parameter. This function continues to work for implementations which
251 * haven't been updated, or where the context parameter is not required.
252 *
db48207e 253 * @param int $modifiedfrom
427b7563 254 * @return \moodle_recordset
255 */
256 public function get_recordset_by_timestamp($modifiedfrom = 0) {
257 $result = $this->get_document_recordset($modifiedfrom);
258 if ($result === false) {
259 throw new \coding_exception(
260 'Search area must implement get_document_recordset or get_recordset_by_timestamp');
261 }
262 return $result;
263 }
264
265 /**
266 * Returns a recordset containing all items from this area, optionally within the given context,
267 * and including only items modifed from (>=) the specified time. The recordset must be ordered
268 * in ascending order of modified time.
269 *
270 * Each record can include any data self::get_document might need. It must include an 'id'
271 * field,a unique identifier (in this area's scope) of a document to index in the search engine.
272 * If the indexed content field can contain embedded files, the 'id' value should match the
273 * filearea itemid.
274 *
275 * The return value can be a recordset, null (if this area does not provide any results in the
276 * given context and there is no need to do a database query to find out), or false (if this
277 * facility is not currently supported by this search area).
278 *
279 * If this function returns false, then:
280 * - If indexing the entire system (no context restriction) the search indexer will try
281 * get_recordset_by_timestamp instead
282 * - If trying to index a context (e.g. when restoring a course), the search indexer will not
283 * index this area, so that restored content may not be indexed.
284 *
285 * The default implementation returns false, indicating that this facility is not supported and
286 * the older get_recordset_by_timestamp function should be used.
287 *
25564a78 288 * This function must accept all possible values for the $context parameter. For example, if
289 * you are implementing this function for the forum module, it should still operate correctly
290 * if called with the context for a glossary module, or for the HTML block. (In these cases
291 * where it will not return any data, it may return null.)
292 *
293 * The $context parameter can also be null or the system context; both of these indicate that
294 * all data, without context restriction, should be returned.
295 *
427b7563 296 * @param int $modifiedfrom Return only records modified after this date
297 * @param \context|null $context Context (null means no context restriction)
298 * @return \moodle_recordset|null|false Recordset / null if no results / false if not supported
299 * @since Moodle 3.4
db48207e 300 */
427b7563 301 public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
302 return false;
303 }
db48207e 304
65da6840 305 /**
306 * Checks if get_document_recordset is supported for this search area.
307 *
308 * For many uses you can simply call get_document_recordset and see if it returns false, but
309 * this function is useful when you don't want to actually call the function right away.
310 */
311 public function supports_get_document_recordset() {
312 // Easiest way to check this is simply to see if the class has overridden the default
313 // function.
314 $method = new \ReflectionMethod($this, 'get_document_recordset');
315 return $method->getDeclaringClass()->getName() !== self::class;
316 }
317
db48207e
DM
318 /**
319 * Returns the document related with the provided record.
320 *
321 * This method receives a record with the document id and other info returned by get_recordset_by_timestamp
322 * or get_recordset_by_contexts that might be useful here. The idea is to restrict database queries to
323 * minimum as this function will be called for each document to index. As an alternative, use cached data.
324 *
325 * Internally it should use \core_search\document to standarise the documents before sending them to the search engine.
326 *
327 * Search areas should send plain text to the search engine, use the following function to convert any user
69d66020 328 * input data to plain text: {@link content_to_text}
db48207e 329 *
091973db
EM
330 * Valid keys for the options array are:
331 * indexfiles => File indexing is enabled if true.
332 * lastindexedtime => The last time this area was indexed. 0 if never indexed.
333 *
4ba11aa9 334 * The lastindexedtime value is not set if indexing a specific context rather than the whole
335 * system.
336 *
db48207e 337 * @param \stdClass $record A record containing, at least, the indexed document id and a modified timestamp
091973db 338 * @param array $options Options for document creation
db48207e
DM
339 * @return \core_search\document
340 */
091973db
EM
341 abstract public function get_document($record, $options = array());
342
10505522
VD
343 /**
344 * Returns the document title to display.
345 *
346 * Allow to customize the document title string to display.
347 *
348 * @param \core_search\document $doc
349 * @return string Document title to display in the search results page
350 */
351 public function get_document_display_title(\core_search\document $doc) {
352
353 return $doc->get('title');
354 }
355
091973db 356 /**
4e921569
MP
357 * Return the context info required to index files for
358 * this search area.
359 *
360 * Should be onerridden by each search area.
361 *
362 * @return array
363 */
364 public function get_search_fileareas() {
365 $fileareas = array();
366
367 return $fileareas;
368 }
369
370 /**
371 * Files related to the current document are attached,
372 * to the document object ready for indexing by
373 * Global Search.
374 *
375 * The default implementation retrieves all files for
376 * the file areas returned by get_search_fileareas().
377 * If you need to filter files to specific items per
378 * file area, you will need to override this method
379 * and explicitly provide the items.
091973db
EM
380 *
381 * @param document $document The current document
382 * @return void
383 */
384 public function attach_files($document) {
4e921569
MP
385 $fileareas = $this->get_search_fileareas();
386 $contextid = $document->get('contextid');
387 $component = $this->get_component_name();
388 $itemid = $document->get('itemid');
389
390 foreach ($fileareas as $filearea) {
391 $fs = get_file_storage();
392 $files = $fs->get_area_files($contextid, $component, $filearea, $itemid, '', false);
393
394 foreach ($files as $file) {
395 $document->add_stored_file($file);
396 }
397 }
398
091973db 399 }
db48207e
DM
400
401 /**
402 * Can the current user see the document.
403 *
404 * @param int $id The internal search area entity id.
a96faa49 405 * @return int manager:ACCESS_xx constant
db48207e
DM
406 */
407 abstract public function check_access($id);
408
409 /**
410 * Returns a url to the document, it might match self::get_context_url().
411 *
412 * @param \core_search\document $doc
413 * @return \moodle_url
414 */
415 abstract public function get_doc_url(\core_search\document $doc);
416
417 /**
418 * Returns a url to the document context.
419 *
420 * @param \core_search\document $doc
421 * @return \moodle_url
422 */
423 abstract public function get_context_url(\core_search\document $doc);
427b7563 424
425 /**
426 * Helper function that gets SQL useful for restricting a search query given a passed-in
427 * context, for data stored at course level.
428 *
429 * The SQL returned will be zero or more JOIN statements, surrounded by whitespace, which act
430 * as restrictions on the query based on the rows in a module table.
431 *
432 * You can pass in a null or system context, which will both return an empty string and no
433 * params.
434 *
435 * Returns an array with two nulls if there can be no results for a course within this context.
436 *
437 * If named parameters are used, these will be named gclcrs0, gclcrs1, etc. The table aliases
438 * used in SQL also all begin with gclcrs, to avoid conflicts.
439 *
440 * @param \context|null $context Context to restrict the query
441 * @param string $coursetable Name of alias for course table e.g. 'c'
442 * @param int $paramtype Type of SQL parameters to use (default question mark)
443 * @return array Array with SQL and parameters; both null if no need to query
444 * @throws \coding_exception If called with invalid params
445 */
446 protected function get_course_level_context_restriction_sql(\context $context = null,
447 $coursetable, $paramtype = SQL_PARAMS_QM) {
448 global $DB;
449
450 if (!$context) {
451 return ['', []];
452 }
453
454 switch ($paramtype) {
455 case SQL_PARAMS_QM:
456 $param1 = '?';
457 $param2 = '?';
458 $key1 = 0;
459 $key2 = 1;
460 break;
461 case SQL_PARAMS_NAMED:
462 $param1 = ':gclcrs0';
463 $param2 = ':gclcrs1';
464 $key1 = 'gclcrs0';
465 $key2 = 'gclcrs1';
466 break;
467 default:
468 throw new \coding_exception('Unexpected $paramtype: ' . $paramtype);
469 }
470
471 $params = [];
472 switch ($context->contextlevel) {
473 case CONTEXT_SYSTEM:
474 $sql = '';
475 break;
476
477 case CONTEXT_COURSECAT:
478 // Find all courses within the specified category or any sub-category.
479 $pathmatch = $DB->sql_like('gclcrscc2.path',
480 $DB->sql_concat('gclcrscc1.path', $param2));
481 $sql = " JOIN {course_categories} gclcrscc1 ON gclcrscc1.id = $param1
482 JOIN {course_categories} gclcrscc2 ON gclcrscc2.id = $coursetable.category
483 AND (gclcrscc2.id = gclcrscc1.id OR $pathmatch) ";
484 $params[$key1] = $context->instanceid;
485 // Note: This param is a bit annoying as it obviously never changes, but sql_like
486 // throws a debug warning if you pass it anything with quotes in, so it has to be
487 // a bound parameter.
488 $params[$key2] = '/%';
489 break;
490
491 case CONTEXT_COURSE:
492 // We just join again against the same course entry and confirm that it has the
493 // same id as the context.
494 $sql = " JOIN {course} gclcrsc ON gclcrsc.id = $coursetable.id
495 AND gclcrsc.id = $param1";
496 $params[$key1] = $context->instanceid;
497 break;
498
499 case CONTEXT_BLOCK:
500 case CONTEXT_MODULE:
501 case CONTEXT_USER:
502 // Context cannot contain any courses.
503 return [null, null];
504
505 default:
506 throw new \coding_exception('Unexpected contextlevel: ' . $context->contextlevel);
507 }
508
509 return [$sql, $params];
510 }
25564a78 511
512 /**
513 * Gets a list of all contexts to reindex when reindexing this search area. The list should be
514 * returned in an order that is likely to be suitable when reindexing, for example with newer
515 * contexts first.
516 *
517 * The default implementation simply returns the system context, which will result in
518 * reindexing everything in normal date order (oldest first).
519 *
520 * @return \Iterator Iterator of contexts to reindex
521 */
522 public function get_contexts_to_reindex() {
523 return new \ArrayIterator([\context_system::instance()]);
524 }
66f145ef
DM
525
526 /**
527 * Returns an icon instance for the document.
528 *
529 * @param \core_search\document $doc
530 * @return \core_search\document_icon
531 */
532 public function get_doc_icon(document $doc) : document_icon {
533 return new document_icon('i/empty');
534 }
db48207e 535}