Merge branch 'MDL-62899-search-icons-master' of https://github.com/dmitriim/moodle
[moodle.git] / search / classes / base.php
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/>.
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  */
25 namespace core_search;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Base search implementation.
31  *
32  * Components and plugins interested in filling the search engine with data should extend this class (or any extension of this
33  * class).
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  */
39 abstract class base {
41     /**
42      * The area name as defined in the class name.
43      *
44      * @var string
45      */
46     protected $areaname = null;
48     /**
49      * The component frankenstyle name.
50      *
51      * @var string
52      */
53     protected $componentname = null;
55     /**
56      * The component type (core or the plugin type).
57      *
58      * @var string
59      */
60     protected $componenttype = null;
62     /**
63      * The context levels the search implementation is working on.
64      *
65      * @var array
66      */
67     protected static $levels = [CONTEXT_SYSTEM];
69     /**
70      * Constructor.
71      *
72      * @throws \coding_exception
73      * @return void
74      */
75     public final function __construct() {
77         $classname = get_class($this);
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         }
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     }
92     /**
93      * Returns context levels property.
94      *
95      * @return int
96      */
97     public static function get_levels() {
98         return static::$levels;
99     }
101     /**
102      * Returns the area id.
103      *
104      * @return string
105      */
106     public function get_area_id() {
107         return $this->areaid;
108     }
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     }
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     }
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) {
140         $component = $this->componentname;
142         // Core subsystem strings go to lang/XX/search.php.
143         if ($this->componenttype === 'core') {
144             $component = 'search';
145         }
146         return get_string('search:' . $this->areaname, $component, null, $lazyload);
147     }
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      *
154      * @access private
155      * @return string Config var path including the plugin (or component) and the varname
156      */
157     public function get_config_var_name() {
159         if ($this->componenttype === 'core') {
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]);
163         }
165         // Plugins config in the plugin scope.
166         return array($this->componentname, 'search_' . $this->areaname);
167     }
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();
177         $config = [];
178         $settingnames = array('_enabled', '_indexingstart', '_indexingend', '_lastindexrun',
179                 '_docsignored', '_docsprocessed', '_recordsprocessed', '_partial');
180         foreach ($settingnames as $name) {
181             $config[$varname . $name] = get_config($componentname, $varname . $name);
182         }
184         // Search areas are enabled by default.
185         if ($config[$varname . '_enabled'] === false) {
186             $config[$varname . '_enabled'] = 1;
187         }
188         return $config;
189     }
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();
199         $value = get_config($componentname, $varname . '_enabled');
201         // Search areas are enabled by default.
202         if ($value === false) {
203             $value = 1;
204         }
205         return (bool)$value;
206     }
208     public function set_enabled($isenabled) {
209         list($componentname, $varname) = $this->get_config_var_name();
210         return set_config($varname . '_enabled', $isenabled, $componentname);
211     }
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     }
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     }
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      *
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      *
253      * @param int $modifiedfrom
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     }
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      *
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      *
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
300      */
301     public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
302         return false;
303     }
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     }
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
328      * input data to plain text: {@link content_to_text}
329      *
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      *
334      * The lastindexedtime value is not set if indexing a specific context rather than the whole
335      * system.
336      *
337      * @param \stdClass $record A record containing, at least, the indexed document id and a modified timestamp
338      * @param array     $options Options for document creation
339      * @return \core_search\document
340      */
341     abstract public function get_document($record, $options = array());
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) {
353         return $doc->get('title');
354     }
356     /**
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();
367         return $fileareas;
368     }
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.
380      *
381      * @param document $document The current document
382      * @return void
383      */
384     public function attach_files($document) {
385         $fileareas = $this->get_search_fileareas();
386         $contextid = $document->get('contextid');
387         $component = $this->get_component_name();
388         $itemid = $document->get('itemid');
390         foreach ($fileareas as $filearea) {
391             $fs = get_file_storage();
392             $files = $fs->get_area_files($contextid, $component, $filearea, $itemid, '', false);
394             foreach ($files as $file) {
395                 $document->add_stored_file($file);
396             }
397         }
399     }
401     /**
402      * Can the current user see the document.
403      *
404      * @param int $id The internal search area entity id.
405      * @return int manager:ACCESS_xx constant
406      */
407     abstract public function check_access($id);
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);
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);
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;
450         if (!$context) {
451             return ['', []];
452         }
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         }
471         $params = [];
472         switch ($context->contextlevel) {
473             case CONTEXT_SYSTEM:
474                 $sql = '';
475                 break;
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;
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;
499             case CONTEXT_BLOCK:
500             case CONTEXT_MODULE:
501             case CONTEXT_USER:
502                 // Context cannot contain any courses.
503                 return [null, null];
505             default:
506                 throw new \coding_exception('Unexpected contextlevel: ' . $context->contextlevel);
507         }
509         return [$sql, $params];
510     }
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     }
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     }