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