search/classes/base.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/>.
  16
  17 /**
  18  * Search base class to be extended by search areas.
  19  *
  20  * @package    core_search
  21  * @copyright  2015 David Monllao {@link http://www.davidmonllao.com}
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 namespace core_search;
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29 /**
  30  * Base search implementation.
  31  *
  32  * Components and plugins interested in filling the search engine with data should extend this class (or any extension of this
  33  * class).
  34  *
  35  * @package    core_search
  36  * @copyright  2015 David Monllao {@link http://www.davidmonllao.com}
  37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38  */
  39 abstract class base {
  40
  41     /**
  42      * The area name as defined in the class name.
  43      *
  44      * @var string
  45      */
  46     protected $areaname = null;
  47
  48     /**
  49      * The component frankenstyle name.
  50      *
  51      * @var string
  52      */
  53     protected $componentname = null;
  54
  55     /**
  56      * The component type (core or the plugin type).
  57      *
  58      * @var string
  59      */
  60     protected $componenttype = null;
  61
  62     /**
  63      * The context levels the search implementation is working on.
  64      *
  65      * @var array
  66      */
  67     protected static $levels = [CONTEXT_SYSTEM];
  68
  69     /**
  70      * Constructor.
  71      *
  72      * @throws \coding_exception
  73      * @return void
  74      */
  75     public final function __construct() {
  76
  77         $classname = get_class($this);
  78
  79         // Detect possible issues when defining the class.
  80         if (strpos($classname, '\search') === false) {
  81             throw new \coding_exception('Search area classes should be located in \PLUGINTYPE_PLUGINNAME\search\AREANAME.');
  82         } else if (strpos($classname, '_') === false) {
  83             throw new \coding_exception($classname . ' class namespace level 1 should be its component frankenstyle name');
  84         }
  85
  86         $this->areaname = substr(strrchr($classname, '\\'), 1);
  87         $this->componentname = substr($classname, 0, strpos($classname, '\\'));
  88         $this->areaid = \core_search\manager::generate_areaid($this->componentname, $this->areaname);
  89         $this->componenttype = substr($this->componentname, 0, strpos($this->componentname, '_'));
  90     }
  91
  92     /**
  93      * Returns context levels property.
  94      *
  95      * @return int
  96      */
  97     public static function get_levels() {
  98         return static::$levels;
  99     }
 100
 101     /**
 102      * Returns the area id.
 103      *
 104      * @return string
 105      */
 106     public function get_area_id() {
 107         return $this->areaid;
 108     }
 109
 110     /**
 111      * Returns the moodle component name.
 112      *
 113      * It might be the plugin name (whole frankenstyle name) or the core subsystem name.
 114      *
 115      * @return string
 116      */
 117     public function get_component_name() {
 118         return $this->componentname;
 119     }
 120
 121     /**
 122      * Returns the component type.
 123      *
 124      * It might be a plugintype or 'core' for core subsystems.
 125      *
 126      * @return string
 127      */
 128     public function get_component_type() {
 129         return $this->componenttype;
 130     }
 131
 132     /**
 133      * Returns the area visible name.
 134      *
 135      * @param bool $lazyload Usually false, unless when in admin settings.
 136      * @return string
 137      */
 138     public function get_visible_name($lazyload = false) {
 139
 140         $component = $this->componentname;
 141
 142         // Core subsystem strings go to lang/XX/search.php.
 143         if ($this->componenttype === 'core') {
 144             $component = 'search';
 145         }
 146         return get_string('search:' . $this->areaname, $component, null, $lazyload);
 147     }
 148
 149     /**
 150      * Returns the config var name.
 151      *
 152      * It depends on whether it is a moodle subsystem or a plugin as plugin-related config should remain in their own scope.
 153      *
 154      * @access private
 155      * @return string Config var path including the plugin (or component) and the varname
 156      */
 157     public function get_config_var_name() {
 158
 159         if ($this->componenttype === 'core') {
 160             // Core subsystems config in core_search and setting name using only [a-zA-Z0-9_]+.
 161             $parts = \core_search\manager::extract_areaid_parts($this->areaid);
 162             return array('core_search', $parts[0] . '_' . $parts[1]);
 163         }
 164
 165         // Plugins config in the plugin scope.
 166         return array($this->componentname, 'search_' . $this->areaname);
 167     }
 168
 169     /**
 170      * Returns all the search area configuration.
 171      *
 172      * @return array
 173      */
 174     public function get_config() {
 175         list($componentname, $varname) = $this->get_config_var_name();
 176
 177         $config = [];
 178         $settingnames = array('_enabled', '_indexingstart', '_indexingend', '_lastindexrun', '_docsignored', '_docsprocessed', '_recordsprocessed');
 179         foreach ($settingnames as $name) {
 180             $config[$varname . $name] = get_config($componentname, $varname . $name);
 181         }
 182
 183         // Search areas are enabled by default.
 184         if ($config[$varname . '_enabled'] === false) {
 185             $config[$varname . '_enabled'] = 1;
 186         }
 187         return $config;
 188     }
 189
 190     /**
 191      * Is the search component enabled by the system administrator?
 192      *
 193      * @return bool
 194      */
 195     public function is_enabled() {
 196         list($componentname, $varname) = $this->get_config_var_name();
 197
 198         $value = get_config($componentname, $varname . '_enabled');
 199
 200         // Search areas are enabled by default.
 201         if ($value === false) {
 202             $value = 1;
 203         }
 204         return (bool)$value;
 205     }
 206
 207     public function set_enabled($isenabled) {
 208         list($componentname, $varname) = $this->get_config_var_name();
 209         return set_config($varname . '_enabled', $isenabled, $componentname);
 210     }
 211
 212     /**
 213      * Returns true if this area uses file indexing.
 214      *
 215      * @return bool
 216      */
 217     public function uses_file_indexing() {
 218         return false;
 219     }
 220
 221     /**
 222      * Returns a recordset ordered by modification date ASC.
 223      *
 224      * Each record can include any data self::get_document might need but it must:
 225      * - Include an 'id' field: Unique identifier (in this area's scope) of a document to index in the search engine
 226      *   If the indexed content field can contain embedded files, the 'id' value should match the filearea itemid.
 227      * - Only return data modified since $modifiedfrom, including $modifiedform to prevent
 228      *   some records from not being indexed (e.g. your-timemodified-fieldname >= $modifiedfrom)
 229      * - Order the returned data by time modified in ascending order, as \core_search::manager will need to store the modified time
 230      *   of the last indexed document.
 231      *
 232      * @param int $modifiedfrom
 233      * @return moodle_recordset
 234      */
 235     abstract public function get_recordset_by_timestamp($modifiedfrom = 0);
 236
 237     /**
 238      * Returns the document related with the provided record.
 239      *
 240      * This method receives a record with the document id and other info returned by get_recordset_by_timestamp
 241      * or get_recordset_by_contexts that might be useful here. The idea is to restrict database queries to
 242      * minimum as this function will be called for each document to index. As an alternative, use cached data.
 243      *
 244      * Internally it should use \core_search\document to standarise the documents before sending them to the search engine.
 245      *
 246      * Search areas should send plain text to the search engine, use the following function to convert any user
 247      * input data to plain text: {@link content_to_text}
 248      *
 249      * Valid keys for the options array are:
 250      *     indexfiles => File indexing is enabled if true.
 251      *     lastindexedtime => The last time this area was indexed. 0 if never indexed.
 252      *
 253      * @param \stdClass $record A record containing, at least, the indexed document id and a modified timestamp
 254      * @param array     $options Options for document creation
 255      * @return \core_search\document
 256      */
 257     abstract public function get_document($record, $options = array());
 258
 259     /**
 260      * Add any files to the document that should be indexed.
 261      *
 262      * @param document $document The current document
 263      * @return void
 264      */
 265     public function attach_files($document) {
 266         return;
 267     }
 268
 269     /**
 270      * Can the current user see the document.
 271      *
 272      * @param int $id The internal search area entity id.
 273      * @return bool True if the user can see it, false otherwise
 274      */
 275     abstract public function check_access($id);
 276
 277     /**
 278      * Returns a url to the document, it might match self::get_context_url().
 279      *
 280      * @param \core_search\document $doc
 281      * @return \moodle_url
 282      */
 283     abstract public function get_doc_url(\core_search\document $doc);
 284
 285     /**
 286      * Returns a url to the document context.
 287      *
 288      * @param \core_search\document $doc
 289      * @return \moodle_url
 290      */
 291     abstract public function get_context_url(\core_search\document $doc);
 292 }