cbe68789a86f3bbd3a49dc47910b69c434ad31cc
[moodle.git] / course / classes / category.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
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  */
26 defined('MOODLE_INTERNAL') || die();
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;
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     );
73     /** @var int */
74     protected $id;
76     /** @var string */
77     protected $name = '';
79     /** @var string */
80     protected $idnumber = null;
82     /** @var string */
83     protected $description = false;
85     /** @var int */
86     protected $descriptionformat = false;
88     /** @var int */
89     protected $parent = 0;
91     /** @var int */
92     protected $sortorder = 0;
94     /** @var int */
95     protected $coursecount = false;
97     /** @var int */
98     protected $visible = 1;
100     /** @var int */
101     protected $visibleold = false;
103     /** @var int */
104     protected $timemodified = false;
106     /** @var int */
107     protected $depth = 0;
109     /** @var string */
110     protected $path = '';
112     /** @var string */
113     protected $theme = false;
115     /** @var bool */
116     protected $fromcache = false;
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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         }
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         }
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     }
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     }
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     }
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     }
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;
372         $coursecatrecordcache = cache::make('core', 'coursecatrecords');
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";
381         $catrs = $DB->get_recordset_sql("{$catsql} {$catsqlwhere} {$catsqlorder}", [
382             'contextlevel' => CONTEXT_COURSECAT,
383         ]);
385         $types['categories'] = [];
386         $categories = [];
387         $toset = [];
388         foreach ($catrs as $record) {
389             $category = new self($record);
390             $toset[$category->id] = $category;
392             if (!empty($options['returnhidden']) || $category->is_uservisible()) {
393                 $categories[$record->id] = $category;
394             }
395         }
396         $catrs->close();
398         $coursecatrecordcache->set_many($toset);
400         return $categories;
402     }
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     }
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     }
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();
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         }
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;
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         }
487         if (isset($data->theme) && !empty($CFG->allowcategorythemes)) {
488             $newcategory->theme = $data->theme;
489         }
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;
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         }
510         $newcategory->sortorder = 0;
511         $newcategory->timemodified = time();
513         $newcategory->id = $DB->insert_record('course_categories', $newcategory);
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));
519         fix_course_sortorder();
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);
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         }
535         $event = \core\event\course_category_created::create(array(
536             'objectid' => $newcategory->id,
537             'context' => $categorycontext
538         ));
539         $event->trigger();
541         cache_helper::purge_by_event('changesincoursecat');
543         return self::get($newcategory->id, MUST_EXIST, true);
544     }
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         }
573         $data = (object)$data;
574         $newcategory = new stdClass();
575         $newcategory->id = $this->id;
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         }
584         if (isset($data->name) && empty($data->name)) {
585             throw new moodle_exception('categorynamerequired');
586         }
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         }
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         }
605         if (isset($data->theme) && !empty($CFG->allowcategorythemes)) {
606             $newcategory->theme = $data->theme;
607         }
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         }
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         }
627         $newcategory->timemodified = time();
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);
636         $event = \core\event\course_category_updated::create(array(
637             'objectid' => $newcategory->id,
638             'context' => $categorycontext
639         ));
640         $event->trigger();
642         fix_course_sortorder();
643         // Purge cache even if fix_course_sortorder() did not do it.
644         cache_helper::purge_by_event('changesincoursecat');
646         // Update all fields in the current object.
647         $this->restore();
648     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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;
895         if ($context->contextlevel > CONTEXT_COURSE) {
896             // No changes to course contacts if role was assigned on the module/block level.
897             return;
898         }
900         // Trigger a purge for all caches listening for changes to category enrolment.
901         cache_helper::purge_by_event('changesincategoryenrolment');
903         if (!$CFG->coursecontact || !in_array($roleid, explode(',', $CFG->coursecontact))) {
904             // The role is not one of course contact roles.
905             return;
906         }
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     }
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     }
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         }
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         }
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         }
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();
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         }
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     }
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     }
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         }
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     }
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);
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         }
1195         return $list;
1196     }
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     }
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         }
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                 }
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     }
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');
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         }
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         }
1363         if (empty($sortedids)) {
1364             return array();
1365         }
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         }
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     }
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         }
1408         return $children;
1409     }
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     }
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         }
1435         if (!is_array($capabilities)) {
1436             $capabilities = array($capabilities);
1437         }
1438         $keys = array();
1439         foreach ($capabilities as $capability) {
1440             $keys[$capability] = sha1($capability);
1441         }
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         }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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);
1575         $coursecatcache = cache::make('core', 'coursecat');
1576         $cachekey = 's-'. serialize(
1577             $search + array('sort' => $sortfields) + array('requiredcapabilities' => $requiredcapabilities)
1578         );
1579         $cntcachekey = 'scnt-'. serialize($search);
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         }
1612         $preloadcoursecontacts = !empty($options['coursecontacts']);
1613         unset($options['coursecontacts']);
1615         // Empty search string will return all results.
1616         if (!isset($search['search'])) {
1617             $search['search'] = '';
1618         }
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         }
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     }
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     }
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);
1783         if (!$this->id && !$recursive) {
1784             // There are no courses on system level unless we need recursive list.
1785             return [];
1786         }
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' : '');
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         }
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);
1841         // Sort and cache list.
1842         self::sort_records($list, $sortfields);
1843         $coursecatcache->set($cachekey, array_keys($list));
1844         $coursecatcache->set($cntcachekey, count($list));
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     }
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     }
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     }
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         }
1927         if (!$this->has_manage_capability()) {
1928             return false;
1929         }
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         }
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         }
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         }
1971         return true;
1972     }
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;
1988         require_once($CFG->libdir.'/gradelib.php');
1989         require_once($CFG->libdir.'/questionlib.php');
1990         require_once($CFG->dirroot.'/cohort/lib.php');
1992         // Make sure we won't timeout when deleting a lot of courses.
1993         $settimeout = core_php_time_limit::raise();
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         }
2001         $deletedcourses = array();
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         }
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         }
2019         // Move or delete cohorts in this context.
2020         cohort_delete_category($this);
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         }
2032         // Delete all events in the category.
2033         $DB->delete_records('event', array('categoryid' => $this->id));
2035         // Finally delete the category and it's context.
2036         $DB->delete_records('course_categories', array('id' => $this->id));
2038         $coursecatcontext = context_coursecat::instance($this->id);
2039         $coursecatcontext->delete();
2041         cache_helper::purge_by_event('changesincoursecat');
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();
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     }
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         }
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         }
2093         // Category is completely empty, no need in target for contents.
2094         return array();
2095     }
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');
2108         if (!$this->has_manage_capability()) {
2109             return false;
2110         }
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         }
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         }
2136         return true;
2137     }
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;
2152         require_once($CFG->libdir.'/gradelib.php');
2153         require_once($CFG->libdir.'/questionlib.php');
2154         require_once($CFG->dirroot.'/cohort/lib.php');
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();
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         }
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         }
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         }
2199         // Move or delete cohorts in this context.
2200         cohort_delete_category($this);
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         }
2224         // Finally delete the category and it's context.
2225         $DB->delete_records('course_categories', array('id' => $this->id));
2226         $context->delete();
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();
2238         cache_helper::purge_by_event('changesincoursecat');
2240         if ($showfeedback) {
2241             echo $OUTPUT->notification(get_string('coursecategorydeleted', '', $catname), 'notifysuccess');
2242         }
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     }
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     }
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;
2297         $context = $this->get_context();
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);
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;
2319         $context->update_moved($newparent);
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]);
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     }
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();
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     }
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;
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         }
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     }
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');
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     }
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;
2460         if ($this->visible) {
2461             // Already visible.
2462             return false;
2463         }
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     }
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');
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     }
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     }
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;
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             }
2540         }, $categories);
2542         return implode($separator, $names);
2543     }
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     }
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');
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         }
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         }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
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;
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();
3057             // Finally reorder courses.
3058             fix_course_sortorder();
3059             cache_helper::purge_by_event('changesincoursecat');
3060             return true;
3061         }
3062         return false;
3063     }
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     }
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     }
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     }