PHPXRef 0.7.1 : Unnamed Project : Detail view of coursecatlib.php

Class to store, cache, render and manage course category

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

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 coursecat::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) X-Ref

Returns coursecat object for requested category

If category is not visible to 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
return: null|coursecat

get_many(array $ids) X-Ref

Load many coursecat objects.

param: array $ids An array of category ID's to load.
return: coursecat[]

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: coursecat

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: coursecat

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 coursecat::change_parent_raw if field 'parent' is updated.
It also calls coursecat::hide_raw or coursecat::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 coursecat::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() X-Ref

Checks if this course category is visible to current user

Please note that methods coursecat::get (without 3rd argumet),
coursecat::get_children(), etc. return only visible categories so it is
usually not needed to call this function outside of this class

return: bool

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 returns false. If 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

count_all() X-Ref

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

return: int

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 course_in_list::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

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 and/or coursecontacts need 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: coursecat[] Array of coursecat objects indexed by category id

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

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 $requiredcapabilites List of capabilities required to see return course.
return: course_in_list[]

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 coursecat::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 $requiredcapabilites 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 course_in_list::$summary and/or
course_in_list::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 course_in_list::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: course_in_list[]

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 coursecat::can_delete_full()} or {@link coursecat::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 coursecat::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 coursecat::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|coursecat $newparentcat
return: bool

change_parent_raw(coursecat $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: coursecat $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 = coursecat::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|coursecat $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_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:
Miscellaneous (id = 1)
Subcategory (id = 2)
Sub-subcategory (id = 4)
Other category (id = 3)

coursecat::get(1)->get_parents() == array()
coursecat::get(2)->get_parents() == array(1)
coursecat::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:
Miscellaneous (id = 1)
Subcategory (id = 2)
Sub-subcategory (id = 4)
Other category (id = 3)
Then after calling this function you will have
array(1 => 'Miscellaneous',
2 => 'Miscellaneous / Subcategory',
4 => 'Miscellaneous / 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.

See also {@link make_categories_options()}

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: coursecat

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

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 coursecat object for this category.

return: coursecat

can_request_course() X-Ref

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

return: bool

can_approve_course_requests() X-Ref

Returns true if the user can approve course requests.

return: bool

Class: course_in_list - X-Ref

Class to store information about one course in a list of courses

Not all information may be retrieved when object is created but
it will be retrieved on demand when appropriate property or method is
called.

Instances of this class are usually returned by functions
{@link coursecat::search_courses()}
and
{@link coursecat::get_courses()}

__construct(stdClass $record) X-Ref

Creates an instance of the class from record

param: stdClass $record except fields from course table it may contain

has_summary() X-Ref

Indicates if the course has non-empty summary field

return: bool

has_course_contacts() X-Ref

Indicates if the course have course contacts to display

return: bool

get_course_contacts() X-Ref

Returns list of course contacts (usually teachers) to display in course link

Roles to display are set up in $CFG->coursecontact

The result is the list of users where user id is the key and the value
is an array with elements:
- 'user' - object containing basic user information
- 'role' - object containing basic role information (id, name, shortname, coursealias)
- 'rolename' => role_get_name($role, $context, ROLENAME_ALIAS)
- 'username' => fullname($user, $canviewfullnames)

return: array

has_course_overviewfiles() X-Ref

Checks if course has any associated overview files

return: bool

get_course_overviewfiles() X-Ref

Returns all course overview files

return: array array of stored_file objects

__isset($name) X-Ref

Magic method to check if property is set

param: string $name
return: bool

__get($name) X-Ref

Magic method to get a course property

Returns any field from table course (retrieves it from DB if it was not retrieved before)

param: string $name
return: mixed

__unset($name) X-Ref

All properties are read only, sorry.

param: string $name

__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

getIterator() X-Ref

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

Implementing method from interface IteratorAggregate

return: ArrayIterator

get_formatted_name() X-Ref

Returns the name of this course as it should be displayed within a list.

return: string

get_formatted_fullname() X-Ref

Returns the formatted fullname for this course.

return: string

get_formatted_shortname() X-Ref

Returns the formatted shortname for this course.

return: string

can_access() X-Ref

Returns true if the current user can access this course.

return: bool

can_edit() X-Ref

Returns true if the user can edit this courses settings.

Note: this function does not check that the current user can access the course.
To do that please call require_login with the course, or if not possible call {@see course_in_list::can_access()}

return: bool

can_change_visibility() X-Ref

Returns true if the user can change the visibility of this course.

Note: this function does not check that the current user can access the course.
To do that please call require_login with the course, or if not possible call {@see course_in_list::can_access()}

return: bool

get_context() X-Ref

Returns the context for this course.

return: context_course

is_uservisible() X-Ref

Returns true if this course is visible to the current user.

return: bool

can_review_enrolments() X-Ref

Returns true if the current user can review enrolments for this course.

Note: this function does not check that the current user can access the course.
To do that please call require_login with the course, or if not possible call {@see course_in_list::can_access()}

return: bool

can_delete() X-Ref

Returns true if the current user can delete this course.

Note: this function does not check that the current user can access the course.
To do that please call require_login with the course, or if not possible call {@see course_in_list::can_access()}

return: bool

can_backup() X-Ref

Returns true if the current user can backup this course.

Note: this function does not check that the current user can access the course.
To do that please call require_login with the course, or if not possible call {@see course_in_list::can_access()}

return: bool

can_restore() X-Ref

Returns true if the current user can restore this course.

Note: this function does not check that the current user can access the course.
To do that please call require_login with the course, or if not possible call {@see course_in_list::can_access()}

return: bool

Class: coursecat_sortable_records - X-Ref

An array of records that is sortable by many fields.

For more info on the ArrayObject class have a look at php.net.

sort(array $records, array $fields) X-Ref

Sorts this array using the given fields.

param: array $records
param: array $fields
return: array

sort_by_many_fields($a, $b) X-Ref

Sorts the two records based upon many fields.

This method should not be called itself, please call $sort instead.
It has been marked as access private as such.

param: stdClass $a
param: stdClass $b
return: int

Copyright:	2013 Marina Glancy
License:	http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size:	3201 lines (127 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of Unnamed Project

/lib/ -> coursecatlib.php (summary)

Defines 3 classes