[Summary view]

Differences Between: [Versions 39 and 310] [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]

   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   * Contains class core_course_category responsible for course category operations
  19   *
  20   * @package    core
  21   * @subpackage course
  22   * @copyright  2013 Marina Glancy
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  /**
  29   * Class to store, cache, render and manage course category
  30   *
  31   * @property-read int $id
  32   * @property-read string $name
  33   * @property-read string $idnumber
  34   * @property-read string $description
  35   * @property-read int $descriptionformat
  36   * @property-read int $parent
  37   * @property-read int $sortorder
  38   * @property-read int $coursecount
  39   * @property-read int $visible
  40   * @property-read int $visibleold
  41   * @property-read int $timemodified
  42   * @property-read int $depth
  43   * @property-read string $path
  44   * @property-read string $theme
  45   *
  46   * @package    core
  47   * @subpackage course
  48   * @copyright  2013 Marina Glancy
  49   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  50   */
  51  class core_course_category implements renderable, cacheable_object, IteratorAggregate {
  52      /** @var core_course_category stores pseudo category with id=0. Use core_course_category::get(0) to retrieve */
  53      protected static $coursecat0;
  54  
  55      /** @var array list of all fields and their short name and default value for caching */
  56      protected static $coursecatfields = array(
  57          'id' => array('id', 0),
  58          'name' => array('na', ''),
  59          'idnumber' => array('in', null),
  60          'description' => null, // Not cached.
  61          'descriptionformat' => null, // Not cached.
  62          'parent' => array('pa', 0),
  63          'sortorder' => array('so', 0),
  64          'coursecount' => array('cc', 0),
  65          'visible' => array('vi', 1),
  66          'visibleold' => null, // Not cached.
  67          'timemodified' => null, // Not cached.
  68          'depth' => array('dh', 1),
  69          'path' => array('ph', null),
  70          'theme' => null, // Not cached.
  71      );
  72  
  73      /** @var int */
  74      protected $id;
  75  
  76      /** @var string */
  77      protected $name = '';
  78  
  79      /** @var string */
  80      protected $idnumber = null;
  81  
  82      /** @var string */
  83      protected $description = false;
  84  
  85      /** @var int */
  86      protected $descriptionformat = false;
  87  
  88      /** @var int */
  89      protected $parent = 0;
  90  
  91      /** @var int */
  92      protected $sortorder = 0;
  93  
  94      /** @var int */
  95      protected $coursecount = false;
  96  
  97      /** @var int */
  98      protected $visible = 1;
  99  
 100      /** @var int */
 101      protected $visibleold = false;
 102  
 103      /** @var int */
 104      protected $timemodified = false;
 105  
 106      /** @var int */
 107      protected $depth = 0;
 108  
 109      /** @var string */
 110      protected $path = '';
 111  
 112      /** @var string */
 113      protected $theme = false;
 114  
 115      /** @var bool */
 116      protected $fromcache = false;
 117  
 118      /**
 119       * Magic setter method, we do not want anybody to modify properties from the outside
 120       *
 121       * @param string $name
 122       * @param mixed $value
 123       */
 124      public function __set($name, $value) {
 125          debugging('Can not change core_course_category instance properties!', DEBUG_DEVELOPER);
 126      }
 127  
 128      /**
 129       * Magic method getter, redirects to read only values. Queries from DB the fields that were not cached
 130       *
 131       * @param string $name
 132       * @return mixed
 133       */
 134      public function __get($name) {
 135          global $DB;
 136          if (array_key_exists($name, self::$coursecatfields)) {
 137              if ($this->$name === false) {
 138                  // Property was not retrieved from DB, retrieve all not retrieved fields.
 139                  $notretrievedfields = array_diff_key(self::$coursecatfields, array_filter(self::$coursecatfields));
 140                  $record = $DB->get_record('course_categories', array('id' => $this->id),
 141                          join(',', array_keys($notretrievedfields)), MUST_EXIST);
 142                  foreach ($record as $key => $value) {
 143                      $this->$key = $value;
 144                  }
 145              }
 146              return $this->$name;
 147          }
 148          debugging('Invalid core_course_category property accessed! '.$name, DEBUG_DEVELOPER);
 149          return null;
 150      }
 151  
 152      /**
 153       * Full support for isset on our magic read only properties.
 154       *
 155       * @param string $name
 156       * @return bool
 157       */
 158      public function __isset($name) {
 159          if (array_key_exists($name, self::$coursecatfields)) {
 160              return isset($this->$name);
 161          }
 162          return false;
 163      }
 164  
 165      /**
 166       * All properties are read only, sorry.
 167       *
 168       * @param string $name
 169       */
 170      public function __unset($name) {
 171          debugging('Can not unset core_course_category instance properties!', DEBUG_DEVELOPER);
 172      }
 173  
 174      /**
 175       * Get list of plugin callback functions.
 176       *
 177       * @param string $name Callback function name.
 178       * @return [callable] $pluginfunctions
 179       */
 180      public function get_plugins_callback_function(string $name) : array {
 181          $pluginfunctions = [];
 182          if ($pluginsfunction = get_plugins_with_function($name)) {
 183              foreach ($pluginsfunction as $plugintype => $plugins) {
 184                  foreach ($plugins as $pluginfunction) {
 185                      $pluginfunctions[] = $pluginfunction;
 186                  }
 187              }
 188          }
 189          return $pluginfunctions;
 190      }
 191  
 192      /**
 193       * Create an iterator because magic vars can't be seen by 'foreach'.
 194       *
 195       * implementing method from interface IteratorAggregate
 196       *
 197       * @return ArrayIterator
 198       */
 199      public function getIterator() {
 200          $ret = array();
 201          foreach (self::$coursecatfields as $property => $unused) {
 202              if ($this->$property !== false) {
 203                  $ret[$property] = $this->$property;
 204              }
 205          }
 206          return new ArrayIterator($ret);
 207      }
 208  
 209      /**
 210       * Constructor
 211       *
 212       * Constructor is protected, use core_course_category::get($id) to retrieve category
 213       *
 214       * @param stdClass $record record from DB (may not contain all fields)
 215       * @param bool $fromcache whether it is being restored from cache
 216       */
 217      protected function __construct(stdClass $record, $fromcache = false) {
 218          context_helper::preload_from_record($record);
 219          foreach ($record as $key => $val) {
 220              if (array_key_exists($key, self::$coursecatfields)) {
 221                  $this->$key = $val;
 222              }
 223          }
 224          $this->fromcache = $fromcache;
 225      }
 226  
 227      /**
 228       * Returns coursecat object for requested category
 229       *
 230       * If category is not visible to the given user, it is treated as non existing
 231       * unless $alwaysreturnhidden is set to true
 232       *
 233       * If id is 0, the pseudo object for root category is returned (convenient
 234       * for calling other functions such as get_children())
 235       *
 236       * @param int $id category id
 237       * @param int $strictness whether to throw an exception (MUST_EXIST) or
 238       *     return null (IGNORE_MISSING) in case the category is not found or
 239       *     not visible to current user
 240       * @param bool $alwaysreturnhidden set to true if you want an object to be
 241       *     returned even if this category is not visible to the current user
 242       *     (category is hidden and user does not have
 243       *     'moodle/category:viewhiddencategories' capability). Use with care!
 244       * @param int|stdClass $user The user id or object. By default (null) checks the visibility to the current user.
 245       * @return null|self
 246       * @throws moodle_exception
 247       */
 248      public static function get($id, $strictness = MUST_EXIST, $alwaysreturnhidden = false, $user = null) {
 249          if (!$id) {
 250              // Top-level category.
 251              if ($alwaysreturnhidden || self::top()->is_uservisible()) {
 252                  return self::top();
 253              }
 254              if ($strictness == MUST_EXIST) {
 255                  throw new moodle_exception('cannotviewcategory');
 256              }
 257              return null;
 258          }
 259  
 260          // Try to get category from cache or retrieve from the DB.
 261          $coursecatrecordcache = cache::make('core', 'coursecatrecords');
 262          $coursecat = $coursecatrecordcache->get($id);
 263          if ($coursecat === false) {
 264              if ($records = self::get_records('cc.id = :id', array('id' => $id))) {
 265                  $record = reset($records);
 266                  $coursecat = new self($record);
 267                  // Store in cache.
 268                  $coursecatrecordcache->set($id, $coursecat);
 269              }
 270          }
 271  
 272          if (!$coursecat) {
 273              // Course category not found.
 274              if ($strictness == MUST_EXIST) {
 275                  throw new moodle_exception('unknowncategory');
 276              }
 277              $coursecat = null;
 278          } else if (!$alwaysreturnhidden && !$coursecat->is_uservisible($user)) {
 279              // Course category is found but user can not access it.
 280              if ($strictness == MUST_EXIST) {
 281                  throw new moodle_exception('cannotviewcategory');
 282              }
 283              $coursecat = null;
 284          }
 285          return $coursecat;
 286      }
 287  
 288      /**
 289       * Returns the pseudo-category representing the whole system (id=0, context_system)
 290       *
 291       * @return core_course_category
 292       */
 293      public static function top() {
 294          if (!isset(self::$coursecat0)) {
 295              $record = new stdClass();
 296              $record->id = 0;
 297              $record->visible = 1;
 298              $record->depth = 0;
 299              $record->path = '';
 300              $record->locked = 0;
 301              self::$coursecat0 = new self($record);
 302          }
 303          return self::$coursecat0;
 304      }
 305  
 306      /**
 307       * Returns the top-most category for the current user
 308       *
 309       * Examples:
 310       * 1. User can browse courses everywhere - return self::top() - pseudo-category with id=0
 311       * 2. User does not have capability to browse courses on the system level but
 312       *    has it in ONE course category - return this course category
 313       * 3. User has capability to browse courses in two course categories - return self::top()
 314       *
 315       * @return core_course_category|null
 316       */
 317      public static function user_top() {
 318          $children = self::top()->get_children();
 319          if (count($children) == 1) {
 320              // User has access to only one category on the top level. Return this category as "user top category".
 321              return reset($children);
 322          }
 323          if (count($children) > 1) {
 324              // User has access to more than one category on the top level. Return the top as "user top category".
 325              // In this case user actually may not have capability 'moodle/category:viewcourselist' on the top level.
 326              return self::top();
 327          }
 328          // User can not access any categories on the top level.
 329          // TODO MDL-10965 find ANY/ALL categories in the tree where user has access to.
 330          return self::get(0, IGNORE_MISSING);
 331      }
 332  
 333      /**
 334       * Load many core_course_category objects.
 335       *
 336       * @param array $ids An array of category ID's to load.
 337       * @return core_course_category[]
 338       */
 339      public static function get_many(array $ids) {
 340          global $DB;
 341          $coursecatrecordcache = cache::make('core', 'coursecatrecords');
 342          $categories = $coursecatrecordcache->get_many($ids);
 343          $toload = array();
 344          foreach ($categories as $id => $result) {
 345              if ($result === false) {
 346                  $toload[] = $id;
 347              }
 348          }
 349          if (!empty($toload)) {
 350              list($where, $params) = $DB->get_in_or_equal($toload, SQL_PARAMS_NAMED);
 351              $records = self::get_records('cc.id '.$where, $params);
 352              $toset = array();
 353              foreach ($records as $record) {
 354                  $categories[$record->id] = new self($record);
 355                  $toset[$record->id] = $categories[$record->id];
 356              }
 357              $coursecatrecordcache->set_many($toset);
 358          }
 359          return $categories;
 360      }
 361  
 362      /**
 363       * Load all core_course_category objects.
 364       *
 365       * @param array $options Options:
 366       *              - returnhidden Return categories even if they are hidden
 367       * @return  core_course_category[]
 368       */
 369      public static function get_all($options = []) {
 370          global $DB;
 371  
 372          $coursecatrecordcache = cache::make('core', 'coursecatrecords');
 373  
 374          $catcontextsql = \context_helper::get_preload_record_columns_sql('ctx');
 375          $catsql = "SELECT cc.*, {$catcontextsql}
 376                       FROM {course_categories} cc
 377                       JOIN {context} ctx ON cc.id = ctx.instanceid";
 378          $catsqlwhere = "WHERE ctx.contextlevel = :contextlevel";
 379          $catsqlorder = "ORDER BY cc.depth ASC, cc.sortorder ASC";
 380  
 381          $catrs = $DB->get_recordset_sql("{$catsql} {$catsqlwhere} {$catsqlorder}", [
 382              'contextlevel' => CONTEXT_COURSECAT,
 383          ]);
 384  
 385          $types['categories'] = [];
 386          $categories = [];
 387          $toset = [];
 388          foreach ($catrs as $record) {
 389              $category = new self($record);
 390              $toset[$category->id] = $category;
 391  
 392              if (!empty($options['returnhidden']) || $category->is_uservisible()) {
 393                  $categories[$record->id] = $category;
 394              }
 395          }
 396          $catrs->close();
 397  
 398          $coursecatrecordcache->set_many($toset);
 399  
 400          return $categories;
 401  
 402      }
 403  
 404      /**
 405       * Returns the first found category
 406       *
 407       * Note that if there are no categories visible to the current user on the first level,
 408       * the invisible category may be returned
 409       *
 410       * @return core_course_category
 411       */
 412      public static function get_default() {
 413          if ($visiblechildren = self::top()->get_children()) {
 414              $defcategory = reset($visiblechildren);
 415          } else {
 416              $toplevelcategories = self::get_tree(0);
 417              $defcategoryid = $toplevelcategories[0];
 418              $defcategory = self::get($defcategoryid, MUST_EXIST, true);
 419          }
 420          return $defcategory;
 421      }
 422  
 423      /**
 424       * Restores the object after it has been externally modified in DB for example
 425       * during {@link fix_course_sortorder()}
 426       */
 427      protected function restore() {
 428          if (!$this->id) {
 429              return;
 430          }
 431          // Update all fields in the current object.
 432          $newrecord = self::get($this->id, MUST_EXIST, true);
 433          foreach (self::$coursecatfields as $key => $unused) {
 434              $this->$key = $newrecord->$key;
 435          }
 436      }
 437  
 438      /**
 439       * Creates a new category either from form data or from raw data
 440       *
 441       * Please note that this function does not verify access control.
 442       *
 443       * Exception is thrown if name is missing or idnumber is duplicating another one in the system.
 444       *
 445       * Category visibility is inherited from parent unless $data->visible = 0 is specified
 446       *
 447       * @param array|stdClass $data
 448       * @param array $editoroptions if specified, the data is considered to be
 449       *    form data and file_postupdate_standard_editor() is being called to
 450       *    process images in description.
 451       * @return core_course_category
 452       * @throws moodle_exception
 453       */
 454      public static function create($data, $editoroptions = null) {
 455          global $DB, $CFG;
 456          $data = (object)$data;
 457          $newcategory = new stdClass();
 458  
 459          $newcategory->descriptionformat = FORMAT_MOODLE;
 460          $newcategory->description = '';
 461          // Copy all description* fields regardless of whether this is form data or direct field update.
 462          foreach ($data as $key => $value) {
 463              if (preg_match("/^description/", $key)) {
 464                  $newcategory->$key = $value;
 465              }
 466          }
 467  
 468          if (empty($data->name)) {
 469              throw new moodle_exception('categorynamerequired');
 470          }
 471          if (core_text::strlen($data->name) > 255) {
 472              throw new moodle_exception('categorytoolong');
 473          }
 474          $newcategory->name = $data->name;
 475  
 476          // Validate and set idnumber.
 477          if (isset($data->idnumber)) {
 478              if (core_text::strlen($data->idnumber) > 100) {
 479                  throw new moodle_exception('idnumbertoolong');
 480              }
 481              if (strval($data->idnumber) !== '' && $DB->record_exists('course_categories', array('idnumber' => $data->idnumber))) {
 482                  throw new moodle_exception('categoryidnumbertaken');
 483              }
 484              $newcategory->idnumber = $data->idnumber;
 485          }
 486  
 487          if (isset($data->theme) && !empty($CFG->allowcategorythemes)) {
 488              $newcategory->theme = $data->theme;
 489          }
 490  
 491          if (empty($data->parent)) {
 492              $parent = self::top();
 493          } else {
 494              $parent = self::get($data->parent, MUST_EXIST, true);
 495          }
 496          $newcategory->parent = $parent->id;
 497          $newcategory->depth = $parent->depth + 1;
 498  
 499          // By default category is visible, unless visible = 0 is specified or parent category is hidden.
 500          if (isset($data->visible) && !$data->visible) {
 501              // Create a hidden category.
 502              $newcategory->visible = $newcategory->visibleold = 0;
 503          } else {
 504              // Create a category that inherits visibility from parent.
 505              $newcategory->visible = $parent->visible;
 506              // In case parent is hidden, when it changes visibility this new subcategory will automatically become visible too.
 507              $newcategory->visibleold = 1;
 508          }
 509  
 510          $newcategory->sortorder = 0;
 511          $newcategory->timemodified = time();
 512  
 513          $newcategory->id = $DB->insert_record('course_categories', $newcategory);
 514  
 515          // Update path (only possible after we know the category id.
 516          $path = $parent->path . '/' . $newcategory->id;
 517          $DB->set_field('course_categories', 'path', $path, array('id' => $newcategory->id));
 518  
 519          fix_course_sortorder();
 520  
 521          // If this is data from form results, save embedded files and update description.
 522          $categorycontext = context_coursecat::instance($newcategory->id);
 523          if ($editoroptions) {
 524              $newcategory = file_postupdate_standard_editor($newcategory, 'description', $editoroptions, $categorycontext,
 525                                                             'coursecat', 'description', 0);
 526  
 527              // Update only fields description and descriptionformat.
 528              $updatedata = new stdClass();
 529              $updatedata->id = $newcategory->id;
 530              $updatedata->description = $newcategory->description;
 531              $updatedata->descriptionformat = $newcategory->descriptionformat;
 532              $DB->update_record('course_categories', $updatedata);
 533          }
 534  
 535          $event = \core\event\course_category_created::create(array(
 536              'objectid' => $newcategory->id,
 537              'context' => $categorycontext
 538          ));
 539          $event->trigger();
 540  
 541          cache_helper::purge_by_event('changesincoursecat');
 542  
 543          return self::get($newcategory->id, MUST_EXIST, true);
 544      }
 545  
 546      /**
 547       * Updates the record with either form data or raw data
 548       *
 549       * Please note that this function does not verify access control.
 550       *
 551       * This function calls core_course_category::change_parent_raw if field 'parent' is updated.
 552       * It also calls core_course_category::hide_raw or core_course_category::show_raw if 'visible' is updated.
 553       * Visibility is changed first and then parent is changed. This means that
 554       * if parent category is hidden, the current category will become hidden
 555       * too and it may overwrite whatever was set in field 'visible'.
 556       *
 557       * Note that fields 'path' and 'depth' can not be updated manually
 558       * Also core_course_category::update() can not directly update the field 'sortoder'
 559       *
 560       * @param array|stdClass $data
 561       * @param array $editoroptions if specified, the data is considered to be
 562       *    form data and file_postupdate_standard_editor() is being called to
 563       *    process images in description.
 564       * @throws moodle_exception
 565       */
 566      public function update($data, $editoroptions = null) {
 567          global $DB, $CFG;
 568          if (!$this->id) {
 569              // There is no actual DB record associated with root category.
 570              return;
 571          }
 572  
 573          $data = (object)$data;
 574          $newcategory = new stdClass();
 575          $newcategory->id = $this->id;
 576  
 577          // Copy all description* fields regardless of whether this is form data or direct field update.
 578          foreach ($data as $key => $value) {
 579              if (preg_match("/^description/", $key)) {
 580                  $newcategory->$key = $value;
 581              }
 582          }
 583  
 584          if (isset($data->name) && empty($data->name)) {
 585              throw new moodle_exception('categorynamerequired');
 586          }
 587  
 588          if (!empty($data->name) && $data->name !== $this->name) {
 589              if (core_text::strlen($data->name) > 255) {
 590                  throw new moodle_exception('categorytoolong');
 591              }
 592              $newcategory->name = $data->name;
 593          }
 594  
 595          if (isset($data->idnumber) && $data->idnumber !== $this->idnumber) {
 596              if (core_text::strlen($data->idnumber) > 100) {
 597                  throw new moodle_exception('idnumbertoolong');
 598              }
 599              if (strval($data->idnumber) !== '' && $DB->record_exists('course_categories', array('idnumber' => $data->idnumber))) {
 600                  throw new moodle_exception('categoryidnumbertaken');
 601              }
 602              $newcategory->idnumber = $data->idnumber;
 603          }
 604  
 605          if (isset($data->theme) && !empty($CFG->allowcategorythemes)) {
 606              $newcategory->theme = $data->theme;
 607          }
 608  
 609          $changes = false;
 610          if (isset($data->visible)) {
 611              if ($data->visible) {
 612                  $changes = $this->show_raw();
 613              } else {
 614                  $changes = $this->hide_raw(0);
 615              }
 616          }
 617  
 618          if (isset($data->parent) && $data->parent != $this->parent) {
 619              if ($changes) {
 620                  cache_helper::purge_by_event('changesincoursecat');
 621              }
 622              $parentcat = self::get($data->parent, MUST_EXIST, true);
 623              $this->change_parent_raw($parentcat);
 624              fix_course_sortorder();
 625          }
 626  
 627          $newcategory->timemodified = time();
 628  
 629          $categorycontext = $this->get_context();
 630          if ($editoroptions) {
 631              $newcategory = file_postupdate_standard_editor($newcategory, 'description', $editoroptions, $categorycontext,
 632                                                             'coursecat', 'description', 0);
 633          }
 634          $DB->update_record('course_categories', $newcategory);
 635  
 636          $event = \core\event\course_category_updated::create(array(
 637              'objectid' => $newcategory->id,
 638              'context' => $categorycontext
 639          ));
 640          $event->trigger();
 641  
 642          fix_course_sortorder();
 643          // Purge cache even if fix_course_sortorder() did not do it.
 644          cache_helper::purge_by_event('changesincoursecat');
 645  
 646          // Update all fields in the current object.
 647          $this->restore();
 648      }
 649  
 650  
 651      /**
 652       * Checks if this course category is visible to a user.
 653       *
 654       * Please note that methods core_course_category::get (without 3rd argumet),
 655       * core_course_category::get_children(), etc. return only visible categories so it is
 656       * usually not needed to call this function outside of this class
 657       *
 658       * @param int|stdClass $user The user id or object. By default (null) checks the visibility to the current user.
 659       * @return bool
 660       */
 661      public function is_uservisible($user = null) {
 662          return self::can_view_category($this, $user);
 663      }
 664  
 665      /**
 666       * Checks if current user has access to the category
 667       *
 668       * @param stdClass|core_course_category $category
 669       * @param int|stdClass $user The user id or object. By default (null) checks access for the current user.
 670       * @return bool
 671       */
 672      public static function can_view_category($category, $user = null) {
 673          if (!$category->id) {
 674              return has_capability('moodle/category:viewcourselist', context_system::instance(), $user);
 675          }
 676          $context = context_coursecat::instance($category->id);
 677          if (!$category->visible && !has_capability('moodle/category:viewhiddencategories', $context, $user)) {
 678              return false;
 679          }
 680          return has_capability('moodle/category:viewcourselist', $context, $user);
 681      }
 682  
 683      /**
 684       * Checks if current user can view course information or enrolment page.
 685       *
 686       * This method does not check if user is already enrolled in the course
 687       *
 688       * @param stdClass $course course object (must have 'id', 'visible' and 'category' fields)
 689       * @param null|stdClass $user The user id or object. By default (null) checks access for the current user.
 690       */
 691      public static function can_view_course_info($course, $user = null) {
 692          if ($course->id == SITEID) {
 693              return true;
 694          }
 695          if (!$course->visible) {
 696              $coursecontext = context_course::instance($course->id);
 697              if (!has_capability('moodle/course:viewhiddencourses', $coursecontext, $user)) {
 698                  return false;
 699              }
 700          }
 701          $categorycontext = isset($course->category) ? context_coursecat::instance($course->category) :
 702              context_course::instance($course->id)->get_parent_context();
 703          return has_capability('moodle/category:viewcourselist', $categorycontext, $user);
 704      }
 705  
 706      /**
 707       * Returns the complete corresponding record from DB table course_categories
 708       *
 709       * Mostly used in deprecated functions
 710       *
 711       * @return stdClass
 712       */
 713      public function get_db_record() {
 714          global $DB;
 715          if ($record = $DB->get_record('course_categories', array('id' => $this->id))) {
 716              return $record;
 717          } else {
 718              return (object)convert_to_array($this);
 719          }
 720      }
 721  
 722      /**
 723       * Returns the entry from categories tree and makes sure the application-level tree cache is built
 724       *
 725       * The following keys can be requested:
 726       *
 727       * 'countall' - total number of categories in the system (always present)
 728       * 0 - array of ids of top-level categories (always present)
 729       * '0i' - array of ids of top-level categories that have visible=0 (always present but may be empty array)
 730       * $id (int) - array of ids of categories that are direct children of category with id $id. If
 731       *   category with id $id does not exist, or category has no children, returns empty array
 732       * $id.'i' - array of ids of children categories that have visible=0
 733       *
 734       * @param int|string $id
 735       * @return mixed
 736       */
 737      protected static function get_tree($id) {
 738          $all = self::get_cached_cat_tree();
 739          if (is_null($all) || !isset($all[$id])) {
 740              // Could not get or rebuild the tree, or requested a non-existant ID.
 741              return [];
 742          } else {
 743              return $all[$id];
 744          }
 745      }
 746  
 747      /**
 748       * Return the course category tree.
 749       *
 750       * Returns the category tree array, from the cache if available or rebuilding the cache
 751       * if required. Uses locking to prevent the cache being rebuilt by multiple requests at once.
 752       *
 753       * @return array|null The tree as an array, or null if rebuilding the tree failed due to a lock timeout.
 754       * @throws coding_exception
 755       * @throws dml_exception
 756       * @throws moodle_exception
 757       */
 758      private static function get_cached_cat_tree() : ?array {
 759          $coursecattreecache = cache::make('core', 'coursecattree');
 760          $all = $coursecattreecache->get('all');
 761          if ($all !== false) {
 762              return $all;
 763          }
 764          // Might need to rebuild the tree. Put a lock in place to ensure other requests don't try and do this in parallel.
 765          $lockfactory = \core\lock\lock_config::get_lock_factory('core_coursecattree');
 766          $lock = $lockfactory->get_lock('core_coursecattree_cache',
 767                  course_modinfo::COURSE_CACHE_LOCK_WAIT, course_modinfo::COURSE_CACHE_LOCK_EXPIRY);
 768          if ($lock === false) {
 769              // Couldn't get a lock to rebuild the tree.
 770              return null;
 771          }
 772          $all = $coursecattreecache->get('all');
 773          if ($all !== false) {
 774              // Tree was built while we were waiting for the lock.
 775              $lock->release();
 776              return $all;
 777          }
 778          // Re-build the tree.
 779          try {
 780              $all = self::rebuild_coursecattree_cache_contents();
 781              $coursecattreecache->set('all', $all);
 782          } finally {
 783              $lock->release();
 784          }
 785          return $all;
 786      }
 787  
 788      /**
 789       * Rebuild the course category tree as an array, including an extra "countall" field.
 790       *
 791       * @return array
 792       * @throws coding_exception
 793       * @throws dml_exception
 794       * @throws moodle_exception
 795       */
 796      private static function rebuild_coursecattree_cache_contents() : array {
 797          global $DB;
 798          $sql = "SELECT cc.id, cc.parent, cc.visible
 799                  FROM {course_categories} cc
 800                  ORDER BY cc.sortorder";
 801          $rs = $DB->get_recordset_sql($sql, array());
 802          $all = array(0 => array(), '0i' => array());
 803          $count = 0;
 804          foreach ($rs as $record) {
 805              $all[$record->id] = array();
 806              $all[$record->id. 'i'] = array();
 807              if (array_key_exists($record->parent, $all)) {
 808                  $all[$record->parent][] = $record->id;
 809                  if (!$record->visible) {
 810                      $all[$record->parent. 'i'][] = $record->id;
 811                  }
 812              } else {
 813                  // Parent not found. This is data consistency error but next fix_course_sortorder() should fix it.
 814                  $all[0][] = $record->id;
 815                  if (!$record->visible) {
 816                      $all['0i'][] = $record->id;
 817                  }
 818              }
 819              $count++;
 820          }
 821          $rs->close();
 822          if (!$count) {
 823              // No categories found.
 824              // This may happen after upgrade of a very old moodle version.
 825              // In new versions the default category is created on install.
 826              $defcoursecat = self::create(array('name' => get_string('miscellaneous')));
 827              set_config('defaultrequestcategory', $defcoursecat->id);
 828              $all[0] = array($defcoursecat->id);
 829              $all[$defcoursecat->id] = array();
 830              $count++;
 831          }
 832          // We must add countall to all in case it was the requested ID.
 833          $all['countall'] = $count;
 834          return $all;
 835      }
 836  
 837      /**
 838       * Returns number of ALL categories in the system regardless if
 839       * they are visible to current user or not
 840       *
 841       * @deprecated since Moodle 3.7
 842       * @return int
 843       */
 844      public static function count_all() {
 845          debugging('Method core_course_category::count_all() is deprecated. Please use ' .
 846              'core_course_category::is_simple_site()', DEBUG_DEVELOPER);
 847          return self::get_tree('countall');
 848      }
 849  
 850      /**
 851       * Checks if the site has only one category and it is visible and available.
 852       *
 853       * In many situations we won't show this category at all
 854       * @return bool
 855       */
 856      public static function is_simple_site() {
 857          if (self::get_tree('countall') != 1) {
 858              return false;
 859          }
 860          $default = self::get_default();
 861          return $default->visible && $default->is_uservisible();
 862      }
 863  
 864      /**
 865       * Retrieves number of records from course_categories table
 866       *
 867       * Only cached fields are retrieved. Records are ready for preloading context
 868       *
 869       * @param string $whereclause
 870       * @param array $params
 871       * @return array array of stdClass objects
 872       */
 873      protected static function get_records($whereclause, $params) {
 874          global $DB;
 875          // Retrieve from DB only the fields that need to be stored in cache.
 876          $fields = array_keys(array_filter(self::$coursecatfields));
 877          $ctxselect = context_helper::get_preload_record_columns_sql('ctx');
 878          $sql = "SELECT cc.". join(',cc.', $fields). ", $ctxselect
 879                  FROM {course_categories} cc
 880                  JOIN {context} ctx ON cc.id = ctx.instanceid AND ctx.contextlevel = :contextcoursecat
 881                  WHERE ". $whereclause." ORDER BY cc.sortorder";
 882          return $DB->get_records_sql($sql,
 883                  array('contextcoursecat' => CONTEXT_COURSECAT) + $params);
 884      }
 885  
 886      /**
 887       * Resets course contact caches when role assignments were changed
 888       *
 889       * @param int $roleid role id that was given or taken away
 890       * @param context $context context where role assignment has been changed
 891       */
 892      public static function role_assignment_changed($roleid, $context) {
 893          global $CFG, $DB;
 894  
 895          if ($context->contextlevel > CONTEXT_COURSE) {
 896              // No changes to course contacts if role was assigned on the module/block level.
 897              return;
 898          }
 899  
 900          // Trigger a purge for all caches listening for changes to category enrolment.
 901          cache_helper::purge_by_event('changesincategoryenrolment');
 902  
 903          if (!$CFG->coursecontact || !in_array($roleid, explode(',', $CFG->coursecontact))) {
 904              // The role is not one of course contact roles.
 905              return;
 906          }
 907  
 908          // Remove from cache course contacts of all affected courses.
 909          $cache = cache::make('core', 'coursecontacts');
 910          if ($context->contextlevel == CONTEXT_COURSE) {
 911              $cache->delete($context->instanceid);
 912          } else if ($context->contextlevel == CONTEXT_SYSTEM) {
 913              $cache->purge();
 914          } else {
 915              $sql = "SELECT ctx.instanceid
 916                      FROM {context} ctx
 917                      WHERE ctx.path LIKE ? AND ctx.contextlevel = ?";
 918              $params = array($context->path . '/%', CONTEXT_COURSE);
 919              if ($courses = $DB->get_fieldset_sql($sql, $params)) {
 920                  $cache->delete_many($courses);
 921              }
 922          }
 923      }
 924  
 925      /**
 926       * Executed when user enrolment was changed to check if course
 927       * contacts cache needs to be cleared
 928       *
 929       * @param int $courseid course id
 930       * @param int $userid user id
 931       * @param int $status new enrolment status (0 - active, 1 - suspended)
 932       * @param int $timestart new enrolment time start
 933       * @param int $timeend new enrolment time end
 934       */
 935      public static function user_enrolment_changed($courseid, $userid,
 936              $status, $timestart = null, $timeend = null) {
 937          $cache = cache::make('core', 'coursecontacts');
 938          $contacts = $cache->get($courseid);
 939          if ($contacts === false) {
 940              // The contacts for the affected course were not cached anyway.
 941              return;
 942          }
 943          $enrolmentactive = ($status == 0) &&
 944                  (!$timestart || $timestart < time()) &&
 945                  (!$timeend || $timeend > time());
 946          if (!$enrolmentactive) {
 947              $isincontacts = false;
 948              foreach ($contacts as $contact) {
 949                  if ($contact->id == $userid) {
 950                      $isincontacts = true;
 951                  }
 952              }
 953              if (!$isincontacts) {
 954                  // Changed user's enrolment does not exist or is not active,
 955                  // and he is not in cached course contacts, no changes to be made.
 956                  return;
 957              }
 958          }
 959          // Either enrolment of manager was deleted/suspended
 960          // or user enrolment was added or activated.
 961          // In order to see if the course contacts for this course need
 962          // changing we would need to make additional queries, they will
 963          // slow down bulk enrolment changes. It is better just to remove
 964          // course contacts cache for this course.
 965          $cache->delete($courseid);
 966      }
 967  
 968      /**
 969       * Given list of DB records from table course populates each record with list of users with course contact roles
 970       *
 971       * This function fills the courses with raw information as {@link get_role_users()} would do.
 972       * See also {@link core_course_list_element::get_course_contacts()} for more readable return
 973       *
 974       * $courses[$i]->managers = array(
 975       *   $roleassignmentid => $roleuser,
 976       *   ...
 977       * );
 978       *
 979       * where $roleuser is an stdClass with the following properties:
 980       *
 981       * $roleuser->raid - role assignment id
 982       * $roleuser->id - user id
 983       * $roleuser->username
 984       * $roleuser->firstname
 985       * $roleuser->lastname
 986       * $roleuser->rolecoursealias
 987       * $roleuser->rolename
 988       * $roleuser->sortorder - role sortorder
 989       * $roleuser->roleid
 990       * $roleuser->roleshortname
 991       *
 992       * @todo MDL-38596 minimize number of queries to preload contacts for the list of courses
 993       *
 994       * @param array $courses
 995       */
 996      public static function preload_course_contacts(&$courses) {
 997          global $CFG, $DB;
 998          if (empty($courses) || empty($CFG->coursecontact)) {
 999              return;
1000          }
1001          $managerroles = explode(',', $CFG->coursecontact);
1002          $cache = cache::make('core', 'coursecontacts');
1003          $cacheddata = $cache->get_many(array_keys($courses));
1004          $courseids = array();
1005          foreach (array_keys($courses) as $id) {
1006              if ($cacheddata[$id] !== false) {
1007                  $courses[$id]->managers = $cacheddata[$id];
1008              } else {
1009                  $courseids[] = $id;
1010              }
1011          }
1012  
1013          // Array $courseids now stores list of ids of courses for which we still need to retrieve contacts.
1014          if (empty($courseids)) {
1015              return;
1016          }
1017  
1018          // First build the array of all context ids of the courses and their categories.
1019          $allcontexts = array();
1020          foreach ($courseids as $id) {
1021              $context = context_course::instance($id);
1022              $courses[$id]->managers = array();
1023              foreach (preg_split('|/|', $context->path, 0, PREG_SPLIT_NO_EMPTY) as $ctxid) {
1024                  if (!isset($allcontexts[$ctxid])) {
1025                      $allcontexts[$ctxid] = array();
1026                  }
1027                  $allcontexts[$ctxid][] = $id;
1028              }
1029          }
1030  
1031          // Fetch list of all users with course contact roles in any of the courses contexts or parent contexts.
1032          list($sql1, $params1) = $DB->get_in_or_equal(array_keys($allcontexts), SQL_PARAMS_NAMED, 'ctxid');
1033          list($sql2, $params2) = $DB->get_in_or_equal($managerroles, SQL_PARAMS_NAMED, 'rid');
1034          list($sort, $sortparams) = users_order_by_sql('u');
1035          $notdeleted = array('notdeleted' => 0);
1036          $allnames = get_all_user_name_fields(true, 'u');
1037          $sql = "SELECT ra.contextid, ra.id AS raid,
1038                         r.id AS roleid, r.name AS rolename, r.shortname AS roleshortname,
1039                         rn.name AS rolecoursealias, u.id, u.username, $allnames
1040                    FROM {role_assignments} ra
1041                    JOIN {user} u ON ra.userid = u.id
1042                    JOIN {role} r ON ra.roleid = r.id
1043               LEFT JOIN {role_names} rn ON (rn.contextid = ra.contextid AND rn.roleid = r.id)
1044                  WHERE  ra.contextid ". $sql1." AND ra.roleid ". $sql2." AND u.deleted = :notdeleted
1045               ORDER BY r.sortorder, $sort";
1046          $rs = $DB->get_recordset_sql($sql, $params1 + $params2 + $notdeleted + $sortparams);
1047          $checkenrolments = array();
1048          foreach ($rs as $ra) {
1049              foreach ($allcontexts[$ra->contextid] as $id) {
1050                  $courses[$id]->managers[$ra->raid] = $ra;
1051                  if (!isset($checkenrolments[$id])) {
1052                      $checkenrolments[$id] = array();
1053                  }
1054                  $checkenrolments[$id][] = $ra->id;
1055              }
1056          }
1057          $rs->close();
1058  
1059          // Remove from course contacts users who are not enrolled in the course.
1060          $enrolleduserids = self::ensure_users_enrolled($checkenrolments);
1061          foreach ($checkenrolments as $id => $userids) {
1062              if (empty($enrolleduserids[$id])) {
1063                  $courses[$id]->managers = array();
1064              } else if ($notenrolled = array_diff($userids, $enrolleduserids[$id])) {
1065                  foreach ($courses[$id]->managers as $raid => $ra) {
1066                      if (in_array($ra->id, $notenrolled)) {
1067                          unset($courses[$id]->managers[$raid]);
1068                      }
1069                  }
1070              }
1071          }
1072  
1073          // Set the cache.
1074          $values = array();
1075          foreach ($courseids as $id) {
1076              $values[$id] = $courses[$id]->managers;
1077          }
1078          $cache->set_many($values);
1079      }
1080  
1081      /**
1082       * Preloads the custom fields values in bulk
1083       *
1084       * @param array $records
1085       */
1086      public static function preload_custom_fields(array &$records) {
1087          $customfields = \core_course\customfield\course_handler::create()->get_instances_data(array_keys($records));
1088          foreach ($customfields as $courseid => $data) {
1089              $records[$courseid]->customfields = $data;
1090          }
1091      }
1092  
1093      /**
1094       * Verify user enrollments for multiple course-user combinations
1095       *
1096       * @param array $courseusers array where keys are course ids and values are array
1097       *     of users in this course whose enrolment we wish to verify
1098       * @return array same structure as input array but values list only users from input
1099       *     who are enrolled in the course
1100       */
1101      protected static function ensure_users_enrolled($courseusers) {
1102          global $DB;
1103          // If the input array is too big, split it into chunks.
1104          $maxcoursesinquery = 20;
1105          if (count($courseusers) > $maxcoursesinquery) {
1106              $rv = array();
1107              for ($offset = 0; $offset < count($courseusers); $offset += $maxcoursesinquery) {
1108                  $chunk = array_slice($courseusers, $offset, $maxcoursesinquery, true);
1109                  $rv = $rv + self::ensure_users_enrolled($chunk);
1110              }
1111              return $rv;
1112          }
1113  
1114          // Create a query verifying valid user enrolments for the number of courses.
1115          $sql = "SELECT DISTINCT e.courseid, ue.userid
1116            FROM {user_enrolments} ue
1117            JOIN {enrol} e ON e.id = ue.enrolid
1118            WHERE ue.status = :active
1119              AND e.status = :enabled
1120              AND ue.timestart < :now1 AND (ue.timeend = 0 OR ue.timeend > :now2)";
1121          $now = round(time(), -2); // Rounding helps caching in DB.
1122          $params = array('enabled' => ENROL_INSTANCE_ENABLED,
1123              'active' => ENROL_USER_ACTIVE,
1124              'now1' => $now, 'now2' => $now);
1125          $cnt = 0;
1126          $subsqls = array();
1127          $enrolled = array();
1128          foreach ($courseusers as $id => $userids) {
1129              $enrolled[$id] = array();
1130              if (count($userids)) {
1131                  list($sql2, $params2) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'userid'.$cnt.'_');
1132                  $subsqls[] = "(e.courseid = :courseid$cnt AND ue.userid ".$sql2.")";
1133                  $params = $params + array('courseid'.$cnt => $id) + $params2;
1134                  $cnt++;
1135              }
1136          }
1137          if (count($subsqls)) {
1138              $sql .= "AND (". join(' OR ', $subsqls).")";
1139              $rs = $DB->get_recordset_sql($sql, $params);
1140              foreach ($rs as $record) {
1141                  $enrolled[$record->courseid][] = $record->userid;
1142              }
1143              $rs->close();
1144          }
1145          return $enrolled;
1146      }
1147  
1148      /**
1149       * Retrieves number of records from course table
1150       *
1151       * Not all fields are retrieved. Records are ready for preloading context
1152       *
1153       * @param string $whereclause
1154       * @param array $params
1155       * @param array $options may indicate that summary needs to be retrieved
1156       * @param bool $checkvisibility if true, capability 'moodle/course:viewhiddencourses' will be checked
1157       *     on not visible courses and 'moodle/category:viewcourselist' on all courses
1158       * @return array array of stdClass objects
1159       */
1160      protected static function get_course_records($whereclause, $params, $options, $checkvisibility = false) {
1161          global $DB;
1162          $ctxselect = context_helper::get_preload_record_columns_sql('ctx');
1163          $fields = array('c.id', 'c.category', 'c.sortorder',
1164                          'c.shortname', 'c.fullname', 'c.idnumber',
1165                          'c.startdate', 'c.enddate', 'c.visible', 'c.cacherev');
1166          if (!empty($options['summary'])) {
1167              $fields[] = 'c.summary';
1168              $fields[] = 'c.summaryformat';
1169          } else {
1170              $fields[] = $DB->sql_substr('c.summary', 1, 1). ' as hassummary';
1171          }
1172          $sql = "SELECT ". join(',', $fields). ", $ctxselect
1173                  FROM {course} c
1174                  JOIN {context} ctx ON c.id = ctx.instanceid AND ctx.contextlevel = :contextcourse
1175                  WHERE ". $whereclause." ORDER BY c.sortorder";
1176          $list = $DB->get_records_sql($sql,
1177                  array('contextcourse' => CONTEXT_COURSE) + $params);
1178  
1179          if ($checkvisibility) {
1180              $mycourses = enrol_get_my_courses();
1181              // Loop through all records and make sure we only return the courses accessible by user.
1182              foreach ($list as $course) {
1183                  if (isset($list[$course->id]->hassummary)) {
1184                      $list[$course->id]->hassummary = strlen($list[$course->id]->hassummary) > 0;
1185                  }
1186                  context_helper::preload_from_record($course);
1187                  $context = context_course::instance($course->id);
1188                  // Check that course is accessible by user.
1189                  if (!array_key_exists($course->id, $mycourses) && !self::can_view_course_info($course)) {
1190                      unset($list[$course->id]);
1191                  }
1192              }
1193          }
1194  
1195          return $list;
1196      }
1197  
1198      /**
1199       * Returns array of ids of children categories that current user can not see
1200       *
1201       * This data is cached in user session cache
1202       *
1203       * @return array
1204       */
1205      protected function get_not_visible_children_ids() {
1206          global $DB;
1207          $coursecatcache = cache::make('core', 'coursecat');
1208          if (($invisibleids = $coursecatcache->get('ic'. $this->id)) === false) {
1209              // We never checked visible children before.
1210              $hidden = self::get_tree($this->id.'i');
1211              $catids = self::get_tree($this->id);
1212              $invisibleids = array();
1213              if ($catids) {
1214                  // Preload categories contexts.
1215                  list($sql, $params) = $DB->get_in_or_equal($catids, SQL_PARAMS_NAMED, 'id');
1216                  $ctxselect = context_helper::get_preload_record_columns_sql('ctx');
1217                  $contexts = $DB->get_records_sql("SELECT $ctxselect FROM {context} ctx
1218                      WHERE ctx.contextlevel = :contextcoursecat AND ctx.instanceid ".$sql,
1219                          array('contextcoursecat' => CONTEXT_COURSECAT) + $params);
1220                  foreach ($contexts as $record) {
1221                      context_helper::preload_from_record($record);
1222                  }
1223                  // Check access for each category.
1224                  foreach ($catids as $id) {
1225                      $cat = (object)['id' => $id, 'visible' => in_array($id, $hidden) ? 0 : 1];
1226                      if (!self::can_view_category($cat)) {
1227                          $invisibleids[] = $id;
1228                      }
1229                  }
1230              }
1231              $coursecatcache->set('ic'. $this->id, $invisibleids);
1232          }
1233          return $invisibleids;
1234      }
1235  
1236      /**
1237       * Sorts list of records by several fields
1238       *
1239       * @param array $records array of stdClass objects
1240       * @param array $sortfields assoc array where key is the field to sort and value is 1 for asc or -1 for desc
1241       * @return int
1242       */
1243      protected static function sort_records(&$records, $sortfields) {
1244          if (empty($records)) {
1245              return;
1246          }
1247          // If sorting by course display name, calculate it (it may be fullname or shortname+fullname).
1248          if (array_key_exists('displayname', $sortfields)) {
1249              foreach ($records as $key => $record) {
1250                  if (!isset($record->displayname)) {
1251                      $records[$key]->displayname = get_course_display_name_for_list($record);
1252                  }
1253              }
1254          }
1255          // Sorting by one field - use core_collator.
1256          if (count($sortfields) == 1) {
1257              $property = key($sortfields);
1258              if (in_array($property, array('sortorder', 'id', 'visible', 'parent', 'depth'))) {
1259                  $sortflag = core_collator::SORT_NUMERIC;
1260              } else if (in_array($property, array('idnumber', 'displayname', 'name', 'shortname', 'fullname'))) {
1261                  $sortflag = core_collator::SORT_STRING;
1262              } else {
1263                  $sortflag = core_collator::SORT_REGULAR;
1264              }
1265              core_collator::asort_objects_by_property($records, $property, $sortflag);
1266              if ($sortfields[$property] < 0) {
1267                  $records = array_reverse($records, true);
1268              }
1269              return;
1270          }
1271  
1272          // Sort by multiple fields - use custom sorting.
1273          uasort($records, function($a, $b) use ($sortfields) {
1274              foreach ($sortfields as $field => $mult) {
1275                  // Nulls first.
1276                  if (is_null($a->$field) && !is_null($b->$field)) {
1277                      return -$mult;
1278                  }
1279                  if (is_null($b->$field) && !is_null($a->$field)) {
1280                      return $mult;
1281                  }
1282  
1283                  if (is_string($a->$field) || is_string($b->$field)) {
1284                      // String fields.
1285                      if ($cmp = strcoll($a->$field, $b->$field)) {
1286                          return $mult * $cmp;
1287                      }
1288                  } else {
1289                      // Int fields.
1290                      if ($a->$field > $b->$field) {
1291                          return $mult;
1292                      }
1293                      if ($a->$field < $b->$field) {
1294                          return -$mult;
1295                      }
1296                  }
1297              }
1298              return 0;
1299          });
1300      }
1301  
1302      /**
1303       * Returns array of children categories visible to the current user
1304       *
1305       * @param array $options options for retrieving children
1306       *    - sort - list of fields to sort. Example
1307       *             array('idnumber' => 1, 'name' => 1, 'id' => -1)
1308       *             will sort by idnumber asc, name asc and id desc.
1309       *             Default: array('sortorder' => 1)
1310       *             Only cached fields may be used for sorting!
1311       *    - offset
1312       *    - limit - maximum number of children to return, 0 or null for no limit
1313       * @return core_course_category[] Array of core_course_category objects indexed by category id
1314       */
1315      public function get_children($options = array()) {
1316          global $DB;
1317          $coursecatcache = cache::make('core', 'coursecat');
1318  
1319          // Get default values for options.
1320          if (!empty($options['sort']) && is_array($options['sort'])) {
1321              $sortfields = $options['sort'];
1322          } else {
1323              $sortfields = array('sortorder' => 1);
1324          }
1325          $limit = null;
1326          if (!empty($options['limit']) && (int)$options['limit']) {
1327              $limit = (int)$options['limit'];
1328          }
1329          $offset = 0;
1330          if (!empty($options['offset']) && (int)$options['offset']) {
1331              $offset = (int)$options['offset'];
1332          }
1333  
1334          // First retrieve list of user-visible and sorted children ids from cache.
1335          $sortedids = $coursecatcache->get('c'. $this->id. ':'.  serialize($sortfields));
1336          if ($sortedids === false) {
1337              $sortfieldskeys = array_keys($sortfields);
1338              if ($sortfieldskeys[0] === 'sortorder') {
1339                  // No DB requests required to build the list of ids sorted by sortorder.
1340                  // We can easily ignore other sort fields because sortorder is always different.
1341                  $sortedids = self::get_tree($this->id);
1342                  if ($sortedids && ($invisibleids = $this->get_not_visible_children_ids())) {
1343                      $sortedids = array_diff($sortedids, $invisibleids);
1344                      if ($sortfields['sortorder'] == -1) {
1345                          $sortedids = array_reverse($sortedids, true);
1346                      }
1347                  }
1348              } else {
1349                  // We need to retrieve and sort all children. Good thing that it is done only on first request.
1350                  if ($invisibleids = $this->get_not_visible_children_ids()) {
1351                      list($sql, $params) = $DB->get_in_or_equal($invisibleids, SQL_PARAMS_NAMED, 'id', false);
1352                      $records = self::get_records('cc.parent = :parent AND cc.id '. $sql,
1353                              array('parent' => $this->id) + $params);
1354                  } else {
1355                      $records = self::get_records('cc.parent = :parent', array('parent' => $this->id));
1356                  }
1357                  self::sort_records($records, $sortfields);
1358                  $sortedids = array_keys($records);
1359              }
1360              $coursecatcache->set('c'. $this->id. ':'.serialize($sortfields), $sortedids);
1361          }
1362  
1363          if (empty($sortedids)) {
1364              return array();
1365          }
1366  
1367          // Now retrieive and return categories.
1368          if ($offset || $limit) {
1369              $sortedids = array_slice($sortedids, $offset, $limit);
1370          }
1371          if (isset($records)) {
1372              // Easy, we have already retrieved records.
1373              if ($offset || $limit) {
1374                  $records = array_slice($records, $offset, $limit, true);
1375              }
1376          } else {
1377              list($sql, $params) = $DB->get_in_or_equal($sortedids, SQL_PARAMS_NAMED, 'id');
1378              $records = self::get_records('cc.id '. $sql, array('parent' => $this->id) + $params);
1379          }
1380  
1381          $rv = array();
1382          foreach ($sortedids as $id) {
1383              if (isset($records[$id])) {
1384                  $rv[$id] = new self($records[$id]);
1385              }
1386          }
1387          return $rv;
1388      }
1389  
1390      /**
1391       * Returns an array of ids of categories that are (direct and indirect) children
1392       * of this category.
1393       *
1394       * @return int[]
1395       */
1396      public function get_all_children_ids() {
1397          $children = [];
1398          $walk = [$this->id];
1399          while (count($walk) > 0) {
1400              $catid = array_pop($walk);
1401              $directchildren = self::get_tree($catid);
1402              if (count($directchildren) > 0) {
1403                  $walk = array_merge($walk, $directchildren);
1404                  $children = array_merge($children, $directchildren);
1405              }
1406          }
1407  
1408          return $children;
1409      }
1410  
1411      /**
1412       * Returns true if the user has the manage capability on any category.
1413       *
1414       * This method uses the coursecat cache and an entry `has_manage_capability` to speed up
1415       * calls to this method.
1416       *
1417       * @return bool
1418       */
1419      public static function has_manage_capability_on_any() {
1420          return self::has_capability_on_any('moodle/category:manage');
1421      }
1422  
1423      /**
1424       * Checks if the user has at least one of the given capabilities on any category.
1425       *
1426       * @param array|string $capabilities One or more capabilities to check. Check made is an OR.
1427       * @return bool
1428       */
1429      public static function has_capability_on_any($capabilities) {
1430          global $DB;
1431          if (!isloggedin() || isguestuser()) {
1432              return false;
1433          }
1434  
1435          if (!is_array($capabilities)) {
1436              $capabilities = array($capabilities);
1437          }
1438          $keys = array();
1439          foreach ($capabilities as $capability) {
1440              $keys[$capability] = sha1($capability);
1441          }
1442  
1443          /** @var cache_session $cache */
1444          $cache = cache::make('core', 'coursecat');
1445          $hascapability = $cache->get_many($keys);
1446          $needtoload = false;
1447          foreach ($hascapability as $capability) {
1448              if ($capability === '1') {
1449                  return true;
1450              } else if ($capability === false) {
1451                  $needtoload = true;
1452              }
1453          }
1454          if ($needtoload === false) {
1455              // All capabilities were retrieved and the user didn't have any.
1456              return false;
1457          }
1458  
1459          $haskey = null;
1460          $fields = context_helper::get_preload_record_columns_sql('ctx');
1461          $sql = "SELECT ctx.instanceid AS categoryid, $fields
1462                        FROM {context} ctx
1463                       WHERE contextlevel = :contextlevel
1464                    ORDER BY depth ASC";
1465          $params = array('contextlevel' => CONTEXT_COURSECAT);
1466          $recordset = $DB->get_recordset_sql($sql, $params);
1467          foreach ($recordset as $context) {
1468              context_helper::preload_from_record($context);
1469              $context = context_coursecat::instance($context->categoryid);
1470              foreach ($capabilities as $capability) {
1471                  if (has_capability($capability, $context)) {
1472                      $haskey = $capability;
1473                      break 2;
1474                  }
1475              }
1476          }
1477          $recordset->close();
1478          if ($haskey === null) {
1479              $data = array();
1480              foreach ($keys as $key) {
1481                  $data[$key] = '0';
1482              }
1483              $cache->set_many($data);
1484              return false;
1485          } else {
1486              $cache->set($haskey, '1');
1487              return true;
1488          }
1489      }
1490  
1491      /**
1492       * Returns true if the user can resort any category.
1493       * @return bool
1494       */
1495      public static function can_resort_any() {
1496          return self::has_manage_capability_on_any();
1497      }
1498  
1499      /**
1500       * Returns true if the user can change the parent of any category.
1501       * @return bool
1502       */
1503      public static function can_change_parent_any() {
1504          return self::has_manage_capability_on_any();
1505      }
1506  
1507      /**
1508       * Returns number of subcategories visible to the current user
1509       *
1510       * @return int
1511       */
1512      public function get_children_count() {
1513          $sortedids = self::get_tree($this->id);
1514          $invisibleids = $this->get_not_visible_children_ids();
1515          return count($sortedids) - count($invisibleids);
1516      }
1517  
1518      /**
1519       * Returns true if the category has ANY children, including those not visible to the user
1520       *
1521       * @return boolean
1522       */
1523      public function has_children() {
1524          $allchildren = self::get_tree($this->id);
1525          return !empty($allchildren);
1526      }
1527  
1528      /**
1529       * Returns true if the category has courses in it (count does not include courses
1530       * in child categories)
1531       *
1532       * @return bool
1533       */
1534      public function has_courses() {
1535          global $DB;
1536          return $DB->record_exists_sql("select 1 from {course} where category = ?",
1537                  array($this->id));
1538      }
1539  
1540      /**
1541       * Get the link used to view this course category.
1542       *
1543       * @return  \moodle_url
1544       */
1545      public function get_view_link() {
1546          return new \moodle_url('/course/index.php', [
1547              'categoryid' => $this->id,
1548          ]);
1549      }
1550  
1551      /**
1552       * Searches courses
1553       *
1554       * List of found course ids is cached for 10 minutes. Cache may be purged prior
1555       * to this when somebody edits courses or categories, however it is very
1556       * difficult to keep track of all possible changes that may affect list of courses.
1557       *
1558       * @param array $search contains search criterias, such as:
1559       *     - search - search string
1560       *     - blocklist - id of block (if we are searching for courses containing specific block0
1561       *     - modulelist - name of module (if we are searching for courses containing specific module
1562       *     - tagid - id of tag
1563       *     - onlywithcompletion - set to true if we only need courses with completion enabled
1564       * @param array $options display options, same as in get_courses() except 'recursive' is ignored -
1565       *                       search is always category-independent
1566       * @param array $requiredcapabilities List of capabilities required to see return course.
1567       * @return core_course_list_element[]
1568       */
1569      public static function search_courses($search, $options = array(), $requiredcapabilities = array()) {
1570          global $DB;
1571          $offset = !empty($options['offset']) ? $options['offset'] : 0;
1572          $limit = !empty($options['limit']) ? $options['limit'] : null;
1573          $sortfields = !empty($options['sort']) ? $options['sort'] : array('sortorder' => 1);
1574  
1575          $coursecatcache = cache::make('core', 'coursecat');
1576          $cachekey = 's-'. serialize(
1577              $search + array('sort' => $sortfields) + array('requiredcapabilities' => $requiredcapabilities)
1578          );
1579          $cntcachekey = 'scnt-'. serialize($search);
1580  
1581          $ids = $coursecatcache->get($cachekey);
1582          if ($ids !== false) {
1583              // We already cached last search result.
1584              $ids = array_slice($ids, $offset, $limit);
1585              $courses = array();
1586              if (!empty($ids)) {
1587                  list($sql, $params) = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'id');
1588                  $records = self::get_course_records("c.id ". $sql, $params, $options);
1589                  // Preload course contacts if necessary - saves DB queries later to do it for each course separately.
1590                  if (!empty($options['coursecontacts'])) {
1591                      self::preload_course_contacts($records);
1592                  }
1593                  // Preload custom fields if necessary - saves DB queries later to do it for each course separately.
1594                  if (!empty($options['customfields'])) {
1595                      self::preload_custom_fields($records);
1596                  }
1597                  // If option 'idonly' is specified no further action is needed, just return list of ids.
1598                  if (!empty($options['idonly'])) {
1599                      return array_keys($records);
1600                  }
1601                  // Prepare the list of core_course_list_element objects.
1602                  foreach ($ids as $id) {
1603                      // If a course is deleted after we got the cache entry it may not exist in the database anymore.
1604                      if (!empty($records[$id])) {
1605                          $courses[$id] = new core_course_list_element($records[$id]);
1606                      }
1607                  }
1608              }
1609              return $courses;
1610          }
1611  
1612          $preloadcoursecontacts = !empty($options['coursecontacts']);
1613          unset($options['coursecontacts']);
1614  
1615          // Empty search string will return all results.
1616          if (!isset($search['search'])) {
1617              $search['search'] = '';
1618          }
1619  
1620          if (empty($search['blocklist']) && empty($search['modulelist']) && empty($search['tagid'])) {
1621              // Search courses that have specified words in their names/summaries.
1622              $searchterms = preg_split('|\s+|', trim($search['search']), 0, PREG_SPLIT_NO_EMPTY);
1623              $searchcond = $searchcondparams = [];
1624              if (!empty($search['onlywithcompletion'])) {
1625                  $searchcond = ['c.enablecompletion = :p1'];
1626                  $searchcondparams = ['p1' => 1];
1627              }
1628              $courselist = get_courses_search($searchterms, 'c.sortorder ASC', 0, 9999999, $totalcount,
1629                  $requiredcapabilities, $searchcond, $searchcondparams);
1630              self::sort_records($courselist, $sortfields);
1631              $coursecatcache->set($cachekey, array_keys($courselist));
1632              $coursecatcache->set($cntcachekey, $totalcount);
1633              $records = array_slice($courselist, $offset, $limit, true);
1634          } else {
1635              if (!empty($search['blocklist'])) {
1636                  // Search courses that have block with specified id.
1637                  $blockname = $DB->get_field('block', 'name', array('id' => $search['blocklist']));
1638                  $where = 'ctx.id in (SELECT distinct bi.parentcontextid FROM {block_instances} bi
1639                      WHERE bi.blockname = :blockname)';
1640                  $params = array('blockname' => $blockname);
1641              } else if (!empty($search['modulelist'])) {
1642                  // Search courses that have module with specified name.
1643                  $where = "c.id IN (SELECT DISTINCT module.course ".
1644                          "FROM {".$search['modulelist']."} module)";
1645                  $params = array();
1646              } else if (!empty($search['tagid'])) {
1647                  // Search courses that are tagged with the specified tag.
1648                  $where = "c.id IN (SELECT t.itemid ".
1649                          "FROM {tag_instance} t WHERE t.tagid = :tagid AND t.itemtype = :itemtype AND t.component = :component)";
1650                  $params = array('tagid' => $search['tagid'], 'itemtype' => 'course', 'component' => 'core');
1651                  if (!empty($search['ctx'])) {
1652                      $rec = isset($search['rec']) ? $search['rec'] : true;
1653                      $parentcontext = context::instance_by_id($search['ctx']);
1654                      if ($parentcontext->contextlevel == CONTEXT_SYSTEM && $rec) {
1655                          // Parent context is system context and recursive is set to yes.
1656                          // Nothing to filter - all courses fall into this condition.
1657                      } else if ($rec) {
1658                          // Filter all courses in the parent context at any level.
1659                          $where .= ' AND ctx.path LIKE :contextpath';
1660                          $params['contextpath'] = $parentcontext->path . '%';
1661                      } else if ($parentcontext->contextlevel == CONTEXT_COURSECAT) {
1662                          // All courses in the given course category.
1663                          $where .= ' AND c.category = :category';
1664                          $params['category'] = $parentcontext->instanceid;
1665                      } else {
1666                          // No courses will satisfy the context criterion, do not bother searching.
1667                          $where = '1=0';
1668                      }
1669                  }
1670              } else {
1671                  debugging('No criteria is specified while searching courses', DEBUG_DEVELOPER);
1672                  return array();
1673              }
1674              $courselist = self::get_course_records($where, $params, $options, true);
1675              if (!empty($requiredcapabilities)) {
1676                  foreach ($courselist as $key => $course) {
1677                      context_helper::preload_from_record($course);
1678                      $coursecontext = context_course::instance($course->id);
1679                      if (!has_all_capabilities($requiredcapabilities, $coursecontext)) {
1680                          unset($courselist[$key]);
1681                      }
1682                  }
1683              }
1684              self::sort_records($courselist, $sortfields);
1685              $coursecatcache->set($cachekey, array_keys($courselist));
1686              $coursecatcache->set($cntcachekey, count($courselist));
1687              $records = array_slice($courselist, $offset, $limit, true);
1688          }
1689  
1690          // Preload course contacts if necessary - saves DB queries later to do it for each course separately.
1691          if (!empty($preloadcoursecontacts)) {
1692              self::preload_course_contacts($records);
1693          }
1694          // Preload custom fields if necessary - saves DB queries later to do it for each course separately.
1695          if (!empty($options['customfields'])) {
1696              self::preload_custom_fields($records);
1697          }
1698          // If option 'idonly' is specified no further action is needed, just return list of ids.
1699          if (!empty($options['idonly'])) {
1700              return array_keys($records);
1701          }
1702          // Prepare the list of core_course_list_element objects.
1703          $courses = array();
1704          foreach ($records as $record) {
1705              $courses[$record->id] = new core_course_list_element($record);
1706          }
1707          return $courses;
1708      }
1709  
1710      /**
1711       * Returns number of courses in the search results
1712       *
1713       * It is recommended to call this function after {@link core_course_category::search_courses()}
1714       * and not before because only course ids are cached. Otherwise search_courses() may
1715       * perform extra DB queries.
1716       *
1717       * @param array $search search criteria, see method search_courses() for more details
1718       * @param array $options display options. They do not affect the result but
1719       *     the 'sort' property is used in cache key for storing list of course ids
1720       * @param array $requiredcapabilities List of capabilities required to see return course.
1721       * @return int
1722       */
1723      public static function search_courses_count($search, $options = array(), $requiredcapabilities = array()) {
1724          $coursecatcache = cache::make('core', 'coursecat');
1725          $cntcachekey = 'scnt-'. serialize($search) . serialize($requiredcapabilities);
1726          if (($cnt = $coursecatcache->get($cntcachekey)) === false) {
1727              // Cached value not found. Retrieve ALL courses and return their count.
1728              unset($options['offset']);
1729              unset($options['limit']);
1730              unset($options['summary']);
1731              unset($options['coursecontacts']);
1732              $options['idonly'] = true;
1733              $courses = self::search_courses($search, $options, $requiredcapabilities);
1734              $cnt = count($courses);
1735          }
1736          return $cnt;
1737      }
1738  
1739      /**
1740       * Retrieves the list of courses accessible by user
1741       *
1742       * Not all information is cached, try to avoid calling this method
1743       * twice in the same request.
1744       *
1745       * The following fields are always retrieved:
1746       * - id, visible, fullname, shortname, idnumber, category, sortorder
1747       *
1748       * If you plan to use properties/methods core_course_list_element::$summary and/or
1749       * core_course_list_element::get_course_contacts()
1750       * you can preload this information using appropriate 'options'. Otherwise
1751       * they will be retrieved from DB on demand and it may end with bigger DB load.
1752       *
1753       * Note that method core_course_list_element::has_summary() will not perform additional
1754       * DB queries even if $options['summary'] is not specified
1755       *
1756       * List of found course ids is cached for 10 minutes. Cache may be purged prior
1757       * to this when somebody edits courses or categories, however it is very
1758       * difficult to keep track of all possible changes that may affect list of courses.
1759       *
1760       * @param array $options options for retrieving children
1761       *    - recursive - return courses from subcategories as well. Use with care,
1762       *      this may be a huge list!
1763       *    - summary - preloads fields 'summary' and 'summaryformat'
1764       *    - coursecontacts - preloads course contacts
1765       *    - sort - list of fields to sort. Example
1766       *             array('idnumber' => 1, 'shortname' => 1, 'id' => -1)
1767       *             will sort by idnumber asc, shortname asc and id desc.
1768       *             Default: array('sortorder' => 1)
1769       *             Only cached fields may be used for sorting!
1770       *    - offset
1771       *    - limit - maximum number of children to return, 0 or null for no limit
1772       *    - idonly - returns the array or course ids instead of array of objects
1773       *               used only in get_courses_count()
1774       * @return core_course_list_element[]
1775       */
1776      public function get_courses($options = array()) {
1777          global $DB;
1778          $recursive = !empty($options['recursive']);
1779          $offset = !empty($options['offset']) ? $options['offset'] : 0;
1780          $limit = !empty($options['limit']) ? $options['limit'] : null;
1781          $sortfields = !empty($options['sort']) ? $options['sort'] : array('sortorder' => 1);
1782  
1783          if (!$this->id && !$recursive) {
1784              // There are no courses on system level unless we need recursive list.
1785              return [];
1786          }
1787  
1788          $coursecatcache = cache::make('core', 'coursecat');
1789          $cachekey = 'l-'. $this->id. '-'. (!empty($options['recursive']) ? 'r' : '').
1790                   '-'. serialize($sortfields);
1791          $cntcachekey = 'lcnt-'. $this->id. '-'. (!empty($options['recursive']) ? 'r' : '');
1792  
1793          // Check if we have already cached results.
1794          $ids = $coursecatcache->get($cachekey);
1795          if ($ids !== false) {
1796              // We already cached last search result and it did not expire yet.
1797              $ids = array_slice($ids, $offset, $limit);
1798              $courses = array();
1799              if (!empty($ids)) {
1800                  list($sql, $params) = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'id');
1801                  $records = self::get_course_records("c.id ". $sql, $params, $options);
1802                  // Preload course contacts if necessary - saves DB queries later to do it for each course separately.
1803                  if (!empty($options['coursecontacts'])) {
1804                      self::preload_course_contacts($records);
1805                  }
1806                  // If option 'idonly' is specified no further action is needed, just return list of ids.
1807                  if (!empty($options['idonly'])) {
1808                      return array_keys($records);
1809                  }
1810                  // Preload custom fields if necessary - saves DB queries later to do it for each course separately.
1811                  if (!empty($options['customfields'])) {
1812                      self::preload_custom_fields($records);
1813                  }
1814                  // Prepare the list of core_course_list_element objects.
1815                  foreach ($ids as $id) {
1816                      // If a course is deleted after we got the cache entry it may not exist in the database anymore.
1817                      if (!empty($records[$id])) {
1818                          $courses[$id] = new core_course_list_element($records[$id]);
1819                      }
1820                  }
1821              }
1822              return $courses;
1823          }
1824  
1825          // Retrieve list of courses in category.
1826          $where = 'c.id <> :siteid';
1827          $params = array('siteid' => SITEID);
1828          if ($recursive) {
1829              if ($this->id) {
1830                  $context = context_coursecat::instance($this->id);
1831                  $where .= ' AND ctx.path like :path';
1832                  $params['path'] = $context->path. '/%';
1833              }
1834          } else {
1835              $where .= ' AND c.category = :categoryid';
1836              $params['categoryid'] = $this->id;
1837          }
1838          // Get list of courses without preloaded coursecontacts because we don't need them for every course.
1839          $list = $this->get_course_records($where, $params, array_diff_key($options, array('coursecontacts' => 1)), true);
1840  
1841          // Sort and cache list.
1842          self::sort_records($list, $sortfields);
1843          $coursecatcache->set($cachekey, array_keys($list));
1844          $coursecatcache->set($cntcachekey, count($list));
1845  
1846          // Apply offset/limit, convert to core_course_list_element and return.
1847          $courses = array();
1848          if (isset($list)) {
1849              if ($offset || $limit) {
1850                  $list = array_slice($list, $offset, $limit, true);
1851              }
1852              // Preload course contacts if necessary - saves DB queries later to do it for each course separately.
1853              if (!empty($options['coursecontacts'])) {
1854                  self::preload_course_contacts($list);
1855              }
1856              // Preload custom fields if necessary - saves DB queries later to do it for each course separately.
1857              if (!empty($options['customfields'])) {
1858                  self::preload_custom_fields($list);
1859              }
1860              // If option 'idonly' is specified no further action is needed, just return list of ids.
1861              if (!empty($options['idonly'])) {
1862                  return array_keys($list);
1863              }
1864              // Prepare the list of core_course_list_element objects.
1865              foreach ($list as $record) {
1866                  $courses[$record->id] = new core_course_list_element($record);
1867              }
1868          }
1869          return $courses;
1870      }
1871  
1872      /**
1873       * Returns number of courses visible to the user
1874       *
1875       * @param array $options similar to get_courses() except some options do not affect
1876       *     number of courses (i.e. sort, summary, offset, limit etc.)
1877       * @return int
1878       */
1879      public function get_courses_count($options = array()) {
1880          $cntcachekey = 'lcnt-'. $this->id. '-'. (!empty($options['recursive']) ? 'r' : '');
1881          $coursecatcache = cache::make('core', 'coursecat');
1882          if (($cnt = $coursecatcache->get($cntcachekey)) === false) {
1883              // Cached value not found. Retrieve ALL courses and return their count.
1884              unset($options['offset']);
1885              unset($options['limit']);
1886              unset($options['summary']);
1887              unset($options['coursecontacts']);
1888              $options['idonly'] = true;
1889              $courses = $this->get_courses($options);
1890              $cnt = count($courses);
1891          }
1892          return $cnt;
1893      }
1894  
1895      /**
1896       * Returns true if the user is able to delete this category.
1897       *
1898       * Note if this category contains any courses this isn't a full check, it will need to be accompanied by a call to either
1899       * {@link core_course_category::can_delete_full()} or {@link core_course_category::can_move_content_to()}
1900       * depending upon what the user wished to do.
1901       *
1902       * @return boolean
1903       */
1904      public function can_delete() {
1905          if (!$this->has_manage_capability()) {
1906              return false;
1907          }
1908          return $this->parent_has_manage_capability();
1909      }
1910  
1911      /**
1912       * Returns true if user can delete current category and all its contents
1913       *
1914       * To be able to delete course category the user must have permission
1915       * 'moodle/category:manage' in ALL child course categories AND
1916       * be able to delete all courses
1917       *
1918       * @return bool
1919       */
1920      public function can_delete_full() {
1921          global $DB;
1922          if (!$this->id) {
1923              // Fool-proof.
1924              return false;
1925          }
1926  
1927          if (!$this->has_manage_capability()) {
1928              return false;
1929          }
1930  
1931          // Check all child categories (not only direct children).
1932          $context = $this->get_context();
1933          $sql = context_helper::get_preload_record_columns_sql('ctx');
1934          $childcategories = $DB->get_records_sql('SELECT c.id, c.visible, '. $sql.
1935              ' FROM {context} ctx '.
1936              ' JOIN {course_categories} c ON c.id = ctx.instanceid'.
1937              ' WHERE ctx.path like ? AND ctx.contextlevel = ?',
1938                  array($context->path. '/%', CONTEXT_COURSECAT));
1939          foreach ($childcategories as $childcat) {
1940              context_helper::preload_from_record($childcat);
1941              $childcontext = context_coursecat::instance($childcat->id);
1942              if ((!$childcat->visible && !has_capability('moodle/category:viewhiddencategories', $childcontext)) ||
1943                      !has_capability('moodle/category:manage', $childcontext)) {
1944                  return false;
1945              }
1946          }
1947  
1948          // Check courses.
1949          $sql = context_helper::get_preload_record_columns_sql('ctx');
1950          $coursescontexts = $DB->get_records_sql('SELECT ctx.instanceid AS courseid, '.
1951                      $sql. ' FROM {context} ctx '.
1952                      'WHERE ctx.path like :pathmask and ctx.contextlevel = :courselevel',
1953                  array('pathmask' => $context->path. '/%',
1954                      'courselevel' => CONTEXT_COURSE));
1955          foreach ($coursescontexts as $ctxrecord) {
1956              context_helper::preload_from_record($ctxrecord);
1957              if (!can_delete_course($ctxrecord->courseid)) {
1958                  return false;
1959              }
1960          }
1961  
1962          // Check if plugins permit deletion of category content.
1963          $pluginfunctions = $this->get_plugins_callback_function('can_course_category_delete');
1964          foreach ($pluginfunctions as $pluginfunction) {
1965              // If at least one plugin does not permit deletion, stop and return false.
1966              if (!$pluginfunction($this)) {
1967                  return false;
1968              }
1969          }
1970  
1971          return true;
1972      }
1973  
1974      /**
1975       * Recursively delete category including all subcategories and courses
1976       *
1977       * Function {@link core_course_category::can_delete_full()} MUST be called prior
1978       * to calling this function because there is no capability check
1979       * inside this function
1980       *
1981       * @param boolean $showfeedback display some notices
1982       * @return array return deleted courses
1983       * @throws moodle_exception
1984       */
1985      public function delete_full($showfeedback = true) {
1986          global $CFG, $DB;
1987  
1988          require_once($CFG->libdir.'/gradelib.php');
1989          require_once($CFG->libdir.'/questionlib.php');
1990          require_once($CFG->dirroot.'/cohort/lib.php');
1991  
1992          // Make sure we won't timeout when deleting a lot of courses.
1993          $settimeout = core_php_time_limit::raise();
1994  
1995          // Allow plugins to use this category before we completely delete it.
1996          $pluginfunctions = $this->get_plugins_callback_function('pre_course_category_delete');
1997          foreach ($pluginfunctions as $pluginfunction) {
1998              $pluginfunction($this->get_db_record());
1999          }
2000  
2001          $deletedcourses = array();
2002  
2003          // Get children. Note, we don't want to use cache here because it would be rebuilt too often.
2004          $children = $DB->get_records('course_categories', array('parent' => $this->id), 'sortorder ASC');
2005          foreach ($children as $record) {
2006              $coursecat = new self($record);
2007              $deletedcourses += $coursecat->delete_full($showfeedback);
2008          }
2009  
2010          if ($courses = $DB->get_records('course', array('category' => $this->id), 'sortorder ASC')) {
2011              foreach ($courses as $course) {
2012                  if (!delete_course($course, false)) {
2013                      throw new moodle_exception('cannotdeletecategorycourse', '', '', $course->shortname);
2014                  }
2015                  $deletedcourses[] = $course;
2016              }
2017          }
2018  
2019          // Move or delete cohorts in this context.
2020          cohort_delete_category($this);
2021  
2022          // Now delete anything that may depend on course category context.
2023          grade_course_category_delete($this->id, 0, $showfeedback);
2024          $cb = new \core_contentbank\contentbank();
2025          if (!$cb->delete_contents($this->get_context())) {
2026              throw new moodle_exception('errordeletingcontentfromcategory', 'contentbank', '', $this->get_formatted_name());
2027          }
2028          if (!question_delete_course_category($this, null)) {
2029              throw new moodle_exception('cannotdeletecategoryquestions', '', '', $this->get_formatted_name());
2030          }
2031  
2032          // Delete all events in the category.
2033          $DB->delete_records('event', array('categoryid' => $this->id));
2034  
2035          // Finally delete the category and it's context.
2036          $DB->delete_records('course_categories', array('id' => $this->id));
2037  
2038          $coursecatcontext = context_coursecat::instance($this->id);
2039          $coursecatcontext->delete();
2040  
2041          cache_helper::purge_by_event('changesincoursecat');
2042  
2043          // Trigger a course category deleted event.
2044          /** @var \core\event\course_category_deleted $event */
2045          $event = \core\event\course_category_deleted::create(array(
2046              'objectid' => $this->id,
2047              'context' => $coursecatcontext,
2048              'other' => array('name' => $this->name)
2049          ));
2050          $event->set_coursecat($this);
2051          $event->trigger();
2052  
2053          // If we deleted $CFG->defaultrequestcategory, make it point somewhere else.
2054          if ($this->id == $CFG->defaultrequestcategory) {
2055              set_config('defaultrequestcategory', $DB->get_field('course_categories', 'MIN(id)', array('parent' => 0)));
2056          }
2057          return $deletedcourses;
2058      }
2059  
2060      /**
2061       * Checks if user can delete this category and move content (courses, subcategories and questions)
2062       * to another category. If yes returns the array of possible target categories names
2063       *
2064       * If user can not manage this category or it is completely empty - empty array will be returned
2065       *
2066       * @return array
2067       */
2068      public function move_content_targets_list() {
2069          global $CFG;
2070          require_once($CFG->libdir . '/questionlib.php');
2071          $context = $this->get_context();
2072          if (!$this->is_uservisible() ||
2073                  !has_capability('moodle/category:manage', $context)) {
2074              // User is not able to manage current category, he is not able to delete it.
2075              // No possible target categories.
2076              return array();
2077          }
2078  
2079          $testcaps = array();
2080          // If this category has courses in it, user must have 'course:create' capability in target category.
2081          if ($this->has_courses()) {
2082              $testcaps[] = 'moodle/course:create';
2083          }
2084          // If this category has subcategories or questions, user must have 'category:manage' capability in target category.
2085          if ($this->has_children() || question_context_has_any_questions($context)) {
2086              $testcaps[] = 'moodle/category:manage';
2087          }
2088          if (!empty($testcaps)) {
2089              // Return list of categories excluding this one and it's children.
2090              return self::make_categories_list($testcaps, $this->id);
2091          }
2092  
2093          // Category is completely empty, no need in target for contents.
2094          return array();
2095      }
2096  
2097      /**
2098       * Checks if user has capability to move all category content to the new parent before
2099       * removing this category
2100       *
2101       * @param int $newcatid
2102       * @return bool
2103       */
2104      public function can_move_content_to($newcatid) {
2105          global $CFG;
2106          require_once($CFG->libdir . '/questionlib.php');
2107  
2108          if (!$this->has_manage_capability()) {
2109              return false;
2110          }
2111  
2112          $testcaps = array();
2113          // If this category has courses in it, user must have 'course:create' capability in target category.
2114          if ($this->has_courses()) {
2115              $testcaps[] = 'moodle/course:create';
2116          }
2117          // If this category has subcategories or questions, user must have 'category:manage' capability in target category.
2118          if ($this->has_children() || question_context_has_any_questions($this->get_context())) {
2119              $testcaps[] = 'moodle/category:manage';
2120          }
2121          if (!empty($testcaps) && !has_all_capabilities($testcaps, context_coursecat::instance($newcatid))) {
2122              // No sufficient capabilities to perform this task.
2123              return false;
2124          }
2125  
2126          // Check if plugins permit moving category content.
2127          $pluginfunctions = $this->get_plugins_callback_function('can_course_category_delete_move');
2128          $newparentcat = self::get($newcatid, MUST_EXIST, true);
2129          foreach ($pluginfunctions as $pluginfunction) {
2130              // If at least one plugin does not permit move on deletion, stop and return false.
2131              if (!$pluginfunction($this, $newparentcat)) {
2132                  return false;
2133              }
2134          }
2135  
2136          return true;
2137      }
2138  
2139      /**
2140       * Deletes a category and moves all content (children, courses and questions) to the new parent
2141       *
2142       * Note that this function does not check capabilities, {@link core_course_category::can_move_content_to()}
2143       * must be called prior
2144       *
2145       * @param int $newparentid
2146       * @param bool $showfeedback
2147       * @return bool
2148       */
2149      public function delete_move($newparentid, $showfeedback = false) {
2150          global $CFG, $DB, $OUTPUT;
2151  
2152          require_once($CFG->libdir.'/gradelib.php');
2153          require_once($CFG->libdir.'/questionlib.php');
2154          require_once($CFG->dirroot.'/cohort/lib.php');
2155  
2156          // Get all objects and lists because later the caches will be reset so.
2157          // We don't need to make extra queries.
2158          $newparentcat = self::get($newparentid, MUST_EXIST, true);
2159          $catname = $this->get_formatted_name();
2160          $children = $this->get_children();
2161          $params = array('category' => $this->id);
2162          $coursesids = $DB->get_fieldset_select('course', 'id', 'category = :category ORDER BY sortorder ASC', $params);
2163          $context = $this->get_context();
2164  
2165          // Allow plugins to make necessary changes before we move the category content.
2166          $pluginfunctions = $this->get_plugins_callback_function('pre_course_category_delete_move');
2167          foreach ($pluginfunctions as $pluginfunction) {
2168              $pluginfunction($this, $newparentcat);
2169          }
2170  
2171          if ($children) {
2172              foreach ($children as $childcat) {
2173                  $childcat->change_parent_raw($newparentcat);
2174                  // Log action.
2175                  $event = \core\event\course_category_updated::create(array(
2176                      'objectid' => $childcat->id,
2177                      'context' => $childcat->get_context()
2178                  ));
2179                  $event->set_legacy_logdata(array(SITEID, 'category', 'move', 'editcategory.php?id=' . $childcat->id,
2180                      $childcat->id));
2181                  $event->trigger();
2182              }
2183              fix_course_sortorder();
2184          }
2185  
2186          if ($coursesids) {
2187              require_once($CFG->dirroot.'/course/lib.php');
2188              if (!move_courses($coursesids, $newparentid)) {
2189                  if ($showfeedback) {
2190                      echo $OUTPUT->notification("Error moving courses");
2191                  }
2192                  return false;
2193              }
2194              if ($showfeedback) {
2195                  echo $OUTPUT->notification(get_string('coursesmovedout', '', $catname), 'notifysuccess');
2196              }
2197          }
2198  
2199          // Move or delete cohorts in this context.
2200          cohort_delete_category($this);
2201  
2202          // Now delete anything that may depend on course category context.
2203          grade_course_category_delete($this->id, $newparentid, $showfeedback);
2204          $cb = new \core_contentbank\contentbank();
2205          $newparentcontext = context_coursecat::instance($newparentid);
2206          $result = $cb->move_contents($context, $newparentcontext);
2207          if ($showfeedback) {
2208              if ($result) {
2209                  echo $OUTPUT->notification(get_string('contentsmoved', 'contentbank', $catname), 'notifysuccess');
2210              } else {
2211                  echo $OUTPUT->notification(
2212                          get_string('errordeletingcontentbankfromcategory', 'contentbank', $catname),
2213                          'notifysuccess'
2214                  );
2215              }
2216          }
2217          if (!question_delete_course_category($this, $newparentcat)) {
2218              if ($showfeedback) {
2219                  echo $OUTPUT->notification(get_string('errordeletingquestionsfromcategory', 'question', $catname), 'notifysuccess');
2220              }
2221              return false;
2222          }
2223  
2224          // Finally delete the category and it's context.
2225          $DB->delete_records('course_categories', array('id' => $this->id));
2226          $context->delete();
2227  
2228          // Trigger a course category deleted event.
2229          /** @var \core\event\course_category_deleted $event */
2230          $event = \core\event\course_category_deleted::create(array(
2231              'objectid' => $this->id,
2232              'context' => $context,
2233              'other' => array('name' => $this->name, 'contentmovedcategoryid' => $newparentid)
2234          ));
2235          $event->set_coursecat($this);
2236          $event->trigger();
2237  
2238          cache_helper::purge_by_event('changesincoursecat');
2239  
2240          if ($showfeedback) {
2241              echo $OUTPUT->notification(get_string('coursecategorydeleted', '', $catname), 'notifysuccess');
2242          }
2243  
2244          // If we deleted $CFG->defaultrequestcategory, make it point somewhere else.
2245          if ($this->id == $CFG->defaultrequestcategory) {
2246              set_config('defaultrequestcategory', $DB->get_field('course_categories', 'MIN(id)', array('parent' => 0)));
2247          }
2248          return true;
2249      }
2250  
2251      /**
2252       * Checks if user can move current category to the new parent
2253       *
2254       * This checks if new parent category exists, user has manage cap there
2255       * and new parent is not a child of this category
2256       *
2257       * @param int|stdClass|core_course_category $newparentcat
2258       * @return bool
2259       */
2260      public function can_change_parent($newparentcat) {
2261          if (!has_capability('moodle/category:manage', $this->get_context())) {
2262              return false;
2263          }
2264          if (is_object($newparentcat)) {
2265              $newparentcat = self::get($newparentcat->id, IGNORE_MISSING);
2266          } else {
2267              $newparentcat = self::get((int)$newparentcat, IGNORE_MISSING);
2268          }
2269          if (!$newparentcat) {
2270              return false;
2271          }
2272          if ($newparentcat->id == $this->id || in_array($this->id, $newparentcat->get_parents())) {
2273              // Can not move to itself or it's own child.
2274              return false;
2275          }
2276          if ($newparentcat->id) {
2277              return has_capability('moodle/category:manage', context_coursecat::instance($newparentcat->id));
2278          } else {
2279              return has_capability('moodle/category:manage', context_system::instance());
2280          }
2281      }
2282  
2283      /**
2284       * Moves the category under another parent category. All associated contexts are moved as well
2285       *
2286       * This is protected function, use change_parent() or update() from outside of this class
2287       *
2288       * @see core_course_category::change_parent()
2289       * @see core_course_category::update()
2290       *
2291       * @param core_course_category $newparentcat
2292       * @throws moodle_exception
2293       */
2294      protected function change_parent_raw(core_course_category $newparentcat) {
2295          global $DB;
2296  
2297          $context = $this->get_context();
2298  
2299          $hidecat = false;
2300          if (empty($newparentcat->id)) {
2301              $DB->set_field('course_categories', 'parent', 0, array('id' => $this->id));
2302              $newparent = context_system::instance();
2303          } else {
2304              if ($newparentcat->id == $this->id || in_array($this->id, $newparentcat->get_parents())) {
2305                  // Can not move to itself or it's own child.
2306                  throw new moodle_exception('cannotmovecategory');
2307              }
2308              $DB->set_field('course_categories', 'parent', $newparentcat->id, array('id' => $this->id));
2309              $newparent = context_coursecat::instance($newparentcat->id);
2310  
2311              if (!$newparentcat->visible and $this->visible) {
2312                  // Better hide category when moving into hidden category, teachers may unhide afterwards and the hidden children
2313                  // will be restored properly.
2314                  $hidecat = true;
2315              }
2316          }
2317          $this->parent = $newparentcat->id;
2318  
2319          $context->update_moved($newparent);
2320  
2321          // Now make it last in new category.
2322          $DB->set_field('course_categories', 'sortorder', MAX_COURSES_IN_CATEGORY * MAX_COURSE_CATEGORIES, ['id' => $this->id]);
2323  
2324          if ($hidecat) {
2325              fix_course_sortorder();
2326              $this->restore();
2327              // Hide object but store 1 in visibleold, because when parent category visibility changes this category must
2328              // become visible again.
2329              $this->hide_raw(1);
2330          }
2331      }
2332  
2333      /**
2334       * Efficiently moves a category - NOTE that this can have
2335       * a huge impact access-control-wise...
2336       *
2337       * Note that this function does not check capabilities.
2338       *
2339       * Example of usage:
2340       * $coursecat = core_course_category::get($categoryid);
2341       * if ($coursecat->can_change_parent($newparentcatid)) {
2342       *     $coursecat->change_parent($newparentcatid);
2343       * }
2344       *
2345       * This function does not update field course_categories.timemodified
2346       * If you want to update timemodified, use
2347       * $coursecat->update(array('parent' => $newparentcat));
2348       *
2349       * @param int|stdClass|core_course_category $newparentcat
2350       */
2351      public function change_parent($newparentcat) {
2352          // Make sure parent category exists but do not check capabilities here that it is visible to current user.
2353          if (is_object($newparentcat)) {
2354              $newparentcat = self::get($newparentcat->id, MUST_EXIST, true);
2355          } else {
2356              $newparentcat = self::get((int)$newparentcat, MUST_EXIST, true);
2357          }
2358          if ($newparentcat->id != $this->parent) {
2359              $this->change_parent_raw($newparentcat);
2360              fix_course_sortorder();
2361              cache_helper::purge_by_event('changesincoursecat');
2362              $this->restore();
2363  
2364              $event = \core\event\course_category_updated::create(array(
2365                  'objectid' => $this->id,
2366                  'context' => $this->get_context()
2367              ));
2368              $event->set_legacy_logdata(array(SITEID, 'category', 'move', 'editcategory.php?id=' . $this->id, $this->id));
2369              $event->trigger();
2370          }
2371      }
2372  
2373      /**
2374       * Hide course category and child course and subcategories
2375       *
2376       * If this category has changed the parent and is moved under hidden
2377       * category we will want to store it's current visibility state in
2378       * the field 'visibleold'. If admin clicked 'hide' for this particular
2379       * category, the field 'visibleold' should become 0.
2380       *
2381       * All subcategories and courses will have their current visibility in the field visibleold
2382       *
2383       * This is protected function, use hide() or update() from outside of this class
2384       *
2385       * @see core_course_category::hide()
2386       * @see core_course_category::update()
2387       *
2388       * @param int $visibleold value to set in field $visibleold for this category
2389       * @return bool whether changes have been made and caches need to be purged afterwards
2390       */
2391      protected function hide_raw($visibleold = 0) {
2392          global $DB;
2393          $changes = false;
2394  
2395          // Note that field 'visibleold' is not cached so we must retrieve it from DB if it is missing.
2396          if ($this->id && $this->__get('visibleold') != $visibleold) {
2397              $this->visibleold = $visibleold;
2398              $DB->set_field('course_categories', 'visibleold', $visibleold, array('id' => $this->id));
2399              $changes = true;
2400          }
2401          if (!$this->visible || !$this->id) {
2402              // Already hidden or can not be hidden.
2403              return $changes;
2404          }
2405  
2406          $this->visible = 0;
2407          $DB->set_field('course_categories', 'visible', 0, array('id' => $this->id));
2408          // Store visible flag so that we can return to it if we immediately unhide.
2409          $DB->execute("UPDATE {course} SET visibleold = visible WHERE category = ?", array($this->id));
2410          $DB->set_field('course', 'visible', 0, array('category' => $this->id));
2411          // Get all child categories and hide too.
2412          if ($subcats = $DB->get_records_select('course_categories', "path LIKE ?", array("$this->path/%"), 'id, visible')) {
2413              foreach ($subcats as $cat) {
2414                  $DB->set_field('course_categories', 'visibleold', $cat->visible, array('id' => $cat->id));
2415                  $DB->set_field('course_categories', 'visible', 0, array('id' => $cat->id));
2416                  $DB->execute("UPDATE {course} SET visibleold = visible WHERE category = ?", array($cat->id));
2417                  $DB->set_field('course', 'visible', 0, array('category' => $cat->id));
2418              }
2419          }
2420          return true;
2421      }
2422  
2423      /**
2424       * Hide course category and child course and subcategories
2425       *
2426       * Note that there is no capability check inside this function
2427       *
2428       * This function does not update field course_categories.timemodified
2429       * If you want to update timemodified, use
2430       * $coursecat->update(array('visible' => 0));
2431       */
2432      public function hide() {
2433          if ($this->hide_raw(0)) {
2434              cache_helper::purge_by_event('changesincoursecat');
2435  
2436              $event = \core\event\course_category_updated::create(array(
2437                  'objectid' => $this->id,
2438                  'context' => $this->get_context()
2439              ));
2440              $event->set_legacy_logdata(array(SITEID, 'category', 'hide', 'editcategory.php?id=' . $this->id, $this->id));
2441              $event->trigger();
2442          }
2443      }
2444  
2445      /**
2446       * Show course category and restores visibility for child course and subcategories
2447       *
2448       * Note that there is no capability check inside this function
2449       *
2450       * This is protected function, use show() or update() from outside of this class
2451       *
2452       * @see core_course_category::show()
2453       * @see core_course_category::update()
2454       *
2455       * @return bool whether changes have been made and caches need to be purged afterwards
2456       */
2457      protected function show_raw() {
2458          global $DB;
2459  
2460          if ($this->visible) {
2461              // Already visible.
2462              return false;
2463          }
2464  
2465          $this->visible = 1;
2466          $this->visibleold = 1;
2467          $DB->set_field('course_categories', 'visible', 1, array('id' => $this->id));
2468          $DB->set_field('course_categories', 'visibleold', 1, array('id' => $this->id));
2469          $DB->execute("UPDATE {course} SET visible = visibleold WHERE category = ?", array($this->id));
2470          // Get all child categories and unhide too.
2471          if ($subcats = $DB->get_records_select('course_categories', "path LIKE ?", array("$this->path/%"), 'id, visibleold')) {
2472              foreach ($subcats as $cat) {
2473                  if ($cat->visibleold) {
2474                      $DB->set_field('course_categories', 'visible', 1, array('id' => $cat->id));
2475                  }
2476                  $DB->execute("UPDATE {course} SET visible = visibleold WHERE category = ?", array($cat->id));
2477              }
2478          }
2479          return true;
2480      }
2481  
2482      /**
2483       * Show course category and restores visibility for child course and subcategories
2484       *
2485       * Note that there is no capability check inside this function
2486       *
2487       * This function does not update field course_categories.timemodified
2488       * If you want to update timemodified, use
2489       * $coursecat->update(array('visible' => 1));
2490       */
2491      public function show() {
2492          if ($this->show_raw()) {
2493              cache_helper::purge_by_event('changesincoursecat');
2494  
2495              $event = \core\event\course_category_updated::create(array(
2496                  'objectid' => $this->id,
2497                  'context' => $this->get_context()
2498              ));
2499              $event->set_legacy_logdata(array(SITEID, 'category', 'show', 'editcategory.php?id=' . $this->id, $this->id));
2500              $event->trigger();
2501          }
2502      }
2503  
2504      /**
2505       * Returns name of the category formatted as a string
2506       *
2507       * @param array $options formatting options other than context
2508       * @return string
2509       */
2510      public function get_formatted_name($options = array()) {
2511          if ($this->id) {
2512              $context = $this->get_context();
2513              return format_string($this->name, true, array('context' => $context) + $options);
2514          } else {
2515              return get_string('top');
2516          }
2517      }
2518  
2519      /**
2520       * Get the nested name of this category, with all of it's parents.
2521       *
2522       * @param   bool    $includelinks Whether to wrap each name in the view link for that category.
2523       * @param   string  $separator The string between each name.
2524       * @param   array   $options Formatting options.
2525       * @return  string
2526       */
2527      public function get_nested_name($includelinks = true, $separator = ' / ', $options = []) {
2528          // Get the name of hierarchical name of this category.
2529          $parents = $this->get_parents();
2530          $categories = static::get_many($parents);
2531          $categories[] = $this;
2532  
2533          $names = array_map(function($category) use ($options, $includelinks) {
2534              if ($includelinks) {
2535                  return html_writer::link($category->get_view_link(), $category->get_formatted_name($options));
2536              } else {
2537                  return $category->get_formatted_name($options);
2538              }
2539  
2540          }, $categories);
2541  
2542          return implode($separator, $names);
2543      }
2544  
2545      /**
2546       * Returns ids of all parents of the category. Last element in the return array is the direct parent
2547       *
2548       * For example, if you have a tree of categories like:
2549       *   Miscellaneous (id = 1)
2550       *      Subcategory (id = 2)
2551       *         Sub-subcategory (id = 4)
2552       *   Other category (id = 3)
2553       *
2554       * core_course_category::get(1)->get_parents() == array()
2555       * core_course_category::get(2)->get_parents() == array(1)
2556       * core_course_category::get(4)->get_parents() == array(1, 2);
2557       *
2558       * Note that this method does not check if all parents are accessible by current user
2559       *
2560       * @return array of category ids
2561       */
2562      public function get_parents() {
2563          $parents = preg_split('|/|', $this->path, 0, PREG_SPLIT_NO_EMPTY);
2564          array_pop($parents);
2565          return $parents;
2566      }
2567  
2568      /**
2569       * This function returns a nice list representing category tree
2570       * for display or to use in a form <select> element
2571       *
2572       * List is cached for 10 minutes
2573       *
2574       * For example, if you have a tree of categories like:
2575       *   Miscellaneous (id = 1)
2576       *      Subcategory (id = 2)
2577       *         Sub-subcategory (id = 4)
2578       *   Other category (id = 3)
2579       * Then after calling this function you will have
2580       * array(1 => 'Miscellaneous',
2581       *       2 => 'Miscellaneous / Subcategory',
2582       *       4 => 'Miscellaneous / Subcategory / Sub-subcategory',
2583       *       3 => 'Other category');
2584       *
2585       * If you specify $requiredcapability, then only categories where the current
2586       * user has that capability will be added to $list.
2587       * If you only have $requiredcapability in a child category, not the parent,
2588       * then the child catgegory will still be included.
2589       *
2590       * If you specify the option $excludeid, then that category, and all its children,
2591       * are omitted from the tree. This is useful when you are doing something like
2592       * moving categories, where you do not want to allow people to move a category
2593       * to be the child of itself.
2594       *
2595       * See also {@link make_categories_options()}
2596       *
2597       * @param string/array $requiredcapability if given, only categories where the current
2598       *      user has this capability will be returned. Can also be an array of capabilities,
2599       *      in which case they are all required.
2600       * @param integer $excludeid Exclude this category and its children from the lists built.
2601       * @param string $separator string to use as a separator between parent and child category. Default ' / '
2602       * @return array of strings
2603       */
2604      public static function make_categories_list($requiredcapability = '', $excludeid = 0, $separator = ' / ') {
2605          global $DB;
2606          $coursecatcache = cache::make('core', 'coursecat');
2607  
2608          // Check if we cached the complete list of user-accessible category names ($baselist) or list of ids
2609          // with requried cap ($thislist).
2610          $currentlang = current_language();
2611          $basecachekey = $currentlang . '_catlist';
2612          $baselist = $coursecatcache->get($basecachekey);
2613          $thislist = false;
2614          $thiscachekey = null;
2615          if (!empty($requiredcapability)) {
2616              $requiredcapability = (array)$requiredcapability;
2617              $thiscachekey = 'catlist:'. serialize($requiredcapability);
2618              if ($baselist !== false && ($thislist = $coursecatcache->get($thiscachekey)) !== false) {
2619                  $thislist = preg_split('|,|', $thislist, -1, PREG_SPLIT_NO_EMPTY);
2620              }
2621          } else if ($baselist !== false) {
2622              $thislist = array_keys(array_filter($baselist, function($el) {
2623                  return $el['name'] !== false;
2624              }));
2625          }
2626  
2627          if ($baselist === false) {
2628              // We don't have $baselist cached, retrieve it. Retrieve $thislist again in any case.
2629              $ctxselect = context_helper::get_preload_record_columns_sql('ctx');
2630              $sql = "SELECT cc.id, cc.sortorder, cc.name, cc.visible, cc.parent, cc.path, $ctxselect
2631                      FROM {course_categories} cc
2632                      JOIN {context} ctx ON cc.id = ctx.instanceid AND ctx.contextlevel = :contextcoursecat
2633                      ORDER BY cc.sortorder";
2634              $rs = $DB->get_recordset_sql($sql, array('contextcoursecat' => CONTEXT_COURSECAT));
2635              $baselist = array();
2636              $thislist = array();
2637              foreach ($rs as $record) {
2638                  context_helper::preload_from_record($record);
2639                  $context = context_coursecat::instance($record->id);
2640                  $canview = self::can_view_category($record);
2641                  $baselist[$record->id] = array(
2642                      'name' => $canview ? format_string($record->name, true, array('context' => $context)) : false,
2643                      'path' => $record->path
2644                  );
2645                  if (!$canview || (!empty($requiredcapability) && !has_all_capabilities($requiredcapability, $context))) {
2646                      // No required capability, added to $baselist but not to $thislist.
2647                      continue;
2648                  }
2649                  $thislist[] = $record->id;
2650              }
2651              $rs->close();
2652              $coursecatcache->set($basecachekey, $baselist);
2653              if (!empty($requiredcapability)) {
2654                  $coursecatcache->set($thiscachekey, join(',', $thislist));
2655              }
2656          } else if ($thislist === false) {
2657              // We have $baselist cached but not $thislist. Simplier query is used to retrieve.
2658              $ctxselect = context_helper::get_preload_record_columns_sql('ctx');
2659              $sql = "SELECT ctx.instanceid AS id, $ctxselect
2660                      FROM {context} ctx WHERE ctx.contextlevel = :contextcoursecat";
2661              $contexts = $DB->get_records_sql($sql, array('contextcoursecat' => CONTEXT_COURSECAT));
2662              $thislist = array();
2663              foreach (array_keys($baselist) as $id) {
2664                  if ($baselist[$id]['name'] !== false) {
2665                      context_helper::preload_from_record($contexts[$id]);
2666                      if (has_all_capabilities($requiredcapability, context_coursecat::instance($id))) {
2667                          $thislist[] = $id;
2668                      }
2669                  }
2670              }
2671              $coursecatcache->set($thiscachekey, join(',', $thislist));
2672          }
2673  
2674          // Now build the array of strings to return, mind $separator and $excludeid.
2675          $names = array();
2676          foreach ($thislist as $id) {
2677              $path = preg_split('|/|', $baselist[$id]['path'], -1, PREG_SPLIT_NO_EMPTY);
2678              if (!$excludeid || !in_array($excludeid, $path)) {
2679                  $namechunks = array();
2680                  foreach ($path as $parentid) {
2681                      if (array_key_exists($parentid, $baselist) && $baselist[$parentid]['name'] !== false) {
2682                          $namechunks[] = $baselist[$parentid]['name'];
2683                      }
2684                  }
2685                  $names[$id] = join($separator, $namechunks);
2686              }
2687          }
2688          return $names;
2689      }
2690  
2691      /**
2692       * Prepares the object for caching. Works like the __sleep method.
2693       *
2694       * implementing method from interface cacheable_object
2695       *
2696       * @return array ready to be cached
2697       */
2698      public function prepare_to_cache() {
2699          $a = array();
2700          foreach (self::$coursecatfields as $property => $cachedirectives) {
2701              if ($cachedirectives !== null) {
2702                  list($shortname, $defaultvalue) = $cachedirectives;
2703                  if ($this->$property !== $defaultvalue) {
2704                      $a[$shortname] = $this->$property;
2705                  }
2706              }
2707          }
2708          $context = $this->get_context();
2709          $a['xi'] = $context->id;
2710          $a['xp'] = $context->path;
2711          $a['xl'] = $context->locked;
2712          return $a;
2713      }
2714  
2715      /**
2716       * Takes the data provided by prepare_to_cache and reinitialises an instance of the associated from it.
2717       *
2718       * implementing method from interface cacheable_object
2719       *
2720       * @param array $a
2721       * @return core_course_category
2722       */
2723      public static function wake_from_cache($a) {
2724          $record = new stdClass;
2725          foreach (self::$coursecatfields as $property => $cachedirectives) {
2726              if ($cachedirectives !== null) {
2727                  list($shortname, $defaultvalue) = $cachedirectives;
2728                  if (array_key_exists($shortname, $a)) {
2729                      $record->$property = $a[$shortname];
2730                  } else {
2731                      $record->$property = $defaultvalue;
2732                  }
2733              }
2734          }
2735          $record->ctxid = $a['xi'];
2736          $record->ctxpath = $a['xp'];
2737          $record->ctxdepth = $record->depth + 1;
2738          $record->ctxlevel = CONTEXT_COURSECAT;
2739          $record->ctxinstance = $record->id;
2740          $record->ctxlocked = $a['xl'];
2741          return new self($record, true);
2742      }
2743  
2744      /**
2745       * Returns true if the user is able to create a top level category.
2746       * @return bool
2747       */
2748      public static function can_create_top_level_category() {
2749          return self::top()->has_manage_capability();
2750      }
2751  
2752      /**
2753       * Returns the category context.
2754       * @return context_coursecat
2755       */
2756      public function get_context() {
2757          if ($this->id === 0) {
2758              // This is the special top level category object.
2759              return context_system::instance();
2760          } else {
2761              return context_coursecat::instance($this->id);
2762          }
2763      }
2764  
2765      /**
2766       * Returns true if the user is able to manage this category.
2767       * @return bool
2768       */
2769      public function has_manage_capability() {
2770          if (!$this->is_uservisible()) {
2771              return false;
2772          }
2773          return has_capability('moodle/category:manage', $this->get_context());
2774      }
2775  
2776      /**
2777       * Returns true if the user has the manage capability on the parent category.
2778       * @return bool
2779       */
2780      public function parent_has_manage_capability() {
2781          return ($parent = $this->get_parent_coursecat()) && $parent->has_manage_capability();
2782      }
2783  
2784      /**
2785       * Returns true if the current user can create subcategories of this category.
2786       * @return bool
2787       */
2788      public function can_create_subcategory() {
2789          return $this->has_manage_capability();
2790      }
2791  
2792      /**
2793       * Returns true if the user can resort this categories sub categories and courses.
2794       * Must have manage capability and be able to see all subcategories.
2795       * @return bool
2796       */
2797      public function can_resort_subcategories() {
2798          return $this->has_manage_capability() && !$this->get_not_visible_children_ids();
2799      }
2800  
2801      /**
2802       * Returns true if the user can resort the courses within this category.
2803       * Must have manage capability and be able to see all courses.
2804       * @return bool
2805       */
2806      public function can_resort_courses() {
2807          return $this->has_manage_capability() && $this->coursecount == $this->get_courses_count();
2808      }
2809  
2810      /**
2811       * Returns true of the user can change the sortorder of this category (resort in the parent category)
2812       * @return bool
2813       */
2814      public function can_change_sortorder() {
2815          return ($parent = $this->get_parent_coursecat()) && $parent->can_resort_subcategories();
2816      }
2817  
2818      /**
2819       * Returns true if the current user can create a course within this category.
2820       * @return bool
2821       */
2822      public function can_create_course() {
2823          return $this->is_uservisible() && has_capability('moodle/course:create', $this->get_context());
2824      }
2825  
2826      /**
2827       * Returns true if the current user can edit this categories settings.
2828       * @return bool
2829       */
2830      public function can_edit() {
2831          return $this->has_manage_capability();
2832      }
2833  
2834      /**
2835       * Returns true if the current user can review role assignments for this category.
2836       * @return bool
2837       */
2838      public function can_review_roles() {
2839          return $this->is_uservisible() && has_capability('moodle/role:assign', $this->get_context());
2840      }
2841  
2842      /**
2843       * Returns true if the current user can review permissions for this category.
2844       * @return bool
2845       */
2846      public function can_review_permissions() {
2847          return $this->is_uservisible() &&
2848          has_any_capability(array(
2849              'moodle/role:assign',
2850              'moodle/role:safeoverride',
2851              'moodle/role:override',
2852              'moodle/role:assign'
2853          ), $this->get_context());
2854      }
2855  
2856      /**
2857       * Returns true if the current user can review cohorts for this category.
2858       * @return bool
2859       */
2860      public function can_review_cohorts() {
2861          return $this->is_uservisible() &&
2862              has_any_capability(array('moodle/cohort:view', 'moodle/cohort:manage'), $this->get_context());
2863      }
2864  
2865      /**
2866       * Returns true if the current user can review filter settings for this category.
2867       * @return bool
2868       */
2869      public function can_review_filters() {
2870          return $this->is_uservisible() &&
2871                  has_capability('moodle/filter:manage', $this->get_context()) &&
2872                  count(filter_get_available_in_context($this->get_context())) > 0;
2873      }
2874  
2875      /**
2876       * Returns true if the current user is able to change the visbility of this category.
2877       * @return bool
2878       */
2879      public function can_change_visibility() {
2880          return $this->parent_has_manage_capability();
2881      }
2882  
2883      /**
2884       * Returns true if the user can move courses out of this category.
2885       * @return bool
2886       */
2887      public function can_move_courses_out_of() {
2888          return $this->has_manage_capability();
2889      }
2890  
2891      /**
2892       * Returns true if the user can move courses into this category.
2893       * @return bool
2894       */
2895      public function can_move_courses_into() {
2896          return $this->has_manage_capability();
2897      }
2898  
2899      /**
2900       * Returns true if the user is able to restore a course into this category as a new course.
2901       * @return bool
2902       */
2903      public function can_restore_courses_into() {
2904          return $this->is_uservisible() && has_capability('moodle/restore:restorecourse', $this->get_context());
2905      }
2906  
2907      /**
2908       * Resorts the sub categories of this category by the given field.
2909       *
2910       * @param string $field One of name, idnumber or descending values of each (appended desc)
2911       * @param bool $cleanup If true cleanup will be done, if false you will need to do it manually later.
2912       * @return bool True on success.
2913       * @throws coding_exception
2914       */
2915      public function resort_subcategories($field, $cleanup = true) {
2916          global $DB;
2917          $desc = false;
2918          if (substr($field, -4) === "desc") {
2919              $desc = true;
2920              $field = substr($field, 0, -4);  // Remove "desc" from field name.
2921          }
2922          if ($field !== 'name' && $field !== 'idnumber') {
2923              throw new coding_exception('Invalid field requested');
2924          }
2925          $children = $this->get_children();
2926          core_collator::asort_objects_by_property($children, $field, core_collator::SORT_NATURAL);
2927          if (!empty($desc)) {
2928              $children = array_reverse($children);
2929          }
2930          $i = 1;
2931          foreach ($children as $cat) {
2932              $i++;
2933              $DB->set_field('course_categories', 'sortorder', $i, array('id' => $cat->id));
2934              $i += $cat->coursecount;
2935          }
2936          if ($cleanup) {
2937              self::resort_categories_cleanup();
2938          }
2939          return true;
2940      }
2941  
2942      /**
2943       * Cleans things up after categories have been resorted.
2944       * @param bool $includecourses If set to true we know courses have been resorted as well.
2945       */
2946      public static function resort_categories_cleanup($includecourses = false) {
2947          // This should not be needed but we do it just to be safe.
2948          fix_course_sortorder();
2949          cache_helper::purge_by_event('changesincoursecat');
2950          if ($includecourses) {
2951              cache_helper::purge_by_event('changesincourse');
2952          }
2953      }
2954  
2955      /**
2956       * Resort the courses within this category by the given field.
2957       *
2958       * @param string $field One of fullname, shortname, idnumber or descending values of each (appended desc)
2959       * @param bool $cleanup
2960       * @return bool True for success.
2961       * @throws coding_exception
2962       */
2963      public function resort_courses($field, $cleanup = true) {
2964          global $DB;
2965          $desc = false;
2966          if (substr($field, -4) === "desc") {
2967              $desc = true;
2968              $field = substr($field, 0, -4);  // Remove "desc" from field name.
2969          }
2970          if ($field !== 'fullname' && $field !== 'shortname' && $field !== 'idnumber' && $field !== 'timecreated') {
2971              // This is ultra important as we use $field in an SQL statement below this.
2972              throw new coding_exception('Invalid field requested');
2973          }
2974          $ctxfields = context_helper::get_preload_record_columns_sql('ctx');
2975          $sql = "SELECT c.id, c.sortorder, c.{$field}, $ctxfields
2976                    FROM {course} c
2977               LEFT JOIN {context} ctx ON ctx.instanceid = c.id
2978                   WHERE ctx.contextlevel = :ctxlevel AND
2979                         c.category = :categoryid";
2980          $params = array(
2981              'ctxlevel' => CONTEXT_COURSE,
2982              'categoryid' => $this->id
2983          );
2984          $courses = $DB->get_records_sql($sql, $params);
2985          if (count($courses) > 0) {
2986              foreach ($courses as $courseid => $course) {
2987                  context_helper::preload_from_record($course);
2988                  if ($field === 'idnumber') {
2989                      $course->sortby = $course->idnumber;
2990                  } else {
2991                      // It'll require formatting.
2992                      $options = array(
2993                          'context' => context_course::instance($course->id)
2994                      );
2995                      // We format the string first so that it appears as the user would see it.
2996                      // This ensures the sorting makes sense to them. However it won't necessarily make
2997                      // sense to everyone if things like multilang filters are enabled.
2998                      // We then strip any tags as we don't want things such as image tags skewing the
2999                      // sort results.
3000                      $course->sortby = strip_tags(format_string($course->$field, true, $options));
3001                  }
3002                  // We set it back here rather than using references as there is a bug with using
3003                  // references in a foreach before passing as an arg by reference.
3004                  $courses[$courseid] = $course;
3005              }
3006              // Sort the courses.
3007              core_collator::asort_objects_by_property($courses, 'sortby', core_collator::SORT_NATURAL);
3008              if (!empty($desc)) {
3009                  $courses = array_reverse($courses);
3010              }
3011              $i = 1;
3012              foreach ($courses as $course) {
3013                  $DB->set_field('course', 'sortorder', $this->sortorder + $i, array('id' => $course->id));
3014                  $i++;
3015              }
3016              if ($cleanup) {
3017                  // This should not be needed but we do it just to be safe.
3018                  fix_course_sortorder();
3019                  cache_helper::purge_by_event('changesincourse');
3020              }
3021          }
3022          return true;
3023      }
3024  
3025      /**
3026       * Changes the sort order of this categories parent shifting this category up or down one.
3027       *
3028       * @param bool $up If set to true the category is shifted up one spot, else its moved down.
3029       * @return bool True on success, false otherwise.
3030       */
3031      public function change_sortorder_by_one($up) {
3032          global $DB;
3033          $params = array($this->sortorder, $this->parent);
3034          if ($up) {
3035              $select = 'sortorder < ? AND parent = ?';
3036              $sort = 'sortorder DESC';
3037          } else {
3038              $select = 'sortorder > ? AND parent = ?';
3039              $sort = 'sortorder ASC';
3040          }
3041          fix_course_sortorder();
3042          $swapcategory = $DB->get_records_select('course_categories', $select, $params, $sort, '*', 0, 1);
3043          $swapcategory = reset($swapcategory);
3044          if ($swapcategory) {
3045              $DB->set_field('course_categories', 'sortorder', $swapcategory->sortorder, array('id' => $this->id));
3046              $DB->set_field('course_categories', 'sortorder', $this->sortorder, array('id' => $swapcategory->id));
3047              $this->sortorder = $swapcategory->sortorder;
3048  
3049              $event = \core\event\course_category_updated::create(array(
3050                  'objectid' => $this->id,
3051                  'context' => $this->get_context()
3052              ));
3053              $event->set_legacy_logdata(array(SITEID, 'category', 'move', 'management.php?categoryid=' . $this->id,
3054                  $this->id));
3055              $event->trigger();
3056  
3057              // Finally reorder courses.
3058              fix_course_sortorder();
3059              cache_helper::purge_by_event('changesincoursecat');
3060              return true;
3061          }
3062          return false;
3063      }
3064  
3065      /**
3066       * Returns the parent core_course_category object for this category.
3067       *
3068       * Only returns parent if it exists and is visible to the current user
3069       *
3070       * @return core_course_category|null
3071       */
3072      public function get_parent_coursecat() {
3073          if (!$this->id) {
3074              return null;
3075          }
3076          return self::get($this->parent, IGNORE_MISSING);
3077      }
3078  
3079  
3080      /**
3081       * Returns true if the user is able to request a new course be created.
3082       * @return bool
3083       */
3084      public function can_request_course() {
3085          return course_request::can_request($this->get_context());
3086      }
3087  
3088      /**
3089       * Returns true if the user can approve course requests.
3090       * @return bool
3091       */
3092      public static function can_approve_course_requests() {
3093          global $CFG, $DB;
3094          if (empty($CFG->enablecourserequests)) {
3095              return false;
3096          }
3097          $context = context_system::instance();
3098          if (!has_capability('moodle/site:approvecourse', $context)) {
3099              return false;
3100          }
3101          if (!$DB->record_exists('course_request', array())) {
3102              return false;
3103          }
3104          return true;
3105      }
3106  }