[Summary 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 area base class for blocks.
  19   *
  20   * Note: Only blocks within courses are supported.
  21   *
  22   * @package core_search
  23   * @copyright 2017 The Open University
  24   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  namespace core_search;
  28  
  29  defined('MOODLE_INTERNAL') || die();
  30  
  31  /**
  32   * Search area base class for blocks.
  33   *
  34   * Note: Only blocks within courses are supported.
  35   *
  36   * @package core_search
  37   * @copyright 2017 The Open University
  38   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39   */
  40  abstract class base_block extends base {
  41      /** @var string Cache name used for block instances */
  42      const CACHE_INSTANCES = 'base_block_instances';
  43  
  44      /**
  45       * The context levels the search area is working on.
  46       *
  47       * This can be overwriten by the search area if it works at multiple
  48       * levels.
  49       *
  50       * @var array
  51       */
  52      protected static $levels = [CONTEXT_BLOCK];
  53  
  54      /**
  55       * Gets the block name only.
  56       *
  57       * @return string Block name e.g. 'html'
  58       */
  59      public function get_block_name() {
  60          // Remove 'block_' text.
  61          return substr($this->get_component_name(), 6);
  62      }
  63  
  64      /**
  65       * Returns restrictions on which block_instances rows to return. By default, excludes rows
  66       * that have empty configdata.
  67       *
  68       * If no restriction is required, you could return ['', []].
  69       *
  70       * @return array 2-element array of SQL restriction and params for it
  71       */
  72      protected function get_indexing_restrictions() {
  73          global $DB;
  74  
  75          // This includes completely empty configdata, and also three other values that are
  76          // equivalent to empty:
  77          // - A serialized completely empty object.
  78          // - A serialized object with one field called '0' (string not int) set to boolean false
  79          //   (this can happen after backup and restore, at least historically).
  80          // - A serialized null.
  81          $stupidobject = (object)[];
  82          $zero = '0';
  83          $stupidobject->{$zero} = false;
  84          return [$DB->sql_compare_text('bi.configdata') . " != ? AND " .
  85                  $DB->sql_compare_text('bi.configdata') . " != ? AND " .
  86                  $DB->sql_compare_text('bi.configdata') . " != ? AND " .
  87                  $DB->sql_compare_text('bi.configdata') . " != ?",
  88                  ['', base64_encode(serialize((object)[])), base64_encode(serialize($stupidobject)),
  89                  base64_encode(serialize(null))]];
  90      }
  91  
  92      /**
  93       * Gets recordset of all blocks of this type modified since given time within the given context.
  94       *
  95       * See base class for detailed requirements. This implementation includes the key fields
  96       * from block_instances.
  97       *
  98       * This can be overridden to do something totally different if the block's data is stored in
  99       * other tables.
 100       *
 101       * If there are certain instances of the block which should not be included in the search index
 102       * then you can override get_indexing_restrictions; by default this excludes rows with empty
 103       * configdata.
 104       *
 105       * @param int $modifiedfrom Return only records modified after this date
 106       * @param \context|null $context Context to find blocks within
 107       * @return false|\moodle_recordset|null
 108       */
 109      public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
 110          global $DB;
 111  
 112          // Get context restrictions.
 113          list ($contextjoin, $contextparams) = $this->get_context_restriction_sql($context, 'bi');
 114  
 115          // Get custom restrictions for block type.
 116          list ($restrictions, $restrictionparams) = $this->get_indexing_restrictions();
 117          if ($restrictions) {
 118              $restrictions = 'AND ' . $restrictions;
 119          }
 120  
 121          // Query for all entries in block_instances for this type of block, within the specified
 122          // context. The query is based on the one from get_recordset_by_timestamp and applies the
 123          // same restrictions.
 124          return $DB->get_recordset_sql("
 125                  SELECT bi.id, bi.timemodified, bi.timecreated, bi.configdata,
 126                         c.id AS courseid, x.id AS contextid
 127                    FROM {block_instances} bi
 128                         $contextjoin
 129                    JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
 130                    JOIN {context} parent ON parent.id = bi.parentcontextid
 131               LEFT JOIN {course_modules} cm ON cm.id = parent.instanceid AND parent.contextlevel = ?
 132                    JOIN {course} c ON c.id = cm.course
 133                         OR (c.id = parent.instanceid AND parent.contextlevel = ?)
 134                   WHERE bi.timemodified >= ?
 135                         AND bi.blockname = ?
 136                         AND (parent.contextlevel = ? AND (" . $DB->sql_like('bi.pagetypepattern', '?') . "
 137                             OR bi.pagetypepattern IN ('site-index', 'course-*', '*')))
 138                         $restrictions
 139                ORDER BY bi.timemodified ASC",
 140                  array_merge($contextparams, [CONTEXT_BLOCK, CONTEXT_MODULE, CONTEXT_COURSE,
 141                      $modifiedfrom, $this->get_block_name(), CONTEXT_COURSE, 'course-view-%'],
 142                  $restrictionparams));
 143      }
 144  
 145      public function get_doc_url(\core_search\document $doc) {
 146          // Load block instance and find cmid if there is one.
 147          $blockinstanceid = preg_replace('~^.*-~', '', $doc->get('id'));
 148          $instance = $this->get_block_instance($blockinstanceid);
 149          $courseid = $doc->get('courseid');
 150          $anchor = 'inst' . $blockinstanceid;
 151  
 152          // Check if the block is at course or module level.
 153          if ($instance->cmid) {
 154              // No module-level page types are supported at present so the search system won't return
 155              // them. But let's put some example code here to indicate how it could work.
 156              debugging('Unexpected module-level page type for block ' . $blockinstanceid . ': ' .
 157                      $instance->pagetypepattern, DEBUG_DEVELOPER);
 158              $modinfo = get_fast_modinfo($courseid);
 159              $cm = $modinfo->get_cm($instance->cmid);
 160              return new \moodle_url($cm->url, null, $anchor);
 161          } else {
 162              // The block is at course level. Let's check the page type, although in practice we
 163              // currently only support the course main page.
 164              if ($instance->pagetypepattern === '*' || $instance->pagetypepattern === 'course-*' ||
 165                      preg_match('~^course-view-(.*)$~', $instance->pagetypepattern)) {
 166                  return new \moodle_url('/course/view.php', ['id' => $courseid], $anchor);
 167              } else if ($instance->pagetypepattern === 'site-index') {
 168                  return new \moodle_url('/', ['redirect' => 0], $anchor);
 169              } else {
 170                  debugging('Unexpected page type for block ' . $blockinstanceid . ': ' .
 171                          $instance->pagetypepattern, DEBUG_DEVELOPER);
 172                  return new \moodle_url('/course/view.php', ['id' => $courseid], $anchor);
 173              }
 174          }
 175      }
 176  
 177      public function get_context_url(\core_search\document $doc) {
 178          return $this->get_doc_url($doc);
 179      }
 180  
 181      /**
 182       * Checks access for a document in this search area.
 183       *
 184       * If you override this function for a block, you should call this base class version first
 185       * as it will check that the block is still visible to users in a supported location.
 186       *
 187       * @param int $id Document id
 188       * @return int manager:ACCESS_xx constant
 189       */
 190      public function check_access($id) {
 191          $instance = $this->get_block_instance($id, IGNORE_MISSING);
 192          if (!$instance) {
 193              // This generally won't happen because if the block has been deleted then we won't have
 194              // included its context in the search area list, but just in case.
 195              return manager::ACCESS_DELETED;
 196          }
 197  
 198          // Check block has not been moved to an unsupported area since it was indexed. (At the
 199          // moment, only blocks within site and course context are supported, also only certain
 200          // page types.)
 201          if (!$instance->courseid ||
 202                  !self::is_supported_page_type_at_course_context($instance->pagetypepattern)) {
 203              return manager::ACCESS_DELETED;
 204          }
 205  
 206          // Note we do not need to check if the block was hidden or if the user has access to the
 207          // context, because those checks are included in the list of search contexts user can access
 208          // that is calculated in manager.php every time they do a query.
 209          return manager::ACCESS_GRANTED;
 210      }
 211  
 212      /**
 213       * Checks if a page type is supported for blocks when at course (or also site) context. This
 214       * function should be consistent with the SQL in get_recordset_by_timestamp.
 215       *
 216       * @param string $pagetype Page type
 217       * @return bool True if supported
 218       */
 219      protected static function is_supported_page_type_at_course_context($pagetype) {
 220          if (in_array($pagetype, ['site-index', 'course-*', '*'])) {
 221              return true;
 222          }
 223          if (preg_match('~^course-view-~', $pagetype)) {
 224              return true;
 225          }
 226          return false;
 227      }
 228  
 229      /**
 230       * Gets a block instance with given id.
 231       *
 232       * Returns the fields id, pagetypepattern, subpagepattern from block_instances and also the
 233       * cmid (if parent context is an activity module).
 234       *
 235       * @param int $id ID of block instance
 236       * @param int $strictness MUST_EXIST or IGNORE_MISSING
 237       * @return false|mixed Block instance data (may be false if strictness is IGNORE_MISSING)
 238       */
 239      protected function get_block_instance($id, $strictness = MUST_EXIST) {
 240          global $DB;
 241  
 242          $cache = \cache::make_from_params(\cache_store::MODE_REQUEST, 'core_search',
 243                  self::CACHE_INSTANCES, [], ['simplekeys' => true]);
 244          $id = (int)$id;
 245          $instance = $cache->get($id);
 246          if (!$instance) {
 247              $instance = $DB->get_record_sql("
 248                      SELECT bi.id, bi.pagetypepattern, bi.subpagepattern,
 249                             c.id AS courseid, cm.id AS cmid
 250                        FROM {block_instances} bi
 251                        JOIN {context} parent ON parent.id = bi.parentcontextid
 252                   LEFT JOIN {course} c ON c.id = parent.instanceid AND parent.contextlevel = ?
 253                   LEFT JOIN {course_modules} cm ON cm.id = parent.instanceid AND parent.contextlevel = ?
 254                       WHERE bi.id = ?",
 255                      [CONTEXT_COURSE, CONTEXT_MODULE, $id], $strictness);
 256              $cache->set($id, $instance);
 257          }
 258          return $instance;
 259      }
 260  
 261      /**
 262       * Clears static cache. This function can be removed (with calls to it in the test script
 263       * replaced with cache_helper::purge_all) if MDL-59427 is fixed.
 264       */
 265      public static function clear_static() {
 266          \cache::make_from_params(\cache_store::MODE_REQUEST, 'core_search',
 267                  self::CACHE_INSTANCES, [], ['simplekeys' => true])->purge();
 268      }
 269  
 270      /**
 271       * Helper function that gets SQL useful for restricting a search query given a passed-in
 272       * context.
 273       *
 274       * The SQL returned will be one or more JOIN statements, surrounded by whitespace, which act
 275       * as restrictions on the query based on the rows in the block_instances table.
 276       *
 277       * We assume the block instances have already been restricted by blockname.
 278       *
 279       * Returns null if there can be no results for this block within this context.
 280       *
 281       * If named parameters are used, these will be named gcrs0, gcrs1, etc. The table aliases used
 282       * in SQL also all begin with gcrs, to avoid conflicts.
 283       *
 284       * @param \context|null $context Context to restrict the query
 285       * @param string $blocktable Alias of block_instances table
 286       * @param int $paramtype Type of SQL parameters to use (default question mark)
 287       * @return array Array with SQL and parameters
 288       * @throws \coding_exception If called with invalid params
 289       */
 290      protected function get_context_restriction_sql(\context $context = null, $blocktable = 'bi',
 291              $paramtype = SQL_PARAMS_QM) {
 292          global $DB;
 293  
 294          if (!$context) {
 295              return ['', []];
 296          }
 297  
 298          switch ($paramtype) {
 299              case SQL_PARAMS_QM:
 300                  $param1 = '?';
 301                  $param2 = '?';
 302                  $key1 = 0;
 303                  $key2 = 1;
 304                  break;
 305              case SQL_PARAMS_NAMED:
 306                  $param1 = ':gcrs0';
 307                  $param2 = ':gcrs1';
 308                  $key1 = 'gcrs0';
 309                  $key2 = 'gcrs1';
 310                  break;
 311              default:
 312                  throw new \coding_exception('Unexpected $paramtype: ' . $paramtype);
 313          }
 314  
 315          $params = [];
 316          switch ($context->contextlevel) {
 317              case CONTEXT_SYSTEM:
 318                  $sql = '';
 319                  break;
 320  
 321              case CONTEXT_COURSECAT:
 322              case CONTEXT_COURSE:
 323              case CONTEXT_MODULE:
 324              case CONTEXT_USER:
 325                  // Find all blocks whose parent is within the specified context.
 326                  $sql = " JOIN {context} gcrsx ON gcrsx.id = $blocktable.parentcontextid
 327                                AND (gcrsx.id = $param1 OR " . $DB->sql_like('gcrsx.path', $param2) . ") ";
 328                  $params[$key1] = $context->id;
 329                  $params[$key2] = $context->path . '/%';
 330                  break;
 331  
 332              case CONTEXT_BLOCK:
 333                  // Find only the specified block of this type. Since we are generating JOINs
 334                  // here, we do this by joining again to the block_instances table with the same ID.
 335                  $sql = " JOIN {block_instances} gcrsbi ON gcrsbi.id = $blocktable.id
 336                                AND gcrsbi.id = $param1 ";
 337                  $params[$key1] = $context->instanceid;
 338                  break;
 339  
 340              default:
 341                  throw new \coding_exception('Unexpected contextlevel: ' . $context->contextlevel);
 342          }
 343  
 344          return [$sql, $params];
 345      }
 346  
 347      /**
 348       * This can be used in subclasses to change ordering within the get_contexts_to_reindex
 349       * function.
 350       *
 351       * It returns 2 values:
 352       * - Extra SQL joins (tables block_instances 'bi' and context 'x' already exist).
 353       * - An ORDER BY value which must use aggregate functions, by default 'MAX(bi.timemodified) DESC'.
 354       *
 355       * Note the query already includes a GROUP BY on the context fields, so if your joins result
 356       * in multiple rows, you can use aggregate functions in the ORDER BY. See forum for an example.
 357       *
 358       * @return string[] Array with 2 elements; extra joins for the query, and ORDER BY value
 359       */
 360      protected function get_contexts_to_reindex_extra_sql() {
 361          return ['', 'MAX(bi.timemodified) DESC'];
 362      }
 363  
 364      /**
 365       * Gets a list of all contexts to reindex when reindexing this search area.
 366       *
 367       * For blocks, the default is to return all contexts for blocks of that type, that are on a
 368       * course page, in order of time added (most recent first).
 369       *
 370       * @return \Iterator Iterator of contexts to reindex
 371       * @throws \moodle_exception If any DB error
 372       */
 373      public function get_contexts_to_reindex() {
 374          global $DB;
 375  
 376          list ($extrajoins, $dborder) = $this->get_contexts_to_reindex_extra_sql();
 377          $contexts = [];
 378          $selectcolumns = \context_helper::get_preload_record_columns_sql('x');
 379          $groupbycolumns = '';
 380          foreach (\context_helper::get_preload_record_columns('x') as $column => $thing) {
 381              if ($groupbycolumns !== '') {
 382                  $groupbycolumns .= ',';
 383              }
 384              $groupbycolumns .= $column;
 385          }
 386          $rs = $DB->get_recordset_sql("
 387                  SELECT $selectcolumns
 388                    FROM {block_instances} bi
 389                    JOIN {context} x ON x.instanceid = bi.id AND x.contextlevel = ?
 390                    JOIN {context} parent ON parent.id = bi.parentcontextid
 391                         $extrajoins
 392                   WHERE bi.blockname = ? AND parent.contextlevel = ?
 393                GROUP BY $groupbycolumns
 394                ORDER BY $dborder", [CONTEXT_BLOCK, $this->get_block_name(), CONTEXT_COURSE]);
 395          return new \core\dml\recordset_walk($rs, function($rec) {
 396              $id = $rec->ctxid;
 397              \context_helper::preload_from_record($rec);
 398              return \context::instance_by_id($id);
 399          });
 400      }
 401  
 402      /**
 403       * Returns an icon instance for the document.
 404       *
 405       * @param \core_search\document $doc
 406       * @return \core_search\document_icon
 407       */
 408      public function get_doc_icon(document $doc) : document_icon {
 409          return new document_icon('e/anchor');
 410      }
 411  
 412      /**
 413       * Returns a list of category names associated with the area.
 414       *
 415       * @return array
 416       */
 417      public function get_category_names() {
 418          return [manager::SEARCH_AREA_CATEGORY_COURSE_CONTENT];
 419      }
 420  }