Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Search base class to be extended by search areas.
 *
 * @package    core_search
 * @copyright  2015 David Monllao {@link http://www.davidmonllao.com}
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core_search;

defined('MOODLE_INTERNAL') || die();

/**
 * Base search implementation.
 *
 * Components and plugins interested in filling the search engine with data should extend this class (or any extension of this
 * class).
 *
 * @package    core_search
 * @copyright  2015 David Monllao {@link http://www.davidmonllao.com}
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class base {

    /**
     * The area name as defined in the class name.
     *
     * @var string
     */
    protected $areaname = null;

    /**
     * The component frankenstyle name.
     *
     * @var string
     */
    protected $componentname = null;

    /**
     * The component type (core or the plugin type).
     *
     * @var string
     */
    protected $componenttype = null;

    /**
     * The context levels the search implementation is working on.
     *
     * @var array
     */
    protected static $levels = [CONTEXT_SYSTEM];

    /**
> * An area id from the componentname and the area name. * Constructor. > * * > * @var string * @throws \coding_exception > */ * @return void > public $areaid; */ > public final function __construct() { > /**
$classname = get_class($this); // Detect possible issues when defining the class. if (strpos($classname, '\search') === false) { throw new \coding_exception('Search area classes should be located in \PLUGINTYPE_PLUGINNAME\search\AREANAME.'); } else if (strpos($classname, '_') === false) { throw new \coding_exception($classname . ' class namespace level 1 should be its component frankenstyle name'); } $this->areaname = substr(strrchr($classname, '\\'), 1); $this->componentname = substr($classname, 0, strpos($classname, '\\')); $this->areaid = \core_search\manager::generate_areaid($this->componentname, $this->areaname); $this->componenttype = substr($this->componentname, 0, strpos($this->componentname, '_')); } /** * Returns context levels property. * * @return int */ public static function get_levels() { return static::$levels; } /** * Returns the area id. * * @return string */ public function get_area_id() { return $this->areaid; } /** * Returns the moodle component name. * * It might be the plugin name (whole frankenstyle name) or the core subsystem name. * * @return string */ public function get_component_name() { return $this->componentname; } /** * Returns the component type. * * It might be a plugintype or 'core' for core subsystems. * * @return string */ public function get_component_type() { return $this->componenttype; } /** * Returns the area visible name. * * @param bool $lazyload Usually false, unless when in admin settings. * @return string */ public function get_visible_name($lazyload = false) { $component = $this->componentname; // Core subsystem strings go to lang/XX/search.php. if ($this->componenttype === 'core') { $component = 'search'; } return get_string('search:' . $this->areaname, $component, null, $lazyload); } /** * Returns the config var name. * * It depends on whether it is a moodle subsystem or a plugin as plugin-related config should remain in their own scope. * * @access private * @return string Config var path including the plugin (or component) and the varname */ public function get_config_var_name() { if ($this->componenttype === 'core') { // Core subsystems config in core_search and setting name using only [a-zA-Z0-9_]+. $parts = \core_search\manager::extract_areaid_parts($this->areaid); return array('core_search', $parts[0] . '_' . $parts[1]); } // Plugins config in the plugin scope. return array($this->componentname, 'search_' . $this->areaname); } /** * Returns all the search area configuration. * * @return array */ public function get_config() { list($componentname, $varname) = $this->get_config_var_name(); $config = []; $settingnames = self::get_settingnames(); foreach ($settingnames as $name) { $config[$varname . $name] = get_config($componentname, $varname . $name); } // Search areas are enabled by default. if ($config[$varname . '_enabled'] === false) { $config[$varname . '_enabled'] = 1; } return $config; } /** * Return a list of all required setting names. * * @return array */ public static function get_settingnames() { return array('_enabled', '_indexingstart', '_indexingend', '_lastindexrun', '_docsignored', '_docsprocessed', '_recordsprocessed', '_partial'); } /** * Is the search component enabled by the system administrator? * * @return bool */ public function is_enabled() { list($componentname, $varname) = $this->get_config_var_name(); $value = get_config($componentname, $varname . '_enabled'); // Search areas are enabled by default. if ($value === false) { $value = 1; } return (bool)$value; } public function set_enabled($isenabled) { list($componentname, $varname) = $this->get_config_var_name(); return set_config($varname . '_enabled', $isenabled, $componentname); } /** * Gets the length of time spent indexing this area (the last time it was indexed). * * @return int|bool Time in seconds spent indexing this area last time, false if never indexed */ public function get_last_indexing_duration() { list($componentname, $varname) = $this->get_config_var_name(); $start = get_config($componentname, $varname . '_indexingstart'); $end = get_config($componentname, $varname . '_indexingend'); if ($start && $end) { return $end - $start; } else { return false; } } /** * Returns true if this area uses file indexing. * * @return bool */ public function uses_file_indexing() { return false; } /** * Returns a recordset ordered by modification date ASC. * * Each record can include any data self::get_document might need but it must: * - Include an 'id' field: Unique identifier (in this area's scope) of a document to index in the search engine * If the indexed content field can contain embedded files, the 'id' value should match the filearea itemid. * - Only return data modified since $modifiedfrom, including $modifiedform to prevent * some records from not being indexed (e.g. your-timemodified-fieldname >= $modifiedfrom) * - Order the returned data by time modified in ascending order, as \core_search::manager will need to store the modified time * of the last indexed document. * * Since Moodle 3.4, subclasses should instead implement get_document_recordset, which has * an additional context parameter. This function continues to work for implementations which * haven't been updated, or where the context parameter is not required. * * @param int $modifiedfrom * @return \moodle_recordset */ public function get_recordset_by_timestamp($modifiedfrom = 0) { $result = $this->get_document_recordset($modifiedfrom); if ($result === false) { throw new \coding_exception( 'Search area must implement get_document_recordset or get_recordset_by_timestamp'); } return $result; } /** * Returns a recordset containing all items from this area, optionally within the given context, * and including only items modifed from (>=) the specified time. The recordset must be ordered * in ascending order of modified time. * * Each record can include any data self::get_document might need. It must include an 'id' * field,a unique identifier (in this area's scope) of a document to index in the search engine. * If the indexed content field can contain embedded files, the 'id' value should match the * filearea itemid. * * The return value can be a recordset, null (if this area does not provide any results in the * given context and there is no need to do a database query to find out), or false (if this * facility is not currently supported by this search area). * * If this function returns false, then: * - If indexing the entire system (no context restriction) the search indexer will try * get_recordset_by_timestamp instead * - If trying to index a context (e.g. when restoring a course), the search indexer will not * index this area, so that restored content may not be indexed. * * The default implementation returns false, indicating that this facility is not supported and * the older get_recordset_by_timestamp function should be used. * * This function must accept all possible values for the $context parameter. For example, if * you are implementing this function for the forum module, it should still operate correctly * if called with the context for a glossary module, or for the HTML block. (In these cases * where it will not return any data, it may return null.) * * The $context parameter can also be null or the system context; both of these indicate that * all data, without context restriction, should be returned. * * @param int $modifiedfrom Return only records modified after this date * @param \context|null $context Context (null means no context restriction) * @return \moodle_recordset|null|false Recordset / null if no results / false if not supported * @since Moodle 3.4 */ public function get_document_recordset($modifiedfrom = 0, \context $context = null) { return false; } /** * Checks if get_document_recordset is supported for this search area. * * For many uses you can simply call get_document_recordset and see if it returns false, but * this function is useful when you don't want to actually call the function right away. */ public function supports_get_document_recordset() { // Easiest way to check this is simply to see if the class has overridden the default // function. $method = new \ReflectionMethod($this, 'get_document_recordset'); return $method->getDeclaringClass()->getName() !== self::class; } /** * Returns the document related with the provided record. * * This method receives a record with the document id and other info returned by get_recordset_by_timestamp * or get_recordset_by_contexts that might be useful here. The idea is to restrict database queries to * minimum as this function will be called for each document to index. As an alternative, use cached data. * * Internally it should use \core_search\document to standarise the documents before sending them to the search engine. * * Search areas should send plain text to the search engine, use the following function to convert any user * input data to plain text: {@link content_to_text} * * Valid keys for the options array are: * indexfiles => File indexing is enabled if true. * lastindexedtime => The last time this area was indexed. 0 if never indexed. * * The lastindexedtime value is not set if indexing a specific context rather than the whole * system. * * @param \stdClass $record A record containing, at least, the indexed document id and a modified timestamp * @param array $options Options for document creation * @return \core_search\document */ abstract public function get_document($record, $options = array()); /** * Returns the document title to display. * * Allow to customize the document title string to display. * * @param \core_search\document $doc * @return string Document title to display in the search results page */ public function get_document_display_title(\core_search\document $doc) { return $doc->get('title'); } /** * Return the context info required to index files for * this search area. * * Should be onerridden by each search area. * * @return array */ public function get_search_fileareas() { $fileareas = array(); return $fileareas; } /** * Files related to the current document are attached, * to the document object ready for indexing by * Global Search. * * The default implementation retrieves all files for * the file areas returned by get_search_fileareas(). * If you need to filter files to specific items per * file area, you will need to override this method * and explicitly provide the items. * * @param document $document The current document * @return void */ public function attach_files($document) { $fileareas = $this->get_search_fileareas(); $contextid = $document->get('contextid'); $component = $this->get_component_name(); $itemid = $document->get('itemid'); foreach ($fileareas as $filearea) { $fs = get_file_storage(); $files = $fs->get_area_files($contextid, $component, $filearea, $itemid, '', false); foreach ($files as $file) { $document->add_stored_file($file); } } } /** * Can the current user see the document. * * @param int $id The internal search area entity id. * @return int manager:ACCESS_xx constant */ abstract public function check_access($id); /** * Returns a url to the document, it might match self::get_context_url(). * * @param \core_search\document $doc * @return \moodle_url */ abstract public function get_doc_url(\core_search\document $doc); /** * Returns a url to the document context. * * @param \core_search\document $doc * @return \moodle_url */ abstract public function get_context_url(\core_search\document $doc); /** * Helper function that gets SQL useful for restricting a search query given a passed-in * context, for data stored at course level. * * The SQL returned will be zero or more JOIN statements, surrounded by whitespace, which act * as restrictions on the query based on the rows in a module table. * * You can pass in a null or system context, which will both return an empty string and no * params. * * Returns an array with two nulls if there can be no results for a course within this context. * * If named parameters are used, these will be named gclcrs0, gclcrs1, etc. The table aliases * used in SQL also all begin with gclcrs, to avoid conflicts. * * @param \context|null $context Context to restrict the query * @param string $coursetable Name of alias for course table e.g. 'c' * @param int $paramtype Type of SQL parameters to use (default question mark) * @return array Array with SQL and parameters; both null if no need to query * @throws \coding_exception If called with invalid params */ protected function get_course_level_context_restriction_sql(?\context $context, $coursetable, $paramtype = SQL_PARAMS_QM) { global $DB; if (!$context) { return ['', []]; } switch ($paramtype) { case SQL_PARAMS_QM: $param1 = '?'; $param2 = '?'; $key1 = 0; $key2 = 1; break; case SQL_PARAMS_NAMED: $param1 = ':gclcrs0'; $param2 = ':gclcrs1'; $key1 = 'gclcrs0'; $key2 = 'gclcrs1'; break; default: throw new \coding_exception('Unexpected $paramtype: ' . $paramtype); } $params = []; switch ($context->contextlevel) { case CONTEXT_SYSTEM: $sql = ''; break; case CONTEXT_COURSECAT: // Find all courses within the specified category or any sub-category. $pathmatch = $DB->sql_like('gclcrscc2.path', $DB->sql_concat('gclcrscc1.path', $param2)); $sql = " JOIN {course_categories} gclcrscc1 ON gclcrscc1.id = $param1 JOIN {course_categories} gclcrscc2 ON gclcrscc2.id = $coursetable.category AND (gclcrscc2.id = gclcrscc1.id OR $pathmatch) "; $params[$key1] = $context->instanceid; // Note: This param is a bit annoying as it obviously never changes, but sql_like // throws a debug warning if you pass it anything with quotes in, so it has to be // a bound parameter. $params[$key2] = '/%'; break; case CONTEXT_COURSE: // We just join again against the same course entry and confirm that it has the // same id as the context. $sql = " JOIN {course} gclcrsc ON gclcrsc.id = $coursetable.id AND gclcrsc.id = $param1"; $params[$key1] = $context->instanceid; break; case CONTEXT_BLOCK: case CONTEXT_MODULE: case CONTEXT_USER: // Context cannot contain any courses. return [null, null]; default: throw new \coding_exception('Unexpected contextlevel: ' . $context->contextlevel); } return [$sql, $params]; } /** * Gets a list of all contexts to reindex when reindexing this search area. The list should be * returned in an order that is likely to be suitable when reindexing, for example with newer * contexts first. * * The default implementation simply returns the system context, which will result in * reindexing everything in normal date order (oldest first). * * @return \Iterator Iterator of contexts to reindex */ public function get_contexts_to_reindex() { return new \ArrayIterator([\context_system::instance()]); } /** * Returns an icon instance for the document. * * @param \core_search\document $doc * @return \core_search\document_icon */ public function get_doc_icon(document $doc) : document_icon { return new document_icon('i/empty'); } /** * Returns a list of category names associated with the area. * * @return array */ public function get_category_names() { return [manager::SEARCH_AREA_CATEGORY_OTHER]; } }