MDL-60913 search: add search area categories
[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 \core_search\engine
147      */
148     protected $engine = null;
150     /**
151      * Note: This should be removed once possible (see MDL-60644).
152      *
153      * @var float Fake current time for use in PHPunit tests
154      */
155     protected static $phpunitfaketime = 0;
157     /**
158      * Constructor, use \core_search\manager::instance instead to get a class instance.
159      *
160      * @param \core_search\base The search engine to use
161      */
162     public function __construct($engine) {
163         $this->engine = $engine;
164     }
166     /**
167      * @var int Record time of each successful schema check, but not more than once per 10 minutes.
168      */
169     const SCHEMA_CHECK_TRACKING_DELAY = 10 * 60;
171     /**
172      * @var int Require a new schema check at least every 4 hours.
173      */
174     const SCHEMA_CHECK_REQUIRED_EVERY = 4 * 3600;
176     /**
177      * Returns an initialised \core_search instance.
178      *
179      * While constructing the instance, checks on the search schema may be carried out. The $fast
180      * parameter provides a way to skip those checks on pages which are used frequently. It has
181      * no effect if an instance has already been constructed in this request.
182      *
183      * @see \core_search\engine::is_installed
184      * @see \core_search\engine::is_server_ready
185      * @param bool $fast Set to true when calling on a page that requires high performance
186      * @throws \core_search\engine_exception
187      * @return \core_search\manager
188      */
189     public static function instance($fast = false) {
190         global $CFG;
192         // One per request, this should be purged during testing.
193         if (static::$instance !== null) {
194             return static::$instance;
195         }
197         if (empty($CFG->searchengine)) {
198             throw new \core_search\engine_exception('enginenotselected', 'search');
199         }
201         if (!$engine = static::search_engine_instance()) {
202             throw new \core_search\engine_exception('enginenotfound', 'search', '', $CFG->searchengine);
203         }
205         // Get time now and at last schema check.
206         $now = (int)self::get_current_time();
207         $lastschemacheck = get_config($engine->get_plugin_name(), 'lastschemacheck');
209         // On pages where performance matters, tell the engine to skip schema checks.
210         $skipcheck = false;
211         if ($fast && $now < $lastschemacheck + self::SCHEMA_CHECK_REQUIRED_EVERY) {
212             $skipcheck = true;
213             $engine->skip_schema_check();
214         }
216         if (!$engine->is_installed()) {
217             throw new \core_search\engine_exception('enginenotinstalled', 'search', '', $CFG->searchengine);
218         }
220         $serverstatus = $engine->is_server_ready();
221         if ($serverstatus !== true) {
222             // Skip this error in Behat when faking seach results.
223             if (!defined('BEHAT_SITE_RUNNING') || !get_config('core_search', 'behat_fakeresult')) {
224                 // Clear the record of successful schema checks since it might have failed.
225                 unset_config('lastschemacheck', $engine->get_plugin_name());
226                 // Error message with no details as this is an exception that any user may find if the server crashes.
227                 throw new \core_search\engine_exception('engineserverstatus', 'search');
228             }
229         }
231         // If we did a successful schema check, record this, but not more than once per 10 minutes
232         // (to avoid updating the config db table/cache too often in case it gets called frequently).
233         if (!$skipcheck && $now >= $lastschemacheck + self::SCHEMA_CHECK_TRACKING_DELAY) {
234             set_config('lastschemacheck', $now, $engine->get_plugin_name());
235         }
237         static::$instance = new \core_search\manager($engine);
238         return static::$instance;
239     }
241     /**
242      * Returns whether global search is enabled or not.
243      *
244      * @return bool
245      */
246     public static function is_global_search_enabled() {
247         global $CFG;
248         return !empty($CFG->enableglobalsearch);
249     }
251     /**
252      * Returns whether indexing is enabled or not (you can enable indexing even when search is not
253      * enabled at the moment, so as to have it ready for students).
254      *
255      * @return bool True if indexing is enabled.
256      */
257     public static function is_indexing_enabled() {
258         global $CFG;
259         return !empty($CFG->enableglobalsearch) || !empty($CFG->searchindexwhendisabled);
260     }
262     /**
263      * Returns an instance of the search engine.
264      *
265      * @return \core_search\engine
266      */
267     public static function search_engine_instance() {
268         global $CFG;
270         $classname = '\\search_' . $CFG->searchengine . '\\engine';
271         if (!class_exists($classname)) {
272             return false;
273         }
275         return new $classname();
276     }
278     /**
279      * Returns the search engine.
280      *
281      * @return \core_search\engine
282      */
283     public function get_engine() {
284         return $this->engine;
285     }
287     /**
288      * Returns a search area class name.
289      *
290      * @param string $areaid
291      * @return string
292      */
293     protected static function get_area_classname($areaid) {
294         list($componentname, $areaname) = static::extract_areaid_parts($areaid);
295         return '\\' . $componentname . '\\search\\' . $areaname;
296     }
298     /**
299      * Returns a new area search indexer instance.
300      *
301      * @param string $areaid
302      * @return \core_search\base|bool False if the area is not available.
303      */
304     public static function get_search_area($areaid) {
306         // We have them all here.
307         if (!empty(static::$allsearchareas[$areaid])) {
308             return static::$allsearchareas[$areaid];
309         }
311         $classname = static::get_area_classname($areaid);
313         if (class_exists($classname) && static::is_search_area($classname)) {
314             return new $classname();
315         }
317         return false;
318     }
320     /**
321      * Return the list of available search areas.
322      *
323      * @param bool $enabled Return only the enabled ones.
324      * @return \core_search\base[]
325      */
326     public static function get_search_areas_list($enabled = false) {
328         // Two different arrays, we don't expect these arrays to be big.
329         if (static::$allsearchareas !== null) {
330             if (!$enabled) {
331                 return static::$allsearchareas;
332             } else {
333                 return static::$enabledsearchareas;
334             }
335         }
337         static::$allsearchareas = array();
338         static::$enabledsearchareas = array();
340         $plugintypes = \core_component::get_plugin_types();
341         foreach ($plugintypes as $plugintype => $unused) {
342             $plugins = \core_component::get_plugin_list($plugintype);
343             foreach ($plugins as $pluginname => $pluginfullpath) {
345                 $componentname = $plugintype . '_' . $pluginname;
346                 $searchclasses = \core_component::get_component_classes_in_namespace($componentname, 'search');
347                 foreach ($searchclasses as $classname => $classpath) {
348                     $areaname = substr(strrchr($classname, '\\'), 1);
350                     if (!static::is_search_area($classname)) {
351                         continue;
352                     }
354                     $areaid = static::generate_areaid($componentname, $areaname);
355                     $searchclass = new $classname();
357                     static::$allsearchareas[$areaid] = $searchclass;
358                     if ($searchclass->is_enabled()) {
359                         static::$enabledsearchareas[$areaid] = $searchclass;
360                     }
361                 }
362             }
363         }
365         $subsystems = \core_component::get_core_subsystems();
366         foreach ($subsystems as $subsystemname => $subsystempath) {
367             $componentname = 'core_' . $subsystemname;
368             $searchclasses = \core_component::get_component_classes_in_namespace($componentname, 'search');
370             foreach ($searchclasses as $classname => $classpath) {
371                 $areaname = substr(strrchr($classname, '\\'), 1);
373                 if (!static::is_search_area($classname)) {
374                     continue;
375                 }
377                 $areaid = static::generate_areaid($componentname, $areaname);
378                 $searchclass = new $classname();
379                 static::$allsearchareas[$areaid] = $searchclass;
380                 if ($searchclass->is_enabled()) {
381                     static::$enabledsearchareas[$areaid] = $searchclass;
382                 }
383             }
384         }
386         if ($enabled) {
387             return static::$enabledsearchareas;
388         }
389         return static::$allsearchareas;
390     }
392     /**
393      * Return search area category instance by category name.
394      *
395      * @param string $name Category name. If name is not valid will return default category.
396      *
397      * @return \core_search\area_category
398      */
399     public static function get_search_area_category_by_name($name) {
400         if (key_exists($name, self::get_search_area_categories())) {
401             return self::get_search_area_categories()[$name];
402         } else {
403             return self::get_search_area_categories()[self::get_default_area_category_name()];
404         }
405     }
407     /**
408      * Return a list of existing search area categories.
409      *
410      * @return \core_search\area_category[]
411      */
412     public static function get_search_area_categories() {
413         if (!isset(static::$searchareacategories)) {
414             $categories = self::get_core_search_area_categories();
416             // Go through all existing search areas and get categories they are assigned to.
417             $areacategories = [];
418             foreach (self::get_search_areas_list() as $searcharea) {
419                 foreach ($searcharea->get_category_names() as $categoryname) {
420                     if (!key_exists($categoryname, $areacategories)) {
421                         $areacategories[$categoryname] = [];
422                     }
424                     $areacategories[$categoryname][] = $searcharea;
425                 }
426             }
428             // Populate core categories by areas.
429             foreach ($areacategories as $name => $searchareas) {
430                 if (key_exists($name, $categories)) {
431                     $categories[$name]->set_areas($searchareas);
432                 } else {
433                     throw new \coding_exception('Unknown core search area category ' . $name);
434                 }
435             }
437             // Get additional categories.
438             $additionalcategories = self::get_additional_search_area_categories();
439             foreach ($additionalcategories as $additionalcategory) {
440                 if (!key_exists($additionalcategory->get_name(), $categories)) {
441                     $categories[$additionalcategory->get_name()] = $additionalcategory;
442                 }
443             }
445             // Remove categories without areas.
446             foreach ($categories as $key => $category) {
447                 if (empty($category->get_areas())) {
448                     unset($categories[$key]);
449                 }
450             }
452             // Sort categories by order.
453             uasort($categories, function($category1, $category2) {
454                 return $category1->get_order() > $category2->get_order();
455             });
457             static::$searchareacategories = $categories;
458         }
460         return static::$searchareacategories;
461     }
463     /**
464      * Get list of core search area categories.
465      *
466      * @return \core_search\area_category[]
467      */
468     protected static function get_core_search_area_categories() {
469         $categories = [];
471         $categories[self::SEARCH_AREA_CATEGORY_ALL] = new area_category(
472             self::SEARCH_AREA_CATEGORY_ALL,
473             get_string('core-all', 'search'),
474             0,
475             self::get_search_areas_list(true)
476         );
478         $categories[self::SEARCH_AREA_CATEGORY_COURSE_CONTENT] = new area_category(
479             self::SEARCH_AREA_CATEGORY_COURSE_CONTENT,
480             get_string('core-course-content', 'search'),
481             1
482         );
484         $categories[self::SEARCH_AREA_CATEGORY_COURSES] = new area_category(
485             self::SEARCH_AREA_CATEGORY_COURSES,
486             get_string('core-courses', 'search'),
487             2
488         );
490         $categories[self::SEARCH_AREA_CATEGORY_USERS] = new area_category(
491             self::SEARCH_AREA_CATEGORY_USERS,
492             get_string('core-users', 'search'),
493             3
494         );
496         $categories[self::SEARCH_AREA_CATEGORY_OTHER] = new area_category(
497             self::SEARCH_AREA_CATEGORY_OTHER,
498             get_string('core-other', 'search'),
499             4
500         );
502         return $categories;
503     }
505     /**
506      * Gets a list of additional search area categories.
507      *
508      * @return \core_search\area_category[]
509      */
510     protected static function get_additional_search_area_categories() {
511         $additionalcategories = [];
513         // Allow plugins to add custom search area categories.
514         if ($pluginsfunction = get_plugins_with_function('search_area_categories')) {
515             foreach ($pluginsfunction as $plugintype => $plugins) {
516                 foreach ($plugins as $pluginfunction) {
517                     $plugincategories = $pluginfunction();
518                     // We're expecting a list of valid area categories.
519                     if (is_array($plugincategories)) {
520                         foreach ($plugincategories as $plugincategory) {
521                             if (self::is_valid_area_category($plugincategory)) {
522                                 $additionalcategories[] = $plugincategory;
523                             } else {
524                                 throw  new \coding_exception('Invalid search area category!');
525                             }
526                         }
527                     } else {
528                         throw  new \coding_exception($pluginfunction . ' should return a list of search area categories!');
529                     }
530                 }
531             }
532         }
534         return $additionalcategories;
535     }
537     /**
538      * Check if provided instance of area category is valid.
539      *
540      * @param mixed $areacategory Area category instance. Potentially could be anything.
541      *
542      * @return bool
543      */
544     protected static function is_valid_area_category($areacategory) {
545         return $areacategory instanceof area_category;
546     }
548     /**
549      * Clears all static caches.
550      *
551      * @return void
552      */
553     public static function clear_static() {
555         static::$enabledsearchareas = null;
556         static::$allsearchareas = null;
557         static::$instance = null;
558         static::$searchareacategories = null;
560         base_block::clear_static();
561         engine::clear_users_cache();
562     }
564     /**
565      * Generates an area id from the componentname and the area name.
566      *
567      * There should not be any naming conflict as the area name is the
568      * class name in component/classes/search/.
569      *
570      * @param string $componentname
571      * @param string $areaname
572      * @return void
573      */
574     public static function generate_areaid($componentname, $areaname) {
575         return $componentname . '-' . $areaname;
576     }
578     /**
579      * Returns all areaid string components (component name and area name).
580      *
581      * @param string $areaid
582      * @return array Component name (Frankenstyle) and area name (search area class name)
583      */
584     public static function extract_areaid_parts($areaid) {
585         return explode('-', $areaid);
586     }
588     /**
589      * Returns information about the areas which the user can access.
590      *
591      * The returned value is a stdClass object with the following fields:
592      * - everything (bool, true for admin only)
593      * - usercontexts (indexed by area identifier then context
594      * - separategroupscontexts (contexts within which group restrictions apply)
595      * - visiblegroupscontextsareas (overrides to the above when the same contexts also have
596      *   'visible groups' for certain search area ids - hopefully rare)
597      * - usergroups (groups which the current user belongs to)
598      *
599      * The areas can be limited by course id and context id. If specifying context ids, results
600      * are limited to the exact context ids specified and not their children (for example, giving
601      * the course context id would result in including search items with the course context id, and
602      * not anything from a context inside the course). For performance, you should also specify
603      * course id(s) when using context ids.
604      *
605      * @param array|false $limitcourseids An array of course ids to limit the search to. False for no limiting.
606      * @param array|false $limitcontextids An array of context ids to limit the search to. False for no limiting.
607      * @return \stdClass Object as described above
608      */
609     protected function get_areas_user_accesses($limitcourseids = false, $limitcontextids = false) {
610         global $DB, $USER;
612         // All results for admins (unless they have chosen to limit results). Eventually we could
613         // add a new capability for managers.
614         if (is_siteadmin() && !$limitcourseids && !$limitcontextids) {
615             return (object)array('everything' => true);
616         }
618         $areasbylevel = array();
620         // Split areas by context level so we only iterate only once through courses and cms.
621         $searchareas = static::get_search_areas_list(true);
622         foreach ($searchareas as $areaid => $unused) {
623             $classname = static::get_area_classname($areaid);
624             $searcharea = new $classname();
625             foreach ($classname::get_levels() as $level) {
626                 $areasbylevel[$level][$areaid] = $searcharea;
627             }
628         }
630         // This will store area - allowed contexts relations.
631         $areascontexts = array();
633         // Initialise two special-case arrays for storing other information related to the contexts.
634         $separategroupscontexts = array();
635         $visiblegroupscontextsareas = array();
636         $usergroups = array();
638         if (empty($limitcourseids) && !empty($areasbylevel[CONTEXT_SYSTEM])) {
639             // We add system context to all search areas working at this level. Here each area is fully responsible of
640             // the access control as we can not automate much, we can not even check guest access as some areas might
641             // want to allow guests to retrieve data from them.
643             $systemcontextid = \context_system::instance()->id;
644             if (!$limitcontextids || in_array($systemcontextid, $limitcontextids)) {
645                 foreach ($areasbylevel[CONTEXT_SYSTEM] as $areaid => $searchclass) {
646                     $areascontexts[$areaid][$systemcontextid] = $systemcontextid;
647                 }
648             }
649         }
651         if (!empty($areasbylevel[CONTEXT_USER])) {
652             if ($usercontext = \context_user::instance($USER->id, IGNORE_MISSING)) {
653                 if (!$limitcontextids || in_array($usercontext->id, $limitcontextids)) {
654                     // Extra checking although only logged users should reach this point, guest users have a valid context id.
655                     foreach ($areasbylevel[CONTEXT_USER] as $areaid => $searchclass) {
656                         $areascontexts[$areaid][$usercontext->id] = $usercontext->id;
657                     }
658                 }
659             }
660         }
662         if (is_siteadmin()) {
663             // Admins have access to all courses regardless of enrolment.
664             if ($limitcourseids) {
665                 list ($coursesql, $courseparams) = $DB->get_in_or_equal($limitcourseids);
666                 $coursesql = 'id ' . $coursesql;
667             } else {
668                 $coursesql = '';
669                 $courseparams = [];
670             }
671             // Get courses using the same list of fields from enrol_get_my_courses.
672             $courses = $DB->get_records_select('course', $coursesql, $courseparams, '',
673                     'id, category, sortorder, shortname, fullname, idnumber, startdate, visible, ' .
674                     'groupmode, groupmodeforce, cacherev');
675         } else {
676             // Get the courses where the current user has access.
677             $courses = enrol_get_my_courses(array('id', 'cacherev'), 'id', 0, [],
678                     (bool)get_config('core', 'searchallavailablecourses'));
679         }
681         if (empty($limitcourseids) || in_array(SITEID, $limitcourseids)) {
682             $courses[SITEID] = get_course(SITEID);
683         }
685         // Keep a list of included course context ids (needed for the block calculation below).
686         $coursecontextids = [];
687         $modulecms = [];
689         foreach ($courses as $course) {
690             if (!empty($limitcourseids) && !in_array($course->id, $limitcourseids)) {
691                 // Skip non-included courses.
692                 continue;
693             }
695             $coursecontext = \context_course::instance($course->id);
696             $coursecontextids[] = $coursecontext->id;
697             $hasgrouprestrictions = false;
699             // Info about the course modules.
700             $modinfo = get_fast_modinfo($course);
702             if (!empty($areasbylevel[CONTEXT_COURSE]) &&
703                     (!$limitcontextids || in_array($coursecontext->id, $limitcontextids))) {
704                 // Add the course contexts the user can view.
705                 foreach ($areasbylevel[CONTEXT_COURSE] as $areaid => $searchclass) {
706                     if ($course->visible || has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
707                         $areascontexts[$areaid][$coursecontext->id] = $coursecontext->id;
708                     }
709                 }
710             }
712             if (!empty($areasbylevel[CONTEXT_MODULE])) {
713                 // Add the module contexts the user can view (cm_info->uservisible).
715                 foreach ($areasbylevel[CONTEXT_MODULE] as $areaid => $searchclass) {
717                     // Removing the plugintype 'mod_' prefix.
718                     $modulename = substr($searchclass->get_component_name(), 4);
720                     $modinstances = $modinfo->get_instances_of($modulename);
721                     foreach ($modinstances as $modinstance) {
722                         // Skip module context if not included in list of context ids.
723                         if ($limitcontextids && !in_array($modinstance->context->id, $limitcontextids)) {
724                             continue;
725                         }
726                         if ($modinstance->uservisible) {
727                             $contextid = $modinstance->context->id;
728                             $areascontexts[$areaid][$contextid] = $contextid;
729                             $modulecms[$modinstance->id] = $modinstance;
731                             if (!has_capability('moodle/site:accessallgroups', $modinstance->context) &&
732                                     ($searchclass instanceof base_mod) &&
733                                     $searchclass->supports_group_restriction()) {
734                                 if ($searchclass->restrict_cm_access_by_group($modinstance)) {
735                                     $separategroupscontexts[$contextid] = $contextid;
736                                     $hasgrouprestrictions = true;
737                                 } else {
738                                     // Track a list of anything that has a group id (so might get
739                                     // filtered) and doesn't want to be, in this context.
740                                     if (!array_key_exists($contextid, $visiblegroupscontextsareas)) {
741                                         $visiblegroupscontextsareas[$contextid] = array();
742                                     }
743                                     $visiblegroupscontextsareas[$contextid][$areaid] = $areaid;
744                                 }
745                             }
746                         }
747                     }
748                 }
749             }
751             // Insert group information for course (unless there aren't any modules restricted by
752             // group for this user in this course, in which case don't bother).
753             if ($hasgrouprestrictions) {
754                 $groups = groups_get_all_groups($course->id, $USER->id, 0, 'g.id');
755                 foreach ($groups as $group) {
756                     $usergroups[$group->id] = $group->id;
757                 }
758             }
759         }
761         // Chuck away all the 'visible groups contexts' data unless there is actually something
762         // that does use separate groups in the same context (this data is only used as an
763         // 'override' in cases where the search is restricting to separate groups).
764         foreach ($visiblegroupscontextsareas as $contextid => $areas) {
765             if (!array_key_exists($contextid, $separategroupscontexts)) {
766                 unset($visiblegroupscontextsareas[$contextid]);
767             }
768         }
770         // Add all supported block contexts, in a single query for performance.
771         if (!empty($areasbylevel[CONTEXT_BLOCK])) {
772             // Get list of all block types we care about.
773             $blocklist = [];
774             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
775                 $blocklist[$searchclass->get_block_name()] = true;
776             }
777             list ($blocknamesql, $blocknameparams) = $DB->get_in_or_equal(array_keys($blocklist));
779             // Get list of course contexts.
780             list ($contextsql, $contextparams) = $DB->get_in_or_equal($coursecontextids);
782             // Get list of block context (if limited).
783             $blockcontextwhere = '';
784             $blockcontextparams = [];
785             if ($limitcontextids) {
786                 list ($blockcontextsql, $blockcontextparams) = $DB->get_in_or_equal($limitcontextids);
787                 $blockcontextwhere = 'AND x.id ' . $blockcontextsql;
788             }
790             // Query all blocks that are within an included course, and are set to be visible, and
791             // in a supported page type (basically just course view). This query could be
792             // extended (or a second query added) to support blocks that are within a module
793             // context as well, and we could add more page types if required.
794             $blockrecs = $DB->get_records_sql("
795                         SELECT x.*, bi.blockname AS blockname, bi.id AS blockinstanceid
796                           FROM {block_instances} bi
797                           JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
798                      LEFT JOIN {block_positions} bp ON bp.blockinstanceid = bi.id
799                                AND bp.contextid = bi.parentcontextid
800                                AND bp.pagetype LIKE 'course-view-%'
801                                AND bp.subpage = ''
802                                AND bp.visible = 0
803                          WHERE bi.parentcontextid $contextsql
804                                $blockcontextwhere
805                                AND bi.blockname $blocknamesql
806                                AND bi.subpagepattern IS NULL
807                                AND (bi.pagetypepattern = 'site-index'
808                                    OR bi.pagetypepattern LIKE 'course-view-%'
809                                    OR bi.pagetypepattern = 'course-*'
810                                    OR bi.pagetypepattern = '*')
811                                AND bp.id IS NULL",
812                     array_merge([CONTEXT_BLOCK], $contextparams, $blockcontextparams, $blocknameparams));
813             $blockcontextsbyname = [];
814             foreach ($blockrecs as $blockrec) {
815                 if (empty($blockcontextsbyname[$blockrec->blockname])) {
816                     $blockcontextsbyname[$blockrec->blockname] = [];
817                 }
818                 \context_helper::preload_from_record($blockrec);
819                 $blockcontextsbyname[$blockrec->blockname][] = \context_block::instance(
820                         $blockrec->blockinstanceid);
821             }
823             // Add the block contexts the user can view.
824             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
825                 if (empty($blockcontextsbyname[$searchclass->get_block_name()])) {
826                     continue;
827                 }
828                 foreach ($blockcontextsbyname[$searchclass->get_block_name()] as $context) {
829                     if (has_capability('moodle/block:view', $context)) {
830                         $areascontexts[$areaid][$context->id] = $context->id;
831                     }
832                 }
833             }
834         }
836         // Return all the data.
837         return (object)array('everything' => false, 'usercontexts' => $areascontexts,
838                 'separategroupscontexts' => $separategroupscontexts, 'usergroups' => $usergroups,
839                 'visiblegroupscontextsareas' => $visiblegroupscontextsareas);
840     }
842     /**
843      * Returns requested page of documents plus additional information for paging.
844      *
845      * This function does not perform any kind of security checking for access, the caller code
846      * should check that the current user have moodle/search:query capability.
847      *
848      * If a page is requested that is beyond the last result, the last valid page is returned in
849      * results, and actualpage indicates which page was returned.
850      *
851      * @param stdClass $formdata
852      * @param int $pagenum The 0 based page number.
853      * @return object An object with 3 properties:
854      *                    results    => An array of \core_search\documents for the actual page.
855      *                    totalcount => Number of records that are possibly available, to base paging on.
856      *                    actualpage => The actual page returned.
857      */
858     public function paged_search(\stdClass $formdata, $pagenum) {
859         $out = new \stdClass();
861         if (self::is_search_area_categories_enabled() && !empty($formdata->cat)) {
862             $cat = self::get_search_area_category_by_name($formdata->cat);
863             if (empty($formdata->areaids)) {
864                 $formdata->areaids = array_keys($cat->get_areas());
865             } else {
866                 foreach ($formdata->areaids as $key => $areaid) {
867                     if (!key_exists($areaid, $cat->get_areas())) {
868                         unset($formdata->areaids[$key]);
869                     }
870                 }
871             }
872         }
874         $perpage = static::DISPLAY_RESULTS_PER_PAGE;
876         // Make sure we only allow request up to max page.
877         $pagenum = min($pagenum, (static::MAX_RESULTS / $perpage) - 1);
879         // Calculate the first and last document number for the current page, 1 based.
880         $mindoc = ($pagenum * $perpage) + 1;
881         $maxdoc = ($pagenum + 1) * $perpage;
883         // Get engine documents, up to max.
884         $docs = $this->search($formdata, $maxdoc);
886         $resultcount = count($docs);
887         if ($resultcount < $maxdoc) {
888             // This means it couldn't give us results to max, so the count must be the max.
889             $out->totalcount = $resultcount;
890         } else {
891             // Get the possible count reported by engine, and limit to our max.
892             $out->totalcount = $this->engine->get_query_total_count();
893             $out->totalcount = min($out->totalcount, static::MAX_RESULTS);
894         }
896         // Determine the actual page.
897         if ($resultcount < $mindoc) {
898             // We couldn't get the min docs for this page, so determine what page we can get.
899             $out->actualpage = floor(($resultcount - 1) / $perpage);
900         } else {
901             $out->actualpage = $pagenum;
902         }
904         // Split the results to only return the page.
905         $out->results = array_slice($docs, $out->actualpage * $perpage, $perpage, true);
907         return $out;
908     }
910     /**
911      * Returns documents from the engine based on the data provided.
912      *
913      * This function does not perform any kind of security checking, the caller code
914      * should check that the current user have moodle/search:query capability.
915      *
916      * It might return the results from the cache instead.
917      *
918      * Valid formdata options include:
919      * - q (query text)
920      * - courseids (optional list of course ids to restrict)
921      * - contextids (optional list of context ids to restrict)
922      * - context (Moodle context object for location user searched from)
923      * - order (optional ordering, one of the types supported by the search engine e.g. 'relevance')
924      * - userids (optional list of user ids to restrict)
925      *
926      * @param \stdClass $formdata Query input data (usually from search form)
927      * @param int $limit The maximum number of documents to return
928      * @return \core_search\document[]
929      */
930     public function search(\stdClass $formdata, $limit = 0) {
931         // For Behat testing, the search results can be faked using a special step.
932         if (defined('BEHAT_SITE_RUNNING')) {
933             $fakeresult = get_config('core_search', 'behat_fakeresult');
934             if ($fakeresult) {
935                 // Clear config setting.
936                 unset_config('core_search', 'behat_fakeresult');
938                 // Check query matches expected value.
939                 $details = json_decode($fakeresult);
940                 if ($formdata->q !== $details->query) {
941                     throw new \coding_exception('Unexpected search query: ' . $formdata->q);
942                 }
944                 // Create search documents from the JSON data.
945                 $docs = [];
946                 foreach ($details->results as $result) {
947                     $doc = new \core_search\document($result->itemid, $result->componentname,
948                             $result->areaname);
949                     foreach ((array)$result->fields as $field => $value) {
950                         $doc->set($field, $value);
951                     }
952                     foreach ((array)$result->extrafields as $field => $value) {
953                         $doc->set_extra($field, $value);
954                     }
955                     $area = $this->get_search_area($doc->get('areaid'));
956                     $doc->set_doc_url($area->get_doc_url($doc));
957                     $doc->set_context_url($area->get_context_url($doc));
958                     $docs[] = $doc;
959                 }
961                 return $docs;
962             }
963         }
965         $limitcourseids = false;
966         if (!empty($formdata->courseids)) {
967             $limitcourseids = $formdata->courseids;
968         }
970         $limitcontextids = false;
971         if (!empty($formdata->contextids)) {
972             $limitcontextids = $formdata->contextids;
973         }
975         // Clears previous query errors.
976         $this->engine->clear_query_error();
978         $contextinfo = $this->get_areas_user_accesses($limitcourseids, $limitcontextids);
979         if (!$contextinfo->everything && !$contextinfo->usercontexts) {
980             // User can not access any context.
981             $docs = array();
982         } else {
983             // If engine does not support groups, remove group information from the context info -
984             // use the old format instead (true = admin, array = user contexts).
985             if (!$this->engine->supports_group_filtering()) {
986                 $contextinfo = $contextinfo->everything ? true : $contextinfo->usercontexts;
987             }
989             // Execute the actual query.
990             $docs = $this->engine->execute_query($formdata, $contextinfo, $limit);
991         }
993         return $docs;
994     }
996     /**
997      * Merge separate index segments into one.
998      */
999     public function optimize_index() {
1000         $this->engine->optimize();
1001     }
1003     /**
1004      * Index all documents.
1005      *
1006      * @param bool $fullindex Whether we should reindex everything or not.
1007      * @param float $timelimit Time limit in seconds (0 = no time limit)
1008      * @param \progress_trace|null $progress Optional class for tracking progress
1009      * @throws \moodle_exception
1010      * @return bool Whether there was any updated document or not.
1011      */
1012     public function index($fullindex = false, $timelimit = 0, \progress_trace $progress = null) {
1013         global $DB;
1015         // Cannot combine time limit with reindex.
1016         if ($timelimit && $fullindex) {
1017             throw new \coding_exception('Cannot apply time limit when reindexing');
1018         }
1019         if (!$progress) {
1020             $progress = new \null_progress_trace();
1021         }
1023         // Unlimited time.
1024         \core_php_time_limit::raise();
1026         // Notify the engine that an index starting.
1027         $this->engine->index_starting($fullindex);
1029         $sumdocs = 0;
1031         $searchareas = $this->get_search_areas_list(true);
1033         if ($timelimit) {
1034             // If time is limited (and therefore we're not just indexing everything anyway), select
1035             // an order for search areas. The intention here is to avoid a situation where a new
1036             // large search area is enabled, and this means all our other search areas go out of
1037             // date while that one is being indexed. To do this, we order by the time we spent
1038             // indexing them last time we ran, meaning anything that took a very long time will be
1039             // done last.
1040             uasort($searchareas, function(\core_search\base $area1, \core_search\base $area2) {
1041                 return (int)$area1->get_last_indexing_duration() - (int)$area2->get_last_indexing_duration();
1042             });
1044             // Decide time to stop.
1045             $stopat = self::get_current_time() + $timelimit;
1046         }
1048         foreach ($searchareas as $areaid => $searcharea) {
1050             $progress->output('Processing area: ' . $searcharea->get_visible_name());
1052             // Notify the engine that an area is starting.
1053             $this->engine->area_index_starting($searcharea, $fullindex);
1055             $indexingstart = (int)self::get_current_time();
1056             $elapsed = self::get_current_time();
1058             // This is used to store this component config.
1059             list($componentconfigname, $varname) = $searcharea->get_config_var_name();
1061             $prevtimestart = intval(get_config($componentconfigname, $varname . '_indexingstart'));
1063             if ($fullindex === true) {
1064                 $referencestarttime = 0;
1066                 // For full index, we delete any queued context index requests, as those will
1067                 // obviously be met by the full index.
1068                 $DB->delete_records('search_index_requests');
1069             } else {
1070                 $partial = get_config($componentconfigname, $varname . '_partial');
1071                 if ($partial) {
1072                     // When the previous index did not complete all data, we start from the time of the
1073                     // last document that was successfully indexed. (Note this will result in
1074                     // re-indexing that one document, but we can't avoid that because there may be
1075                     // other documents in the same second.)
1076                     $referencestarttime = intval(get_config($componentconfigname, $varname . '_lastindexrun'));
1077                 } else {
1078                     $referencestarttime = $prevtimestart;
1079                 }
1080             }
1082             // Getting the recordset from the area.
1083             $recordset = $searcharea->get_recordset_by_timestamp($referencestarttime);
1084             $initialquerytime = self::get_current_time() - $elapsed;
1085             if ($initialquerytime > self::DISPLAY_LONG_QUERY_TIME) {
1086                 $progress->output('Initial query took ' . round($initialquerytime, 1) .
1087                         ' seconds.', 1);
1088             }
1090             // Pass get_document as callback.
1091             $fileindexing = $this->engine->file_indexing_enabled() && $searcharea->uses_file_indexing();
1092             $options = array('indexfiles' => $fileindexing, 'lastindexedtime' => $prevtimestart);
1093             if ($timelimit) {
1094                 $options['stopat'] = $stopat;
1095             }
1096             $options['progress'] = $progress;
1097             $iterator = new skip_future_documents_iterator(new \core\dml\recordset_walk(
1098                     $recordset, array($searcharea, 'get_document'), $options));
1099             $result = $this->engine->add_documents($iterator, $searcharea, $options);
1100             $recordset->close();
1101             if (count($result) === 5) {
1102                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial) = $result;
1103             } else {
1104                 // Backward compatibility for engines that don't support partial adding.
1105                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
1106                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
1107                         DEBUG_DEVELOPER);
1108                 $partial = false;
1109             }
1111             if ($numdocs > 0) {
1112                 $elapsed = round((self::get_current_time() - $elapsed), 1);
1114                 $partialtext = '';
1115                 if ($partial) {
1116                     $partialtext = ' (not complete; done to ' . userdate($lastindexeddoc,
1117                             get_string('strftimedatetimeshort', 'langconfig')) . ')';
1118                 }
1120                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
1121                         ' documents, in ' . $elapsed . ' seconds' . $partialtext . '.', 1);
1122             } else {
1123                 $progress->output('No new documents to index.', 1);
1124             }
1126             // Notify the engine this area is complete, and only mark times if true.
1127             if ($this->engine->area_index_complete($searcharea, $numdocs, $fullindex)) {
1128                 $sumdocs += $numdocs;
1130                 // Store last index run once documents have been committed to the search engine.
1131                 set_config($varname . '_indexingstart', $indexingstart, $componentconfigname);
1132                 set_config($varname . '_indexingend', (int)self::get_current_time(), $componentconfigname);
1133                 set_config($varname . '_docsignored', $numdocsignored, $componentconfigname);
1134                 set_config($varname . '_docsprocessed', $numdocs, $componentconfigname);
1135                 set_config($varname . '_recordsprocessed', $numrecords, $componentconfigname);
1136                 if ($lastindexeddoc > 0) {
1137                     set_config($varname . '_lastindexrun', $lastindexeddoc, $componentconfigname);
1138                 }
1139                 if ($partial) {
1140                     set_config($varname . '_partial', 1, $componentconfigname);
1141                 } else {
1142                     unset_config($varname . '_partial', $componentconfigname);
1143                 }
1144             } else {
1145                 $progress->output('Engine reported error.');
1146             }
1148             if ($timelimit && (self::get_current_time() >= $stopat)) {
1149                 $progress->output('Stopping indexing due to time limit.');
1150                 break;
1151             }
1152         }
1154         if ($sumdocs > 0) {
1155             $event = \core\event\search_indexed::create(
1156                     array('context' => \context_system::instance()));
1157             $event->trigger();
1158         }
1160         $this->engine->index_complete($sumdocs, $fullindex);
1162         return (bool)$sumdocs;
1163     }
1165     /**
1166      * Indexes or reindexes a specific context of the system, e.g. one course.
1167      *
1168      * The function returns an object with field 'complete' (true or false).
1169      *
1170      * This function supports partial indexing via the time limit parameter. If the time limit
1171      * expires, it will return values for $startfromarea and $startfromtime which can be passed
1172      * next time to continue indexing.
1173      *
1174      * @param \context $context Context to restrict index.
1175      * @param string $singleareaid If specified, indexes only the given area.
1176      * @param float $timelimit Time limit in seconds (0 = no time limit)
1177      * @param \progress_trace|null $progress Optional class for tracking progress
1178      * @param string $startfromarea Area to start from
1179      * @param int $startfromtime Timestamp to start from
1180      * @return \stdClass Object indicating success
1181      */
1182     public function index_context($context, $singleareaid = '', $timelimit = 0,
1183             \progress_trace $progress = null, $startfromarea = '', $startfromtime = 0) {
1184         if (!$progress) {
1185             $progress = new \null_progress_trace();
1186         }
1188         // Work out time to stop, if limited.
1189         if ($timelimit) {
1190             // Decide time to stop.
1191             $stopat = self::get_current_time() + $timelimit;
1192         }
1194         // No PHP time limit.
1195         \core_php_time_limit::raise();
1197         // Notify the engine that an index starting.
1198         $this->engine->index_starting(false);
1200         $sumdocs = 0;
1202         // Get all search areas, in consistent order.
1203         $searchareas = $this->get_search_areas_list(true);
1204         ksort($searchareas);
1206         // Are we skipping past some that were handled previously?
1207         $skipping = $startfromarea ? true : false;
1209         foreach ($searchareas as $areaid => $searcharea) {
1210             // If we're only processing one area id, skip all the others.
1211             if ($singleareaid && $singleareaid !== $areaid) {
1212                 continue;
1213             }
1215             // If we're skipping to a later area, continue through the loop.
1216             $referencestarttime = 0;
1217             if ($skipping) {
1218                 if ($areaid !== $startfromarea) {
1219                     continue;
1220                 }
1221                 // Stop skipping and note the reference start time.
1222                 $skipping = false;
1223                 $referencestarttime = $startfromtime;
1224             }
1226             $progress->output('Processing area: ' . $searcharea->get_visible_name());
1228             $elapsed = self::get_current_time();
1230             // Get the recordset of all documents from the area for this context.
1231             $recordset = $searcharea->get_document_recordset($referencestarttime, $context);
1232             if (!$recordset) {
1233                 if ($recordset === null) {
1234                     $progress->output('Skipping (not relevant to context).', 1);
1235                 } else {
1236                     $progress->output('Skipping (does not support context indexing).', 1);
1237                 }
1238                 continue;
1239             }
1241             // Notify the engine that an area is starting.
1242             $this->engine->area_index_starting($searcharea, false);
1244             // Work out search options.
1245             $options = [];
1246             $options['indexfiles'] = $this->engine->file_indexing_enabled() &&
1247                     $searcharea->uses_file_indexing();
1248             if ($timelimit) {
1249                 $options['stopat'] = $stopat;
1250             }
1252             // Construct iterator which will use get_document on the recordset results.
1253             $iterator = new \core\dml\recordset_walk($recordset,
1254                     array($searcharea, 'get_document'), $options);
1256             // Use this iterator to add documents.
1257             $result = $this->engine->add_documents($iterator, $searcharea, $options);
1258             if (count($result) === 5) {
1259                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial) = $result;
1260             } else {
1261                 // Backward compatibility for engines that don't support partial adding.
1262                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
1263                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
1264                         DEBUG_DEVELOPER);
1265                 $partial = false;
1266             }
1268             if ($numdocs > 0) {
1269                 $elapsed = round((self::get_current_time() - $elapsed), 3);
1270                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
1271                         ' documents, in ' . $elapsed . ' seconds' .
1272                         ($partial ? ' (not complete)' : '') . '.', 1);
1273             } else {
1274                 $progress->output('No documents to index.', 1);
1275             }
1277             // Notify the engine this area is complete, but don't store any times as this is not
1278             // part of the 'normal' search index.
1279             if (!$this->engine->area_index_complete($searcharea, $numdocs, false)) {
1280                 $progress->output('Engine reported error.', 1);
1281             }
1283             if ($partial && $timelimit && (self::get_current_time() >= $stopat)) {
1284                 $progress->output('Stopping indexing due to time limit.');
1285                 break;
1286             }
1287         }
1289         if ($sumdocs > 0) {
1290             $event = \core\event\search_indexed::create(
1291                     array('context' => $context));
1292             $event->trigger();
1293         }
1295         $this->engine->index_complete($sumdocs, false);
1297         // Indicate in result whether we completed indexing, or only part of it.
1298         $result = new \stdClass();
1299         if ($partial) {
1300             $result->complete = false;
1301             $result->startfromarea = $areaid;
1302             $result->startfromtime = $lastindexeddoc;
1303         } else {
1304             $result->complete = true;
1305         }
1306         return $result;
1307     }
1309     /**
1310      * Resets areas config.
1311      *
1312      * @throws \moodle_exception
1313      * @param string $areaid
1314      * @return void
1315      */
1316     public function reset_config($areaid = false) {
1318         if (!empty($areaid)) {
1319             $searchareas = array();
1320             if (!$searchareas[$areaid] = static::get_search_area($areaid)) {
1321                 throw new \moodle_exception('errorareanotavailable', 'search', '', $areaid);
1322             }
1323         } else {
1324             // Only the enabled ones.
1325             $searchareas = static::get_search_areas_list(true);
1326         }
1328         foreach ($searchareas as $searcharea) {
1329             list($componentname, $varname) = $searcharea->get_config_var_name();
1330             $config = $searcharea->get_config();
1332             foreach ($config as $key => $value) {
1333                 // We reset them all but the enable/disabled one.
1334                 if ($key !== $varname . '_enabled') {
1335                     set_config($key, 0, $componentname);
1336                 }
1337             }
1338         }
1339     }
1341     /**
1342      * Deletes an area's documents or all areas documents.
1343      *
1344      * @param string $areaid The area id or false for all
1345      * @return void
1346      */
1347     public function delete_index($areaid = false) {
1348         if (!empty($areaid)) {
1349             $this->engine->delete($areaid);
1350             $this->reset_config($areaid);
1351         } else {
1352             $this->engine->delete();
1353             $this->reset_config();
1354         }
1355     }
1357     /**
1358      * Deletes index by id.
1359      *
1360      * @param int Solr Document string $id
1361      */
1362     public function delete_index_by_id($id) {
1363         $this->engine->delete_by_id($id);
1364     }
1366     /**
1367      * Returns search areas configuration.
1368      *
1369      * @param \core_search\base[] $searchareas
1370      * @return \stdClass[] $configsettings
1371      */
1372     public function get_areas_config($searchareas) {
1374         $vars = array('indexingstart', 'indexingend', 'lastindexrun', 'docsignored',
1375                 'docsprocessed', 'recordsprocessed', 'partial');
1377         $configsettings = [];
1378         foreach ($searchareas as $searcharea) {
1380             $areaid = $searcharea->get_area_id();
1382             $configsettings[$areaid] = new \stdClass();
1383             list($componentname, $varname) = $searcharea->get_config_var_name();
1385             if (!$searcharea->is_enabled()) {
1386                 // We delete all indexed data on disable so no info.
1387                 foreach ($vars as $var) {
1388                     $configsettings[$areaid]->{$var} = 0;
1389                 }
1390             } else {
1391                 foreach ($vars as $var) {
1392                     $configsettings[$areaid]->{$var} = get_config($componentname, $varname .'_' . $var);
1393                 }
1394             }
1396             // Formatting the time.
1397             if (!empty($configsettings[$areaid]->lastindexrun)) {
1398                 $configsettings[$areaid]->lastindexrun = userdate($configsettings[$areaid]->lastindexrun);
1399             } else {
1400                 $configsettings[$areaid]->lastindexrun = get_string('never');
1401             }
1402         }
1403         return $configsettings;
1404     }
1406     /**
1407      * Triggers search_results_viewed event
1408      *
1409      * Other data required:
1410      * - q: The query string
1411      * - page: The page number
1412      * - title: Title filter
1413      * - areaids: Search areas filter
1414      * - courseids: Courses filter
1415      * - timestart: Time start filter
1416      * - timeend: Time end filter
1417      *
1418      * @since Moodle 3.2
1419      * @param array $other Other info for the event.
1420      * @return \core\event\search_results_viewed
1421      */
1422     public static function trigger_search_results_viewed($other) {
1423         $event = \core\event\search_results_viewed::create([
1424             'context' => \context_system::instance(),
1425             'other' => $other
1426         ]);
1427         $event->trigger();
1429         return $event;
1430     }
1432     /**
1433      * Checks whether a classname is of an actual search area.
1434      *
1435      * @param string $classname
1436      * @return bool
1437      */
1438     protected static function is_search_area($classname) {
1439         if (is_subclass_of($classname, 'core_search\base')) {
1440             return (new \ReflectionClass($classname))->isInstantiable();
1441         }
1443         return false;
1444     }
1446     /**
1447      * Requests that a specific context is indexed by the scheduled task. The context will be
1448      * added to a queue which is processed by the task.
1449      *
1450      * This is used after a restore to ensure that restored items are indexed, even though their
1451      * modified time will be older than the latest indexed. It is also used by the 'Gradual reindex'
1452      * admin feature from the search areas screen.
1453      *
1454      * @param \context $context Context to index within
1455      * @param string $areaid Area to index, '' = all areas
1456      * @param int $priority Priority (INDEX_PRIORITY_xx constant)
1457      */
1458     public static function request_index(\context $context, $areaid = '',
1459             $priority = self::INDEX_PRIORITY_NORMAL) {
1460         global $DB;
1462         // Check through existing requests for this context or any parent context.
1463         list ($contextsql, $contextparams) = $DB->get_in_or_equal(
1464                 $context->get_parent_context_ids(true));
1465         $existing = $DB->get_records_select('search_index_requests',
1466                 'contextid ' . $contextsql, $contextparams, '',
1467                 'id, searcharea, partialarea, indexpriority');
1468         foreach ($existing as $rec) {
1469             // If we haven't started processing the existing request yet, and it covers the same
1470             // area (or all areas) then that will be sufficient so don't add anything else.
1471             if ($rec->partialarea === '' && ($rec->searcharea === $areaid || $rec->searcharea === '')) {
1472                 // If the existing request has the same (or higher) priority, no need to add anything.
1473                 if ($rec->indexpriority >= $priority) {
1474                     return;
1475                 }
1476                 // The existing request has lower priority. If it is exactly the same, then just
1477                 // adjust the priority of the existing request.
1478                 if ($rec->searcharea === $areaid) {
1479                     $DB->set_field('search_index_requests', 'indexpriority', $priority,
1480                             ['id' => $rec->id]);
1481                     return;
1482                 }
1483                 // The existing request would cover this area but is a lower priority. We need to
1484                 // add the new request even though that means we will index part of it twice.
1485             }
1486         }
1488         // No suitable existing request, so add a new one.
1489         $newrecord = [ 'contextid' => $context->id, 'searcharea' => $areaid,
1490                 'timerequested' => (int)self::get_current_time(),
1491                 'partialarea' => '', 'partialtime' => 0,
1492                 'indexpriority' => $priority ];
1493         $DB->insert_record('search_index_requests', $newrecord);
1494     }
1496     /**
1497      * Processes outstanding index requests. This will take the first item from the queue (taking
1498      * account the indexing priority) and process it, continuing until an optional time limit is
1499      * reached.
1500      *
1501      * If there are no index requests, the function will do nothing.
1502      *
1503      * @param float $timelimit Time limit (0 = none)
1504      * @param \progress_trace|null $progress Optional progress indicator
1505      */
1506     public function process_index_requests($timelimit = 0.0, \progress_trace $progress = null) {
1507         global $DB;
1509         if (!$progress) {
1510             $progress = new \null_progress_trace();
1511         }
1513         $before = self::get_current_time();
1514         if ($timelimit) {
1515             $stopat = $before + $timelimit;
1516         }
1517         while (true) {
1518             // Retrieve first request, using fully defined ordering.
1519             $requests = $DB->get_records('search_index_requests', null,
1520                     'indexpriority DESC, timerequested, contextid, searcharea',
1521                     'id, contextid, searcharea, partialarea, partialtime', 0, 1);
1522             if (!$requests) {
1523                 // If there are no more requests, stop.
1524                 break;
1525             }
1526             $request = reset($requests);
1528             // Calculate remaining time.
1529             $remainingtime = 0;
1530             $beforeindex = self::get_current_time();
1531             if ($timelimit) {
1532                 $remainingtime = $stopat - $beforeindex;
1534                 // If the time limit expired already, stop now. (Otherwise we might accidentally
1535                 // index with no time limit or a negative time limit.)
1536                 if ($remainingtime <= 0) {
1537                     break;
1538                 }
1539             }
1541             // Show a message before each request, indicating what will be indexed.
1542             $context = \context::instance_by_id($request->contextid, IGNORE_MISSING);
1543             if (!$context) {
1544                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1545                 $progress->output('Skipped deleted context: ' . $request->contextid);
1546                 continue;
1547             }
1548             $contextname = $context->get_context_name();
1549             if ($request->searcharea) {
1550                 $contextname .= ' (search area: ' . $request->searcharea . ')';
1551             }
1552             $progress->output('Indexing requested context: ' . $contextname);
1554             // Actually index the context.
1555             $result = $this->index_context($context, $request->searcharea, $remainingtime,
1556                     $progress, $request->partialarea, $request->partialtime);
1558             // Work out shared part of message.
1559             $endmessage = $contextname . ' (' . round(self::get_current_time() - $beforeindex, 1) . 's)';
1561             // Update database table and continue/stop as appropriate.
1562             if ($result->complete) {
1563                 // If we completed the request, remove it from the table.
1564                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1565                 $progress->output('Completed requested context: ' . $endmessage);
1566             } else {
1567                 // If we didn't complete the request, store the partial details (how far it got).
1568                 $DB->update_record('search_index_requests', ['id' => $request->id,
1569                         'partialarea' => $result->startfromarea,
1570                         'partialtime' => $result->startfromtime]);
1571                 $progress->output('Ending requested context: ' . $endmessage);
1573                 // The time limit must have expired, so stop looping.
1574                 break;
1575             }
1576         }
1577     }
1579     /**
1580      * Gets information about the request queue, in the form of a plain object suitable for passing
1581      * to a template for rendering.
1582      *
1583      * @return \stdClass Information about queued index requests
1584      */
1585     public function get_index_requests_info() {
1586         global $DB;
1588         $result = new \stdClass();
1590         $result->total = $DB->count_records('search_index_requests');
1591         $result->topten = $DB->get_records('search_index_requests', null,
1592                 'indexpriority DESC, timerequested, contextid, searcharea',
1593                 'id, contextid, timerequested, searcharea, partialarea, partialtime, indexpriority',
1594                 0, 10);
1595         foreach ($result->topten as $item) {
1596             $context = \context::instance_by_id($item->contextid);
1597             $item->contextlink = \html_writer::link($context->get_url(),
1598                     s($context->get_context_name()));
1599             if ($item->searcharea) {
1600                 $item->areaname = $this->get_search_area($item->searcharea)->get_visible_name();
1601             }
1602             if ($item->partialarea) {
1603                 $item->partialareaname = $this->get_search_area($item->partialarea)->get_visible_name();
1604             }
1605             switch ($item->indexpriority) {
1606                 case self::INDEX_PRIORITY_REINDEXING :
1607                     $item->priorityname = get_string('priority_reindexing', 'search');
1608                     break;
1609                 case self::INDEX_PRIORITY_NORMAL :
1610                     $item->priorityname = get_string('priority_normal', 'search');
1611                     break;
1612             }
1613         }
1615         // Normalise array indices.
1616         $result->topten = array_values($result->topten);
1618         if ($result->total > 10) {
1619             $result->ellipsis = true;
1620         }
1622         return $result;
1623     }
1625     /**
1626      * Gets current time for use in search system.
1627      *
1628      * Note: This should be replaced with generic core functionality once possible (see MDL-60644).
1629      *
1630      * @return float Current time in seconds (with decimals)
1631      */
1632     public static function get_current_time() {
1633         if (PHPUNIT_TEST && self::$phpunitfaketime) {
1634             return self::$phpunitfaketime;
1635         }
1636         return microtime(true);
1637     }
1639     /**
1640      * Check if search area categories functionality is enabled.
1641      *
1642      * @return bool
1643      */
1644     public static function is_search_area_categories_enabled() {
1645         return !empty(get_config('core', 'searchenablecategories'));
1646     }
1648     /**
1649      * Check if all results category should be hidden.
1650      *
1651      * @return bool
1652      */
1653     public static function should_hide_all_results_category() {
1654         return get_config('core', 'searchhideallcategory');
1655     }
1657     /**
1658      * Returns default search area category name.
1659      *
1660      * @return string
1661      */
1662     public static function get_default_area_category_name() {
1663         $default = get_config('core', 'searchdefaultcategory');
1665         if (empty($default)) {
1666             $default = self::SEARCH_AREA_CATEGORY_ALL;
1667         }
1669         if ($default == self::SEARCH_AREA_CATEGORY_ALL && self::should_hide_all_results_category()) {
1670             $default = self::SEARCH_AREA_CATEGORY_COURSE_CONTENT;
1671         }
1673         return $default;
1674     }