MDL-68334 user: Display name in footer as elsewhere.
[moodle.git] / search / classes / manager.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 subsystem manager.
19  *
20  * @package   core_search
21  * @copyright Prateek Sachan {@link http://prateeksachan.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 require_once($CFG->dirroot . '/lib/accesslib.php');
31 /**
32  * Search subsystem manager.
33  *
34  * @package   core_search
35  * @copyright Prateek Sachan {@link http://prateeksachan.com}
36  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  */
38 class manager {
40     /**
41      * @var int Text contents.
42      */
43     const TYPE_TEXT = 1;
45     /**
46      * @var int File contents.
47      */
48     const TYPE_FILE = 2;
50     /**
51      * @var int User can not access the document.
52      */
53     const ACCESS_DENIED = 0;
55     /**
56      * @var int User can access the document.
57      */
58     const ACCESS_GRANTED = 1;
60     /**
61      * @var int The document was deleted.
62      */
63     const ACCESS_DELETED = 2;
65     /**
66      * @var int Maximum number of results that will be retrieved from the search engine.
67      */
68     const MAX_RESULTS = 100;
70     /**
71      * @var int Number of results per page.
72      */
73     const DISPLAY_RESULTS_PER_PAGE = 10;
75     /**
76      * @var int The id to be placed in owneruserid when there is no owner.
77      */
78     const NO_OWNER_ID = 0;
80     /**
81      * @var float If initial query takes longer than N seconds, this will be shown in cron log.
82      */
83     const DISPLAY_LONG_QUERY_TIME = 5.0;
85     /**
86      * @var float Adds indexing progress within one search area to cron log every N seconds.
87      */
88     const DISPLAY_INDEXING_PROGRESS_EVERY = 30.0;
90     /**
91      * @var int Context indexing: normal priority.
92      */
93     const INDEX_PRIORITY_NORMAL = 100;
95     /**
96      * @var int Context indexing: low priority for reindexing.
97      */
98     const INDEX_PRIORITY_REINDEXING = 50;
100     /**
101      * @var string Core search area category for all results.
102      */
103     const SEARCH_AREA_CATEGORY_ALL = 'core-all';
105     /**
106      * @var string Core search area category for course content.
107      */
108     const SEARCH_AREA_CATEGORY_COURSE_CONTENT = 'core-course-content';
110     /**
111      * @var string Core search area category for courses.
112      */
113     const SEARCH_AREA_CATEGORY_COURSES = 'core-courses';
115     /**
116      * @var string Core search area category for users.
117      */
118     const SEARCH_AREA_CATEGORY_USERS = 'core-users';
120     /**
121      * @var string Core search area category for results that do not fit into any of existing categories.
122      */
123     const SEARCH_AREA_CATEGORY_OTHER = 'core-other';
125     /**
126      * @var \core_search\base[] Enabled search areas.
127      */
128     protected static $enabledsearchareas = null;
130     /**
131      * @var \core_search\base[] All system search areas.
132      */
133     protected static $allsearchareas = null;
135     /**
136      * @var \core_search\area_category[] A list of search area categories.
137      */
138     protected static $searchareacategories = null;
140     /**
141      * @var \core_search\manager
142      */
143     protected static $instance = null;
145     /**
146      * @var array IDs (as keys) of course deletions in progress in this requuest, if any.
147      */
148     protected static $coursedeleting = [];
150     /**
151      * @var \core_search\engine
152      */
153     protected $engine = null;
155     /**
156      * Note: This should be removed once possible (see MDL-60644).
157      *
158      * @var float Fake current time for use in PHPunit tests
159      */
160     protected static $phpunitfaketime = 0;
162     /**
163      * @var int Result count when used with mock results for Behat tests.
164      */
165     protected $behatresultcount = 0;
167     /**
168      * Constructor, use \core_search\manager::instance instead to get a class instance.
169      *
170      * @param \core_search\base The search engine to use
171      */
172     public function __construct($engine) {
173         $this->engine = $engine;
174     }
176     /**
177      * @var int Record time of each successful schema check, but not more than once per 10 minutes.
178      */
179     const SCHEMA_CHECK_TRACKING_DELAY = 10 * 60;
181     /**
182      * @var int Require a new schema check at least every 4 hours.
183      */
184     const SCHEMA_CHECK_REQUIRED_EVERY = 4 * 3600;
186     /**
187      * Returns an initialised \core_search instance.
188      *
189      * While constructing the instance, checks on the search schema may be carried out. The $fast
190      * parameter provides a way to skip those checks on pages which are used frequently. It has
191      * no effect if an instance has already been constructed in this request.
192      *
193      * @see \core_search\engine::is_installed
194      * @see \core_search\engine::is_server_ready
195      * @param bool $fast Set to true when calling on a page that requires high performance
196      * @throws \core_search\engine_exception
197      * @return \core_search\manager
198      */
199     public static function instance($fast = false) {
200         global $CFG;
202         // One per request, this should be purged during testing.
203         if (static::$instance !== null) {
204             return static::$instance;
205         }
207         if (empty($CFG->searchengine)) {
208             throw new \core_search\engine_exception('enginenotselected', 'search');
209         }
211         if (!$engine = static::search_engine_instance()) {
212             throw new \core_search\engine_exception('enginenotfound', 'search', '', $CFG->searchengine);
213         }
215         // Get time now and at last schema check.
216         $now = (int)self::get_current_time();
217         $lastschemacheck = get_config($engine->get_plugin_name(), 'lastschemacheck');
219         // On pages where performance matters, tell the engine to skip schema checks.
220         $skipcheck = false;
221         if ($fast && $now < $lastschemacheck + self::SCHEMA_CHECK_REQUIRED_EVERY) {
222             $skipcheck = true;
223             $engine->skip_schema_check();
224         }
226         if (!$engine->is_installed()) {
227             throw new \core_search\engine_exception('enginenotinstalled', 'search', '', $CFG->searchengine);
228         }
230         $serverstatus = $engine->is_server_ready();
231         if ($serverstatus !== true) {
232             // Skip this error in Behat when faking seach results.
233             if (!defined('BEHAT_SITE_RUNNING') || !get_config('core_search', 'behat_fakeresult')) {
234                 // Clear the record of successful schema checks since it might have failed.
235                 unset_config('lastschemacheck', $engine->get_plugin_name());
236                 // Error message with no details as this is an exception that any user may find if the server crashes.
237                 throw new \core_search\engine_exception('engineserverstatus', 'search');
238             }
239         }
241         // If we did a successful schema check, record this, but not more than once per 10 minutes
242         // (to avoid updating the config db table/cache too often in case it gets called frequently).
243         if (!$skipcheck && $now >= $lastschemacheck + self::SCHEMA_CHECK_TRACKING_DELAY) {
244             set_config('lastschemacheck', $now, $engine->get_plugin_name());
245         }
247         static::$instance = new \core_search\manager($engine);
248         return static::$instance;
249     }
251     /**
252      * Returns whether global search is enabled or not.
253      *
254      * @return bool
255      */
256     public static function is_global_search_enabled() {
257         global $CFG;
258         return !empty($CFG->enableglobalsearch);
259     }
261     /**
262      * Returns the search URL for course search
263      *
264      * @return moodle_url
265      */
266     public static function get_course_search_url() {
267         if (self::is_global_search_enabled()) {
268             $searchurl = '/search/index.php';
269         } else {
270             $searchurl = '/course/search.php';
271         }
273         return new \moodle_url($searchurl);
274     }
276     /**
277      * Returns whether indexing is enabled or not (you can enable indexing even when search is not
278      * enabled at the moment, so as to have it ready for students).
279      *
280      * @return bool True if indexing is enabled.
281      */
282     public static function is_indexing_enabled() {
283         global $CFG;
284         return !empty($CFG->enableglobalsearch) || !empty($CFG->searchindexwhendisabled);
285     }
287     /**
288      * Returns an instance of the search engine.
289      *
290      * @return \core_search\engine
291      */
292     public static function search_engine_instance() {
293         global $CFG;
295         $classname = '\\search_' . $CFG->searchengine . '\\engine';
296         if (!class_exists($classname)) {
297             return false;
298         }
300         return new $classname();
301     }
303     /**
304      * Returns the search engine.
305      *
306      * @return \core_search\engine
307      */
308     public function get_engine() {
309         return $this->engine;
310     }
312     /**
313      * Returns a search area class name.
314      *
315      * @param string $areaid
316      * @return string
317      */
318     protected static function get_area_classname($areaid) {
319         list($componentname, $areaname) = static::extract_areaid_parts($areaid);
320         return '\\' . $componentname . '\\search\\' . $areaname;
321     }
323     /**
324      * Returns a new area search indexer instance.
325      *
326      * @param string $areaid
327      * @return \core_search\base|bool False if the area is not available.
328      */
329     public static function get_search_area($areaid) {
331         // We have them all here.
332         if (!empty(static::$allsearchareas[$areaid])) {
333             return static::$allsearchareas[$areaid];
334         }
336         $classname = static::get_area_classname($areaid);
338         if (class_exists($classname) && static::is_search_area($classname)) {
339             return new $classname();
340         }
342         return false;
343     }
345     /**
346      * Return the list of available search areas.
347      *
348      * @param bool $enabled Return only the enabled ones.
349      * @return \core_search\base[]
350      */
351     public static function get_search_areas_list($enabled = false) {
353         // Two different arrays, we don't expect these arrays to be big.
354         if (static::$allsearchareas !== null) {
355             if (!$enabled) {
356                 return static::$allsearchareas;
357             } else {
358                 return static::$enabledsearchareas;
359             }
360         }
362         static::$allsearchareas = array();
363         static::$enabledsearchareas = array();
364         $searchclasses = \core_component::get_component_classes_in_namespace(null, 'search');
366         foreach ($searchclasses as $classname => $classpath) {
367             $areaname = substr(strrchr($classname, '\\'), 1);
368             $componentname = strstr($classname, '\\', 1);
369             if (!static::is_search_area($classname)) {
370                 continue;
371             }
373             $areaid = static::generate_areaid($componentname, $areaname);
374             $searchclass = new $classname();
375             static::$allsearchareas[$areaid] = $searchclass;
376             if ($searchclass->is_enabled()) {
377                 static::$enabledsearchareas[$areaid] = $searchclass;
378             }
379         }
381         if ($enabled) {
382             return static::$enabledsearchareas;
383         }
384         return static::$allsearchareas;
385     }
387     /**
388      * Return search area category instance by category name.
389      *
390      * @param string $name Category name. If name is not valid will return default category.
391      *
392      * @return \core_search\area_category
393      */
394     public static function get_search_area_category_by_name($name) {
395         if (key_exists($name, self::get_search_area_categories())) {
396             return self::get_search_area_categories()[$name];
397         } else {
398             return self::get_search_area_categories()[self::get_default_area_category_name()];
399         }
400     }
402     /**
403      * Return a list of existing search area categories.
404      *
405      * @return \core_search\area_category[]
406      */
407     public static function get_search_area_categories() {
408         if (!isset(static::$searchareacategories)) {
409             $categories = self::get_core_search_area_categories();
411             // Go through all existing search areas and get categories they are assigned to.
412             $areacategories = [];
413             foreach (self::get_search_areas_list() as $searcharea) {
414                 foreach ($searcharea->get_category_names() as $categoryname) {
415                     if (!key_exists($categoryname, $areacategories)) {
416                         $areacategories[$categoryname] = [];
417                     }
419                     $areacategories[$categoryname][] = $searcharea;
420                 }
421             }
423             // Populate core categories by areas.
424             foreach ($areacategories as $name => $searchareas) {
425                 if (key_exists($name, $categories)) {
426                     $categories[$name]->set_areas($searchareas);
427                 } else {
428                     throw new \coding_exception('Unknown core search area category ' . $name);
429                 }
430             }
432             // Get additional categories.
433             $additionalcategories = self::get_additional_search_area_categories();
434             foreach ($additionalcategories as $additionalcategory) {
435                 if (!key_exists($additionalcategory->get_name(), $categories)) {
436                     $categories[$additionalcategory->get_name()] = $additionalcategory;
437                 }
438             }
440             // Remove categories without areas.
441             foreach ($categories as $key => $category) {
442                 if (empty($category->get_areas())) {
443                     unset($categories[$key]);
444                 }
445             }
447             // Sort categories by order.
448             uasort($categories, function($category1, $category2) {
449                 return $category1->get_order() > $category2->get_order();
450             });
452             static::$searchareacategories = $categories;
453         }
455         return static::$searchareacategories;
456     }
458     /**
459      * Get list of core search area categories.
460      *
461      * @return \core_search\area_category[]
462      */
463     protected static function get_core_search_area_categories() {
464         $categories = [];
466         $categories[self::SEARCH_AREA_CATEGORY_ALL] = new area_category(
467             self::SEARCH_AREA_CATEGORY_ALL,
468             get_string('core-all', 'search'),
469             0,
470             self::get_search_areas_list(true)
471         );
473         $categories[self::SEARCH_AREA_CATEGORY_COURSE_CONTENT] = new area_category(
474             self::SEARCH_AREA_CATEGORY_COURSE_CONTENT,
475             get_string('core-course-content', 'search'),
476             1
477         );
479         $categories[self::SEARCH_AREA_CATEGORY_COURSES] = new area_category(
480             self::SEARCH_AREA_CATEGORY_COURSES,
481             get_string('core-courses', 'search'),
482             2
483         );
485         $categories[self::SEARCH_AREA_CATEGORY_USERS] = new area_category(
486             self::SEARCH_AREA_CATEGORY_USERS,
487             get_string('core-users', 'search'),
488             3
489         );
491         $categories[self::SEARCH_AREA_CATEGORY_OTHER] = new area_category(
492             self::SEARCH_AREA_CATEGORY_OTHER,
493             get_string('core-other', 'search'),
494             4
495         );
497         return $categories;
498     }
500     /**
501      * Gets a list of additional search area categories.
502      *
503      * @return \core_search\area_category[]
504      */
505     protected static function get_additional_search_area_categories() {
506         $additionalcategories = [];
508         // Allow plugins to add custom search area categories.
509         if ($pluginsfunction = get_plugins_with_function('search_area_categories')) {
510             foreach ($pluginsfunction as $plugintype => $plugins) {
511                 foreach ($plugins as $pluginfunction) {
512                     $plugincategories = $pluginfunction();
513                     // We're expecting a list of valid area categories.
514                     if (is_array($plugincategories)) {
515                         foreach ($plugincategories as $plugincategory) {
516                             if (self::is_valid_area_category($plugincategory)) {
517                                 $additionalcategories[] = $plugincategory;
518                             } else {
519                                 throw  new \coding_exception('Invalid search area category!');
520                             }
521                         }
522                     } else {
523                         throw  new \coding_exception($pluginfunction . ' should return a list of search area categories!');
524                     }
525                 }
526             }
527         }
529         return $additionalcategories;
530     }
532     /**
533      * Check if provided instance of area category is valid.
534      *
535      * @param mixed $areacategory Area category instance. Potentially could be anything.
536      *
537      * @return bool
538      */
539     protected static function is_valid_area_category($areacategory) {
540         return $areacategory instanceof area_category;
541     }
543     /**
544      * Clears all static caches.
545      *
546      * @return void
547      */
548     public static function clear_static() {
550         static::$enabledsearchareas = null;
551         static::$allsearchareas = null;
552         static::$instance = null;
553         static::$searchareacategories = null;
555         base_block::clear_static();
556         engine::clear_users_cache();
557     }
559     /**
560      * Generates an area id from the componentname and the area name.
561      *
562      * There should not be any naming conflict as the area name is the
563      * class name in component/classes/search/.
564      *
565      * @param string $componentname
566      * @param string $areaname
567      * @return void
568      */
569     public static function generate_areaid($componentname, $areaname) {
570         return $componentname . '-' . $areaname;
571     }
573     /**
574      * Returns all areaid string components (component name and area name).
575      *
576      * @param string $areaid
577      * @return array Component name (Frankenstyle) and area name (search area class name)
578      */
579     public static function extract_areaid_parts($areaid) {
580         return explode('-', $areaid);
581     }
583     /**
584      * Parse a search area id and get plugin name and config name prefix from it.
585      *
586      * @param string $areaid Search area id.
587      * @return array Where the first element is a plugin name and the second is config names prefix.
588      */
589     public static function parse_areaid($areaid) {
590         $parts = self::extract_areaid_parts($areaid);
592         if (empty($parts[1])) {
593             throw new \coding_exception('Trying to parse invalid search area id ' . $areaid);
594         }
596         $component = $parts[0];
597         $area = $parts[1];
599         if (strpos($component, 'core') === 0) {
600             $plugin = 'core_search';
601             $configprefix = str_replace('-', '_', $areaid);
602         } else {
603             $plugin = $component;
604             $configprefix = 'search_' . $area;
605         }
607         return [$plugin, $configprefix];
608     }
610     /**
611      * Returns information about the areas which the user can access.
612      *
613      * The returned value is a stdClass object with the following fields:
614      * - everything (bool, true for admin only)
615      * - usercontexts (indexed by area identifier then context
616      * - separategroupscontexts (contexts within which group restrictions apply)
617      * - visiblegroupscontextsareas (overrides to the above when the same contexts also have
618      *   'visible groups' for certain search area ids - hopefully rare)
619      * - usergroups (groups which the current user belongs to)
620      *
621      * The areas can be limited by course id and context id. If specifying context ids, results
622      * are limited to the exact context ids specified and not their children (for example, giving
623      * the course context id would result in including search items with the course context id, and
624      * not anything from a context inside the course). For performance, you should also specify
625      * course id(s) when using context ids.
626      *
627      * @param array|false $limitcourseids An array of course ids to limit the search to. False for no limiting.
628      * @param array|false $limitcontextids An array of context ids to limit the search to. False for no limiting.
629      * @return \stdClass Object as described above
630      */
631     protected function get_areas_user_accesses($limitcourseids = false, $limitcontextids = false) {
632         global $DB, $USER;
634         // All results for admins (unless they have chosen to limit results). Eventually we could
635         // add a new capability for managers.
636         if (is_siteadmin() && !$limitcourseids && !$limitcontextids) {
637             return (object)array('everything' => true);
638         }
640         $areasbylevel = array();
642         // Split areas by context level so we only iterate only once through courses and cms.
643         $searchareas = static::get_search_areas_list(true);
644         foreach ($searchareas as $areaid => $unused) {
645             $classname = static::get_area_classname($areaid);
646             $searcharea = new $classname();
647             foreach ($classname::get_levels() as $level) {
648                 $areasbylevel[$level][$areaid] = $searcharea;
649             }
650         }
652         // This will store area - allowed contexts relations.
653         $areascontexts = array();
655         // Initialise two special-case arrays for storing other information related to the contexts.
656         $separategroupscontexts = array();
657         $visiblegroupscontextsareas = array();
658         $usergroups = array();
660         if (empty($limitcourseids) && !empty($areasbylevel[CONTEXT_SYSTEM])) {
661             // We add system context to all search areas working at this level. Here each area is fully responsible of
662             // the access control as we can not automate much, we can not even check guest access as some areas might
663             // want to allow guests to retrieve data from them.
665             $systemcontextid = \context_system::instance()->id;
666             if (!$limitcontextids || in_array($systemcontextid, $limitcontextids)) {
667                 foreach ($areasbylevel[CONTEXT_SYSTEM] as $areaid => $searchclass) {
668                     $areascontexts[$areaid][$systemcontextid] = $systemcontextid;
669                 }
670             }
671         }
673         if (!empty($areasbylevel[CONTEXT_USER])) {
674             if ($usercontext = \context_user::instance($USER->id, IGNORE_MISSING)) {
675                 if (!$limitcontextids || in_array($usercontext->id, $limitcontextids)) {
676                     // Extra checking although only logged users should reach this point, guest users have a valid context id.
677                     foreach ($areasbylevel[CONTEXT_USER] as $areaid => $searchclass) {
678                         $areascontexts[$areaid][$usercontext->id] = $usercontext->id;
679                     }
680                 }
681             }
682         }
684         if (is_siteadmin()) {
685             $allcourses = $this->get_all_courses($limitcourseids);
686         } else {
687             $allcourses = $mycourses = $this->get_my_courses((bool)get_config('core', 'searchallavailablecourses'));
689             if (self::include_all_courses()) {
690                 $allcourses = $this->get_all_courses($limitcourseids);
691             }
692         }
694         if (empty($limitcourseids) || in_array(SITEID, $limitcourseids)) {
695             $allcourses[SITEID] = get_course(SITEID);
696             if (isset($mycourses)) {
697                 $mycourses[SITEID] = get_course(SITEID);
698             }
699         }
701         // Keep a list of included course context ids (needed for the block calculation below).
702         $coursecontextids = [];
703         $modulecms = [];
705         foreach ($allcourses as $course) {
706             if (!empty($limitcourseids) && !in_array($course->id, $limitcourseids)) {
707                 // Skip non-included courses.
708                 continue;
709             }
711             $coursecontext = \context_course::instance($course->id);
712             $hasgrouprestrictions = false;
714             if (!empty($areasbylevel[CONTEXT_COURSE]) &&
715                     (!$limitcontextids || in_array($coursecontext->id, $limitcontextids))) {
716                 // Add the course contexts the user can view.
717                 foreach ($areasbylevel[CONTEXT_COURSE] as $areaid => $searchclass) {
718                     if (!empty($mycourses[$course->id]) || \core_course_category::can_view_course_info($course)) {
719                         $areascontexts[$areaid][$coursecontext->id] = $coursecontext->id;
720                     }
721                 }
722             }
724             // Skip module context if a user can't access related course.
725             if (isset($mycourses) && !key_exists($course->id, $mycourses)) {
726                 continue;
727             }
729             $coursecontextids[] = $coursecontext->id;
731             // Info about the course modules.
732             $modinfo = get_fast_modinfo($course);
734             if (!empty($areasbylevel[CONTEXT_MODULE])) {
735                 // Add the module contexts the user can view (cm_info->uservisible).
737                 foreach ($areasbylevel[CONTEXT_MODULE] as $areaid => $searchclass) {
739                     // Removing the plugintype 'mod_' prefix.
740                     $modulename = substr($searchclass->get_component_name(), 4);
742                     $modinstances = $modinfo->get_instances_of($modulename);
743                     foreach ($modinstances as $modinstance) {
744                         // Skip module context if not included in list of context ids.
745                         if ($limitcontextids && !in_array($modinstance->context->id, $limitcontextids)) {
746                             continue;
747                         }
748                         if ($modinstance->uservisible) {
749                             $contextid = $modinstance->context->id;
750                             $areascontexts[$areaid][$contextid] = $contextid;
751                             $modulecms[$modinstance->id] = $modinstance;
753                             if (!has_capability('moodle/site:accessallgroups', $modinstance->context) &&
754                                     ($searchclass instanceof base_mod) &&
755                                     $searchclass->supports_group_restriction()) {
756                                 if ($searchclass->restrict_cm_access_by_group($modinstance)) {
757                                     $separategroupscontexts[$contextid] = $contextid;
758                                     $hasgrouprestrictions = true;
759                                 } else {
760                                     // Track a list of anything that has a group id (so might get
761                                     // filtered) and doesn't want to be, in this context.
762                                     if (!array_key_exists($contextid, $visiblegroupscontextsareas)) {
763                                         $visiblegroupscontextsareas[$contextid] = array();
764                                     }
765                                     $visiblegroupscontextsareas[$contextid][$areaid] = $areaid;
766                                 }
767                             }
768                         }
769                     }
770                 }
771             }
773             // Insert group information for course (unless there aren't any modules restricted by
774             // group for this user in this course, in which case don't bother).
775             if ($hasgrouprestrictions) {
776                 $groups = groups_get_all_groups($course->id, $USER->id, 0, 'g.id');
777                 foreach ($groups as $group) {
778                     $usergroups[$group->id] = $group->id;
779                 }
780             }
781         }
783         // Chuck away all the 'visible groups contexts' data unless there is actually something
784         // that does use separate groups in the same context (this data is only used as an
785         // 'override' in cases where the search is restricting to separate groups).
786         foreach ($visiblegroupscontextsareas as $contextid => $areas) {
787             if (!array_key_exists($contextid, $separategroupscontexts)) {
788                 unset($visiblegroupscontextsareas[$contextid]);
789             }
790         }
792         // Add all supported block contexts, in a single query for performance.
793         if (!empty($areasbylevel[CONTEXT_BLOCK])) {
794             // Get list of all block types we care about.
795             $blocklist = [];
796             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
797                 $blocklist[$searchclass->get_block_name()] = true;
798             }
799             list ($blocknamesql, $blocknameparams) = $DB->get_in_or_equal(array_keys($blocklist));
801             // Get list of course contexts.
802             list ($contextsql, $contextparams) = $DB->get_in_or_equal($coursecontextids);
804             // Get list of block context (if limited).
805             $blockcontextwhere = '';
806             $blockcontextparams = [];
807             if ($limitcontextids) {
808                 list ($blockcontextsql, $blockcontextparams) = $DB->get_in_or_equal($limitcontextids);
809                 $blockcontextwhere = 'AND x.id ' . $blockcontextsql;
810             }
812             // Query all blocks that are within an included course, and are set to be visible, and
813             // in a supported page type (basically just course view). This query could be
814             // extended (or a second query added) to support blocks that are within a module
815             // context as well, and we could add more page types if required.
816             $blockrecs = $DB->get_records_sql("
817                         SELECT x.*, bi.blockname AS blockname, bi.id AS blockinstanceid
818                           FROM {block_instances} bi
819                           JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
820                      LEFT JOIN {block_positions} bp ON bp.blockinstanceid = bi.id
821                                AND bp.contextid = bi.parentcontextid
822                                AND bp.pagetype LIKE 'course-view-%'
823                                AND bp.subpage = ''
824                                AND bp.visible = 0
825                          WHERE bi.parentcontextid $contextsql
826                                $blockcontextwhere
827                                AND bi.blockname $blocknamesql
828                                AND bi.subpagepattern IS NULL
829                                AND (bi.pagetypepattern = 'site-index'
830                                    OR bi.pagetypepattern LIKE 'course-view-%'
831                                    OR bi.pagetypepattern = 'course-*'
832                                    OR bi.pagetypepattern = '*')
833                                AND bp.id IS NULL",
834                     array_merge([CONTEXT_BLOCK], $contextparams, $blockcontextparams, $blocknameparams));
835             $blockcontextsbyname = [];
836             foreach ($blockrecs as $blockrec) {
837                 if (empty($blockcontextsbyname[$blockrec->blockname])) {
838                     $blockcontextsbyname[$blockrec->blockname] = [];
839                 }
840                 \context_helper::preload_from_record($blockrec);
841                 $blockcontextsbyname[$blockrec->blockname][] = \context_block::instance(
842                         $blockrec->blockinstanceid);
843             }
845             // Add the block contexts the user can view.
846             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
847                 if (empty($blockcontextsbyname[$searchclass->get_block_name()])) {
848                     continue;
849                 }
850                 foreach ($blockcontextsbyname[$searchclass->get_block_name()] as $context) {
851                     if (has_capability('moodle/block:view', $context)) {
852                         $areascontexts[$areaid][$context->id] = $context->id;
853                     }
854                 }
855             }
856         }
858         // Return all the data.
859         return (object)array('everything' => false, 'usercontexts' => $areascontexts,
860                 'separategroupscontexts' => $separategroupscontexts, 'usergroups' => $usergroups,
861                 'visiblegroupscontextsareas' => $visiblegroupscontextsareas);
862     }
864     /**
865      * Returns requested page of documents plus additional information for paging.
866      *
867      * This function does not perform any kind of security checking for access, the caller code
868      * should check that the current user have moodle/search:query capability.
869      *
870      * If a page is requested that is beyond the last result, the last valid page is returned in
871      * results, and actualpage indicates which page was returned.
872      *
873      * @param stdClass $formdata
874      * @param int $pagenum The 0 based page number.
875      * @return object An object with 3 properties:
876      *                    results    => An array of \core_search\documents for the actual page.
877      *                    totalcount => Number of records that are possibly available, to base paging on.
878      *                    actualpage => The actual page returned.
879      */
880     public function paged_search(\stdClass $formdata, $pagenum) {
881         $out = new \stdClass();
883         if (self::is_search_area_categories_enabled() && !empty($formdata->cat)) {
884             $cat = self::get_search_area_category_by_name($formdata->cat);
885             if (empty($formdata->areaids)) {
886                 $formdata->areaids = array_keys($cat->get_areas());
887             } else {
888                 foreach ($formdata->areaids as $key => $areaid) {
889                     if (!key_exists($areaid, $cat->get_areas())) {
890                         unset($formdata->areaids[$key]);
891                     }
892                 }
893             }
894         }
896         $perpage = static::DISPLAY_RESULTS_PER_PAGE;
898         // Make sure we only allow request up to max page.
899         $pagenum = min($pagenum, (static::MAX_RESULTS / $perpage) - 1);
901         // Calculate the first and last document number for the current page, 1 based.
902         $mindoc = ($pagenum * $perpage) + 1;
903         $maxdoc = ($pagenum + 1) * $perpage;
905         // Get engine documents, up to max.
906         $docs = $this->search($formdata, $maxdoc);
908         $resultcount = count($docs);
909         if ($resultcount < $maxdoc) {
910             // This means it couldn't give us results to max, so the count must be the max.
911             $out->totalcount = $resultcount;
912         } else {
913             // Get the possible count reported by engine, and limit to our max.
914             $out->totalcount = $this->engine->get_query_total_count();
915             if (defined('BEHAT_SITE_RUNNING') && $this->behatresultcount) {
916                 // Override results when using Behat mock results.
917                 $out->totalcount = $this->behatresultcount;
918             }
919             $out->totalcount = min($out->totalcount, static::MAX_RESULTS);
920         }
922         // Determine the actual page.
923         if ($resultcount < $mindoc) {
924             // We couldn't get the min docs for this page, so determine what page we can get.
925             $out->actualpage = floor(($resultcount - 1) / $perpage);
926         } else {
927             $out->actualpage = $pagenum;
928         }
930         // Split the results to only return the page.
931         $out->results = array_slice($docs, $out->actualpage * $perpage, $perpage, true);
933         return $out;
934     }
936     /**
937      * Returns documents from the engine based on the data provided.
938      *
939      * This function does not perform any kind of security checking, the caller code
940      * should check that the current user have moodle/search:query capability.
941      *
942      * It might return the results from the cache instead.
943      *
944      * Valid formdata options include:
945      * - q (query text)
946      * - courseids (optional list of course ids to restrict)
947      * - contextids (optional list of context ids to restrict)
948      * - context (Moodle context object for location user searched from)
949      * - order (optional ordering, one of the types supported by the search engine e.g. 'relevance')
950      * - userids (optional list of user ids to restrict)
951      *
952      * @param \stdClass $formdata Query input data (usually from search form)
953      * @param int $limit The maximum number of documents to return
954      * @return \core_search\document[]
955      */
956     public function search(\stdClass $formdata, $limit = 0) {
957         // For Behat testing, the search results can be faked using a special step.
958         if (defined('BEHAT_SITE_RUNNING')) {
959             $fakeresult = get_config('core_search', 'behat_fakeresult');
960             if ($fakeresult) {
961                 // Clear config setting.
962                 unset_config('core_search', 'behat_fakeresult');
964                 // Check query matches expected value.
965                 $details = json_decode($fakeresult);
966                 if ($formdata->q !== $details->query) {
967                     throw new \coding_exception('Unexpected search query: ' . $formdata->q);
968                 }
970                 // Create search documents from the JSON data.
971                 $docs = [];
972                 foreach ($details->results as $result) {
973                     $doc = new \core_search\document($result->itemid, $result->componentname,
974                             $result->areaname);
975                     foreach ((array)$result->fields as $field => $value) {
976                         $doc->set($field, $value);
977                     }
978                     foreach ((array)$result->extrafields as $field => $value) {
979                         $doc->set_extra($field, $value);
980                     }
981                     $area = $this->get_search_area($doc->get('areaid'));
982                     $doc->set_doc_url($area->get_doc_url($doc));
983                     $doc->set_context_url($area->get_context_url($doc));
984                     $docs[] = $doc;
985                 }
987                 // Store the mock count, and apply the limit to the returned results.
988                 $this->behatresultcount = count($docs);
989                 if ($this->behatresultcount > $limit) {
990                     $docs = array_slice($docs, 0, $limit);
991                 }
993                 return $docs;
994             }
995         }
997         $limitcourseids = $this->build_limitcourseids($formdata);
999         $limitcontextids = false;
1000         if (!empty($formdata->contextids)) {
1001             $limitcontextids = $formdata->contextids;
1002         }
1004         // Clears previous query errors.
1005         $this->engine->clear_query_error();
1007         $contextinfo = $this->get_areas_user_accesses($limitcourseids, $limitcontextids);
1008         if (!$contextinfo->everything && !$contextinfo->usercontexts) {
1009             // User can not access any context.
1010             $docs = array();
1011         } else {
1012             // If engine does not support groups, remove group information from the context info -
1013             // use the old format instead (true = admin, array = user contexts).
1014             if (!$this->engine->supports_group_filtering()) {
1015                 $contextinfo = $contextinfo->everything ? true : $contextinfo->usercontexts;
1016             }
1018             // Execute the actual query.
1019             $docs = $this->engine->execute_query($formdata, $contextinfo, $limit);
1020         }
1022         return $docs;
1023     }
1025     /**
1026      * Build a list of course ids to limit the search based on submitted form data.
1027      *
1028      * @param \stdClass $formdata Submitted search form data.
1029      *
1030      * @return array|bool
1031      */
1032     protected function build_limitcourseids(\stdClass $formdata) {
1033         $limitcourseids = false;
1035         if (!empty($formdata->mycoursesonly)) {
1036             $limitcourseids = array_keys($this->get_my_courses(false));
1037         }
1039         if (!empty($formdata->courseids)) {
1040             if (empty($limitcourseids)) {
1041                 $limitcourseids = $formdata->courseids;
1042             } else {
1043                 $limitcourseids = array_intersect($limitcourseids, $formdata->courseids);
1044             }
1045         }
1047         return $limitcourseids;
1048     }
1050     /**
1051      * Merge separate index segments into one.
1052      */
1053     public function optimize_index() {
1054         $this->engine->optimize();
1055     }
1057     /**
1058      * Index all documents.
1059      *
1060      * @param bool $fullindex Whether we should reindex everything or not.
1061      * @param float $timelimit Time limit in seconds (0 = no time limit)
1062      * @param \progress_trace|null $progress Optional class for tracking progress
1063      * @throws \moodle_exception
1064      * @return bool Whether there was any updated document or not.
1065      */
1066     public function index($fullindex = false, $timelimit = 0, \progress_trace $progress = null) {
1067         global $DB;
1069         // Cannot combine time limit with reindex.
1070         if ($timelimit && $fullindex) {
1071             throw new \coding_exception('Cannot apply time limit when reindexing');
1072         }
1073         if (!$progress) {
1074             $progress = new \null_progress_trace();
1075         }
1077         // Unlimited time.
1078         \core_php_time_limit::raise();
1080         // Notify the engine that an index starting.
1081         $this->engine->index_starting($fullindex);
1083         $sumdocs = 0;
1085         $searchareas = $this->get_search_areas_list(true);
1087         if ($timelimit) {
1088             // If time is limited (and therefore we're not just indexing everything anyway), select
1089             // an order for search areas. The intention here is to avoid a situation where a new
1090             // large search area is enabled, and this means all our other search areas go out of
1091             // date while that one is being indexed. To do this, we order by the time we spent
1092             // indexing them last time we ran, meaning anything that took a very long time will be
1093             // done last.
1094             uasort($searchareas, function(\core_search\base $area1, \core_search\base $area2) {
1095                 return (int)$area1->get_last_indexing_duration() - (int)$area2->get_last_indexing_duration();
1096             });
1098             // Decide time to stop.
1099             $stopat = self::get_current_time() + $timelimit;
1100         }
1102         foreach ($searchareas as $areaid => $searcharea) {
1104             $progress->output('Processing area: ' . $searcharea->get_visible_name());
1106             // Notify the engine that an area is starting.
1107             $this->engine->area_index_starting($searcharea, $fullindex);
1109             $indexingstart = (int)self::get_current_time();
1110             $elapsed = self::get_current_time();
1112             // This is used to store this component config.
1113             list($componentconfigname, $varname) = $searcharea->get_config_var_name();
1115             $prevtimestart = intval(get_config($componentconfigname, $varname . '_indexingstart'));
1117             if ($fullindex === true) {
1118                 $referencestarttime = 0;
1120                 // For full index, we delete any queued context index requests, as those will
1121                 // obviously be met by the full index.
1122                 $DB->delete_records('search_index_requests');
1123             } else {
1124                 $partial = get_config($componentconfigname, $varname . '_partial');
1125                 if ($partial) {
1126                     // When the previous index did not complete all data, we start from the time of the
1127                     // last document that was successfully indexed. (Note this will result in
1128                     // re-indexing that one document, but we can't avoid that because there may be
1129                     // other documents in the same second.)
1130                     $referencestarttime = intval(get_config($componentconfigname, $varname . '_lastindexrun'));
1131                 } else {
1132                     $referencestarttime = $prevtimestart;
1133                 }
1134             }
1136             // Getting the recordset from the area.
1137             $recordset = $searcharea->get_recordset_by_timestamp($referencestarttime);
1138             $initialquerytime = self::get_current_time() - $elapsed;
1139             if ($initialquerytime > self::DISPLAY_LONG_QUERY_TIME) {
1140                 $progress->output('Initial query took ' . round($initialquerytime, 1) .
1141                         ' seconds.', 1);
1142             }
1144             // Pass get_document as callback.
1145             $fileindexing = $this->engine->file_indexing_enabled() && $searcharea->uses_file_indexing();
1146             $options = array('indexfiles' => $fileindexing, 'lastindexedtime' => $prevtimestart);
1147             if ($timelimit) {
1148                 $options['stopat'] = $stopat;
1149             }
1150             $options['progress'] = $progress;
1151             $iterator = new skip_future_documents_iterator(new \core\dml\recordset_walk(
1152                     $recordset, array($searcharea, 'get_document'), $options));
1153             $result = $this->engine->add_documents($iterator, $searcharea, $options);
1154             $recordset->close();
1155             $batchinfo = '';
1156             if (count($result) === 6) {
1157                 [$numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial, $batches] = $result;
1158                 // Only show the batch count if we actually batched any requests.
1159                 if ($batches !== $numdocs + $numdocsignored) {
1160                     $batchinfo = ' (' . $batches . ' batch' . ($batches === 1 ? '' : 'es') . ')';
1161                 }
1162             } else if (count($result) === 5) {
1163                 // Backward compatibility for engines that don't return a batch count.
1164                 [$numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial] = $result;
1165                 // Deprecated since Moodle 4.0 MDL-68690.
1166                 // TODO: MDL-68776 This will be deleted in Moodle 4.4.
1167                 debugging('engine::add_documents() should return $batches (5-value return is deprecated)',
1168                         DEBUG_DEVELOPER);
1169             } else {
1170                 throw new coding_exception('engine::add_documents() should return $partial (4-value return is deprecated)');
1171             }
1173             if ($numdocs > 0) {
1174                 $elapsed = round((self::get_current_time() - $elapsed), 1);
1176                 $partialtext = '';
1177                 if ($partial) {
1178                     $partialtext = ' (not complete; done to ' . userdate($lastindexeddoc,
1179                             get_string('strftimedatetimeshort', 'langconfig')) . ')';
1180                 }
1182                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
1183                         ' documents' . $batchinfo . ', in ' . $elapsed . ' seconds' . $partialtext . '.', 1);
1184             } else {
1185                 $progress->output('No new documents to index.', 1);
1186             }
1188             // Notify the engine this area is complete, and only mark times if true.
1189             if ($this->engine->area_index_complete($searcharea, $numdocs, $fullindex)) {
1190                 $sumdocs += $numdocs;
1192                 // Store last index run once documents have been committed to the search engine.
1193                 set_config($varname . '_indexingstart', $indexingstart, $componentconfigname);
1194                 set_config($varname . '_indexingend', (int)self::get_current_time(), $componentconfigname);
1195                 set_config($varname . '_docsignored', $numdocsignored, $componentconfigname);
1196                 set_config($varname . '_docsprocessed', $numdocs, $componentconfigname);
1197                 set_config($varname . '_recordsprocessed', $numrecords, $componentconfigname);
1198                 if ($lastindexeddoc > 0) {
1199                     set_config($varname . '_lastindexrun', $lastindexeddoc, $componentconfigname);
1200                 }
1201                 if ($partial) {
1202                     set_config($varname . '_partial', 1, $componentconfigname);
1203                 } else {
1204                     unset_config($varname . '_partial', $componentconfigname);
1205                 }
1206             } else {
1207                 $progress->output('Engine reported error.');
1208             }
1210             if ($timelimit && (self::get_current_time() >= $stopat)) {
1211                 $progress->output('Stopping indexing due to time limit.');
1212                 break;
1213             }
1214         }
1216         if ($sumdocs > 0) {
1217             $event = \core\event\search_indexed::create(
1218                     array('context' => \context_system::instance()));
1219             $event->trigger();
1220         }
1222         $this->engine->index_complete($sumdocs, $fullindex);
1224         return (bool)$sumdocs;
1225     }
1227     /**
1228      * Indexes or reindexes a specific context of the system, e.g. one course.
1229      *
1230      * The function returns an object with field 'complete' (true or false).
1231      *
1232      * This function supports partial indexing via the time limit parameter. If the time limit
1233      * expires, it will return values for $startfromarea and $startfromtime which can be passed
1234      * next time to continue indexing.
1235      *
1236      * @param \context $context Context to restrict index.
1237      * @param string $singleareaid If specified, indexes only the given area.
1238      * @param float $timelimit Time limit in seconds (0 = no time limit)
1239      * @param \progress_trace|null $progress Optional class for tracking progress
1240      * @param string $startfromarea Area to start from
1241      * @param int $startfromtime Timestamp to start from
1242      * @return \stdClass Object indicating success
1243      */
1244     public function index_context($context, $singleareaid = '', $timelimit = 0,
1245             \progress_trace $progress = null, $startfromarea = '', $startfromtime = 0) {
1246         if (!$progress) {
1247             $progress = new \null_progress_trace();
1248         }
1250         // Work out time to stop, if limited.
1251         if ($timelimit) {
1252             // Decide time to stop.
1253             $stopat = self::get_current_time() + $timelimit;
1254         }
1256         // No PHP time limit.
1257         \core_php_time_limit::raise();
1259         // Notify the engine that an index starting.
1260         $this->engine->index_starting(false);
1262         $sumdocs = 0;
1264         // Get all search areas, in consistent order.
1265         $searchareas = $this->get_search_areas_list(true);
1266         ksort($searchareas);
1268         // Are we skipping past some that were handled previously?
1269         $skipping = $startfromarea ? true : false;
1271         foreach ($searchareas as $areaid => $searcharea) {
1272             // If we're only processing one area id, skip all the others.
1273             if ($singleareaid && $singleareaid !== $areaid) {
1274                 continue;
1275             }
1277             // If we're skipping to a later area, continue through the loop.
1278             $referencestarttime = 0;
1279             if ($skipping) {
1280                 if ($areaid !== $startfromarea) {
1281                     continue;
1282                 }
1283                 // Stop skipping and note the reference start time.
1284                 $skipping = false;
1285                 $referencestarttime = $startfromtime;
1286             }
1288             $progress->output('Processing area: ' . $searcharea->get_visible_name());
1290             $elapsed = self::get_current_time();
1292             // Get the recordset of all documents from the area for this context.
1293             $recordset = $searcharea->get_document_recordset($referencestarttime, $context);
1294             if (!$recordset) {
1295                 if ($recordset === null) {
1296                     $progress->output('Skipping (not relevant to context).', 1);
1297                 } else {
1298                     $progress->output('Skipping (does not support context indexing).', 1);
1299                 }
1300                 continue;
1301             }
1303             // Notify the engine that an area is starting.
1304             $this->engine->area_index_starting($searcharea, false);
1306             // Work out search options.
1307             $options = [];
1308             $options['indexfiles'] = $this->engine->file_indexing_enabled() &&
1309                     $searcharea->uses_file_indexing();
1310             if ($timelimit) {
1311                 $options['stopat'] = $stopat;
1312             }
1314             // Construct iterator which will use get_document on the recordset results.
1315             $iterator = new \core\dml\recordset_walk($recordset,
1316                     array($searcharea, 'get_document'), $options);
1318             // Use this iterator to add documents.
1319             $result = $this->engine->add_documents($iterator, $searcharea, $options);
1320             $batchinfo = '';
1321             if (count($result) === 6) {
1322                 [$numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial, $batches] = $result;
1323                 // Only show the batch count if we actually batched any requests.
1324                 if ($batches !== $numdocs + $numdocsignored) {
1325                     $batchinfo = ' (' . $batches . ' batch' . ($batches === 1 ? '' : 'es') . ')';
1326                 }
1327             } else if (count($result) === 5) {
1328                 // Backward compatibility for engines that don't return a batch count.
1329                 [$numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial] = $result;
1330                 // Deprecated since Moodle 4.0 MDL-68690.
1331                 // TODO: MDL-68776 This will be deleted in Moodle 4.4 (as should the below bit).
1332                 debugging('engine::add_documents() should return $batches (5-value return is deprecated)',
1333                         DEBUG_DEVELOPER);
1334             } else {
1335                 // Backward compatibility for engines that don't support partial adding.
1336                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
1337                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
1338                         DEBUG_DEVELOPER);
1339                 $partial = false;
1340             }
1342             if ($numdocs > 0) {
1343                 $elapsed = round((self::get_current_time() - $elapsed), 3);
1344                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
1345                         ' documents' . $batchinfo . ', in ' . $elapsed . ' seconds' .
1346                         ($partial ? ' (not complete)' : '') . '.', 1);
1347             } else {
1348                 $progress->output('No documents to index.', 1);
1349             }
1351             // Notify the engine this area is complete, but don't store any times as this is not
1352             // part of the 'normal' search index.
1353             if (!$this->engine->area_index_complete($searcharea, $numdocs, false)) {
1354                 $progress->output('Engine reported error.', 1);
1355             }
1357             if ($partial && $timelimit && (self::get_current_time() >= $stopat)) {
1358                 $progress->output('Stopping indexing due to time limit.');
1359                 break;
1360             }
1361         }
1363         if ($sumdocs > 0) {
1364             $event = \core\event\search_indexed::create(
1365                     array('context' => $context));
1366             $event->trigger();
1367         }
1369         $this->engine->index_complete($sumdocs, false);
1371         // Indicate in result whether we completed indexing, or only part of it.
1372         $result = new \stdClass();
1373         if ($partial) {
1374             $result->complete = false;
1375             $result->startfromarea = $areaid;
1376             $result->startfromtime = $lastindexeddoc;
1377         } else {
1378             $result->complete = true;
1379         }
1380         return $result;
1381     }
1383     /**
1384      * Resets areas config.
1385      *
1386      * @throws \moodle_exception
1387      * @param string $areaid
1388      * @return void
1389      */
1390     public function reset_config($areaid = false) {
1392         if (!empty($areaid)) {
1393             $searchareas = array();
1394             if (!$searchareas[$areaid] = static::get_search_area($areaid)) {
1395                 throw new \moodle_exception('errorareanotavailable', 'search', '', $areaid);
1396             }
1397         } else {
1398             // Only the enabled ones.
1399             $searchareas = static::get_search_areas_list(true);
1400         }
1402         foreach ($searchareas as $searcharea) {
1403             list($componentname, $varname) = $searcharea->get_config_var_name();
1404             $config = $searcharea->get_config();
1406             foreach ($config as $key => $value) {
1407                 // We reset them all but the enable/disabled one.
1408                 if ($key !== $varname . '_enabled') {
1409                     set_config($key, 0, $componentname);
1410                 }
1411             }
1412         }
1413     }
1415     /**
1416      * Deletes an area's documents or all areas documents.
1417      *
1418      * @param string $areaid The area id or false for all
1419      * @return void
1420      */
1421     public function delete_index($areaid = false) {
1422         if (!empty($areaid)) {
1423             $this->engine->delete($areaid);
1424             $this->reset_config($areaid);
1425         } else {
1426             $this->engine->delete();
1427             $this->reset_config();
1428         }
1429     }
1431     /**
1432      * Deletes index by id.
1433      *
1434      * @param int Solr Document string $id
1435      */
1436     public function delete_index_by_id($id) {
1437         $this->engine->delete_by_id($id);
1438     }
1440     /**
1441      * Returns search areas configuration.
1442      *
1443      * @param \core_search\base[] $searchareas
1444      * @return \stdClass[] $configsettings
1445      */
1446     public function get_areas_config($searchareas) {
1448         $vars = array('indexingstart', 'indexingend', 'lastindexrun', 'docsignored',
1449                 'docsprocessed', 'recordsprocessed', 'partial');
1451         $configsettings = [];
1452         foreach ($searchareas as $searcharea) {
1454             $areaid = $searcharea->get_area_id();
1456             $configsettings[$areaid] = new \stdClass();
1457             list($componentname, $varname) = $searcharea->get_config_var_name();
1459             if (!$searcharea->is_enabled()) {
1460                 // We delete all indexed data on disable so no info.
1461                 foreach ($vars as $var) {
1462                     $configsettings[$areaid]->{$var} = 0;
1463                 }
1464             } else {
1465                 foreach ($vars as $var) {
1466                     $configsettings[$areaid]->{$var} = get_config($componentname, $varname .'_' . $var);
1467                 }
1468             }
1470             // Formatting the time.
1471             if (!empty($configsettings[$areaid]->lastindexrun)) {
1472                 $configsettings[$areaid]->lastindexrun = userdate($configsettings[$areaid]->lastindexrun);
1473             } else {
1474                 $configsettings[$areaid]->lastindexrun = get_string('never');
1475             }
1476         }
1477         return $configsettings;
1478     }
1480     /**
1481      * Triggers search_results_viewed event
1482      *
1483      * Other data required:
1484      * - q: The query string
1485      * - page: The page number
1486      * - title: Title filter
1487      * - areaids: Search areas filter
1488      * - courseids: Courses filter
1489      * - timestart: Time start filter
1490      * - timeend: Time end filter
1491      *
1492      * @since Moodle 3.2
1493      * @param array $other Other info for the event.
1494      * @return \core\event\search_results_viewed
1495      */
1496     public static function trigger_search_results_viewed($other) {
1497         $event = \core\event\search_results_viewed::create([
1498             'context' => \context_system::instance(),
1499             'other' => $other
1500         ]);
1501         $event->trigger();
1503         return $event;
1504     }
1506     /**
1507      * Checks whether a classname is of an actual search area.
1508      *
1509      * @param string $classname
1510      * @return bool
1511      */
1512     protected static function is_search_area($classname) {
1513         if (is_subclass_of($classname, 'core_search\base')) {
1514             return (new \ReflectionClass($classname))->isInstantiable();
1515         }
1517         return false;
1518     }
1520     /**
1521      * Requests that a specific context is indexed by the scheduled task. The context will be
1522      * added to a queue which is processed by the task.
1523      *
1524      * This is used after a restore to ensure that restored items are indexed, even though their
1525      * modified time will be older than the latest indexed. It is also used by the 'Gradual reindex'
1526      * admin feature from the search areas screen.
1527      *
1528      * @param \context $context Context to index within
1529      * @param string $areaid Area to index, '' = all areas
1530      * @param int $priority Priority (INDEX_PRIORITY_xx constant)
1531      */
1532     public static function request_index(\context $context, $areaid = '',
1533             $priority = self::INDEX_PRIORITY_NORMAL) {
1534         global $DB;
1536         // Check through existing requests for this context or any parent context.
1537         list ($contextsql, $contextparams) = $DB->get_in_or_equal(
1538                 $context->get_parent_context_ids(true));
1539         $existing = $DB->get_records_select('search_index_requests',
1540                 'contextid ' . $contextsql, $contextparams, '',
1541                 'id, searcharea, partialarea, indexpriority');
1542         foreach ($existing as $rec) {
1543             // If we haven't started processing the existing request yet, and it covers the same
1544             // area (or all areas) then that will be sufficient so don't add anything else.
1545             if ($rec->partialarea === '' && ($rec->searcharea === $areaid || $rec->searcharea === '')) {
1546                 // If the existing request has the same (or higher) priority, no need to add anything.
1547                 if ($rec->indexpriority >= $priority) {
1548                     return;
1549                 }
1550                 // The existing request has lower priority. If it is exactly the same, then just
1551                 // adjust the priority of the existing request.
1552                 if ($rec->searcharea === $areaid) {
1553                     $DB->set_field('search_index_requests', 'indexpriority', $priority,
1554                             ['id' => $rec->id]);
1555                     return;
1556                 }
1557                 // The existing request would cover this area but is a lower priority. We need to
1558                 // add the new request even though that means we will index part of it twice.
1559             }
1560         }
1562         // No suitable existing request, so add a new one.
1563         $newrecord = [ 'contextid' => $context->id, 'searcharea' => $areaid,
1564                 'timerequested' => (int)self::get_current_time(),
1565                 'partialarea' => '', 'partialtime' => 0,
1566                 'indexpriority' => $priority ];
1567         $DB->insert_record('search_index_requests', $newrecord);
1568     }
1570     /**
1571      * Processes outstanding index requests. This will take the first item from the queue (taking
1572      * account the indexing priority) and process it, continuing until an optional time limit is
1573      * reached.
1574      *
1575      * If there are no index requests, the function will do nothing.
1576      *
1577      * @param float $timelimit Time limit (0 = none)
1578      * @param \progress_trace|null $progress Optional progress indicator
1579      */
1580     public function process_index_requests($timelimit = 0.0, \progress_trace $progress = null) {
1581         global $DB;
1583         if (!$progress) {
1584             $progress = new \null_progress_trace();
1585         }
1587         $before = self::get_current_time();
1588         if ($timelimit) {
1589             $stopat = $before + $timelimit;
1590         }
1591         while (true) {
1592             // Retrieve first request, using fully defined ordering.
1593             $requests = $DB->get_records('search_index_requests', null,
1594                     'indexpriority DESC, timerequested, contextid, searcharea',
1595                     'id, contextid, searcharea, partialarea, partialtime', 0, 1);
1596             if (!$requests) {
1597                 // If there are no more requests, stop.
1598                 break;
1599             }
1600             $request = reset($requests);
1602             // Calculate remaining time.
1603             $remainingtime = 0;
1604             $beforeindex = self::get_current_time();
1605             if ($timelimit) {
1606                 $remainingtime = $stopat - $beforeindex;
1608                 // If the time limit expired already, stop now. (Otherwise we might accidentally
1609                 // index with no time limit or a negative time limit.)
1610                 if ($remainingtime <= 0) {
1611                     break;
1612                 }
1613             }
1615             // Show a message before each request, indicating what will be indexed.
1616             $context = \context::instance_by_id($request->contextid, IGNORE_MISSING);
1617             if (!$context) {
1618                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1619                 $progress->output('Skipped deleted context: ' . $request->contextid);
1620                 continue;
1621             }
1622             $contextname = $context->get_context_name();
1623             if ($request->searcharea) {
1624                 $contextname .= ' (search area: ' . $request->searcharea . ')';
1625             }
1626             $progress->output('Indexing requested context: ' . $contextname);
1628             // Actually index the context.
1629             $result = $this->index_context($context, $request->searcharea, $remainingtime,
1630                     $progress, $request->partialarea, $request->partialtime);
1632             // Work out shared part of message.
1633             $endmessage = $contextname . ' (' . round(self::get_current_time() - $beforeindex, 1) . 's)';
1635             // Update database table and continue/stop as appropriate.
1636             if ($result->complete) {
1637                 // If we completed the request, remove it from the table.
1638                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1639                 $progress->output('Completed requested context: ' . $endmessage);
1640             } else {
1641                 // If we didn't complete the request, store the partial details (how far it got).
1642                 $DB->update_record('search_index_requests', ['id' => $request->id,
1643                         'partialarea' => $result->startfromarea,
1644                         'partialtime' => $result->startfromtime]);
1645                 $progress->output('Ending requested context: ' . $endmessage);
1647                 // The time limit must have expired, so stop looping.
1648                 break;
1649             }
1650         }
1651     }
1653     /**
1654      * Gets information about the request queue, in the form of a plain object suitable for passing
1655      * to a template for rendering.
1656      *
1657      * @return \stdClass Information about queued index requests
1658      */
1659     public function get_index_requests_info() {
1660         global $DB;
1662         $result = new \stdClass();
1664         $result->total = $DB->count_records('search_index_requests');
1665         $result->topten = $DB->get_records('search_index_requests', null,
1666                 'indexpriority DESC, timerequested, contextid, searcharea',
1667                 'id, contextid, timerequested, searcharea, partialarea, partialtime, indexpriority',
1668                 0, 10);
1669         foreach ($result->topten as $item) {
1670             $context = \context::instance_by_id($item->contextid);
1671             $item->contextlink = \html_writer::link($context->get_url(),
1672                     s($context->get_context_name()));
1673             if ($item->searcharea) {
1674                 $item->areaname = $this->get_search_area($item->searcharea)->get_visible_name();
1675             }
1676             if ($item->partialarea) {
1677                 $item->partialareaname = $this->get_search_area($item->partialarea)->get_visible_name();
1678             }
1679             switch ($item->indexpriority) {
1680                 case self::INDEX_PRIORITY_REINDEXING :
1681                     $item->priorityname = get_string('priority_reindexing', 'search');
1682                     break;
1683                 case self::INDEX_PRIORITY_NORMAL :
1684                     $item->priorityname = get_string('priority_normal', 'search');
1685                     break;
1686             }
1687         }
1689         // Normalise array indices.
1690         $result->topten = array_values($result->topten);
1692         if ($result->total > 10) {
1693             $result->ellipsis = true;
1694         }
1696         return $result;
1697     }
1699     /**
1700      * Gets current time for use in search system.
1701      *
1702      * Note: This should be replaced with generic core functionality once possible (see MDL-60644).
1703      *
1704      * @return float Current time in seconds (with decimals)
1705      */
1706     public static function get_current_time() {
1707         if (PHPUNIT_TEST && self::$phpunitfaketime) {
1708             return self::$phpunitfaketime;
1709         }
1710         return microtime(true);
1711     }
1713     /**
1714      * Check if search area categories functionality is enabled.
1715      *
1716      * @return bool
1717      */
1718     public static function is_search_area_categories_enabled() {
1719         return !empty(get_config('core', 'searchenablecategories'));
1720     }
1722     /**
1723      * Check if all results category should be hidden.
1724      *
1725      * @return bool
1726      */
1727     public static function should_hide_all_results_category() {
1728         return get_config('core', 'searchhideallcategory');
1729     }
1731     /**
1732      * Returns default search area category name.
1733      *
1734      * @return string
1735      */
1736     public static function get_default_area_category_name() {
1737         $default = get_config('core', 'searchdefaultcategory');
1739         if (empty($default)) {
1740             $default = self::SEARCH_AREA_CATEGORY_ALL;
1741         }
1743         if ($default == self::SEARCH_AREA_CATEGORY_ALL && self::should_hide_all_results_category()) {
1744             $default = self::SEARCH_AREA_CATEGORY_COURSE_CONTENT;
1745         }
1747         return $default;
1748     }
1750     /**
1751      * Get a list of all courses limited by ids if required.
1752      *
1753      * @param array|false $limitcourseids An array of course ids to limit the search to. False for no limiting.
1754      * @return array
1755      */
1756     protected function get_all_courses($limitcourseids) {
1757         global $DB;
1759         if ($limitcourseids) {
1760             list ($coursesql, $courseparams) = $DB->get_in_or_equal($limitcourseids);
1761             $coursesql = 'id ' . $coursesql;
1762         } else {
1763             $coursesql = '';
1764             $courseparams = [];
1765         }
1767         // Get courses using the same list of fields from enrol_get_my_courses.
1768         return $DB->get_records_select('course', $coursesql, $courseparams, '',
1769             'id, category, sortorder, shortname, fullname, idnumber, startdate, visible, ' .
1770             'groupmode, groupmodeforce, cacherev');
1771     }
1773     /**
1774      * Get a list of courses as user can access.
1775      *
1776      * @param bool $allaccessible Include courses user is not enrolled in, but can access.
1777      * @return array
1778      */
1779     protected function get_my_courses($allaccessible) {
1780         return enrol_get_my_courses(array('id', 'cacherev'), 'id', 0, [], $allaccessible);
1781     }
1783     /**
1784      * Check if search all courses setting is enabled.
1785      *
1786      * @return bool
1787      */
1788     public static function include_all_courses() {
1789         return !empty(get_config('core', 'searchincludeallcourses'));
1790     }
1792     /**
1793      * Cleans up non existing search area.
1794      *
1795      * 1. Remove all configs from {config_plugins} table.
1796      * 2. Delete all related indexed documents.
1797      *
1798      * @param string $areaid Search area id.
1799      */
1800     public static function clean_up_non_existing_area($areaid) {
1801         global $DB;
1803         if (!empty(self::get_search_area($areaid))) {
1804             throw new \coding_exception("Area $areaid exists. Please use appropriate search area class to manipulate the data.");
1805         }
1807         $parts = self::parse_areaid($areaid);
1809         $plugin = $parts[0];
1810         $configprefix = $parts[1];
1812         foreach (base::get_settingnames() as $settingname) {
1813             $name = $configprefix. $settingname;
1814             $DB->delete_records('config_plugins', ['name' => $name, 'plugin' => $plugin]);
1815         }
1817         $engine = self::instance()->get_engine();
1818         $engine->delete($areaid);
1819     }
1821     /**
1822      * Informs the search system that a context has been deleted.
1823      *
1824      * This will clear the data from the search index, where the search engine supports that.
1825      *
1826      * This function does not usually throw an exception (so as not to get in the way of the
1827      * context deletion finishing).
1828      *
1829      * This is called for all types of context deletion.
1830      *
1831      * @param \context $context Context object that has just been deleted
1832      */
1833     public static function context_deleted(\context $context) {
1834         if (self::is_indexing_enabled()) {
1835             try {
1836                 // Hold on, are we deleting a course? If so, and this context is part of the course,
1837                 // then don't bother to send a delete because we delete the whole course at once
1838                 // later.
1839                 if (!empty(self::$coursedeleting)) {
1840                     $coursecontext = $context->get_course_context(false);
1841                     if ($coursecontext && array_key_exists($coursecontext->instanceid, self::$coursedeleting)) {
1842                         // Skip further processing.
1843                         return;
1844                     }
1845                 }
1847                 $engine = self::instance()->get_engine();
1848                 $engine->delete_index_for_context($context->id);
1849             } catch (\moodle_exception $e) {
1850                 debugging('Error deleting search index data for context ' . $context->id . ': ' . $e->getMessage());
1851             }
1852         }
1853     }
1855     /**
1856      * Informs the search system that a course is about to be deleted.
1857      *
1858      * This prevents it from sending hundreds of 'delete context' updates for all the individual
1859      * contexts that are deleted.
1860      *
1861      * If you call this, you must call course_deleting_finish().
1862      *
1863      * @param int $courseid Course id that is being deleted
1864      */
1865     public static function course_deleting_start(int $courseid) {
1866         self::$coursedeleting[$courseid] = true;
1867     }
1869     /**
1870      * Informs the search engine that a course has now been deleted.
1871      *
1872      * This causes the search engine to actually delete the index for the whole course.
1873      *
1874      * @param int $courseid Course id that no longer exists
1875      */
1876     public static function course_deleting_finish(int $courseid) {
1877         if (!array_key_exists($courseid, self::$coursedeleting)) {
1878             // Show a debug warning. It doesn't actually matter very much, as we will now delete
1879             // the course data anyhow.
1880             debugging('course_deleting_start not called before deletion of ' . $courseid, DEBUG_DEVELOPER);
1881         }
1882         unset(self::$coursedeleting[$courseid]);
1884         if (self::is_indexing_enabled()) {
1885             try {
1886                 $engine = self::instance()->get_engine();
1887                 $engine->delete_index_for_course($courseid);
1888             } catch (\moodle_exception $e) {
1889                 debugging('Error deleting search index data for course ' . $courseid . ': ' . $e->getMessage());
1890             }
1891         }
1892     }