ea9510807d1facacf3b9885a819891fac465dcf3
[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 \core_search\base[] Enabled search areas.
82      */
83     protected static $enabledsearchareas = null;
85     /**
86      * @var \core_search\base[] All system search areas.
87      */
88     protected static $allsearchareas = null;
90     /**
91      * @var \core_search\manager
92      */
93     protected static $instance = null;
95     /**
96      * @var \core_search\engine
97      */
98     protected $engine = null;
100     /**
101      * Constructor, use \core_search\manager::instance instead to get a class instance.
102      *
103      * @param \core_search\base The search engine to use
104      */
105     public function __construct($engine) {
106         $this->engine = $engine;
107     }
109     /**
110      * Returns an initialised \core_search instance.
111      *
112      * @see \core_search\engine::is_installed
113      * @see \core_search\engine::is_server_ready
114      * @throws \core_search\engine_exception
115      * @return \core_search\manager
116      */
117     public static function instance() {
118         global $CFG;
120         // One per request, this should be purged during testing.
121         if (static::$instance !== null) {
122             return static::$instance;
123         }
125         if (empty($CFG->searchengine)) {
126             throw new \core_search\engine_exception('enginenotselected', 'search');
127         }
129         if (!$engine = static::search_engine_instance()) {
130             throw new \core_search\engine_exception('enginenotfound', 'search', '', $CFG->searchengine);
131         }
133         if (!$engine->is_installed()) {
134             throw new \core_search\engine_exception('enginenotinstalled', 'search', '', $CFG->searchengine);
135         }
137         $serverstatus = $engine->is_server_ready();
138         if ($serverstatus !== true) {
139             // Skip this error in Behat when faking seach results.
140             if (!defined('BEHAT_SITE_RUNNING') || !get_config('core_search', 'behat_fakeresult')) {
141                 // Error message with no details as this is an exception that any user may find if the server crashes.
142                 throw new \core_search\engine_exception('engineserverstatus', 'search');
143             }
144         }
146         static::$instance = new \core_search\manager($engine);
147         return static::$instance;
148     }
150     /**
151      * Returns whether global search is enabled or not.
152      *
153      * @return bool
154      */
155     public static function is_global_search_enabled() {
156         global $CFG;
157         return !empty($CFG->enableglobalsearch);
158     }
160     /**
161      * Returns whether indexing is enabled or not (you can enable indexing even when search is not
162      * enabled at the moment, so as to have it ready for students).
163      *
164      * @return bool True if indexing is enabled.
165      */
166     public static function is_indexing_enabled() {
167         global $CFG;
168         return !empty($CFG->enableglobalsearch) || !empty($CFG->searchindexwhendisabled);
169     }
171     /**
172      * Returns an instance of the search engine.
173      *
174      * @return \core_search\engine
175      */
176     public static function search_engine_instance() {
177         global $CFG;
179         $classname = '\\search_' . $CFG->searchengine . '\\engine';
180         if (!class_exists($classname)) {
181             return false;
182         }
184         return new $classname();
185     }
187     /**
188      * Returns the search engine.
189      *
190      * @return \core_search\engine
191      */
192     public function get_engine() {
193         return $this->engine;
194     }
196     /**
197      * Returns a search area class name.
198      *
199      * @param string $areaid
200      * @return string
201      */
202     protected static function get_area_classname($areaid) {
203         list($componentname, $areaname) = static::extract_areaid_parts($areaid);
204         return '\\' . $componentname . '\\search\\' . $areaname;
205     }
207     /**
208      * Returns a new area search indexer instance.
209      *
210      * @param string $areaid
211      * @return \core_search\base|bool False if the area is not available.
212      */
213     public static function get_search_area($areaid) {
215         // We have them all here.
216         if (!empty(static::$allsearchareas[$areaid])) {
217             return static::$allsearchareas[$areaid];
218         }
220         $classname = static::get_area_classname($areaid);
222         if (class_exists($classname) && static::is_search_area($classname)) {
223             return new $classname();
224         }
226         return false;
227     }
229     /**
230      * Return the list of available search areas.
231      *
232      * @param bool $enabled Return only the enabled ones.
233      * @return \core_search\base[]
234      */
235     public static function get_search_areas_list($enabled = false) {
237         // Two different arrays, we don't expect these arrays to be big.
238         if (static::$allsearchareas !== null) {
239             if (!$enabled) {
240                 return static::$allsearchareas;
241             } else {
242                 return static::$enabledsearchareas;
243             }
244         }
246         static::$allsearchareas = array();
247         static::$enabledsearchareas = array();
249         $plugintypes = \core_component::get_plugin_types();
250         foreach ($plugintypes as $plugintype => $unused) {
251             $plugins = \core_component::get_plugin_list($plugintype);
252             foreach ($plugins as $pluginname => $pluginfullpath) {
254                 $componentname = $plugintype . '_' . $pluginname;
255                 $searchclasses = \core_component::get_component_classes_in_namespace($componentname, 'search');
256                 foreach ($searchclasses as $classname => $classpath) {
257                     $areaname = substr(strrchr($classname, '\\'), 1);
259                     if (!static::is_search_area($classname)) {
260                         continue;
261                     }
263                     $areaid = static::generate_areaid($componentname, $areaname);
264                     $searchclass = new $classname();
266                     static::$allsearchareas[$areaid] = $searchclass;
267                     if ($searchclass->is_enabled()) {
268                         static::$enabledsearchareas[$areaid] = $searchclass;
269                     }
270                 }
271             }
272         }
274         $subsystems = \core_component::get_core_subsystems();
275         foreach ($subsystems as $subsystemname => $subsystempath) {
276             $componentname = 'core_' . $subsystemname;
277             $searchclasses = \core_component::get_component_classes_in_namespace($componentname, 'search');
279             foreach ($searchclasses as $classname => $classpath) {
280                 $areaname = substr(strrchr($classname, '\\'), 1);
282                 if (!static::is_search_area($classname)) {
283                     continue;
284                 }
286                 $areaid = static::generate_areaid($componentname, $areaname);
287                 $searchclass = new $classname();
288                 static::$allsearchareas[$areaid] = $searchclass;
289                 if ($searchclass->is_enabled()) {
290                     static::$enabledsearchareas[$areaid] = $searchclass;
291                 }
292             }
293         }
295         if ($enabled) {
296             return static::$enabledsearchareas;
297         }
298         return static::$allsearchareas;
299     }
301     /**
302      * Clears all static caches.
303      *
304      * @return void
305      */
306     public static function clear_static() {
308         static::$enabledsearchareas = null;
309         static::$allsearchareas = null;
310         static::$instance = null;
312         base_block::clear_static();
313     }
315     /**
316      * Generates an area id from the componentname and the area name.
317      *
318      * There should not be any naming conflict as the area name is the
319      * class name in component/classes/search/.
320      *
321      * @param string $componentname
322      * @param string $areaname
323      * @return void
324      */
325     public static function generate_areaid($componentname, $areaname) {
326         return $componentname . '-' . $areaname;
327     }
329     /**
330      * Returns all areaid string components (component name and area name).
331      *
332      * @param string $areaid
333      * @return array Component name (Frankenstyle) and area name (search area class name)
334      */
335     public static function extract_areaid_parts($areaid) {
336         return explode('-', $areaid);
337     }
339     /**
340      * Returns the contexts the user can access.
341      *
342      * The returned value is a multidimensional array because some search engines can group
343      * information and there will be a performance benefit on passing only some contexts
344      * instead of the whole context array set.
345      *
346      * @param array|false $limitcourseids An array of course ids to limit the search to. False for no limiting.
347      * @return bool|array Indexed by area identifier (component + area name). Returns true if the user can see everything.
348      */
349     protected function get_areas_user_accesses($limitcourseids = false) {
350         global $DB, $USER;
352         // All results for admins. Eventually we could add a new capability for managers.
353         if (is_siteadmin()) {
354             return true;
355         }
357         $areasbylevel = array();
359         // Split areas by context level so we only iterate only once through courses and cms.
360         $searchareas = static::get_search_areas_list(true);
361         foreach ($searchareas as $areaid => $unused) {
362             $classname = static::get_area_classname($areaid);
363             $searcharea = new $classname();
364             foreach ($classname::get_levels() as $level) {
365                 $areasbylevel[$level][$areaid] = $searcharea;
366             }
367         }
369         // This will store area - allowed contexts relations.
370         $areascontexts = array();
372         if (empty($limitcourseids) && !empty($areasbylevel[CONTEXT_SYSTEM])) {
373             // We add system context to all search areas working at this level. Here each area is fully responsible of
374             // the access control as we can not automate much, we can not even check guest access as some areas might
375             // want to allow guests to retrieve data from them.
377             $systemcontextid = \context_system::instance()->id;
378             foreach ($areasbylevel[CONTEXT_SYSTEM] as $areaid => $searchclass) {
379                 $areascontexts[$areaid][$systemcontextid] = $systemcontextid;
380             }
381         }
383         if (!empty($areasbylevel[CONTEXT_USER])) {
384             if ($usercontext = \context_user::instance($USER->id, IGNORE_MISSING)) {
385                 // Extra checking although only logged users should reach this point, guest users have a valid context id.
386                 foreach ($areasbylevel[CONTEXT_USER] as $areaid => $searchclass) {
387                     $areascontexts[$areaid][$usercontext->id] = $usercontext->id;
388                 }
389             }
390         }
392         // Get the courses where the current user has access.
393         $courses = enrol_get_my_courses(array('id', 'cacherev'), 'id', 0, [],
394                 (bool)get_config('core', 'searchallavailablecourses'));
396         if (empty($limitcourseids) || in_array(SITEID, $limitcourseids)) {
397             $courses[SITEID] = get_course(SITEID);
398         }
400         // Keep a list of included course context ids (needed for the block calculation below).
401         $coursecontextids = [];
403         foreach ($courses as $course) {
404             if (!empty($limitcourseids) && !in_array($course->id, $limitcourseids)) {
405                 // Skip non-included courses.
406                 continue;
407             }
409             $coursecontext = \context_course::instance($course->id);
410             $coursecontextids[] = $coursecontext->id;
412             // Info about the course modules.
413             $modinfo = get_fast_modinfo($course);
415             if (!empty($areasbylevel[CONTEXT_COURSE])) {
416                 // Add the course contexts the user can view.
417                 foreach ($areasbylevel[CONTEXT_COURSE] as $areaid => $searchclass) {
418                     if ($course->visible || has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
419                         $areascontexts[$areaid][$coursecontext->id] = $coursecontext->id;
420                     }
421                 }
422             }
424             if (!empty($areasbylevel[CONTEXT_MODULE])) {
425                 // Add the module contexts the user can view (cm_info->uservisible).
427                 foreach ($areasbylevel[CONTEXT_MODULE] as $areaid => $searchclass) {
429                     // Removing the plugintype 'mod_' prefix.
430                     $modulename = substr($searchclass->get_component_name(), 4);
432                     $modinstances = $modinfo->get_instances_of($modulename);
433                     foreach ($modinstances as $modinstance) {
434                         if ($modinstance->uservisible) {
435                             $areascontexts[$areaid][$modinstance->context->id] = $modinstance->context->id;
436                         }
437                     }
438                 }
439             }
440         }
442         // Add all supported block contexts, in a single query for performance.
443         if (!empty($areasbylevel[CONTEXT_BLOCK])) {
444             // Get list of all block types we care about.
445             $blocklist = [];
446             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
447                 $blocklist[$searchclass->get_block_name()] = true;
448             }
449             list ($blocknamesql, $blocknameparams) = $DB->get_in_or_equal(array_keys($blocklist));
451             // Get list of course contexts.
452             list ($contextsql, $contextparams) = $DB->get_in_or_equal($coursecontextids);
454             // Query all blocks that are within an included course, and are set to be visible, and
455             // in a supported page type (basically just course view). This query could be
456             // extended (or a second query added) to support blocks that are within a module
457             // context as well, and we could add more page types if required.
458             $blockrecs = $DB->get_records_sql("
459                         SELECT x.*, bi.blockname AS blockname, bi.id AS blockinstanceid
460                           FROM {block_instances} bi
461                           JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
462                      LEFT JOIN {block_positions} bp ON bp.blockinstanceid = bi.id
463                                AND bp.contextid = bi.parentcontextid
464                                AND bp.pagetype LIKE 'course-view-%'
465                                AND bp.subpage = ''
466                                AND bp.visible = 0
467                          WHERE bi.parentcontextid $contextsql
468                                AND bi.blockname $blocknamesql
469                                AND bi.subpagepattern IS NULL
470                                AND (bi.pagetypepattern = 'site-index'
471                                    OR bi.pagetypepattern LIKE 'course-view-%'
472                                    OR bi.pagetypepattern = 'course-*'
473                                    OR bi.pagetypepattern = '*')
474                                AND bp.id IS NULL",
475                     array_merge([CONTEXT_BLOCK], $contextparams, $blocknameparams));
476             $blockcontextsbyname = [];
477             foreach ($blockrecs as $blockrec) {
478                 if (empty($blockcontextsbyname[$blockrec->blockname])) {
479                     $blockcontextsbyname[$blockrec->blockname] = [];
480                 }
481                 \context_helper::preload_from_record($blockrec);
482                 $blockcontextsbyname[$blockrec->blockname][] = \context_block::instance(
483                         $blockrec->blockinstanceid);
484             }
486             // Add the block contexts the user can view.
487             foreach ($areasbylevel[CONTEXT_BLOCK] as $areaid => $searchclass) {
488                 if (empty($blockcontextsbyname[$searchclass->get_block_name()])) {
489                     continue;
490                 }
491                 foreach ($blockcontextsbyname[$searchclass->get_block_name()] as $context) {
492                     if (has_capability('moodle/block:view', $context)) {
493                         $areascontexts[$areaid][$context->id] = $context->id;
494                     }
495                 }
496             }
497         }
499         return $areascontexts;
500     }
502     /**
503      * Returns requested page of documents plus additional information for paging.
504      *
505      * This function does not perform any kind of security checking for access, the caller code
506      * should check that the current user have moodle/search:query capability.
507      *
508      * If a page is requested that is beyond the last result, the last valid page is returned in
509      * results, and actualpage indicates which page was returned.
510      *
511      * @param stdClass $formdata
512      * @param int $pagenum The 0 based page number.
513      * @return object An object with 3 properties:
514      *                    results    => An array of \core_search\documents for the actual page.
515      *                    totalcount => Number of records that are possibly available, to base paging on.
516      *                    actualpage => The actual page returned.
517      */
518     public function paged_search(\stdClass $formdata, $pagenum) {
519         $out = new \stdClass();
521         $perpage = static::DISPLAY_RESULTS_PER_PAGE;
523         // Make sure we only allow request up to max page.
524         $pagenum = min($pagenum, (static::MAX_RESULTS / $perpage) - 1);
526         // Calculate the first and last document number for the current page, 1 based.
527         $mindoc = ($pagenum * $perpage) + 1;
528         $maxdoc = ($pagenum + 1) * $perpage;
530         // Get engine documents, up to max.
531         $docs = $this->search($formdata, $maxdoc);
533         $resultcount = count($docs);
534         if ($resultcount < $maxdoc) {
535             // This means it couldn't give us results to max, so the count must be the max.
536             $out->totalcount = $resultcount;
537         } else {
538             // Get the possible count reported by engine, and limit to our max.
539             $out->totalcount = $this->engine->get_query_total_count();
540             $out->totalcount = min($out->totalcount, static::MAX_RESULTS);
541         }
543         // Determine the actual page.
544         if ($resultcount < $mindoc) {
545             // We couldn't get the min docs for this page, so determine what page we can get.
546             $out->actualpage = floor(($resultcount - 1) / $perpage);
547         } else {
548             $out->actualpage = $pagenum;
549         }
551         // Split the results to only return the page.
552         $out->results = array_slice($docs, $out->actualpage * $perpage, $perpage, true);
554         return $out;
555     }
557     /**
558      * Returns documents from the engine based on the data provided.
559      *
560      * This function does not perform any kind of security checking, the caller code
561      * should check that the current user have moodle/search:query capability.
562      *
563      * It might return the results from the cache instead.
564      *
565      * @param stdClass $formdata
566      * @param int      $limit The maximum number of documents to return
567      * @return \core_search\document[]
568      */
569     public function search(\stdClass $formdata, $limit = 0) {
570         // For Behat testing, the search results can be faked using a special step.
571         if (defined('BEHAT_SITE_RUNNING')) {
572             $fakeresult = get_config('core_search', 'behat_fakeresult');
573             if ($fakeresult) {
574                 // Clear config setting.
575                 unset_config('core_search', 'behat_fakeresult');
577                 // Check query matches expected value.
578                 $details = json_decode($fakeresult);
579                 if ($formdata->q !== $details->query) {
580                     throw new \coding_exception('Unexpected search query: ' . $formdata->q);
581                 }
583                 // Create search documents from the JSON data.
584                 $docs = [];
585                 foreach ($details->results as $result) {
586                     $doc = new \core_search\document($result->itemid, $result->componentname,
587                             $result->areaname);
588                     foreach ((array)$result->fields as $field => $value) {
589                         $doc->set($field, $value);
590                     }
591                     foreach ((array)$result->extrafields as $field => $value) {
592                         $doc->set_extra($field, $value);
593                     }
594                     $area = $this->get_search_area($doc->get('areaid'));
595                     $doc->set_doc_url($area->get_doc_url($doc));
596                     $doc->set_context_url($area->get_context_url($doc));
597                     $docs[] = $doc;
598                 }
600                 return $docs;
601             }
602         }
604         $limitcourseids = false;
605         if (!empty($formdata->courseids)) {
606             $limitcourseids = $formdata->courseids;
607         }
609         // Clears previous query errors.
610         $this->engine->clear_query_error();
612         $areascontexts = $this->get_areas_user_accesses($limitcourseids);
613         if (!$areascontexts) {
614             // User can not access any context.
615             $docs = array();
616         } else {
617             $docs = $this->engine->execute_query($formdata, $areascontexts, $limit);
618         }
620         return $docs;
621     }
623     /**
624      * Merge separate index segments into one.
625      */
626     public function optimize_index() {
627         $this->engine->optimize();
628     }
630     /**
631      * Index all documents.
632      *
633      * @param bool $fullindex Whether we should reindex everything or not.
634      * @param float $timelimit Time limit in seconds (0 = no time limit)
635      * @param \progress_trace|null $progress Optional class for tracking progress
636      * @throws \moodle_exception
637      * @return bool Whether there was any updated document or not.
638      */
639     public function index($fullindex = false, $timelimit = 0, \progress_trace $progress = null) {
640         global $DB;
642         // Cannot combine time limit with reindex.
643         if ($timelimit && $fullindex) {
644             throw new \coding_exception('Cannot apply time limit when reindexing');
645         }
646         if (!$progress) {
647             $progress = new \null_progress_trace();
648         }
650         // Unlimited time.
651         \core_php_time_limit::raise();
653         // Notify the engine that an index starting.
654         $this->engine->index_starting($fullindex);
656         $sumdocs = 0;
658         $searchareas = $this->get_search_areas_list(true);
660         if ($timelimit) {
661             // If time is limited (and therefore we're not just indexing everything anyway), select
662             // an order for search areas. The intention here is to avoid a situation where a new
663             // large search area is enabled, and this means all our other search areas go out of
664             // date while that one is being indexed. To do this, we order by the time we spent
665             // indexing them last time we ran, meaning anything that took a very long time will be
666             // done last.
667             uasort($searchareas, function(\core_search\base $area1, \core_search\base $area2) {
668                 return (int)$area1->get_last_indexing_duration() - (int)$area2->get_last_indexing_duration();
669             });
671             // Decide time to stop.
672             $stopat = microtime(true) + $timelimit;
673         }
675         foreach ($searchareas as $areaid => $searcharea) {
677             $progress->output('Processing area: ' . $searcharea->get_visible_name());
679             // Notify the engine that an area is starting.
680             $this->engine->area_index_starting($searcharea, $fullindex);
682             $indexingstart = time();
683             $elapsed = microtime(true);
685             // This is used to store this component config.
686             list($componentconfigname, $varname) = $searcharea->get_config_var_name();
688             $prevtimestart = intval(get_config($componentconfigname, $varname . '_indexingstart'));
690             if ($fullindex === true) {
691                 $referencestarttime = 0;
693                 // For full index, we delete any queued context index requests, as those will
694                 // obviously be met by the full index.
695                 $DB->delete_records('search_index_requests');
696             } else {
697                 $partial = get_config($componentconfigname, $varname . '_partial');
698                 if ($partial) {
699                     // When the previous index did not complete all data, we start from the time of the
700                     // last document that was successfully indexed. (Note this will result in
701                     // re-indexing that one document, but we can't avoid that because there may be
702                     // other documents in the same second.)
703                     $referencestarttime = intval(get_config($componentconfigname, $varname . '_lastindexrun'));
704                 } else {
705                     $referencestarttime = $prevtimestart;
706                 }
707             }
709             // Getting the recordset from the area.
710             $recordset = $searcharea->get_recordset_by_timestamp($referencestarttime);
712             // Pass get_document as callback.
713             $fileindexing = $this->engine->file_indexing_enabled() && $searcharea->uses_file_indexing();
714             $options = array('indexfiles' => $fileindexing, 'lastindexedtime' => $prevtimestart);
715             if ($timelimit) {
716                 $options['stopat'] = $stopat;
717             }
718             $iterator = new skip_future_documents_iterator(new \core\dml\recordset_walk(
719                     $recordset, array($searcharea, 'get_document'), $options));
720             $result = $this->engine->add_documents($iterator, $searcharea, $options);
721             $recordset->close();
722             if (count($result) === 5) {
723                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial) = $result;
724             } else {
725                 // Backward compatibility for engines that don't support partial adding.
726                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
727                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
728                         DEBUG_DEVELOPER);
729                 $partial = false;
730             }
732             if ($numdocs > 0) {
733                 $elapsed = round((microtime(true) - $elapsed), 3);
734                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
735                         ' documents, in ' . $elapsed . ' seconds' .
736                         ($partial ? ' (not complete)' : '') . '.', 1);
737             } else {
738                 $progress->output('No new documents to index.', 1);
739             }
741             // Notify the engine this area is complete, and only mark times if true.
742             if ($this->engine->area_index_complete($searcharea, $numdocs, $fullindex)) {
743                 $sumdocs += $numdocs;
745                 // Store last index run once documents have been committed to the search engine.
746                 set_config($varname . '_indexingstart', $indexingstart, $componentconfigname);
747                 set_config($varname . '_indexingend', time(), $componentconfigname);
748                 set_config($varname . '_docsignored', $numdocsignored, $componentconfigname);
749                 set_config($varname . '_docsprocessed', $numdocs, $componentconfigname);
750                 set_config($varname . '_recordsprocessed', $numrecords, $componentconfigname);
751                 if ($lastindexeddoc > 0) {
752                     set_config($varname . '_lastindexrun', $lastindexeddoc, $componentconfigname);
753                 }
754                 if ($partial) {
755                     set_config($varname . '_partial', 1, $componentconfigname);
756                 } else {
757                     unset_config($varname . '_partial', $componentconfigname);
758                 }
759             } else {
760                 $progress->output('Engine reported error.');
761             }
763             if ($timelimit && (microtime(true) >= $stopat)) {
764                 $progress->output('Stopping indexing due to time limit.');
765                 break;
766             }
767         }
769         if ($sumdocs > 0) {
770             $event = \core\event\search_indexed::create(
771                     array('context' => \context_system::instance()));
772             $event->trigger();
773         }
775         $this->engine->index_complete($sumdocs, $fullindex);
777         return (bool)$sumdocs;
778     }
780     /**
781      * Indexes or reindexes a specific context of the system, e.g. one course.
782      *
783      * The function returns an object with field 'complete' (true or false).
784      *
785      * This function supports partial indexing via the time limit parameter. If the time limit
786      * expires, it will return values for $startfromarea and $startfromtime which can be passed
787      * next time to continue indexing.
788      *
789      * @param \context $context Context to restrict index.
790      * @param string $singleareaid If specified, indexes only the given area.
791      * @param float $timelimit Time limit in seconds (0 = no time limit)
792      * @param \progress_trace|null $progress Optional class for tracking progress
793      * @param string $startfromarea Area to start from
794      * @param int $startfromtime Timestamp to start from
795      * @return \stdClass Object indicating success
796      */
797     public function index_context($context, $singleareaid = '', $timelimit = 0,
798             \progress_trace $progress = null, $startfromarea = '', $startfromtime = 0) {
799         if (!$progress) {
800             $progress = new \null_progress_trace();
801         }
803         // Work out time to stop, if limited.
804         if ($timelimit) {
805             // Decide time to stop.
806             $stopat = microtime(true) + $timelimit;
807         }
809         // No PHP time limit.
810         \core_php_time_limit::raise();
812         // Notify the engine that an index starting.
813         $this->engine->index_starting(false);
815         $sumdocs = 0;
817         // Get all search areas, in consistent order.
818         $searchareas = $this->get_search_areas_list(true);
819         ksort($searchareas);
821         // Are we skipping past some that were handled previously?
822         $skipping = $startfromarea ? true : false;
824         foreach ($searchareas as $areaid => $searcharea) {
825             // If we're only processing one area id, skip all the others.
826             if ($singleareaid && $singleareaid !== $areaid) {
827                 continue;
828             }
830             // If we're skipping to a later area, continue through the loop.
831             $referencestarttime = 0;
832             if ($skipping) {
833                 if ($areaid !== $startfromarea) {
834                     continue;
835                 }
836                 // Stop skipping and note the reference start time.
837                 $skipping = false;
838                 $referencestarttime = $startfromtime;
839             }
841             $progress->output('Processing area: ' . $searcharea->get_visible_name());
843             $elapsed = microtime(true);
845             // Get the recordset of all documents from the area for this context.
846             $recordset = $searcharea->get_document_recordset($referencestarttime, $context);
847             if (!$recordset) {
848                 if ($recordset === null) {
849                     $progress->output('Skipping (not relevant to context).', 1);
850                 } else {
851                     $progress->output('Skipping (does not support context indexing).', 1);
852                 }
853                 continue;
854             }
856             // Notify the engine that an area is starting.
857             $this->engine->area_index_starting($searcharea, false);
859             // Work out search options.
860             $options = [];
861             $options['indexfiles'] = $this->engine->file_indexing_enabled() &&
862                     $searcharea->uses_file_indexing();
863             if ($timelimit) {
864                 $options['stopat'] = $stopat;
865             }
867             // Construct iterator which will use get_document on the recordset results.
868             $iterator = new \core\dml\recordset_walk($recordset,
869                     array($searcharea, 'get_document'), $options);
871             // Use this iterator to add documents.
872             $result = $this->engine->add_documents($iterator, $searcharea, $options);
873             if (count($result) === 5) {
874                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc, $partial) = $result;
875             } else {
876                 // Backward compatibility for engines that don't support partial adding.
877                 list($numrecords, $numdocs, $numdocsignored, $lastindexeddoc) = $result;
878                 debugging('engine::add_documents() should return $partial (4-value return is deprecated)',
879                         DEBUG_DEVELOPER);
880                 $partial = false;
881             }
883             if ($numdocs > 0) {
884                 $elapsed = round((microtime(true) - $elapsed), 3);
885                 $progress->output('Processed ' . $numrecords . ' records containing ' . $numdocs .
886                         ' documents, in ' . $elapsed . ' seconds' .
887                         ($partial ? ' (not complete)' : '') . '.', 1);
888             } else {
889                 $progress->output('No documents to index.', 1);
890             }
892             // Notify the engine this area is complete, but don't store any times as this is not
893             // part of the 'normal' search index.
894             if (!$this->engine->area_index_complete($searcharea, $numdocs, false)) {
895                 $progress->output('Engine reported error.', 1);
896             }
898             if ($partial && $timelimit && (microtime(true) >= $stopat)) {
899                 $progress->output('Stopping indexing due to time limit.');
900                 break;
901             }
902         }
904         if ($sumdocs > 0) {
905             $event = \core\event\search_indexed::create(
906                     array('context' => $context));
907             $event->trigger();
908         }
910         $this->engine->index_complete($sumdocs, false);
912         // Indicate in result whether we completed indexing, or only part of it.
913         $result = new \stdClass();
914         if ($partial) {
915             $result->complete = false;
916             $result->startfromarea = $areaid;
917             $result->startfromtime = $lastindexeddoc;
918         } else {
919             $result->complete = true;
920         }
921         return $result;
922     }
924     /**
925      * Resets areas config.
926      *
927      * @throws \moodle_exception
928      * @param string $areaid
929      * @return void
930      */
931     public function reset_config($areaid = false) {
933         if (!empty($areaid)) {
934             $searchareas = array();
935             if (!$searchareas[$areaid] = static::get_search_area($areaid)) {
936                 throw new \moodle_exception('errorareanotavailable', 'search', '', $areaid);
937             }
938         } else {
939             // Only the enabled ones.
940             $searchareas = static::get_search_areas_list(true);
941         }
943         foreach ($searchareas as $searcharea) {
944             list($componentname, $varname) = $searcharea->get_config_var_name();
945             $config = $searcharea->get_config();
947             foreach ($config as $key => $value) {
948                 // We reset them all but the enable/disabled one.
949                 if ($key !== $varname . '_enabled') {
950                     set_config($key, 0, $componentname);
951                 }
952             }
953         }
954     }
956     /**
957      * Deletes an area's documents or all areas documents.
958      *
959      * @param string $areaid The area id or false for all
960      * @return void
961      */
962     public function delete_index($areaid = false) {
963         if (!empty($areaid)) {
964             $this->engine->delete($areaid);
965             $this->reset_config($areaid);
966         } else {
967             $this->engine->delete();
968             $this->reset_config();
969         }
970     }
972     /**
973      * Deletes index by id.
974      *
975      * @param int Solr Document string $id
976      */
977     public function delete_index_by_id($id) {
978         $this->engine->delete_by_id($id);
979     }
981     /**
982      * Returns search areas configuration.
983      *
984      * @param \core_search\base[] $searchareas
985      * @return \stdClass[] $configsettings
986      */
987     public function get_areas_config($searchareas) {
989         $vars = array('indexingstart', 'indexingend', 'lastindexrun', 'docsignored',
990                 'docsprocessed', 'recordsprocessed', 'partial');
992         $configsettings = [];
993         foreach ($searchareas as $searcharea) {
995             $areaid = $searcharea->get_area_id();
997             $configsettings[$areaid] = new \stdClass();
998             list($componentname, $varname) = $searcharea->get_config_var_name();
1000             if (!$searcharea->is_enabled()) {
1001                 // We delete all indexed data on disable so no info.
1002                 foreach ($vars as $var) {
1003                     $configsettings[$areaid]->{$var} = 0;
1004                 }
1005             } else {
1006                 foreach ($vars as $var) {
1007                     $configsettings[$areaid]->{$var} = get_config($componentname, $varname .'_' . $var);
1008                 }
1009             }
1011             // Formatting the time.
1012             if (!empty($configsettings[$areaid]->lastindexrun)) {
1013                 $configsettings[$areaid]->lastindexrun = userdate($configsettings[$areaid]->lastindexrun);
1014             } else {
1015                 $configsettings[$areaid]->lastindexrun = get_string('never');
1016             }
1017         }
1018         return $configsettings;
1019     }
1021     /**
1022      * Triggers search_results_viewed event
1023      *
1024      * Other data required:
1025      * - q: The query string
1026      * - page: The page number
1027      * - title: Title filter
1028      * - areaids: Search areas filter
1029      * - courseids: Courses filter
1030      * - timestart: Time start filter
1031      * - timeend: Time end filter
1032      *
1033      * @since Moodle 3.2
1034      * @param array $other Other info for the event.
1035      * @return \core\event\search_results_viewed
1036      */
1037     public static function trigger_search_results_viewed($other) {
1038         $event = \core\event\search_results_viewed::create([
1039             'context' => \context_system::instance(),
1040             'other' => $other
1041         ]);
1042         $event->trigger();
1044         return $event;
1045     }
1047     /**
1048      * Checks whether a classname is of an actual search area.
1049      *
1050      * @param string $classname
1051      * @return bool
1052      */
1053     protected static function is_search_area($classname) {
1054         if (is_subclass_of($classname, 'core_search\base')) {
1055             return (new \ReflectionClass($classname))->isInstantiable();
1056         }
1058         return false;
1059     }
1061     /**
1062      * Requests that a specific context is indexed by the scheduled task. The context will be
1063      * added to a queue which is processed by the task.
1064      *
1065      * This is used after a restore to ensure that restored items are indexed, even though their
1066      * modified time will be older than the latest indexed.
1067      *
1068      * @param \context $context Context to index within
1069      * @param string $areaid Area to index, '' = all areas
1070      */
1071     public static function request_index(\context $context, $areaid = '') {
1072         global $DB;
1074         // Check through existing requests for this context or any parent context.
1075         list ($contextsql, $contextparams) = $DB->get_in_or_equal(
1076                 $context->get_parent_context_ids(true));
1077         $existing = $DB->get_records_select('search_index_requests',
1078                 'contextid ' . $contextsql, $contextparams, '', 'id, searcharea, partialarea');
1079         foreach ($existing as $rec) {
1080             // If we haven't started processing the existing request yet, and it covers the same
1081             // area (or all areas) then that will be sufficient so don't add anything else.
1082             if ($rec->partialarea === '' && ($rec->searcharea === $areaid || $rec->searcharea === '')) {
1083                 return;
1084             }
1085         }
1087         // No suitable existing request, so add a new one.
1088         $newrecord = [ 'contextid' => $context->id, 'searcharea' => $areaid,
1089                 'timerequested' => time(), 'partialarea' => '', 'partialtime' => 0 ];
1090         $DB->insert_record('search_index_requests', $newrecord);
1091     }
1093     /**
1094      * Processes outstanding index requests. This will take the first item from the queue and
1095      * process it, continuing until an optional time limit is reached.
1096      *
1097      * If there are no index requests, the function will do nothing.
1098      *
1099      * @param float $timelimit Time limit (0 = none)
1100      * @param \progress_trace|null $progress Optional progress indicator
1101      */
1102     public function process_index_requests($timelimit = 0.0, \progress_trace $progress = null) {
1103         global $DB;
1105         if (!$progress) {
1106             $progress = new \null_progress_trace();
1107         }
1109         $complete = false;
1110         $before = microtime(true);
1111         if ($timelimit) {
1112             $stopat = $before + $timelimit;
1113         }
1114         while (true) {
1115             // Retrieve first request, using fully defined ordering.
1116             $requests = $DB->get_records('search_index_requests', null,
1117                     'timerequested, contextid, searcharea',
1118                     'id, contextid, searcharea, partialarea, partialtime', 0, 1);
1119             if (!$requests) {
1120                 // If there are no more requests, stop.
1121                 $complete = true;
1122                 break;
1123             }
1124             $request = reset($requests);
1126             // Calculate remaining time.
1127             $remainingtime = 0;
1128             $beforeindex = microtime(true);
1129             if ($timelimit) {
1130                 $remainingtime = $stopat - $beforeindex;
1131             }
1133             // Show a message before each request, indicating what will be indexed.
1134             $context = \context::instance_by_id($request->contextid);
1135             $contextname = $context->get_context_name();
1136             if ($request->searcharea) {
1137                 $contextname .= ' (search area: ' . $request->searcharea . ')';
1138             }
1139             $progress->output('Indexing requested context: ' . $contextname);
1141             // Actually index the context.
1142             $result = $this->index_context($context, $request->searcharea, $remainingtime,
1143                     $progress, $request->partialarea, $request->partialtime);
1145             // Work out shared part of message.
1146             $endmessage = $contextname . ' (' . round(microtime(true) - $beforeindex, 1) . 's)';
1148             // Update database table and continue/stop as appropriate.
1149             if ($result->complete) {
1150                 // If we completed the request, remove it from the table.
1151                 $DB->delete_records('search_index_requests', ['id' => $request->id]);
1152                 $progress->output('Completed requested context: ' . $endmessage);
1153             } else {
1154                 // If we didn't complete the request, store the partial details (how far it got).
1155                 $DB->update_record('search_index_requests', ['id' => $request->id,
1156                         'partialarea' => $result->startfromarea,
1157                         'partialtime' => $result->startfromtime]);
1158                 $progress->output('Ending requested context: ' . $endmessage);
1160                 // The time limit must have expired, so stop looping.
1161                 break;
1162             }
1163         }
1164     }