Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/course/classes/ -> category.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
Contains class core_course_category responsible for course category operations
| Copyright: | 2013 Marina Glancy |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 3256 lines (132 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 1 class
core_course_category:: (96 methods):
__set()
__get()
__isset()
__unset()
get_plugins_callback_function()
getIterator()
__construct()
get()
top()
user_top()
get_many()
get_all()
get_default()
restore()
create()
update()
is_uservisible()
can_view_category()
can_view_course_info()
get_db_record()
get_tree()
get_cached_cat_tree()
rebuild_coursecattree_cache_contents()
count_all()
is_simple_site()
get_records()
role_assignment_changed()
user_enrolment_changed()
preload_course_contacts()
preload_custom_fields()
ensure_users_enrolled()
get_course_records()
get_not_visible_children_ids()
sort_records()
get_children()
get_all_children_ids()
has_manage_capability_on_any()
has_capability_on_any()
can_resort_any()
can_change_parent_any()
get_children_count()
has_children()
has_courses()
get_view_link()
search_courses()
search_courses_count()
get_courses()
get_courses_count()
can_delete()
can_delete_full()
delete_full()
move_content_targets_list()
can_move_content_to()
delete_move()
can_change_parent()
change_parent_raw()
change_parent()
hide_raw()
hide()
show_raw()
show()
get_formatted_name()
get_nested_name()
get_parents()
make_categories_list()
prepare_to_cache()
wake_from_cache()
can_create_top_level_category()
get_context()
has_manage_capability()
has_contentbank()
parent_has_manage_capability()
can_create_subcategory()
can_resort_subcategories()
can_resort_courses()
can_change_sortorder()
can_create_course()
can_edit()
can_review_roles()
can_review_permissions()
can_review_cohorts()
can_review_filters()
can_change_visibility()
can_move_courses_out_of()
can_move_courses_into()
can_restore_courses_into()
resort_subcategories()
resort_categories_cleanup()
resort_courses()
change_sortorder_by_one()
get_parent_coursecat()
can_request_course()
has_capabilities()
can_approve_course_requests()
page_setup()
get_nearest_editable_subcategory()
Class: core_course_category - X-Ref
Class to store, cache, render and manage course category| __set($name, $value) X-Ref |
| Magic setter method, we do not want anybody to modify properties from the outside param: string $name param: mixed $value |
| __get($name) X-Ref |
| Magic method getter, redirects to read only values. Queries from DB the fields that were not cached param: string $name return: mixed |
| __isset($name) X-Ref |
| Full support for isset on our magic read only properties. param: string $name return: bool |
| __unset($name) X-Ref |
| All properties are read only, sorry. param: string $name |
| get_plugins_callback_function(string $name) X-Ref |
| Get list of plugin callback functions. param: string $name Callback function name. return: [callable] $pluginfunctions |
| getIterator() X-Ref |
| Create an iterator because magic vars can't be seen by 'foreach'. implementing method from interface IteratorAggregate return: ArrayIterator |
| __construct(stdClass $record, $fromcache = false) X-Ref |
| Constructor Constructor is protected, use core_course_category::get($id) to retrieve category param: stdClass $record record from DB (may not contain all fields) param: bool $fromcache whether it is being restored from cache |
| get($id, $strictness = MUST_EXIST, $alwaysreturnhidden = false, $user = null) X-Ref |
| Returns coursecat object for requested category If category is not visible to the given user, it is treated as non existing unless $alwaysreturnhidden is set to true If id is 0, the pseudo object for root category is returned (convenient for calling other functions such as get_children()) param: int $id category id param: int $strictness whether to throw an exception (MUST_EXIST) or param: bool $alwaysreturnhidden set to true if you want an object to be param: int|stdClass $user The user id or object. By default (null) checks the visibility to the current user. return: null|self |
| top() X-Ref |
| Returns the pseudo-category representing the whole system (id=0, context_system) return: core_course_category |
| user_top() X-Ref |
| Returns the top-most category for the current user Examples: 1. User can browse courses everywhere - return self::top() - pseudo-category with id=0 2. User does not have capability to browse courses on the system level but has it in ONE course category - return this course category 3. User has capability to browse courses in two course categories - return self::top() return: core_course_category|null |
| get_many(array $ids) X-Ref |
| Load many core_course_category objects. param: array $ids An array of category ID's to load. return: core_course_category[] |
| get_all($options = []) X-Ref |
| Load all core_course_category objects. param: array $options Options: return: core_course_category[] |
| get_default() X-Ref |
| Returns the first found category Note that if there are no categories visible to the current user on the first level, the invisible category may be returned return: core_course_category |
| restore() X-Ref |
| Restores the object after it has been externally modified in DB for example during {@link fix_course_sortorder()} |
| create($data, $editoroptions = null) X-Ref |
| Creates a new category either from form data or from raw data Please note that this function does not verify access control. Exception is thrown if name is missing or idnumber is duplicating another one in the system. Category visibility is inherited from parent unless $data->visible = 0 is specified param: array|stdClass $data param: array $editoroptions if specified, the data is considered to be return: core_course_category |
| update($data, $editoroptions = null) X-Ref |
| Updates the record with either form data or raw data Please note that this function does not verify access control. This function calls core_course_category::change_parent_raw if field 'parent' is updated. It also calls core_course_category::hide_raw or core_course_category::show_raw if 'visible' is updated. Visibility is changed first and then parent is changed. This means that if parent category is hidden, the current category will become hidden too and it may overwrite whatever was set in field 'visible'. Note that fields 'path' and 'depth' can not be updated manually Also core_course_category::update() can not directly update the field 'sortoder' param: array|stdClass $data param: array $editoroptions if specified, the data is considered to be |
| is_uservisible($user = null) X-Ref |
| Checks if this course category is visible to a user. Please note that methods core_course_category::get (without 3rd argumet), core_course_category::get_children(), etc. return only visible categories so it is usually not needed to call this function outside of this class param: int|stdClass $user The user id or object. By default (null) checks the visibility to the current user. return: bool |
| can_view_category($category, $user = null) X-Ref |
| Checks if current user has access to the category param: stdClass|core_course_category $category param: int|stdClass $user The user id or object. By default (null) checks access for the current user. return: bool |
| can_view_course_info($course, $user = null) X-Ref |
| Checks if current user can view course information or enrolment page. This method does not check if user is already enrolled in the course param: stdClass $course course object (must have 'id', 'visible' and 'category' fields) param: null|stdClass $user The user id or object. By default (null) checks access for the current user. |
| get_db_record() X-Ref |
| Returns the complete corresponding record from DB table course_categories Mostly used in deprecated functions return: stdClass |
| get_tree($id) X-Ref |
| Returns the entry from categories tree and makes sure the application-level tree cache is built The following keys can be requested: 'countall' - total number of categories in the system (always present) 0 - array of ids of top-level categories (always present) '0i' - array of ids of top-level categories that have visible=0 (always present but may be empty array) $id (int) - array of ids of categories that are direct children of category with id $id. If category with id $id does not exist, or category has no children, returns empty array $id.'i' - array of ids of children categories that have visible=0 param: int|string $id return: mixed |
| get_cached_cat_tree() X-Ref |
| Return the course category tree. Returns the category tree array, from the cache if available or rebuilding the cache if required. Uses locking to prevent the cache being rebuilt by multiple requests at once. return: array|null The tree as an array, or null if rebuilding the tree failed due to a lock timeout. |
| rebuild_coursecattree_cache_contents() X-Ref |
| Rebuild the course category tree as an array, including an extra "countall" field. return: array |
| count_all() X-Ref |
| Returns number of ALL categories in the system regardless if they are visible to current user or not return: int |
| is_simple_site() X-Ref |
| Checks if the site has only one category and it is visible and available. In many situations we won't show this category at all return: bool |
| get_records($whereclause, $params) X-Ref |
| Retrieves number of records from course_categories table Only cached fields are retrieved. Records are ready for preloading context param: string $whereclause param: array $params return: array array of stdClass objects |
| role_assignment_changed($roleid, $context) X-Ref |
| Resets course contact caches when role assignments were changed param: int $roleid role id that was given or taken away param: context $context context where role assignment has been changed |
| user_enrolment_changed($courseid, $userid,$status, $timestart = null, $timeend = null) X-Ref |
| Executed when user enrolment was changed to check if course contacts cache needs to be cleared param: int $courseid course id param: int $userid user id param: int $status new enrolment status (0 - active, 1 - suspended) param: int $timestart new enrolment time start param: int $timeend new enrolment time end |
| preload_course_contacts(&$courses) X-Ref |
| Given list of DB records from table course populates each record with list of users with course contact roles This function fills the courses with raw information as {@link get_role_users()} would do. See also {@link core_course_list_element::get_course_contacts()} for more readable return $courses[$i]->managers = array( $roleassignmentid => $roleuser, ... ); where $roleuser is an stdClass with the following properties: $roleuser->raid - role assignment id $roleuser->id - user id $roleuser->username $roleuser->firstname $roleuser->lastname $roleuser->rolecoursealias $roleuser->rolename $roleuser->sortorder - role sortorder $roleuser->roleid $roleuser->roleshortname param: array $courses |
| preload_custom_fields(array &$records) X-Ref |
| Preloads the custom fields values in bulk param: array $records |
| ensure_users_enrolled($courseusers) X-Ref |
| Verify user enrollments for multiple course-user combinations param: array $courseusers array where keys are course ids and values are array return: array same structure as input array but values list only users from input |
| get_course_records($whereclause, $params, $options, $checkvisibility = false) X-Ref |
| Retrieves number of records from course table Not all fields are retrieved. Records are ready for preloading context param: string $whereclause param: array $params param: array $options may indicate that summary needs to be retrieved param: bool $checkvisibility if true, capability 'moodle/course:viewhiddencourses' will be checked return: array array of stdClass objects |
| get_not_visible_children_ids() X-Ref |
| Returns array of ids of children categories that current user can not see This data is cached in user session cache return: array |
| sort_records(&$records, $sortfields) X-Ref |
| Sorts list of records by several fields param: array $records array of stdClass objects param: array $sortfields assoc array where key is the field to sort and value is 1 for asc or -1 for desc return: int |
| get_children($options = array() X-Ref |
| Returns array of children categories visible to the current user param: array $options options for retrieving children return: core_course_category[] Array of core_course_category objects indexed by category id |
| get_all_children_ids() X-Ref |
| Returns an array of ids of categories that are (direct and indirect) children of this category. return: int[] |
| has_manage_capability_on_any() X-Ref |
| Returns true if the user has the manage capability on any category. This method uses the coursecat cache and an entry `has_manage_capability` to speed up calls to this method. return: bool |
| has_capability_on_any($capabilities) X-Ref |
| Checks if the user has at least one of the given capabilities on any category. param: array|string $capabilities One or more capabilities to check. Check made is an OR. return: bool |
| can_resort_any() X-Ref |
| Returns true if the user can resort any category. return: bool |
| can_change_parent_any() X-Ref |
| Returns true if the user can change the parent of any category. return: bool |
| get_children_count() X-Ref |
| Returns number of subcategories visible to the current user return: int |
| has_children() X-Ref |
| Returns true if the category has ANY children, including those not visible to the user return: boolean |
| has_courses() X-Ref |
| Returns true if the category has courses in it (count does not include courses in child categories) return: bool |
| get_view_link() X-Ref |
| Get the link used to view this course category. return: \moodle_url |
| search_courses($search, $options = array() X-Ref |
| Searches courses List of found course ids is cached for 10 minutes. Cache may be purged prior to this when somebody edits courses or categories, however it is very difficult to keep track of all possible changes that may affect list of courses. param: array $search contains search criterias, such as: param: array $options display options, same as in get_courses() except 'recursive' is ignored - param: array $requiredcapabilities List of capabilities required to see return course. return: core_course_list_element[] |
| search_courses_count($search, $options = array() X-Ref |
| Returns number of courses in the search results It is recommended to call this function after {@link core_course_category::search_courses()} and not before because only course ids are cached. Otherwise search_courses() may perform extra DB queries. param: array $search search criteria, see method search_courses() for more details param: array $options display options. They do not affect the result but param: array $requiredcapabilities List of capabilities required to see return course. return: int |
| get_courses($options = array() X-Ref |
| Retrieves the list of courses accessible by user Not all information is cached, try to avoid calling this method twice in the same request. The following fields are always retrieved: - id, visible, fullname, shortname, idnumber, category, sortorder If you plan to use properties/methods core_course_list_element::$summary and/or core_course_list_element::get_course_contacts() you can preload this information using appropriate 'options'. Otherwise they will be retrieved from DB on demand and it may end with bigger DB load. Note that method core_course_list_element::has_summary() will not perform additional DB queries even if $options['summary'] is not specified List of found course ids is cached for 10 minutes. Cache may be purged prior to this when somebody edits courses or categories, however it is very difficult to keep track of all possible changes that may affect list of courses. param: array $options options for retrieving children return: core_course_list_element[] |
| get_courses_count($options = array() X-Ref |
| Returns number of courses visible to the user param: array $options similar to get_courses() except some options do not affect return: int |
| can_delete() X-Ref |
| Returns true if the user is able to delete this category. Note if this category contains any courses this isn't a full check, it will need to be accompanied by a call to either {@link core_course_category::can_delete_full()} or {@link core_course_category::can_move_content_to()} depending upon what the user wished to do. return: boolean |
| can_delete_full() X-Ref |
| Returns true if user can delete current category and all its contents To be able to delete course category the user must have permission 'moodle/category:manage' in ALL child course categories AND be able to delete all courses return: bool |
| delete_full($showfeedback = true) X-Ref |
| Recursively delete category including all subcategories and courses Function {@link core_course_category::can_delete_full()} MUST be called prior to calling this function because there is no capability check inside this function param: boolean $showfeedback display some notices return: array return deleted courses |
| move_content_targets_list() X-Ref |
| Checks if user can delete this category and move content (courses, subcategories and questions) to another category. If yes returns the array of possible target categories names If user can not manage this category or it is completely empty - empty array will be returned return: array |
| can_move_content_to($newcatid) X-Ref |
| Checks if user has capability to move all category content to the new parent before removing this category param: int $newcatid return: bool |
| delete_move($newparentid, $showfeedback = false) X-Ref |
| Deletes a category and moves all content (children, courses and questions) to the new parent Note that this function does not check capabilities, {@link core_course_category::can_move_content_to()} must be called prior param: int $newparentid param: bool $showfeedback return: bool |
| can_change_parent($newparentcat) X-Ref |
| Checks if user can move current category to the new parent This checks if new parent category exists, user has manage cap there and new parent is not a child of this category param: int|stdClass|core_course_category $newparentcat return: bool |
| change_parent_raw(core_course_category $newparentcat) X-Ref |
| Moves the category under another parent category. All associated contexts are moved as well This is protected function, use change_parent() or update() from outside of this class param: core_course_category $newparentcat |
| change_parent($newparentcat) X-Ref |
| Efficiently moves a category - NOTE that this can have a huge impact access-control-wise... Note that this function does not check capabilities. Example of usage: $coursecat = core_course_category::get($categoryid); if ($coursecat->can_change_parent($newparentcatid)) { $coursecat->change_parent($newparentcatid); } This function does not update field course_categories.timemodified If you want to update timemodified, use $coursecat->update(array('parent' => $newparentcat)); param: int|stdClass|core_course_category $newparentcat |
| hide_raw($visibleold = 0) X-Ref |
| Hide course category and child course and subcategories If this category has changed the parent and is moved under hidden category we will want to store it's current visibility state in the field 'visibleold'. If admin clicked 'hide' for this particular category, the field 'visibleold' should become 0. All subcategories and courses will have their current visibility in the field visibleold This is protected function, use hide() or update() from outside of this class param: int $visibleold value to set in field $visibleold for this category return: bool whether changes have been made and caches need to be purged afterwards |
| hide() X-Ref |
| Hide course category and child course and subcategories Note that there is no capability check inside this function This function does not update field course_categories.timemodified If you want to update timemodified, use $coursecat->update(array('visible' => 0)); |
| show_raw() X-Ref |
| Show course category and restores visibility for child course and subcategories Note that there is no capability check inside this function This is protected function, use show() or update() from outside of this class return: bool whether changes have been made and caches need to be purged afterwards |
| show() X-Ref |
| Show course category and restores visibility for child course and subcategories Note that there is no capability check inside this function This function does not update field course_categories.timemodified If you want to update timemodified, use $coursecat->update(array('visible' => 1)); |
| get_formatted_name($options = array() X-Ref |
| Returns name of the category formatted as a string param: array $options formatting options other than context return: string |
| get_nested_name($includelinks = true, $separator = ' / ', $options = []) X-Ref |
| Get the nested name of this category, with all of it's parents. param: bool $includelinks Whether to wrap each name in the view link for that category. param: string $separator The string between each name. param: array $options Formatting options. return: string |
| get_parents() X-Ref |
| Returns ids of all parents of the category. Last element in the return array is the direct parent For example, if you have a tree of categories like: Category (id = 1) Subcategory (id = 2) Sub-subcategory (id = 4) Other category (id = 3) core_course_category::get(1)->get_parents() == array() core_course_category::get(2)->get_parents() == array(1) core_course_category::get(4)->get_parents() == array(1, 2); Note that this method does not check if all parents are accessible by current user return: array of category ids |
| make_categories_list($requiredcapability = '', $excludeid = 0, $separator = ' / ') X-Ref |
| This function returns a nice list representing category tree for display or to use in a form <select> element List is cached for 10 minutes For example, if you have a tree of categories like: Category (id = 1) Subcategory (id = 2) Sub-subcategory (id = 4) Other category (id = 3) Then after calling this function you will have array(1 => 'Category', 2 => 'Category / Subcategory', 4 => 'Category / Subcategory / Sub-subcategory', 3 => 'Other category'); If you specify $requiredcapability, then only categories where the current user has that capability will be added to $list. If you only have $requiredcapability in a child category, not the parent, then the child catgegory will still be included. If you specify the option $excludeid, then that category, and all its children, are omitted from the tree. This is useful when you are doing something like moving categories, where you do not want to allow people to move a category to be the child of itself. param: string/array $requiredcapability if given, only categories where the current param: integer $excludeid Exclude this category and its children from the lists built. param: string $separator string to use as a separator between parent and child category. Default ' / ' return: array of strings |
| prepare_to_cache() X-Ref |
| Prepares the object for caching. Works like the __sleep method. implementing method from interface cacheable_object return: array ready to be cached |
| wake_from_cache($a) X-Ref |
| Takes the data provided by prepare_to_cache and reinitialises an instance of the associated from it. implementing method from interface cacheable_object param: array $a return: core_course_category |
| can_create_top_level_category() X-Ref |
| Returns true if the user is able to create a top level category. return: bool |
| get_context() X-Ref |
| Returns the category context. return: context_coursecat |
| has_manage_capability() X-Ref |
| Returns true if the user is able to manage this category. return: bool |
| has_contentbank() X-Ref |
| Checks whether the category has access to content bank return: bool |
| parent_has_manage_capability() X-Ref |
| Returns true if the user has the manage capability on the parent category. return: bool |
| can_create_subcategory() X-Ref |
| Returns true if the current user can create subcategories of this category. return: bool |
| can_resort_subcategories() X-Ref |
| Returns true if the user can resort this categories sub categories and courses. Must have manage capability and be able to see all subcategories. return: bool |
| can_resort_courses() X-Ref |
| Returns true if the user can resort the courses within this category. Must have manage capability and be able to see all courses. return: bool |
| can_change_sortorder() X-Ref |
| Returns true of the user can change the sortorder of this category (resort in the parent category) return: bool |
| can_create_course() X-Ref |
| Returns true if the current user can create a course within this category. return: bool |
| can_edit() X-Ref |
| Returns true if the current user can edit this categories settings. return: bool |
| can_review_roles() X-Ref |
| Returns true if the current user can review role assignments for this category. return: bool |
| can_review_permissions() X-Ref |
| Returns true if the current user can review permissions for this category. return: bool |
| can_review_cohorts() X-Ref |
| Returns true if the current user can review cohorts for this category. return: bool |
| can_review_filters() X-Ref |
| Returns true if the current user can review filter settings for this category. return: bool |
| can_change_visibility() X-Ref |
| Returns true if the current user is able to change the visbility of this category. return: bool |
| can_move_courses_out_of() X-Ref |
| Returns true if the user can move courses out of this category. return: bool |
| can_move_courses_into() X-Ref |
| Returns true if the user can move courses into this category. return: bool |
| can_restore_courses_into() X-Ref |
| Returns true if the user is able to restore a course into this category as a new course. return: bool |
| resort_subcategories($field, $cleanup = true) X-Ref |
| Resorts the sub categories of this category by the given field. param: string $field One of name, idnumber or descending values of each (appended desc) param: bool $cleanup If true cleanup will be done, if false you will need to do it manually later. return: bool True on success. |
| resort_categories_cleanup($includecourses = false) X-Ref |
| Cleans things up after categories have been resorted. param: bool $includecourses If set to true we know courses have been resorted as well. |
| resort_courses($field, $cleanup = true) X-Ref |
| Resort the courses within this category by the given field. param: string $field One of fullname, shortname, idnumber or descending values of each (appended desc) param: bool $cleanup return: bool True for success. |
| change_sortorder_by_one($up) X-Ref |
| Changes the sort order of this categories parent shifting this category up or down one. param: bool $up If set to true the category is shifted up one spot, else its moved down. return: bool True on success, false otherwise. |
| get_parent_coursecat() X-Ref |
| Returns the parent core_course_category object for this category. Only returns parent if it exists and is visible to the current user return: core_course_category|null |
| can_request_course() X-Ref |
| Returns true if the user is able to request a new course be created. return: bool |
| has_capabilities(array $permissionstocheck) X-Ref |
| Returns true if the user has all the given permissions. param: array $permissionstocheck The value can be create, manage or any specific capability. return: bool |
| can_approve_course_requests() X-Ref |
| Returns true if the user can approve course requests. return: bool |
| page_setup() X-Ref |
| General page setup for the course category pages. This method sets up things which are common for the course category pages such as page heading, the active nodes in the page navigation block, the active item in the primary navigation (when applicable). return: void |
| get_nearest_editable_subcategory(core_course_category $parentcat,array $permissionstocheck) X-Ref |
| Returns the core_course_category object for the first category that the current user have the permission for the course. Only returns if it exists and is creatable/manageable to the current user param: core_course_category $parentcat Parent category to check. param: array $permissionstocheck The value can be create, manage or any specific capability. return: core_course_category|null |
