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