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