[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   * Class core_tag_index_builder
  19   *
  20   * @package   core_tag
  21   * @copyright 2016 Marina Glancy
  22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  defined('MOODLE_INTERNAL') || die();
  26  
  27  /**
  28   * Helper to build tag index
  29   *
  30   * This can be used by components to implement tag area callbacks. This is especially
  31   * useful for in-course content when we need to check and cache user's access to
  32   * multiple courses. Course access and accessible items are stored in session cache
  33   * with 15 minutes expiry time.
  34   *
  35   * Example of usage:
  36   *
  37   * $builder = new core_tag_index_builder($component, $itemtype, $sql, $params, $from, $limit);
  38   * while ($item = $builder->has_item_that_needs_access_check()) {
  39   *     if (!$builder->can_access_course($item->courseid)) {
  40   *         $builder->set_accessible($item, false);
  41   *     } else {
  42   *         $accessible = true; // Check access and set $accessible respectively.
  43   *         $builder->set_accessible($item, $accessible);
  44   *     }
  45   * }
  46   * $items = $builder->get_items();
  47   *
  48   * @package   core_tag
  49   * @copyright 2016 Marina Glancy
  50   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  51   */
  52  class core_tag_index_builder {
  53  
  54      /** @var string component specified in the constructor */
  55      protected $component;
  56  
  57      /** @var string itemtype specified in the constructor */
  58      protected $itemtype;
  59  
  60      /** @var string SQL statement */
  61      protected $sql;
  62  
  63      /** @var array parameters for SQL statement */
  64      protected $params;
  65  
  66      /** @var int index from which to return records */
  67      protected $from;
  68  
  69      /** @var int maximum number of records to return */
  70      protected $limit;
  71  
  72      /** @var array result of SQL query */
  73      protected $items;
  74  
  75      /** @var array list of item ids ( array_keys($this->items) ) */
  76      protected $itemkeys;
  77  
  78      /** @var string alias of the item id in the SQL result */
  79      protected $idfield = 'id';
  80  
  81      /** @var array cache of items accessibility (id => bool) */
  82      protected $accessibleitems;
  83  
  84      /** @var array cache of courses accessibility (courseid => bool) */
  85      protected $courseaccess;
  86  
  87      /** @var bool indicates that items cache was changed in this class and needs pushing to MUC */
  88      protected $cachechangedaccessible = false;
  89  
  90      /** @var bool indicates that course accessibiity cache was changed in this class and needs pushing to MUC */
  91      protected $cachechangedcourse = false;
  92  
  93      /** @var array cached courses (not pushed to MUC) */
  94      protected $courses;
  95  
  96      /**
  97       * Constructor.
  98       *
  99       * Specify the SQL query for retrieving the tagged items, SQL query must:
 100       * - return the item id as the first field and make sure that it is unique in the result
 101       * - provide ORDER BY that exclude any possibility of random results, if $fromctx was specified when searching
 102       *   for tagged items it is the best practice to make sure that items from this context are returned first.
 103       *
 104       * This query may also contain placeholders %COURSEFILTER% or %ITEMFILTER% that will be substituted with
 105       * expressions excluding courses and/or filters that are already known as inaccessible.
 106       *
 107       * Example: "WHERE c.id %COURSEFILTER% AND cm.id %ITEMFILTER%"
 108       *
 109       * This query may contain fields to preload context if context is needed for formatting values.
 110       *
 111       * It is recommended to sort by course sortorder first, this way the items from the same course will be next to
 112       * each other and the sequence of courses will the same in different tag areas.
 113       *
 114       * @param string $component component responsible for tagging
 115       * @param string $itemtype type of item that is being tagged
 116       * @param string $sql SQL query that would retrieve all relevant items without permission check
 117       * @param array $params parameters for the query (must be named)
 118       * @param int $from return a subset of records, starting at this point
 119       * @param int $limit return a subset comprising this many records in total (this field is NOT optional)
 120       */
 121      public function __construct($component, $itemtype, $sql, $params, $from, $limit) {
 122          $this->component = preg_replace('/[^A-Za-z0-9_]/i', '', $component);
 123          $this->itemtype = preg_replace('/[^A-Za-z0-9_]/i', '', $itemtype);
 124          $this->sql = $sql;
 125          $this->params = $params;
 126          $this->from = $from;
 127          $this->limit = $limit;
 128          $this->courses = array();
 129      }
 130  
 131      /**
 132       * Substitute %COURSEFILTER% with an expression filtering out courses where current user does not have access
 133       */
 134      protected function prepare_sql_courses() {
 135          global $DB;
 136          if (!preg_match('/\\%COURSEFILTER\\%/', $this->sql)) {
 137              return;
 138          }
 139          $this->init_course_access();
 140          $unaccessiblecourses = array_filter($this->courseaccess, function($item) {
 141              return !$item;
 142          });
 143          $idx = 0;
 144          while (preg_match('/^([^\\0]*?)\\%COURSEFILTER\\%([^\\0]*)$/', $this->sql, $matches)) {
 145              list($sql, $params) = $DB->get_in_or_equal(array_keys($unaccessiblecourses),
 146                      SQL_PARAMS_NAMED, 'ca_'.($idx++).'_', false, 0);
 147              $this->sql = $matches[1].' '.$sql.' '.$matches[2];
 148              $this->params += $params;
 149          }
 150      }
 151  
 152      /**
 153       * Substitute %ITEMFILTER% with an expression filtering out items where current user does not have access
 154       */
 155      protected function prepare_sql_items() {
 156          global $DB;
 157          if (!preg_match('/\\%ITEMFILTER\\%/', $this->sql)) {
 158              return;
 159          }
 160          $this->init_items_access();
 161          $unaccessibleitems = array_filter($this->accessibleitems, function($item) {
 162              return !$item;
 163          });
 164          $idx = 0;
 165          while (preg_match('/^([^\\0]*?)\\%ITEMFILTER\\%([^\\0]*)$/', $this->sql, $matches)) {
 166              list($sql, $params) = $DB->get_in_or_equal(array_keys($unaccessibleitems),
 167                      SQL_PARAMS_NAMED, 'ia_'.($idx++).'_', false, 0);
 168              $this->sql = $matches[1].' '.$sql.' '.$matches[2];
 169              $this->params += $params;
 170          }
 171      }
 172  
 173      /**
 174       * Ensures that SQL query was executed and $this->items is filled
 175       */
 176      protected function retrieve_items() {
 177          global $DB;
 178          if ($this->items !== null) {
 179              return;
 180          }
 181          $this->prepare_sql_courses();
 182          $this->prepare_sql_items();
 183          $this->items = $DB->get_records_sql($this->sql, $this->params);
 184          $this->itemkeys = array_keys($this->items);
 185          if ($this->items) {
 186              // Find the name of the first key of the item - usually 'id' but can be something different.
 187              // This must be a unique identifier of the item.
 188              $firstitem = reset($this->items);
 189              $firstitemarray = (array)$firstitem;
 190              $this->idfield = key($firstitemarray);
 191          }
 192      }
 193  
 194      /**
 195       * Returns the filtered records from SQL query result.
 196       *
 197       * This function can only be executed after $builder->has_item_that_needs_access_check() returns null
 198       *
 199       *
 200       * @return array
 201       */
 202      public function get_items() {
 203          global $DB, $CFG;
 204          if (is_siteadmin()) {
 205              $this->sql = preg_replace('/\\%COURSEFILTER\\%/', '<>0', $this->sql);
 206              $this->sql = preg_replace('/\\%ITEMFILTER\\%/', '<>0', $this->sql);
 207              return $DB->get_records_sql($this->sql, $this->params, $this->from, $this->limit);
 208          }
 209          if ($CFG->debugdeveloper && $this->has_item_that_needs_access_check()) {
 210              debugging('Caller must ensure that has_item_that_needs_access_check() does not return anything '
 211                      . 'before calling get_items(). The item list may be incomplete', DEBUG_DEVELOPER);
 212          }
 213          $this->retrieve_items();
 214          $this->save_caches();
 215          $idx = 0;
 216          $items = array();
 217          foreach ($this->itemkeys as $id) {
 218              if (!array_key_exists($id, $this->accessibleitems) || !$this->accessibleitems[$id]) {
 219                  continue;
 220              }
 221              if ($idx >= $this->from) {
 222                  $items[$id] = $this->items[$id];
 223              }
 224              $idx++;
 225              if ($idx >= $this->from + $this->limit) {
 226                  break;
 227              }
 228          }
 229          return $items;
 230      }
 231  
 232      /**
 233       * Returns the first row from the SQL result that we don't know whether it is accessible by user or not.
 234       *
 235       * This will return null when we have necessary number of accessible items to return in {@link get_items()}
 236       *
 237       * After analyzing you may decide to mark not only this record but all similar as accessible or not accessible.
 238       * For example, if you already call get_fast_modinfo() to check this item's accessibility, why not mark all
 239       * items in the same course as accessible or not accessible.
 240       *
 241       * Helpful methods: {@link set_accessible()} and {@link walk()}
 242       *
 243       * @return null|object
 244       */
 245      public function has_item_that_needs_access_check() {
 246          if (is_siteadmin()) {
 247              return null;
 248          }
 249          $this->retrieve_items();
 250          $counter = 0; // Counter for accessible items.
 251          foreach ($this->itemkeys as $id) {
 252              if (!array_key_exists($id, $this->accessibleitems)) {
 253                  return (object)(array)$this->items[$id];
 254              }
 255              $counter += $this->accessibleitems[$id] ? 1 : 0;
 256              if ($counter >= $this->from + $this->limit) {
 257                  // We found enough accessible items fot get_items() method, do not look any further.
 258                  return null;
 259              }
 260          }
 261          return null;
 262      }
 263  
 264      /**
 265       * Walk through the array of items and call $callable for each of them
 266       * @param callable $callable
 267       */
 268      public function walk($callable) {
 269          $this->retrieve_items();
 270          array_walk($this->items, $callable);
 271      }
 272  
 273      /**
 274       * Marks record or group of records as accessible (or not accessible)
 275       *
 276       * @param int|std_Class $identifier either record id of the item that needs to be set accessible
 277       * @param bool $accessible whether to mark as accessible or not accessible (default true)
 278       */
 279      public function set_accessible($identifier, $accessible = true) {
 280          if (is_object($identifier)) {
 281              $identifier = (int)($identifier->{$this->idfield});
 282          }
 283          $this->init_items_access();
 284          if (is_int($identifier)) {
 285              $accessible = (int)(bool)$accessible;
 286              if (!array_key_exists($identifier, $this->accessibleitems) ||
 287                      $this->accessibleitems[$identifier] != $accessible) {
 288                  $this->accessibleitems[$identifier] = $accessible;
 289                  $this->cachechangedaccessible;
 290              }
 291          } else {
 292              throw new coding_exception('Argument $identifier must be either int or object');
 293          }
 294      }
 295  
 296      /**
 297       * Retrieves a course record (only fields id,visible,fullname,shortname,cacherev).
 298       *
 299       * This method is useful because it also caches results and preloads course context.
 300       *
 301       * @param int $courseid
 302       */
 303      public function get_course($courseid) {
 304          global $DB;
 305          if (!array_key_exists($courseid, $this->courses)) {
 306              $ctxquery = context_helper::get_preload_record_columns_sql('ctx');
 307              $sql = "SELECT c.id,c.visible,c.fullname,c.shortname,c.cacherev, $ctxquery
 308              FROM {course} c JOIN {context} ctx ON ctx.contextlevel = ? AND ctx.instanceid=c.id
 309              WHERE c.id = ?";
 310              $params = array(CONTEXT_COURSE, $courseid);
 311              $this->courses[$courseid] = $DB->get_record_sql($sql, $params);
 312              context_helper::preload_from_record($this->courses[$courseid]);
 313          }
 314          return $this->courses[$courseid];
 315      }
 316  
 317      /**
 318       * Ensures that we read the course access from the cache.
 319       */
 320      protected function init_course_access() {
 321          if ($this->courseaccess === null) {
 322              $this->courseaccess = cache::make('core', 'tagindexbuilder')->get('courseaccess') ?: [];
 323          }
 324      }
 325  
 326      /**
 327       * Ensures that we read the items access from the cache.
 328       */
 329      protected function init_items_access() {
 330          if ($this->accessibleitems === null) {
 331              $this->accessibleitems = cache::make('core', 'tagindexbuilder')->get($this->component.'__'.$this->itemtype) ?: [];
 332          }
 333      }
 334  
 335      /**
 336       * Checks if current user has access to the course
 337       *
 338       * This method calls global function {@link can_access_course} and caches results
 339       *
 340       * @param int $courseid
 341       * @return bool
 342       */
 343      public function can_access_course($courseid) {
 344          $this->init_course_access();
 345          if (!array_key_exists($courseid, $this->courseaccess)) {
 346              $this->courseaccess[$courseid] = can_access_course($this->get_course($courseid)) ? 1 : 0;
 347              $this->cachechangedcourse = true;
 348          }
 349          return $this->courseaccess[$courseid];
 350      }
 351  
 352      /**
 353       * Saves course/items caches if needed
 354       */
 355      protected function save_caches() {
 356          if ($this->cachechangedcourse) {
 357              cache::make('core', 'tagindexbuilder')->set('courseaccess', $this->courseaccess);
 358              $this->cachechangedcourse = false;
 359          }
 360          if ($this->cachechangedaccessible) {
 361              cache::make('core', 'tagindexbuilder')->set($this->component.'__'.$this->itemtype,
 362                      $this->accessibleitems);
 363              $this->cachechangedaccessible = false;
 364          }
 365      }
 366  
 367      /**
 368       * Resets all course/items session caches - useful in unittests when we change users and enrolments.
 369       */
 370      public static function reset_caches() {
 371          cache_helper::purge_by_event('resettagindexbuilder');
 372      }
 373  }