Class to store, cache, render and manage course category. More...

Inheritance diagram for core_course_category:

Public Member Functions
	__get ($name)
	Magic method getter, redirects to read only values.

	__isset ($name)
	Full support for isset on our magic read only properties.

	__set ($name, $value)
	Magic setter method, we do not want anybody to modify properties from the outside.

	__unset ($name)
	All properties are read only, sorry.

	can_change_parent ($newparentcat)
	Checks if user can move current category to the new parent.

	can_change_sortorder ()
	Returns true of the user can change the sortorder of this category (resort in the parent category)

	can_change_visibility ()
	Returns true if the current user is able to change the visbility of this category.

	can_create_course ()
	Returns true if the current user can create a course within this category.

	can_create_subcategory ()
	Returns true if the current user can create subcategories of this category.

	can_delete ()
	Returns true if the user is able to delete this category.

	can_delete_full ()
	Returns true if user can delete current category and all its contents.

	can_edit ()
	Returns true if the current user can edit this categories settings.

	can_move_content_to ($newcatid)
	Checks if user has capability to move all category content to the new parent before removing this category.

	can_move_courses_into ()
	Returns true if the user can move courses into this category.

	can_move_courses_out_of ()
	Returns true if the user can move courses out of this category.

	can_request_course ()
	Returns true if the user is able to request a new course be created.

	can_resort_courses ()
	Returns true if the user can resort the courses within this category.

	can_resort_subcategories ()
	Returns true if the user can resort this categories sub categories and courses.

	can_restore_courses_into ()
	Returns true if the user is able to restore a course into this category as a new course.

	can_review_cohorts ()
	Returns true if the current user can review cohorts for this category.

	can_review_filters ()
	Returns true if the current user can review filter settings for this category.

	can_review_permissions ()
	Returns true if the current user can review permissions for this category.

	can_review_roles ()
	Returns true if the current user can review role assignments for this category.

	change_parent ($newparentcat)
	Efficiently moves a category - NOTE that this can have a huge impact access-control-wise...

	change_sortorder_by_one ($up)
	Changes the sort order of this categories parent shifting this category up or down one.

	delete_full ($showfeedback=true)
	Recursively delete category including all subcategories and courses.

	delete_move ($newparentid, $showfeedback=false)
	Deletes a category and moves all content (children, courses and questions) to the new parent.

	get_all_children_ids ()
	Returns an array of ids of categories that are (direct and indirect) children of this category.

	get_children ($options=array())
	Returns array of children categories visible to the current user.

	get_children_count ()
	Returns number of subcategories visible to the current user.

	get_context ()
	Returns the category context.

	get_courses ($options=array())
	Retrieves the list of courses accessible by user.

	get_courses_count ($options=array())
	Returns number of courses visible to the user.

	get_db_record ()
	Returns the complete corresponding record from DB table course_categories.

	get_formatted_name ($options=array())
	Returns name of the category formatted as a string.

	get_nested_name ($includelinks=true, $separator='/', $options=[])
	Get the nested name of this category, with all of it's parents.

	get_parent_coursecat ()
	Returns the parent core_course_category object for this category.

	get_parents ()
	Returns ids of all parents of the category.

	get_plugins_callback_function (string $name)
	Get list of plugin callback functions.

	get_view_link ()
	Get the link used to view this course category.

	getIterator ()
	Create an iterator because magic vars can't be seen by 'foreach'.

	has_children ()
	Returns true if the category has ANY children, including those not visible to the user.

	has_contentbank ()
	Checks whether the category has access to content bank.

	has_courses ()
	Returns true if the category has courses in it (count does not include courses in child categories)

	has_manage_capability ()
	Returns true if the user is able to manage this category.

	hide ()
	Hide course category and child course and subcategories.

	is_uservisible ($user=null)
	Checks if this course category is visible to a user.

	move_content_targets_list ()
	Checks if user can delete this category and move content (courses, subcategories and questions) to another category.

	parent_has_manage_capability ()
	Returns true if the user has the manage capability on the parent category.

	prepare_to_cache ()
	Prepares the object for caching.

	resort_courses ($field, $cleanup=true)
	Resort the courses within this category by the given field.

	resort_subcategories ($field, $cleanup=true)
	Resorts the sub categories of this category by the given field.

	show ()
	Show course category and restores visibility for child course and subcategories.

	update ($data, $editoroptions=null)
	Updates the record with either form data or raw data.

Static Public Member Functions
static	can_approve_course_requests ()
	Returns true if the user can approve course requests.

static	can_change_parent_any ()
	Returns true if the user can change the parent of any category.

static	can_create_top_level_category ()
	Returns true if the user is able to create a top level category.

static	can_resort_any ()
	Returns true if the user can resort any category.

static	can_view_category ($category, $user=null)
	Checks if current user has access to the category.

static	can_view_course_info ($course, $user=null)
	Checks if current user can view course information or enrolment page.

static	count_all ()
	Returns number of ALL categories in the system regardless if they are visible to current user or not.

static	create ($data, $editoroptions=null)
	Creates a new category either from form data or from raw data.

static	get ($id, $strictness=MUST_EXIST, $alwaysreturnhidden=false, $user=null)
	Returns coursecat object for requested category.

static	get_all ($options=[])
	Load all core_course_category objects.

static	get_default ()
	Returns the first found category.

static	get_many (array $ids)
	Load many core_course_category objects.

static	get_nearest_editable_subcategory (core_course_category $parentcat, array $permissionstocheck)
	Returns the core_course_category object for the first category that the current user have the permission for the course.

static	has_capability_on_any ($capabilities)
	Checks if the user has at least one of the given capabilities on any category.

static	has_manage_capability_on_any ()
	Returns true if the user has the manage capability on any category.

static	is_simple_site ()
	Checks if the site has only one category and it is visible and available.

static	make_categories_list ($requiredcapability='', $excludeid=0, $separator='/')
	This function returns a nice list representing category tree for display or to use in a form <select> element.

static	page_setup ()
	General page setup for the course category pages.

static	preload_course_contacts (&$courses)
	Given list of DB records from table course populates each record with list of users with course contact roles.

static	preload_custom_fields (array &$records)
	Preloads the custom fields values in bulk.

static	resort_categories_cleanup ($includecourses=false)
	Cleans things up after categories have been resorted.

static	role_assignment_changed ($roleid, $context)
	Resets course contact caches when role assignments were changed.

static	search_courses ($search, $options=array(), $requiredcapabilities=array())
	Searches courses.

static	search_courses_count ($search, $options=array(), $requiredcapabilities=array())
	Returns number of courses in the search results.

static	top ()
	Returns the pseudo-category representing the whole system (id=0, context_system)

static	user_enrolment_changed ($courseid, $userid, $status, $timestart=null, $timeend=null)
	Executed when user enrolment was changed to check if course contacts cache needs to be cleared.

static	user_top ()
	Returns the top-most category for the current user.

static	wake_from_cache ($a)
	Takes the data provided by prepare_to_cache and reinitialises an instance of the associated from it.

Protected Member Functions
	__construct (stdClass $record, $fromcache=false)
	Constructor.

	change_parent_raw (core_course_category $newparentcat)
	Moves the category under another parent category.

	get_not_visible_children_ids ()
	Returns array of ids of children categories that current user can not see.

	hide_raw ($visibleold=0)
	Hide course category and child course and subcategories.

	restore ()
	Restores the object after it has been externally modified in DB for example during fix_course_sortorder().

	show_raw ()
	Show course category and restores visibility for child course and subcategories.

Static Protected Member Functions
static	ensure_users_enrolled ($courseusers)
	Verify user enrollments for multiple course-user combinations.

static	get_course_records ($whereclause, $params, $options, $checkvisibility=false)
	Retrieves number of records from course table.

static	get_records ($whereclause, $params)
	Retrieves number of records from course_categories table.

static	get_tree ($id)
	Returns the entry from categories tree and makes sure the application-level tree cache is built.

static	sort_records (&$records, $sortfields)
	Sorts list of records by several fields.

Protected Attributes
int	$coursecount = false

int	$depth = 0

string	$description = false

int	$descriptionformat = false

bool	$fromcache = false

int	$id

string	$idnumber = null

string	$name = ''

int	$parent = 0

string	$path = ''

int	$sortorder = 0

string	$theme = false

int	$timemodified = false

int	$visible = 1

int	$visibleold = false

Static Protected Attributes
static core_course_category	$coursecat0
	stores pseudo category with id=0.

static array	$coursecatfields
	list of all fields and their short name and default value for caching

Detailed Description

Class to store, cache, render and manage course category.

Copyright: 2013 Marina Glancy

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

core_course_category::__construct	(	stdClass	$record,
			$fromcache = false )

protected

Constructor.

Constructor is protected, use core_course_category\get($id) to retrieve category

Parameters

stdClass	$record	record from DB (may not contain all fields)
bool	$fromcache	whether it is being restored from cache

Member Function Documentation

◆ __get()

core_course_category::__get ( $name )

Magic method getter, redirects to read only values.

Queries from DB the fields that were not cached

Parameters

string $name

Return values

mixed

◆ __isset()

core_course_category::__isset ( $name )

Full support for isset on our magic read only properties.

Parameters

string $name

Return values

bool

◆ __set()

core_course_category::__set	(		$name,
			$value )

Magic setter method, we do not want anybody to modify properties from the outside.

Parameters

string	$name
mixed	$value

◆ __unset()

core_course_category::__unset ( $name )

All properties are read only, sorry.

Parameters

string $name

◆ can_approve_course_requests()

static core_course_category::can_approve_course_requests ( )

static

Returns true if the user can approve course requests.

Return values

bool

◆ can_change_parent()

core_course_category::can_change_parent ( $newparentcat )

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

Parameters

int | stdClass | core_course_category $newparentcat

Return values

bool

◆ can_change_parent_any()

static core_course_category::can_change_parent_any ( )

static

Returns true if the user can change the parent of any category.

Return values

bool

◆ can_change_sortorder()

core_course_category::can_change_sortorder ( )

Returns true of the user can change the sortorder of this category (resort in the parent category)

Return values

bool

◆ can_change_visibility()

core_course_category::can_change_visibility ( )

Returns true if the current user is able to change the visbility of this category.

Return values

bool

◆ can_create_course()

core_course_category::can_create_course ( )

Returns true if the current user can create a course within this category.

Return values

bool

◆ can_create_subcategory()

core_course_category::can_create_subcategory ( )

Returns true if the current user can create subcategories of this category.

Return values

bool

◆ can_create_top_level_category()

static core_course_category::can_create_top_level_category ( )

static

Returns true if the user is able to create a top level category.

Return values

bool

◆ can_delete()

core_course_category::can_delete ( )

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 core_course_category::can_delete_full() or core_course_category::can_move_content_to() depending upon what the user wished to do.

Return values

boolean

◆ can_delete_full()

core_course_category::can_delete_full ( )

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 values

bool

◆ can_edit()

core_course_category::can_edit ( )

Returns true if the current user can edit this categories settings.

Return values

bool

◆ can_move_content_to()

core_course_category::can_move_content_to ( $newcatid )

Checks if user has capability to move all category content to the new parent before removing this category.

Parameters

int $newcatid

Return values

bool

◆ can_move_courses_into()

core_course_category::can_move_courses_into ( )

Returns true if the user can move courses into this category.

Return values

bool

◆ can_move_courses_out_of()

core_course_category::can_move_courses_out_of ( )

Returns true if the user can move courses out of this category.

Return values

bool

◆ can_request_course()

core_course_category::can_request_course ( )

Returns true if the user is able to request a new course be created.

Return values

bool

◆ can_resort_any()

static core_course_category::can_resort_any ( )

static

Returns true if the user can resort any category.

Return values

bool

◆ can_resort_courses()

core_course_category::can_resort_courses ( )

Returns true if the user can resort the courses within this category.

Must have manage capability and be able to see all courses.

Return values

bool

◆ can_resort_subcategories()

core_course_category::can_resort_subcategories ( )

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 values

bool

◆ can_restore_courses_into()

core_course_category::can_restore_courses_into ( )

Returns true if the user is able to restore a course into this category as a new course.

Return values

bool

◆ can_review_cohorts()

core_course_category::can_review_cohorts ( )

Returns true if the current user can review cohorts for this category.

Return values

bool

◆ can_review_filters()

core_course_category::can_review_filters ( )

Returns true if the current user can review filter settings for this category.

Return values

bool

◆ can_review_permissions()

core_course_category::can_review_permissions ( )

Returns true if the current user can review permissions for this category.

Return values

bool

◆ can_review_roles()

core_course_category::can_review_roles ( )

Returns true if the current user can review role assignments for this category.

Return values

bool

◆ can_view_category()

static core_course_category::can_view_category	(		$category,
			$user = null )

static

Checks if current user has access to the category.

Parameters

stdClass \| core_course_category	$category
int \| stdClass	$user	The user id or object. By default (null) checks access for the current user.

Return values

bool

◆ can_view_course_info()

static core_course_category::can_view_course_info	(		$course,
			$user = null )

static

Checks if current user can view course information or enrolment page.

This method does not check if user is already enrolled in the course

Parameters

stdClass	$course	course object (must have 'id', 'visible' and 'category' fields)
null \| stdClass	$user	The user id or object. By default (null) checks access for the current user.

◆ change_parent()

core_course_category::change_parent ( $newparentcat )

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));

Parameters

int | stdClass | core_course_category $newparentcat

◆ change_parent_raw()

core_course_category::change_parent_raw ( core_course_category $newparentcat )

protected

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

See also: core_course_category\change_parent(); core_course_category\update()

Parameters

core_course_category $newparentcat

Exceptions

moodle_exception

◆ change_sortorder_by_one()

core_course_category::change_sortorder_by_one ( $up )

Changes the sort order of this categories parent shifting this category up or down one.

Parameters

bool $up If set to true the category is shifted up one spot, else its moved down.

Return values

bool	True on success, false otherwise.

◆ count_all()

static core_course_category::count_all ( )

static

Returns number of ALL categories in the system regardless if they are visible to current user or not.

Deprecated: since Moodle 3.7

Return values

int

◆ create()

static core_course_category::create	(		$data,
			$editoroptions = null )

static

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

Parameters

array \| stdClass	$data
array	$editoroptions	if specified, the data is considered to be form data and file_postupdate_standard_editor() is being called to process images in description.

Return values

core_course_category

Exceptions

moodle_exception

◆ delete_full()

core_course_category::delete_full ( $showfeedback = true )

Recursively delete category including all subcategories and courses.

Function core_course_category::can_delete_full() MUST be called prior to calling this function because there is no capability check inside this function

Parameters

boolean $showfeedback display some notices

Return values

array return deleted courses

Exceptions

moodle_exception

◆ delete_move()

core_course_category::delete_move	(		$newparentid,
			$showfeedback = false )

Deletes a category and moves all content (children, courses and questions) to the new parent.

Note that this function does not check capabilities, core_course_category::can_move_content_to() must be called prior

Parameters

int	$newparentid
bool	$showfeedback

Return values

bool

◆ ensure_users_enrolled()

static core_course_category::ensure_users_enrolled ( $courseusers )

staticprotected

Verify user enrollments for multiple course-user combinations.

Parameters

array $courseusers array where keys are course ids and values are array of users in this course whose enrolment we wish to verify

Return values

array same structure as input array but values list only users from input who are enrolled in the course

◆ get()

static core_course_category::get	(	$id,
		$strictness = MUST_EXIST,
		$alwaysreturnhidden = false,
		$user = null )

static

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())

Parameters

int	$id	category id
int	$strictness	whether to throw an exception (MUST_EXIST) or return null (IGNORE_MISSING) in case the category is not found or not visible to current user
bool	$alwaysreturnhidden	set to true if you want an object to be returned even if this category is not visible to the current user (category is hidden and user does not have 'moodle/category:viewhiddencategories' capability). Use with care!
int \| stdClass	$user	The user id or object. By default (null) checks the visibility to the current user.

Return values

null|self

Exceptions

moodle_exception

◆ get_all()

static core_course_category::get_all ( $options = [] )

static

Load all core_course_category objects.

Parameters

array

$options

Options:

returnhidden Return categories even if they are hidden

Return values

core_course_category[]

◆ get_all_children_ids()

core_course_category::get_all_children_ids ( )

Returns an array of ids of categories that are (direct and indirect) children of this category.

Return values

int[]

◆ get_children()

core_course_category::get_children ( $options = array() )

Returns array of children categories visible to the current user.

Parameters

array

$options

options for retrieving children

sort - list of fields to sort. Example array('idnumber' => 1, 'name' => 1, 'id' => -1) will sort by idnumber asc, name asc and id desc. Default: array('sortorder' => 1) Only cached fields may be used for sorting!
offset
limit - maximum number of children to return, 0 or null for no limit

Return values

core_course_category[] Array of core_course_category objects indexed by category id

◆ get_children_count()

core_course_category::get_children_count ( )

Returns number of subcategories visible to the current user.

Return values

int

◆ get_context()

core_course_category::get_context ( )

Returns the category context.

Return values

context_coursecat

◆ get_course_records()

static core_course_category::get_course_records	(	$whereclause,
		$params,
		$options,
		$checkvisibility = false )

staticprotected

Retrieves number of records from course table.

Not all fields are retrieved. Records are ready for preloading context

Parameters

string	$whereclause
array	$params
array	$options	may indicate that summary needs to be retrieved
bool	$checkvisibility	if true, capability 'moodle/course:viewhiddencourses' will be checked on not visible courses and 'moodle/category:viewcourselist' on all courses

Return values

array array of stdClass objects

◆ get_courses()

core_course_category::get_courses ( $options = array() )

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.

Parameters

array

$options

options for retrieving children

recursive - return courses from subcategories as well. Use with care, this may be a huge list!
summary - preloads fields 'summary' and 'summaryformat'
coursecontacts - preloads course contacts
sort - list of fields to sort. Example array('idnumber' => 1, 'shortname' => 1, 'id' => -1) will sort by idnumber asc, shortname asc and id desc. Default: array('sortorder' => 1) Only cached fields may be used for sorting!
offset
limit - maximum number of children to return, 0 or null for no limit
idonly - returns the array or course ids instead of array of objects used only in get_courses_count()

Return values

core_course_list_element[]

◆ get_courses_count()

core_course_category::get_courses_count ( $options = array() )

Returns number of courses visible to the user.

Parameters

array $options similar to get_courses() except some options do not affect number of courses (i.e. sort, summary, offset, limit etc.)

Return values

int

◆ get_db_record()

core_course_category::get_db_record ( )

Returns the complete corresponding record from DB table course_categories.

Mostly used in deprecated functions

Return values

stdClass

◆ get_default()

static core_course_category::get_default ( )

static

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 values

core_course_category

◆ get_formatted_name()

core_course_category::get_formatted_name ( $options = array() )

Returns name of the category formatted as a string.

Parameters

array $options formatting options other than context

Return values

string

◆ get_many()

static core_course_category::get_many ( array $ids )

static

Load many core_course_category objects.

Parameters

array $ids An array of category ID's to load.

Return values

core_course_category[]

◆ get_nearest_editable_subcategory()

static core_course_category::get_nearest_editable_subcategory	(	core_course_category	$parentcat,
		array	$permissionstocheck )

static

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

Parameters

core_course_category	$parentcat	Parent category to check.
array	$permissionstocheck	The value can be create, manage or any specific capability.

Return values

core_course_category|null

◆ get_nested_name()

core_course_category::get_nested_name	(	$includelinks = true,
		$separator = ' / ',
		$options = [] )

Get the nested name of this category, with all of it's parents.

Parameters

bool	$includelinks	Whether to wrap each name in the view link for that category.
string	$separator	The string between each name.
array	$options	Formatting options.

Return values

string

◆ get_not_visible_children_ids()

core_course_category::get_not_visible_children_ids ( )

protected

Returns array of ids of children categories that current user can not see.

This data is cached in user session cache

Return values

array

◆ get_parent_coursecat()

core_course_category::get_parent_coursecat ( )

Returns the parent core_course_category object for this category.

Only returns parent if it exists and is visible to the current user

Return values

core_course_category|null

◆ get_parents()

core_course_category::get_parents ( )

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 values

array of category ids

◆ get_plugins_callback_function()

core_course_category::get_plugins_callback_function ( string $name )

Get list of plugin callback functions.

Parameters

string $name Callback function name.

Return values

[callable] $pluginfunctions

◆ get_records()

static core_course_category::get_records	(		$whereclause,
			$params )

staticprotected

Retrieves number of records from course_categories table.

Only cached fields are retrieved. Records are ready for preloading context

Parameters

string	$whereclause
array	$params

Return values

array array of stdClass objects

◆ get_tree()

static core_course_category::get_tree ( $id )

staticprotected

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

Parameters

int | string $id

Return values

mixed

◆ get_view_link()

core_course_category::get_view_link ( )

Get the link used to view this course category.

Return values

moodle_url

◆ getIterator()

core_course_category::getIterator ( )

Create an iterator because magic vars can't be seen by 'foreach'.

implementing method from interface IteratorAggregate

Return values

ArrayIterator

◆ has_capability_on_any()

static core_course_category::has_capability_on_any ( $capabilities )

static

Checks if the user has at least one of the given capabilities on any category.

Parameters

array | string $capabilities One or more capabilities to check. Check made is an OR.

Return values

bool

◆ has_children()

core_course_category::has_children ( )

Returns true if the category has ANY children, including those not visible to the user.

Return values

boolean

◆ has_contentbank()

core_course_category::has_contentbank ( )

Checks whether the category has access to content bank.

Return values

bool

◆ has_courses()

core_course_category::has_courses ( )

Returns true if the category has courses in it (count does not include courses in child categories)

Return values

bool

◆ has_manage_capability()

core_course_category::has_manage_capability ( )

Returns true if the user is able to manage this category.

Return values

bool

◆ has_manage_capability_on_any()

static core_course_category::has_manage_capability_on_any ( )

static

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 values

bool

◆ hide()

core_course_category::hide ( )

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));

◆ hide_raw()

core_course_category::hide_raw ( $visibleold = 0 )

protected

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

See also: core_course_category\hide(); core_course_category\update()

Parameters

int $visibleold value to set in field $visibleold for this category

Return values

bool	whether changes have been made and caches need to be purged afterwards

◆ is_simple_site()

static core_course_category::is_simple_site ( )

static

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 values

bool

◆ is_uservisible()

core_course_category::is_uservisible ( $user = null )

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

Parameters

int | stdClass $user The user id or object. By default (null) checks the visibility to the current user.

Return values

bool

◆ make_categories_list()

static core_course_category::make_categories_list	(	$requiredcapability = '',
		$excludeid = 0,
		$separator = ' / ' )

static

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.

Parameters

	string/array	$requiredcapability if given, only categories where the current user has this capability will be returned. Can also be an array of capabilities, in which case they are all required.
integer	$excludeid	Exclude this category and its children from the lists built.
string	$separator	string to use as a separator between parent and child category. Default ' / '

Return values

array of strings

◆ move_content_targets_list()

core_course_category::move_content_targets_list ( )

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 values

array

◆ page_setup()

static core_course_category::page_setup ( )

static

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 values

void

◆ parent_has_manage_capability()

core_course_category::parent_has_manage_capability ( )

Returns true if the user has the manage capability on the parent category.

Return values

bool

◆ preload_course_contacts()

static core_course_category::preload_course_contacts ( & $courses )

static

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 get_role_users() would do. See also 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

Todo: MDL-38596 minimize number of queries to preload contacts for the list of courses

Parameters

array $courses

◆ preload_custom_fields()

static core_course_category::preload_custom_fields ( array & $records )

static

Preloads the custom fields values in bulk.

Parameters

array $records

◆ prepare_to_cache()

core_course_category::prepare_to_cache ( )

Prepares the object for caching.

Works like the __sleep method.

implementing method from interface cacheable_object

Return values

array ready to be cached

Implements cacheable_object.

◆ resort_categories_cleanup()

static core_course_category::resort_categories_cleanup ( $includecourses = false )

static

Cleans things up after categories have been resorted.

Parameters

bool $includecourses If set to true we know courses have been resorted as well.

◆ resort_courses()

core_course_category::resort_courses	(		$field,
			$cleanup = true )

Resort the courses within this category by the given field.

Parameters

string	$field	One of fullname, shortname, idnumber or descending values of each (appended desc)
bool	$cleanup

Return values

bool	True for success.

Exceptions

coding_exception

◆ resort_subcategories()

core_course_category::resort_subcategories	(		$field,
			$cleanup = true )

Resorts the sub categories of this category by the given field.

Parameters

string	$field	One of name, idnumber or descending values of each (appended desc)
bool	$cleanup	If true cleanup will be done, if false you will need to do it manually later.

Return values

bool	True on success.

Exceptions

coding_exception

◆ role_assignment_changed()

static core_course_category::role_assignment_changed	(		$roleid,
			$context )

static

Resets course contact caches when role assignments were changed.

Parameters

int	$roleid	role id that was given or taken away
context	$context	context where role assignment has been changed

◆ search_courses()

static core_course_category::search_courses	(	$search,
		$options = array(),
		$requiredcapabilities = array() )

static

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.

Parameters

array	$search	contains search criterias, such as: search - search string blocklist - id of block (if we are searching for courses containing specific block0 modulelist - name of module (if we are searching for courses containing specific module tagid - id of tag onlywithcompletion - set to true if we only need courses with completion enabled
array	$options	display options, same as in get_courses() except 'recursive' is ignored - search is always category-independent
array	$requiredcapabilities	List of capabilities required to see return course.

Return values

core_course_list_element[]

◆ search_courses_count()

static core_course_category::search_courses_count	(	$search,
		$options = array(),
		$requiredcapabilities = array() )

static

Returns number of courses in the search results.

It is recommended to call this function after core_course_category::search_courses() and not before because only course ids are cached. Otherwise search_courses() may perform extra DB queries.

Parameters

array	$search	search criteria, see method search_courses() for more details
array	$options	display options. They do not affect the result but the 'sort' property is used in cache key for storing list of course ids
array	$requiredcapabilities	List of capabilities required to see return course.

Return values

int

◆ show()

core_course_category::show ( )

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));

◆ show_raw()

core_course_category::show_raw ( )

protected

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

See also: core_course_category\show(); core_course_category\update()

Return values

bool	whether changes have been made and caches need to be purged afterwards

◆ sort_records()

static core_course_category::sort_records	(	&	$records,
			$sortfields )

staticprotected

Sorts list of records by several fields.

Parameters

array	$records	array of stdClass objects
array	$sortfields	assoc array where key is the field to sort and value is 1 for asc or -1 for desc

Return values

int

◆ top()

static core_course_category::top ( )

static

Returns the pseudo-category representing the whole system (id=0, context_system)

Return values

core_course_category

◆ update()

core_course_category::update	(		$data,
			$editoroptions = null )

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'

Parameters

array \| stdClass	$data
array	$editoroptions	if specified, the data is considered to be form data and file_postupdate_standard_editor() is being called to process images in description.

Exceptions

moodle_exception

◆ user_enrolment_changed()

static core_course_category::user_enrolment_changed	(	$courseid,
		$userid,
		$status,
		$timestart = null,
		$timeend = null )

static

Executed when user enrolment was changed to check if course contacts cache needs to be cleared.

Parameters

int	$courseid	course id
int	$userid	user id
int	$status	new enrolment status (0 - active, 1 - suspended)
int	$timestart	new enrolment time start
int	$timeend	new enrolment time end

◆ user_top()

static core_course_category::user_top ( )

static

Returns the top-most category for the current user.

Examples:

User can browse courses everywhere - return self\top() - pseudo-category with id=0
User does not have capability to browse courses on the system level but has it in ONE course category - return this course category
User has capability to browse courses in two course categories - return self\top()

Return values

core_course_category|null

◆ wake_from_cache()

static core_course_category::wake_from_cache ( $a )

static

Takes the data provided by prepare_to_cache and reinitialises an instance of the associated from it.

implementing method from interface cacheable_object

Parameters

array $a

Return values

core_course_category

Implements cacheable_object.

Member Data Documentation

◆ $coursecat0

core_course_category core_course_category::$coursecat0

staticprotected

stores pseudo category with id=0.

Use core_course_category\get(0) to retrieve

◆ $coursecatfields

array core_course_category::$coursecatfields

staticprotected

Initial value:

= array(
        'id' => array('id', 0),
        'name' => array('na', ''),
        'idnumber' => array('in', null),
        'description' => null, 
        'descriptionformat' => null, 
        'parent' => array('pa', 0),
        'sortorder' => array('so', 0),
        'coursecount' => array('cc', 0),
        'visible' => array('vi', 1),
        'visibleold' => null, 
        'timemodified' => null, 
        'depth' => array('dh', 1),
        'path' => array('ph', null),
        'theme' => null, 
    )

list of all fields and their short name and default value for caching

The documentation for this class was generated from the following file:

course/classes/category.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ __get()

◆ __isset()

◆ __set()

◆ __unset()

◆ can_approve_course_requests()

◆ can_change_parent()

◆ can_change_parent_any()

◆ can_change_sortorder()

◆ can_change_visibility()

◆ can_create_course()

◆ can_create_subcategory()

◆ can_create_top_level_category()

◆ can_delete()

◆ can_delete_full()

◆ can_edit()

◆ can_move_content_to()

◆ can_move_courses_into()

◆ can_move_courses_out_of()

◆ can_request_course()

◆ can_resort_any()

◆ can_resort_courses()

◆ can_resort_subcategories()

◆ can_restore_courses_into()

◆ can_review_cohorts()

◆ can_review_filters()

◆ can_review_permissions()

◆ can_review_roles()

◆ can_view_category()

◆ can_view_course_info()

◆ change_parent()

◆ change_parent_raw()

◆ change_sortorder_by_one()

◆ count_all()

◆ create()

◆ delete_full()

◆ delete_move()

◆ ensure_users_enrolled()

◆ get()

◆ get_all()

◆ get_all_children_ids()

◆ get_children()

◆ get_children_count()

◆ get_context()

◆ get_course_records()

◆ get_courses()

◆ get_courses_count()

◆ get_db_record()

◆ get_default()

◆ get_formatted_name()

◆ get_many()

◆ get_nearest_editable_subcategory()

◆ get_nested_name()

◆ get_not_visible_children_ids()

◆ get_parent_coursecat()

◆ get_parents()

◆ get_plugins_callback_function()

◆ get_records()

◆ get_tree()

◆ get_view_link()

◆ getIterator()

◆ has_capability_on_any()

◆ has_children()

◆ has_contentbank()

◆ has_courses()

◆ has_manage_capability()

◆ has_manage_capability_on_any()

◆ hide()

◆ hide_raw()

◆ is_simple_site()

◆ is_uservisible()