[Summary view] [Print] [Text view]

   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  }