5345b6cbd5e5f168dd18dd8e0e3fa3a5d4b55a26
[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 \core_search\base[] Enabled search areas.
102      */
103     protected static $enabledsearchareas = null;
105     /**
106      * @var \core_search\base[] All system search areas.
107      */
108     protected static $allsearchareas = null;
110     /**
111      * @var \core_search\manager
112      */
113     protected static $instance = null;
115     /**
116      * @var \core_search\engine
117      */
118     protected $engine = null;
120     /**
121      * Note: This should be removed once possible (see MDL-60644).
122      *
123      * @var float Fake current time for use in PHPunit tests
124      */
125     protected static $phpunitfaketime = 0;
127     /**
128      * Constructor, use \core_search\manager::instance instead to get a class instance.
129      *
130      * @param \core_search\base The search engine to use
131      */
132     public function __construct($engine) {
133         $this->engine = $engine;
134     }
136     /**
137      * Returns an initialised \core_search instance.
138      *
139      * @see \core_search\engine::is_installed
140      * @see \core_search\engine::is_server_ready
141      * @throws \core_search\engine_exception
142      * @return \core_search\manager
143      */
144     public static function instance() {
145         global $CFG;
147         // One per request, this should be purged during testing.
148         if (static::$instance !== null) {
149             return static::$instance;
150         }
152         if (empty($CFG->searchengine)) {
153             throw new \core_search\engine_exception('enginenotselected', 'search');
154         }
156         if (!$engine = static::search_engine_instance()) {
157             throw new \core_search\engine_exception('enginenotfound', 'search', '', $CFG->searchengine);
158         }
160         if (!$engine->is_installed()) {
161             throw new \core_search\engine_exception('enginenotinstalled', 'search', '', $CFG->searchengine);
162         }
164         $serverstatus = $engine->is_server_ready();
165         if ($serverstatus !== true) {
166             // Skip this error in Behat when faking seach results.
167             if (!defined('BEHAT_SITE_RUNNING') || !get_config('core_search', 'behat_fakeresult')) {
168                 // Error message with no details as this is an exception that any user may find if the server crashes.
169                 throw new \core_search\engine_exception('engineserverstatus', 'search');
170             }
171         }
173         static::$instance = new \core_search\manager($engine);
174         return static::$instance;
175     }
177     /**
178      * Returns whether global search is enabled or not.
179      *
180      * @return bool
181      */
182     public static function is_global_search_enabled() {
183         global $CFG;
184         return !empty($CFG->enableglobalsearch);
185     }
187     /**
188      * Returns whether indexing is enabled or not (you can enable indexing even when search is not
189      * enabled at the moment, so as to have it ready for students).
190      *
191      * @return bool True if indexing is enabled.
192      */
193     public static function is_indexing_enabled() {
194         global $CFG;
195         return !empty($CFG->enableglobalsearch) || !empty($CFG->searchindexwhendisabled);
196     }
198     /**
199      * Returns an instance of the search engine.
200      *
201      * @return \core_search\engine
202      */
203     public static function search_engine_instance() {
204         global $CFG;
206         $classname = '\\search_' . $CFG->searchengine . '\\engine';
207         if (!class_exists($classname)) {
208             return false;
209         }
211         return new $classname();
212     }
214     /**
215      * Returns the search engine.
216      *
217      * @return \core_search\engine
218      */
219     public function get_engine() {
220         return $this->engine;
221     }
223     /**
224      * Returns a search area class name.
225      *
226      * @param string $areaid
227      * @return string
228      */
229     protected static function get_area_classname($areaid) {
230         list($componentname, $areaname) = static::extract_areaid_parts($areaid);
231         return '\\' . $componentname . '\\search\\' . $areaname;
232     }
234     /**
235      * Returns a new area search indexer instance.
236      *
237      * @param string $areaid
238      * @return \core_search\base|bool False if the area is not available.
239      */
240     public static function get_search_area($areaid) {
242         // We have them all here.
243         if (!empty(static::$allsearchareas[$areaid])) {
244             return static::$allsearchareas[$areaid];
245         }
247         $classname = static::get_area_classname($areaid);
249         if (class_exists($classname) && static::is_search_area($classname)) {
250             return new $classname();
251         }
253         return false;
254     }
256     /**
257      * Return the list of available search areas.
258      *
259      * @param bool $enabled Return only the enabled ones.
260      * @return \core_search\base[]
261      */
262     public static function get_search_areas_list($enabled = false) {
264         // Two different arrays, we don't expect these arrays to be big.
265         if (static::$allsearchareas !== null) {
266             if (!$enabled) {
267                 return static::$allsearchareas;
268             } else {
269                 return static::$enabledsearchareas;
270             }
271         }
273         static::$allsearchareas = array();
274         static::$enabledsearchareas = array();
276         $plugintypes = \core_component::get_plugin_types();
277         foreach ($plugintypes as $plugintype => $unused) {
278             $plugins = \core_component::get_plugin_list($plugintype);
279             foreach ($plugins as $pluginname => $pluginfullpath) {
281                 $componentname = $plugintype . '_' . $pluginname;
282                 $searchclasses = \core_component::get_component_classes_in_namespace($componentname, 'search');
283                 foreach ($searchclasses as $classname => $classpath) {
284                     $areaname = substr(strrchr($classname, '\\'), 1);
286                     if (!static::is_search_area($classname)) {
287                         continue;
288                     }
290                     $areaid = static::generate_areaid($componentname, $areaname);
291                     $searchclass = new $classname();
293                     static::$allsearchareas[$areaid] = $searchclass;
294                     if ($searchclass->is_enabled()) {
295                         static::$enabledsearchareas[$areaid] = $searchclass;
296                     }
297                 }
298             }
299         }
301         $subsystems = \core_component::get_core_subsystems();
302         foreach ($subsystems as $subsystemname => $subsystempath) {
303             $componentname = 'core_' . $subsystemname;
304             $searchclasses = \core_component::get_component_classes_in_namespace($componentname, 'search');
306             foreach ($searchclasses as $classname => $classpath) {
307                 $areaname = substr(strrchr($classname, '\\'), 1);
309                 if (!static::is_search_area($classname)) {
310                     continue;
311                 }
313                 $areaid = static::generate_areaid($componentname, $areaname);
314                 $searchclass = new $classname();
315                 static::$allsearchareas[$areaid] = $searchclass;
316                 if ($searchclass->is_enabled()) {
317                     static::$enabledsearchareas[$areaid] = $searchclass;
318                 }
319             }
320         }
322         if ($enabled) {
323             return static::$enabledsearchareas;
324         }
325         return static::$allsearchareas;
326     }
328     /**
329      * Clears all static caches.
330      *
331      * @return void
332      */
333     public static function clear_static() {
335         static::$enabledsearchareas = null;
336         static::$allsearchareas = null;
337         static::$instance = null;
339         base_block::clear_static();
340     }
342     /**
343      * Generates an area id from the componentname and the area name.
344      *
345      * There should not be any naming conflict as the area name is the
346      * class name in component/classes/search/.
347      *
348      * @param string $componentname
349      * @param string $areaname
350      * @return void
351      */
352     public static function generate_areaid($componentname, $areaname) {
353         return $componentname . '-' . $areaname;
354     }
356     /**
357      * Returns all areaid string components (component name and area name).
358      *
359      * @param string $areaid
360      * @return array Component name (Frankenstyle) and area name (search area class name)
361      */
362     public static function extract_areaid_parts($areaid) {
363         return explode('-', $areaid);
364     }
366     /**
367      * Returns information about the areas which the user can access.
368      *
369      * The returned value is a stdClass object with the following fields:
370      * - everything (bool, true for admin only)
371      * - usercontexts (indexed by area identifier then context
372      * - separategroupscontexts (contexts within which group restrictions apply)
373      * - visiblegroupscontextsareas (overrides to the above when the same contexts also have
374      *   'visible groups' for certain search area ids - hopefully rare)
375      * - usergroups (groups which the current user belongs to)
376      *
377      * The areas can be limited by course id and context id. If specifying context ids, results
378      * are limited to the exact context ids specified and not their children (for example, giving
379      * the course context id would result in including search items with the course context id, and
380      * not anything from a context inside the course). For performance, you should also specify
381      * course id(s) when using context ids.
382      *
383      * @param array|false $limitcourseids An array of course ids to limit the search to. False for no limiting.
384      * @param array|false $limitcontextids An array of context ids to limit the search to. False for no limiting.
385      * @return \stdClass Object as described above
386      */
387     protected function get_areas_user_accesses($limitcourseids = false, $limitcontextids = false) {
388         global $DB, $USER;
390         // All results for admins (unless they have chosen to limit results). Eventually we could
391         // add a new capability for managers.
392         if (is_siteadmin() && !$limitcourseids && !$limitcontextids) {
393             return (object)array('everything' => true);
394         }
396         $areasbylevel = array();
398         // Split areas by context level so we only iterate only once through courses and cms.
399         $searchareas = static::get_search_areas_list(true);
400         foreach ($searchareas as $areaid => $unused) {
401             $classname = static::get_area_classname($areaid);
402             $searcharea = new $classname();
403             foreach ($classname::get_levels() as $level) {
404                 $areasbylevel[$level][$areaid] = $searcharea;
405             }
406         }
408         // This will store area - allowed contexts relations.
409         $areascontexts = array();
411         // Initialise two special-case arrays for storing other information related to the contexts.
412         $separategroupscontexts = array();
413         $visiblegroupscontextsareas = array();
414         $usergroups = array();
416         if (empty($limitcourseids) && !empty($areasbylevel[CONTEXT_SYSTEM])) {
417             // We add system context to all search areas working at this level. Here each area is fully responsible of
418             // the access control as we can not automate much, we can not even check guest access as some areas might
419             // want to allow guests to retrieve data from them.
421             $systemcontextid = \context_system::instance()->id;
422             if (!$limitcontextids || in_array($systemcontextid, $limitcontextids)) {
423                 foreach ($areasbylevel[CONTEXT_SYSTEM] as $areaid => $searchclass) {
424                     $areascontexts[$areaid][$systemcontextid] = $systemcontextid;
425                 }
426             }
427         }
429         if (!empty($areasbylevel[CONTEXT_USER])) {
430             if ($usercontext = \context_user::instance($USER->id, IGNORE_MISSING)) {
431                 if (!$limitcontextids || in_array($usercontext->id, $limitcontextids)) {
432                     // Extra checking although only logged users should reach this point, guest users have a valid context id.
433                     foreach ($areasbylevel[CONTEXT_USER] as $areaid => $searchclass) {
434                         $areascontexts[$areaid][$usercontext->id] = $usercontext->id;
435                     }
436                 }
437             }
438         }
440         if (is_siteadmin()) {
441             // Admins have access to all courses regardless of enrolment.
442             if ($limitcourseids) {
443                 list ($coursesql, $courseparams) = $DB->get_in_or_equal($limitcourseids);
444                 $coursesql = 'id ' . $coursesql;
445             } else {
446                 $coursesql = '';
447                 $courseparams = [];
448             }
449             // Get courses using the same list of fields from enrol_get_my_courses.
450             $courses = $DB->get_records_select('course', $coursesql, $courseparams, '',
451                     'id, category, sortorder, shortname, fullname, idnumber, startdate, visible, ' .
452                     'groupmode, groupmodeforce, cacherev');
453         } else {
454             // Get the courses where the current user has access.
455             $courses = enrol_get_my_courses(array('id', 'cacherev'), 'id', 0, [],
456                     (bool)get_config('core', 'searchallavailablecourses'));
457         }
459         if (empty($limitcourseids) || in_array(SITEID, $limitcourseids)) {
460             $courses[SITEID] = get_course(SITEID);
461         }
463         // Keep a list of included course context ids (needed for the block calculation below).
464         $coursecontextids = [];
465         $modulecms = [];
467         foreach ($courses as $course) {
468             if (!empty($limitcourseids) && !in_array($course->id, $limitcourseids)) {
469                 // Skip non-included courses.
470                 continue;
471             }
473             $coursecontext = \context_course::instance($course->id);
474             $coursecontextids[] = $coursecontext->id;
475             $hasgrouprestrictions = false;
477             // Info about the course modules.
478             $modinfo = get_fast_modinfo($course);
480             if (!empty($areasbylevel[CONTEXT_COURSE]) &&
481                     (!$limitcontextids || in_array($coursecontext->id, $limitcontextids))) {
482                 // Add the course contexts the user can view.
483                 foreach ($areasbylevel[CONTEXT_COURSE] as $areaid => $searchclass) {
484                     if ($course->visible || has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
485                         $areascontexts[$areaid][$coursecontext->id] = $coursecontext->id;
486                     }
487                 }
488             }
490             if (!empty($areasbylevel[CONTEXT_MODULE])) {
491                 // Add the module contexts the user can view (cm_info->uservisible).
493                 foreach ($areasbylevel[CONTEXT_MODULE] as $areaid => $searchclass) {
495                     // Removing the plugintype 'mod_' prefix.
496                     $modulename = substr($searchclass->get_component_name(), 4);
498                     $modinstances = $modinfo->get_instances_of($modulename);
499                     foreach ($modinstances as $modinstance) {
500                         // Skip module context if not included in list of context ids.
501                         if ($limitcontextids && !in_array($modinstance->context->id, $limitcontextids)) {
502                             continue;
503                         }
504                         if ($modinstance->uservisible) {
505                             $contextid = $modinstance->context->id;
506                             $areascontexts[$areaid][$contextid] = $contextid;
507                             $modulecms[$modinstance->id] = $modinstance;
509                             if (!has_capability('moodle/site:accessallgroups', $modinstance->context) &&
510                                     ($searchclass instanceof base_mod) &&
511                                     $searchclass->supports_group_restriction()) {
512                                 if ($searchclass->restrict_cm_access_by_group($modinstance)) {
513                                     $separategroupscontexts[$contextid] = $contextid;
514                                     $hasgrouprestrictions = true;
515                                 } else {
516                                     // Track a list of anything that has a group id (so might get
517                                     // filtered) and doesn't want to be, in this context.
518                                     if (!array_key_exists($contextid, $visiblegroupscontextsareas)) {
519                                         $visiblegroupscontextsareas[$contextid] = array();
520                                     }
521                                     $visiblegroupscontextsareas[$contextid][$areaid] = $areaid;
522                                 }
523                             }
524                         }
525                     }
526                 }
527             }
529             // Insert group information for course (unless there aren't any modules restricted by
530             // group for this user in this course, in which case don't bother).
531             if ($hasgrouprestrictions) {
532                 $groups = groups_get_all_groups($course->id, $USER->id, 0, 'g.id');
533                 foreach ($groups as $group) {
534                     $usergroups[$group->id] = $group->id;
535                 }
536             }
537         }
539         // Chuck away all the 'visible groups contexts' data unless there is actually something
540         // that does use separate groups in the same context (this data is only used as an
541         // 'override' in cases where the search is restricting to separate groups).
542         foreach ($visiblegroupscontextsareas as $contextid => $areas) {
543             if (!array_key_exists($contextid, $separategroupscontexts)) {
544                 unset($visiblegroupscontextsareas[$contextid]);
545             }
546         }
548         // Add all supported block contexts, in a single query for performance.
549         if (!empty($areasbylevel[CONTEXT_BLOCK])) {
550             // Get list of all block types we care about.
551             $blocklist = [];
552             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
553                 $blocklist[$searchclass->get_block_name()] = true;
554             }
555             list ($blocknamesql, $blocknameparams) = $DB->get_in_or_equal(array_keys($blocklist));
557             // Get list of course contexts.
558             list ($contextsql, $contextparams) = $DB->get_in_or_equal($coursecontextids);
560             // Get list of block context (if limited).
561             $blockcontextwhere = '';
562             $blockcontextparams = [];
563             if ($limitcontextids) {
564                 list ($blockcontextsql, $blockcontextparams) = $DB->get_in_or_equal($limitcontextids);
565                 $blockcontextwhere = 'AND x.id ' . $blockcontextsql;
566             }
568             // Query all blocks that are within an included course, and are set to be visible, and
569             // in a supported page type (basically just course view). This query could be
570             // extended (or a second query added) to support blocks that are within a module
571             // context as well, and we could add more page types if required.
572             $blockrecs = $DB->get_records_sql("
573                         SELECT x.*, bi.blockname AS blockname, bi.id AS blockinstanceid
574                           FROM {block_instances} bi
575                           JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
576                      LEFT JOIN {block_positions} bp ON bp.blockinstanceid = bi.id
577                                AND bp.contextid = bi.parentcontextid
578                                AND bp.pagetype LIKE 'course-view-%'
579                                AND bp.subpage = ''
580                                AND bp.visible = 0
581                          WHERE bi.parentcontextid $contextsql
582                                $blockcontextwhere
583                                AND bi.blockname $blocknamesql
584                                AND bi.subpagepattern IS NULL
585                                AND (bi.pagetypepattern = 'site-index'
586                                    OR bi.pagetypepattern LIKE 'course-view-%'
587                                    OR bi.pagetypepattern = 'course-*'
588                                    OR bi.pagetypepattern = '*')
589                                AND bp.id IS NULL",
590                     array_merge([CONTEXT_BLOCK], $contextparams, $blockcontextparams, $blocknameparams));
591             $blockcontextsbyname = [];
592             foreach ($blockrecs as $blockrec) {
593                 if (empty($blockcontextsbyname[$blockrec->blockname])) {
594                     $blockcontextsbyname[$blockrec->blockname] = [];
595                 }
596                 \context_helper::preload_from_record($blockrec);
597                 $blockcontextsbyname[$blockrec->blockname][] = \context_block::instance(
598                         $blockrec->blockinstanceid);
599             }
601             // Add the block contexts the user can view.
602             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
603                 if (empty($blockcontextsbyname[$searchclass->get_block_name()])) {
604                     continue;
605                 }
606                 foreach ($blockcontextsbyname[$searchclass->get_block_name()] as $context) {
607                     if (has_capability('moodle/block:view', $context)) {
608                         $areascontexts[$areaid][$context->id] = $context->id;
609                     }
610                 }
611             }
612         }
614         // Return all the data.
615         return (object)array('everything' => false, 'usercontexts' => $areascontexts,
616                 'separategroupscontexts' => $separategroupscontexts, 'usergroups' => $usergroups,
617                 'visiblegroupscontextsareas' => $visiblegroupscontextsareas);
618     }
620     /**
621      * Returns requested page of documents plus additional information for paging.
622      *
623      * This function does not perform any kind of security checking for access, the caller code
624      * should check that the current user have moodle/search:query capability.
625      *
626      * If a page is requested that is beyond the last result, the last valid page is returned in
627      * results, and actualpage indicates which page was returned.
628      *
629      * @param stdClass $formdata
630      * @param int $pagenum The 0 based page number.
631      * @return object An object with 3 properties:
632      *                    results    => An array of \core_search\documents for the actual page.
633      *                    totalcount => Number of records that are possibly available, to base paging on.
634      *                    actualpage => The actual page returned.
635      */
636     public function paged_search(\stdClass $formdata, $pagenum) {
637         $out = new \stdClass();
639         $perpage = static::DISPLAY_RESULTS_PER_PAGE;
641         // Make sure we only allow request up to max page.
642         $pagenum = min($pagenum, (static::MAX_RESULTS / $perpage) - 1);
644         // Calculate the first and last document number for the current page, 1 based.
645         $mindoc = ($pagenum * $perpage) + 1;
646         $maxdoc = ($pagenum + 1) * $perpage;
648         // Get engine documents, up to max.
649         $docs = $this->search($formdata, $maxdoc);
651         $resultcount = count($docs);
652         if ($resultcount < $maxdoc) {
653             // This means it couldn't give us results to max, so the count must be the max.
654             $out->totalcount = $resultcount;
655         } else {
656             // Get the possible count reported by engine, and limit to our max.
657             $out->totalcount = $this->engine->get_query_total_count();
658             $out->totalcount = min($out->totalcount, static::MAX_RESULTS);
659         }
661         // Determine the actual page.
662         if ($resultcount < $mindoc) {
663             // We couldn't get the min docs for this page, so determine what page we can get.
664             $out->actualpage = floor(($resultcount - 1) / $perpage);
665         } else {
666             $out->actualpage = $pagenum;
667         }
669         // Split the results to only return the page.
670         $out->results = array_slice($docs, $out->actualpage * $perpage, $perpage, true);
672         return $out;
673     }
675     /**
676      * Returns documents from the engine based on the data provided.
677      *
678      * This function does not perform any kind of security checking, the caller code
679      * should check that the current user have moodle/search:query capability.
680      *
681      * It might return the results from the cache instead.
682      *
683      * Valid formdata options include:
684      * - q (query text)
685      * - courseids (optional list of course ids to restrict)
686      * - contextids (optional list of context ids to restrict)
687      * - context (Moodle context object for location user searched from)
688      * - order (optional ordering, one of the types supported by the search engine e.g. 'relevance')
689      *
690      * @param \stdClass $formdata Query input data (usually from search form)
691      * @param int $limit The maximum number of documents to return
692      * @return \core_search\document[]
693      */
694     public function search(\stdClass $formdata, $limit = 0) {
695         // For Behat testing, the search results can be faked using a special step.
696         if (defined('BEHAT_SITE_RUNNING')) {
697             $fakeresult = get_config('core_search', 'behat_fakeresult');
698             if ($fakeresult) {
699                 // Clear config setting.
700                 unset_config('core_search', 'behat_fakeresult');
702                 // Check query matches expected value.
703                 $details = json_decode($fakeresult);
704                 if ($formdata->q !== $details->query) {
705                     throw new \coding_exception('Unexpected search query: ' . $formdata->q);
706                 }
708                 // Create search documents from the JSON data.
709                 $docs = [];
710                 foreach ($details->results as $result) {
711                     $doc = new \core_search\document($result->itemid, $result->componentname,
712                             $result->areaname);
713                     foreach ((array)$result->fields as $field => $value) {
714                         $doc->set($field, $value);
715                     }
716                     foreach ((array)$result->extrafields as $field => $value) {
717                         $doc->set_extra($field, $value);
718                     }
719                     $area = $this->get_search_area($doc->get('areaid'));
720                     $doc->set_doc_url($area->get_doc_url($doc));
721                     $doc->set_context_url($area->get_context_url($doc));
722                     $docs[] = $doc;
723                 }
725                 return $docs;
726             }
727         }
729         $limitcourseids = false;
730         if (!empty($formdata->courseids)) {
731             $limitcourseids = $formdata->courseids;
732         }
734         $limitcontextids = false;
735         if (!empty($formdata->contextids)) {
736             $limitcontextids = $formdata->contextids;
737         }
739         // Clears previous query errors.
740         $this->engine->clear_query_error();
742         $contextinfo = $this->get_areas_user_accesses($limitcourseids, $limitcontextids);
743         if (!$contextinfo->everything && !$contextinfo->usercontexts) {
744             // User can not access any context.
745             $docs = array();
746         } else {
747             // If engine does not support groups, remove group information from the context info -
748             // use the old format instead (true = admin, array = user contexts).
749             if (!$this->engine->supports_group_filtering()) {
750                 $contextinfo = $contextinfo->everything ? true : $contextinfo->usercontexts;
751             }
753             // Execute the actual query.
754             $docs = $this->engine->execute_query($formdata, $contextinfo, $limit);
755         }
757         return $docs;
758     }
760     /**
761      * Merge separate index segments into one.
762      */
763     public function optimize_index() {
764         $this->engine->optimize();
765     }
767     /**
768      * Index all documents.
769      *
770      * @param bool $fullindex Whether we should reindex everything or not.
771      * @param float $timelimit Time limit in seconds (0 = no time limit)
772      * @param \progress_trace|null $progress Optional class for tracking progress
773      * @throws \moodle_exception
774      * @return bool Whether there was any updated document or not.
775      */
776     public function index($fullindex = false, $timelimit = 0, \progress_trace $progress = null) {
777         global $DB;
779         // Cannot combine time limit with reindex.
780         if ($timelimit && $fullindex) {
781             throw new \coding_exception('Cannot apply time limit when reindexing');
782         }
783         if (!$progress) {
784             $progress = new \null_progress_trace();
785         }
787         // Unlimited time.
788         \core_php_time_limit::raise();
790         // Notify the engine that an index starting.
791         $this->engine->index_starting($fullindex);
793         $sumdocs = 0;
795         $searchareas = $this->get_search_areas_list(true);
797         if ($timelimit) {
798             // If time is limited (and therefore we're not just indexing everything anyway), select
799             // an order for search areas. The intention here is to avoid a situation where a new
800             // large search area is enabled, and this means all our other search areas go out of
801             // date while that one is being indexed. To do this, we order by the time we spent
802             // indexing them last time we ran, meaning anything that took a very long time will be
803             // done last.
804             uasort($searchareas, function(\core_search\base $area1, \core_search\base $area2) {
805                 return (int)$area1->get_last_indexing_duration() - (int)$area2->get_last_indexing_duration();
806             });
808             // Decide time to stop.
809             $stopat = self::get_current_time() + $timelimit;
810         }
812         foreach ($searchareas as $areaid => $searcharea) {
814             $progress->output('Processing area: ' . $searcharea->get_visible_name());
816             // Notify the engine that an area is starting.
817             $this->engine->area_index_starting($searcharea, $fullindex);
819             $indexingstart = (int)self::get_current_time();
820             $elapsed = self::get_current_time();
822             // This is used to store this component config.
823             list($componentconfigname, $varname) = $searcharea->get_config_var_name();
825             $prevtimestart = intval(get_config($componentconfigname, $varname . '_indexingstart'));
827             if ($fullindex === true) {
828                 $referencestarttime = 0;
830                 // For full index, we delete any queued context index requests, as those will
831                 // obviously be met by the full index.
832                 $DB->delete_records('search_index_requests');
833             } else {
834                 $partial = get_config($componentconfigname, $varname . '_partial');
835                 if ($partial) {
836                     // When the previous index did not complete all data, we start from the time of the
837                     // last document that was successfully indexed. (Note this will result in
838                     // re-indexing that one document, but we can't avoid that because there may be
839                     // other documents in the same second.)
840                     $referencestarttime = intval(get_config($componentconfigname, $varname . '_lastindexrun'));
841                 } else {
842                     $referencestarttime = $prevtimestart;
843                 }
844             }
846             // Getting the recordset from the area.
847             $recordset = $searcharea->get_recordset_by_timestamp($referencestarttime);
848             $initialquerytime = self::get_current_time() - $elapsed;
849             if ($initialquerytime > self::DISPLAY_LONG_QUERY_TIME) {
850                 $progress->output('Initial query took ' . round($initialquerytime, 1) .
851                         ' seconds.', 1);
852             }
854             // Pass get_document as callback.
855             $fileindexing = $this->engine->file_indexing_enabled() && $searcharea->uses_file_indexing();
856             $options = array('indexfiles' => $fileindexing, 'lastindexedtime' => $prevtimestart);
857             if ($timelimit) {
858                 $options['stopat'] = $stopat;
859             }
860             $options['progress'] = $progress;
861             $iterator = new skip_future_documents_iterator(new \core\dml\recordset_walk(
862                     $recordset, array($searcharea, 'get_document'), $options));
863             $result = $this->engine->add_documents($iterator, $searcharea, $options);
864             $recordset->close();
865             if (count($result) === 5) {
866                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial) = $result;
867             } else {
868                 // Backward compatibility for engines that don't support partial adding.
869                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
870                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
871                         DEBUG_DEVELOPER);
872                 $partial = false;
873             }
875             if ($numdocs > 0) {
876                 $elapsed = round((self::get_current_time() - $elapsed), 1);
878                 $partialtext = '';
879                 if ($partial) {
880                     $partialtext = ' (not complete; done to ' . userdate($lastindexeddoc,
881                             get_string('strftimedatetimeshort', 'langconfig')) . ')';
882                 }
884                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
885                         ' documents, in ' . $elapsed . ' seconds' . $partialtext . '.', 1);
886             } else {
887                 $progress->output('No new documents to index.', 1);
888             }
890             // Notify the engine this area is complete, and only mark times if true.
891             if ($this->engine->area_index_complete($searcharea, $numdocs, $fullindex)) {
892                 $sumdocs += $numdocs;
894                 // Store last index run once documents have been committed to the search engine.
895                 set_config($varname . '_indexingstart', $indexingstart, $componentconfigname);
896                 set_config($varname . '_indexingend', (int)self::get_current_time(), $componentconfigname);
897                 set_config($varname . '_docsignored', $numdocsignored, $componentconfigname);
898                 set_config($varname . '_docsprocessed', $numdocs, $componentconfigname);
899                 set_config($varname . '_recordsprocessed', $numrecords, $componentconfigname);
900                 if ($lastindexeddoc > 0) {
901                     set_config($varname . '_lastindexrun', $lastindexeddoc, $componentconfigname);
902                 }
903                 if ($partial) {
904                     set_config($varname . '_partial', 1, $componentconfigname);
905                 } else {
906                     unset_config($varname . '_partial', $componentconfigname);
907                 }
908             } else {
909                 $progress->output('Engine reported error.');
910             }
912             if ($timelimit && (self::get_current_time() >= $stopat)) {
913                 $progress->output('Stopping indexing due to time limit.');
914                 break;
915             }
916         }
918         if ($sumdocs > 0) {
919             $event = \core\event\search_indexed::create(
920                     array('context' => \context_system::instance()));
921             $event->trigger();
922         }
924         $this->engine->index_complete($sumdocs, $fullindex);
926         return (bool)$sumdocs;
927     }
929     /**
930      * Indexes or reindexes a specific context of the system, e.g. one course.
931      *
932      * The function returns an object with field 'complete' (true or false).
933      *
934      * This function supports partial indexing via the time limit parameter. If the time limit
935      * expires, it will return values for $startfromarea and $startfromtime which can be passed
936      * next time to continue indexing.
937      *
938      * @param \context $context Context to restrict index.
939      * @param string $singleareaid If specified, indexes only the given area.
940      * @param float $timelimit Time limit in seconds (0 = no time limit)
941      * @param \progress_trace|null $progress Optional class for tracking progress
942      * @param string $startfromarea Area to start from
943      * @param int $startfromtime Timestamp to start from
944      * @return \stdClass Object indicating success
945      */
946     public function index_context($context, $singleareaid = '', $timelimit = 0,
947             \progress_trace $progress = null, $startfromarea = '', $startfromtime = 0) {
948         if (!$progress) {
949             $progress = new \null_progress_trace();
950         }
952         // Work out time to stop, if limited.
953         if ($timelimit) {
954             // Decide time to stop.
955             $stopat = self::get_current_time() + $timelimit;
956         }
958         // No PHP time limit.
959         \core_php_time_limit::raise();
961         // Notify the engine that an index starting.
962         $this->engine->index_starting(false);
964         $sumdocs = 0;
966         // Get all search areas, in consistent order.
967         $searchareas = $this->get_search_areas_list(true);
968         ksort($searchareas);
970         // Are we skipping past some that were handled previously?
971         $skipping = $startfromarea ? true : false;
973         foreach ($searchareas as $areaid => $searcharea) {
974             // If we're only processing one area id, skip all the others.
975             if ($singleareaid && $singleareaid !== $areaid) {
976                 continue;
977             }
979             // If we're skipping to a later area, continue through the loop.
980             $referencestarttime = 0;
981             if ($skipping) {
982                 if ($areaid !== $startfromarea) {
983                     continue;
984                 }
985                 // Stop skipping and note the reference start time.
986                 $skipping = false;
987                 $referencestarttime = $startfromtime;
988             }
990             $progress->output('Processing area: ' . $searcharea->get_visible_name());
992             $elapsed = self::get_current_time();
994             // Get the recordset of all documents from the area for this context.
995             $recordset = $searcharea->get_document_recordset($referencestarttime, $context);
996             if (!$recordset) {
997                 if ($recordset === null) {
998                     $progress->output('Skipping (not relevant to context).', 1);
999                 } else {
1000                     $progress->output('Skipping (does not support context indexing).', 1);
1001                 }
1002                 continue;
1003             }
1005             // Notify the engine that an area is starting.
1006             $this->engine->area_index_starting($searcharea, false);
1008             // Work out search options.
1009             $options = [];
1010             $options['indexfiles'] = $this->engine->file_indexing_enabled() &&
1011                     $searcharea->uses_file_indexing();
1012             if ($timelimit) {
1013                 $options['stopat'] = $stopat;
1014             }
1016             // Construct iterator which will use get_document on the recordset results.
1017             $iterator = new \core\dml\recordset_walk($recordset,
1018                     array($searcharea, 'get_document'), $options);
1020             // Use this iterator to add documents.
1021             $result = $this->engine->add_documents($iterator, $searcharea, $options);
1022             if (count($result) === 5) {
1023                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial) = $result;
1024             } else {
1025                 // Backward compatibility for engines that don't support partial adding.
1026                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
1027                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
1028                         DEBUG_DEVELOPER);
1029                 $partial = false;
1030             }
1032             if ($numdocs > 0) {
1033                 $elapsed = round((self::get_current_time() - $elapsed), 3);
1034                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
1035                         ' documents, in ' . $elapsed . ' seconds' .
1036                         ($partial ? ' (not complete)' : '') . '.', 1);
1037             } else {
1038                 $progress->output('No documents to index.', 1);
1039             }
1041             // Notify the engine this area is complete, but don't store any times as this is not
1042             // part of the 'normal' search index.
1043             if (!$this->engine->area_index_complete($searcharea, $numdocs, false)) {
1044                 $progress->output('Engine reported error.', 1);
1045             }
1047             if ($partial && $timelimit && (self::get_current_time() >= $stopat)) {
1048                 $progress->output('Stopping indexing due to time limit.');
1049                 break;
1050             }
1051         }
1053         if ($sumdocs > 0) {
1054             $event = \core\event\search_indexed::create(
1055                     array('context' => $context));
1056             $event->trigger();
1057         }
1059         $this->engine->index_complete($sumdocs, false);
1061         // Indicate in result whether we completed indexing, or only part of it.
1062         $result = new \stdClass();
1063         if ($partial) {
1064             $result->complete = false;
1065             $result->startfromarea = $areaid;
1066             $result->startfromtime = $lastindexeddoc;
1067         } else {
1068             $result->complete = true;
1069         }
1070         return $result;
1071     }
1073     /**
1074      * Resets areas config.
1075      *
1076      * @throws \moodle_exception
1077      * @param string $areaid
1078      * @return void
1079      */
1080     public function reset_config($areaid = false) {
1082         if (!empty($areaid)) {
1083             $searchareas = array();
1084             if (!$searchareas[$areaid] = static::get_search_area($areaid)) {
1085                 throw new \moodle_exception('errorareanotavailable', 'search', '', $areaid);
1086             }
1087         } else {
1088             // Only the enabled ones.
1089             $searchareas = static::get_search_areas_list(true);
1090         }
1092         foreach ($searchareas as $searcharea) {
1093             list($componentname, $varname) = $searcharea->get_config_var_name();
1094             $config = $searcharea->get_config();
1096             foreach ($config as $key => $value) {
1097                 // We reset them all but the enable/disabled one.
1098                 if ($key !== $varname . '_enabled') {
1099                     set_config($key, 0, $componentname);
1100                 }
1101             }
1102         }
1103     }
1105     /**
1106      * Deletes an area's documents or all areas documents.
1107      *
1108      * @param string $areaid The area id or false for all
1109      * @return void
1110      */
1111     public function delete_index($areaid = false) {
1112         if (!empty($areaid)) {
1113             $this->engine->delete($areaid);
1114             $this->reset_config($areaid);
1115         } else {
1116             $this->engine->delete();
1117             $this->reset_config();
1118         }
1119     }
1121     /**
1122      * Deletes index by id.
1123      *
1124      * @param int Solr Document string $id
1125      */
1126     public function delete_index_by_id($id) {
1127         $this->engine->delete_by_id($id);
1128     }
1130     /**
1131      * Returns search areas configuration.
1132      *
1133      * @param \core_search\base[] $searchareas
1134      * @return \stdClass[] $configsettings
1135      */
1136     public function get_areas_config($searchareas) {
1138         $vars = array('indexingstart', 'indexingend', 'lastindexrun', 'docsignored',
1139                 'docsprocessed', 'recordsprocessed', 'partial');
1141         $configsettings = [];
1142         foreach ($searchareas as $searcharea) {
1144             $areaid = $searcharea->get_area_id();
1146             $configsettings[$areaid] = new \stdClass();
1147             list($componentname, $varname) = $searcharea->get_config_var_name();
1149             if (!$searcharea->is_enabled()) {
1150                 // We delete all indexed data on disable so no info.
1151                 foreach ($vars as $var) {
1152                     $configsettings[$areaid]->{$var} = 0;
1153                 }
1154             } else {
1155                 foreach ($vars as $var) {
1156                     $configsettings[$areaid]->{$var} = get_config($componentname, $varname .'_' . $var);
1157                 }
1158             }
1160             // Formatting the time.
1161             if (!empty($configsettings[$areaid]->lastindexrun)) {
1162                 $configsettings[$areaid]->lastindexrun = userdate($configsettings[$areaid]->lastindexrun);
1163             } else {
1164                 $configsettings[$areaid]->lastindexrun = get_string('never');
1165             }
1166         }
1167         return $configsettings;
1168     }
1170     /**
1171      * Triggers search_results_viewed event
1172      *
1173      * Other data required:
1174      * - q: The query string
1175      * - page: The page number
1176      * - title: Title filter
1177      * - areaids: Search areas filter
1178      * - courseids: Courses filter
1179      * - timestart: Time start filter
1180      * - timeend: Time end filter
1181      *
1182      * @since Moodle 3.2
1183      * @param array $other Other info for the event.
1184      * @return \core\event\search_results_viewed
1185      */
1186     public static function trigger_search_results_viewed($other) {
1187         $event = \core\event\search_results_viewed::create([
1188             'context' => \context_system::instance(),
1189             'other' => $other
1190         ]);
1191         $event->trigger();
1193         return $event;
1194     }
1196     /**
1197      * Checks whether a classname is of an actual search area.
1198      *
1199      * @param string $classname
1200      * @return bool
1201      */
1202     protected static function is_search_area($classname) {
1203         if (is_subclass_of($classname, 'core_search\base')) {
1204             return (new \ReflectionClass($classname))->isInstantiable();
1205         }
1207         return false;
1208     }
1210     /**
1211      * Requests that a specific context is indexed by the scheduled task. The context will be
1212      * added to a queue which is processed by the task.
1213      *
1214      * This is used after a restore to ensure that restored items are indexed, even though their
1215      * modified time will be older than the latest indexed. It is also used by the 'Gradual reindex'
1216      * admin feature from the search areas screen.
1217      *
1218      * @param \context $context Context to index within
1219      * @param string $areaid Area to index, '' = all areas
1220      * @param int $priority Priority (INDEX_PRIORITY_xx constant)
1221      */
1222     public static function request_index(\context $context, $areaid = '',
1223             $priority = self::INDEX_PRIORITY_NORMAL) {
1224         global $DB;
1226         // Check through existing requests for this context or any parent context.
1227         list ($contextsql, $contextparams) = $DB->get_in_or_equal(
1228                 $context->get_parent_context_ids(true));
1229         $existing = $DB->get_records_select('search_index_requests',
1230                 'contextid ' . $contextsql, $contextparams, '',
1231                 'id, searcharea, partialarea, indexpriority');
1232         foreach ($existing as $rec) {
1233             // If we haven't started processing the existing request yet, and it covers the same
1234             // area (or all areas) then that will be sufficient so don't add anything else.
1235             if ($rec->partialarea === '' && ($rec->searcharea === $areaid || $rec->searcharea === '')) {
1236                 // If the existing request has the same (or higher) priority, no need to add anything.
1237                 if ($rec->indexpriority >= $priority) {
1238                     return;
1239                 }
1240                 // The existing request has lower priority. If it is exactly the same, then just
1241                 // adjust the priority of the existing request.
1242                 if ($rec->searcharea === $areaid) {
1243                     $DB->set_field('search_index_requests', 'indexpriority', $priority,
1244                             ['id' => $rec->id]);
1245                     return;
1246                 }
1247                 // The existing request would cover this area but is a lower priority. We need to
1248                 // add the new request even though that means we will index part of it twice.
1249             }
1250         }
1252         // No suitable existing request, so add a new one.
1253         $newrecord = [ 'contextid' => $context->id, 'searcharea' => $areaid,
1254                 'timerequested' => (int)self::get_current_time(),
1255                 'partialarea' => '', 'partialtime' => 0,
1256                 'indexpriority' => $priority ];
1257         $DB->insert_record('search_index_requests', $newrecord);
1258     }
1260     /**
1261      * Processes outstanding index requests. This will take the first item from the queue (taking
1262      * account the indexing priority) and process it, continuing until an optional time limit is
1263      * reached.
1264      *
1265      * If there are no index requests, the function will do nothing.
1266      *
1267      * @param float $timelimit Time limit (0 = none)
1268      * @param \progress_trace|null $progress Optional progress indicator
1269      */
1270     public function process_index_requests($timelimit = 0.0, \progress_trace $progress = null) {
1271         global $DB;
1273         if (!$progress) {
1274             $progress = new \null_progress_trace();
1275         }
1277         $before = self::get_current_time();
1278         if ($timelimit) {
1279             $stopat = $before + $timelimit;
1280         }
1281         while (true) {
1282             // Retrieve first request, using fully defined ordering.
1283             $requests = $DB->get_records('search_index_requests', null,
1284                     'indexpriority DESC, timerequested, contextid, searcharea',
1285                     'id, contextid, searcharea, partialarea, partialtime', 0, 1);
1286             if (!$requests) {
1287                 // If there are no more requests, stop.
1288                 break;
1289             }
1290             $request = reset($requests);
1292             // Calculate remaining time.
1293             $remainingtime = 0;
1294             $beforeindex = self::get_current_time();
1295             if ($timelimit) {
1296                 $remainingtime = $stopat - $beforeindex;
1298                 // If the time limit expired already, stop now. (Otherwise we might accidentally
1299                 // index with no time limit or a negative time limit.)
1300                 if ($remainingtime <= 0) {
1301                     break;
1302                 }
1303             }
1305             // Show a message before each request, indicating what will be indexed.
1306             $context = \context::instance_by_id($request->contextid, IGNORE_MISSING);
1307             if (!$context) {
1308                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1309                 $progress->output('Skipped deleted context: ' . $request->contextid);
1310                 continue;
1311             }
1312             $contextname = $context->get_context_name();
1313             if ($request->searcharea) {
1314                 $contextname .= ' (search area: ' . $request->searcharea . ')';
1315             }
1316             $progress->output('Indexing requested context: ' . $contextname);
1318             // Actually index the context.
1319             $result = $this->index_context($context, $request->searcharea, $remainingtime,
1320                     $progress, $request->partialarea, $request->partialtime);
1322             // Work out shared part of message.
1323             $endmessage = $contextname . ' (' . round(self::get_current_time() - $beforeindex, 1) . 's)';
1325             // Update database table and continue/stop as appropriate.
1326             if ($result->complete) {
1327                 // If we completed the request, remove it from the table.
1328                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1329                 $progress->output('Completed requested context: ' . $endmessage);
1330             } else {
1331                 // If we didn't complete the request, store the partial details (how far it got).
1332                 $DB->update_record('search_index_requests', ['id' => $request->id,
1333                         'partialarea' => $result->startfromarea,
1334                         'partialtime' => $result->startfromtime]);
1335                 $progress->output('Ending requested context: ' . $endmessage);
1337                 // The time limit must have expired, so stop looping.
1338                 break;
1339             }
1340         }
1341     }
1343     /**
1344      * Gets information about the request queue, in the form of a plain object suitable for passing
1345      * to a template for rendering.
1346      *
1347      * @return \stdClass Information about queued index requests
1348      */
1349     public function get_index_requests_info() {
1350         global $DB;
1352         $result = new \stdClass();
1354         $result->total = $DB->count_records('search_index_requests');
1355         $result->topten = $DB->get_records('search_index_requests', null,
1356                 'indexpriority DESC, timerequested, contextid, searcharea',
1357                 'id, contextid, timerequested, searcharea, partialarea, partialtime, indexpriority',
1358                 0, 10);
1359         foreach ($result->topten as $item) {
1360             $context = \context::instance_by_id($item->contextid);
1361             $item->contextlink = \html_writer::link($context->get_url(),
1362                     s($context->get_context_name()));
1363             if ($item->searcharea) {
1364                 $item->areaname = $this->get_search_area($item->searcharea)->get_visible_name();
1365             }
1366             if ($item->partialarea) {
1367                 $item->partialareaname = $this->get_search_area($item->partialarea)->get_visible_name();
1368             }
1369             switch ($item->indexpriority) {
1370                 case self::INDEX_PRIORITY_REINDEXING :
1371                     $item->priorityname = get_string('priority_reindexing', 'search');
1372                     break;
1373                 case self::INDEX_PRIORITY_NORMAL :
1374                     $item->priorityname = get_string('priority_normal', 'search');
1375                     break;
1376             }
1377         }
1379         // Normalise array indices.
1380         $result->topten = array_values($result->topten);
1382         if ($result->total > 10) {
1383             $result->ellipsis = true;
1384         }
1386         return $result;
1387     }
1389     /**
1390      * Gets current time for use in search system.
1391      *
1392      * Note: This should be replaced with generic core functionality once possible (see MDL-60644).
1393      *
1394      * @return float Current time in seconds (with decimals)
1395      */
1396     public static function get_current_time() {
1397         if (PHPUNIT_TEST && self::$phpunitfaketime) {
1398             return self::$phpunitfaketime;
1399         }
1400         return microtime(true);
1401     }