Search moodle.org's
Developer Documentation


/course/ -> lib.php (summary)

Library of useful functions

Copyright: 1999 Martin Dougiamas http://dougiamas.com
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 3714 lines (143 kb)
Included or required: 11 times
Referenced: 70 times
Includes or requires: 0 files

Defines 1 class

Defines 27 functions


Class: course_request  - X-Ref

This class pertains to course requests and contains methods associated with
create, approving, and removing course requests.

Please note we do not allow embedded images here because there is no context
to store them with proper access control.

prepare($data=null)   X-Ref
Static function to prepare the summary editor for working with a course
request.

param: null|stdClass $data Optional, an object containing the default values
return: stdClass An object that can be used to set the default values for

create($data)   X-Ref
Static function to create a new course request when passed an array of properties
for it.

This function also handles saving any files that may have been used in the editor

param: stdClass $data
return: course_request The newly created course request

summary_editor_options()   X-Ref
Returns an array of options to use with a summary editor

return: array An array of options to use with the editor

__construct($properties)   X-Ref
Loads the properties for this course request object. Id is required and if
only id is provided then we load the rest of the properties from the database

param: stdClass|int $properties Either an object containing properties

__get($key)   X-Ref
Returns the requested property

param: string $key
return: mixed

__isset($key)   X-Ref
Override this to ensure empty($request->blah) calls return a reliable answer...

This is required because we define the __get method

param: mixed $key
return: bool True is it not empty, false otherwise

get_requester()   X-Ref
Returns the user who requested this course

Uses a static var to cache the results and cut down the number of db queries

return: stdClass The user who requested the course

check_shortname_collision($shortnamemark = '[*]')   X-Ref
Checks that the shortname used by the course does not conflict with any other
courses that exist

param: string|null $shortnamemark The string to append to the requests shortname
return: bool true is there is a conflict, false otherwise

get_category()   X-Ref
Returns the category where this course request should be created

Note that we don't check here that user has a capability to view
hidden categories if he has capabilities 'moodle/site:approvecourse' and
'moodle/course:changecategory'

return: coursecat

approve()   X-Ref
This function approves the request turning it into a course

This function converts the course request into a course, at the same time
transferring any files used in the summary to the new course and then removing
the course request and the files associated with it.

return: int The id of the course that was created from this request

reject($notice)   X-Ref
Reject a course request

This function rejects a course request, emailing the requesting user the
provided notice and then removing the request from the database

param: string $notice The message to display to the user

delete()   X-Ref
Deletes the course request and any associated files


notify($touser, $fromuser, $name='courserequested', $subject, $message)   X-Ref
Send a message from one user to another using events_trigger

param: object $touser
param: object $fromuser
param: string $name
param: string $subject
param: string $message

course_page_type_list($pagetype, $parentcontext, $currentcontext)   X-Ref
Return a list of page types

param: string $pagetype current page type
param: context $parentcontext Block's parent context
param: context $currentcontext Current context of block
return: array array of page types

course_ajax_enabled($course)   X-Ref
Determine whether course ajax should be enabled for the specified course

param: stdClass $course The course to test against
return: boolean Whether course ajax is enabled or note

include_course_ajax($course, $usedmodules = array()   X-Ref
Include the relevant javascript and language strings for the resource
toolbox YUI module

param: integer $id The ID of the course being applied to
param: array $usedmodules An array containing the names of the modules in use on the page
param: array $enabledmodules An array containing the names of the enabled (visible) modules on this site
param: stdClass $config An object containing configuration parameters for ajax modules including:
return: bool

get_sorted_course_formats($enabledonly = false)   X-Ref
Returns the sorted list of available course formats, filtered by enabled if necessary

param: bool $enabledonly return only formats that are enabled
return: array array of sorted format names

course_get_url($courseorid, $section = null, $options = array()   X-Ref
The URL to use for the specified course (with section)

param: int|stdClass $courseorid The course to get the section name for (either object or just course id)
param: int|stdClass $section Section object from database or just field course_sections.section
param: array $options options for view URL. At the moment core uses:
return: moodle_url The url of course

create_module($moduleinfo)   X-Ref
Create a module.

It includes:
- capability checks and other checks
- create the module from the module info

param: object $module
return: object the created module info

update_module($moduleinfo)   X-Ref
Update a module.

It includes:
- capability and other checks
- update the module

param: object $module
return: object the updated module info

mod_duplicate_activity($course, $cm, $sr = null)   X-Ref
Duplicate a module on the course for ajax.

param: object $course The course
param: object $cm The course module to duplicate
param: int $sr The section to link back to (used for creating the links)
return: Object containing:

duplicate_module($course, $cm)   X-Ref
Api to duplicate a module.

param: object $course course object.
param: object $cm course module object to be duplicated.
return: cm_info|null cminfo object if we sucessfully duplicated the mod and found the new cm.

compare_activities_by_time_desc($a, $b)   X-Ref
Compare two objects to find out their correct order based on timestamp (to be used by usort).
Sorts by descending order of time.

param: stdClass $a First object
param: stdClass $b Second object
return: int 0,1,-1 representing the order

compare_activities_by_time_asc($a, $b)   X-Ref
Compare two objects to find out their correct order based on timestamp (to be used by usort).
Sorts by ascending order of time.

param: stdClass $a First object
param: stdClass $b Second object
return: int 0,1,-1 representing the order

course_change_visibility($courseid, $show = true)   X-Ref
Changes the visibility of a course.

param: int $courseid The course to change.
param: bool $show True to make it visible, false otherwise.
return: bool

course_change_sortorder_by_one($course, $up)   X-Ref
Changes the course sortorder by one, moving it up or down one in respect to sort order.

param: stdClass|course_in_list $course
param: bool $up If set to true the course will be moved up one. Otherwise down one.
return: bool

course_change_sortorder_after_course($courseorid, $moveaftercourseid)   X-Ref
Changes the sort order of courses in a category so that the first course appears after the second.

param: int|stdClass $courseorid The course to focus on.
param: int $moveaftercourseid The course to shifter after or 0 if you want it to be the first course in the category.
return: bool

Functions that are not part of a class:

make_log_url($module, $url)   X-Ref
No description

build_mnet_logs_array($hostid, $course, $user=0, $date=0, $order="l.time ASC", $limitfrom='', $limitnum='',$modname="", $modid=0, $modaction="", $groupid=0)   X-Ref
No description

build_logs_array($course, $user=0, $date=0, $order="l.time ASC", $limitfrom='', $limitnum='',$modname="", $modid=0, $modaction="", $groupid=0)   X-Ref
No description

print_log($course, $user=0, $date=0, $order="l.time ASC", $page=0, $perpage=100,$url="", $modname="", $modid=0, $modaction="", $groupid=0)   X-Ref
No description

print_mnet_log($hostid, $course, $user=0, $date=0, $order="l.time ASC", $page=0, $perpage=100,$url="", $modname="", $modid=0, $modaction="", $groupid=0)   X-Ref
No description

print_log_csv($course, $user, $date, $order='l.time DESC', $modname,$modid, $modaction, $groupid)   X-Ref
No description

print_log_xls($course, $user, $date, $order='l.time DESC', $modname,$modid, $modaction, $groupid)   X-Ref
No description

print_log_ods($course, $user, $date, $order='l.time DESC', $modname,$modid, $modaction, $groupid)   X-Ref
No description

course_integrity_check($courseid, $rawmods = null, $sections = null, $fullcheck = false, $checkonly = false)   X-Ref
Checks the integrity of the course data.

In summary - compares course_sections.sequence and course_modules.section.

More detailed, checks that:
- course_sections.sequence contains each module id not more than once in the course
- for each moduleid from course_sections.sequence the field course_modules.section
refers to the same section id (this means course_sections.sequence is more
important if they are different)
- ($fullcheck only) each module in the course is present in one of
course_sections.sequence
- ($fullcheck only) removes non-existing course modules from section sequences

If there are any mismatches, the changes are made and records are updated in DB.

Course cache is NOT rebuilt if there are any errors!

This function is used each time when course cache is being rebuilt with $fullcheck = false
and in CLI script admin/cli/fix_course_sequence.php with $fullcheck = true

param: int $courseid id of the course
param: array $rawmods result of funciton {@link get_course_mods()} - containst
param: array $sections records from course_sections table for this course.
param: bool $fullcheck Will add orphaned modules to their sections and remove non-existing
param: bool $checkonly Only performs the check without updating DB, outputs all errors as debug messages.
return: array array of messages with found problems. Empty output means everything is ok

get_array_of_activities($courseid)   X-Ref
For a given course, returns an array of course activity objects
Each item in the array contains he following properties:


get_module_types_names($plural = false)   X-Ref
Returns the localised human-readable names of all used modules

param: bool $plural if true returns the plural forms of the names
return: array where key is the module name (component name without 'mod_') and

course_set_marker($courseid, $marker)   X-Ref
Set highlighted section. Only one section can be highlighted at the time.

param: int $courseid course id
param: int $marker highlight section with this number, 0 means remove higlightin
return: void

set_section_visible($courseid, $sectionnumber, $visibility)   X-Ref
For a given course section, marks it visible or hidden,
and does the same for every activity in that section

param: int $courseid course id
param: int $sectionnumber The section number to adjust
param: int $visibility The new visibility
return: array A list of resources which were hidden in the section

get_module_metadata($course, $modnames, $sectionreturn = null)   X-Ref
Retrieve all metadata for the requested modules

param: object $course The Course
param: array $modnames An array containing the list of modules and their
param: int $sectionreturn The section to return to
return: array A list of stdClass objects containing metadata about each

get_category_or_system_context($categoryid)   X-Ref
Return the course category context for the category with id $categoryid, except
that if $categoryid is 0, return the system context.

param: integer $categoryid a category id or 0.
return: context the corresponding context

make_categories_options()   X-Ref
Returns full course categories trees to be used in html_writer::select()

Calls {@link coursecat::make_categories_list()} to build the tree and
adds whitespace to denote nesting

return: array array mapping coursecat id to the display name

print_course_request_buttons($context)   X-Ref
Print the buttons relating to course requests.

param: object $context current page context.

can_edit_in_category($categoryid = 0)   X-Ref
Does the user have permission to edit things in this category?

param: integer $categoryid The id of the category we are showing, or 0 for system context.
return: boolean has_any_capability(array(...), ...); in the appropriate context.

add_course_module($mod)   X-Ref
No description

course_create_sections_if_missing($courseorid, $sections)   X-Ref
Creates missing course section(s) and rebuilds course cache

param: int|stdClass $courseorid course id or course object
param: int|array $sections list of relative section numbers to create
return: bool if there were any sections created

course_add_cm_to_section($courseorid, $cmid, $sectionnum, $beforemod = null)   X-Ref
Adds an existing module to the section

Updates both tables {course_sections} and {course_modules}

Note: This function does not use modinfo PROVIDED that the section you are
adding the module to already exists. If the section does not exist, it will
build modinfo if necessary and create the section.

param: int|stdClass $courseorid course id or course object
param: int $cmid id of the module already existing in course_modules table
param: int $sectionnum relative number of the section (field course_sections.section)
param: int|stdClass $beforemod id or object with field id corresponding to the module
return: int The course_sections ID where the module is inserted

set_coursemodule_groupmode($id, $groupmode)   X-Ref
Change the group mode of a course module.

Note: Do not forget to trigger the event \core\event\course_module_updated as it needs
to be triggered manually, refer to {@link \core\event\course_module_updated::create_from_cm()}.

param: int $id course module ID.
param: int $groupmode the new groupmode value.
return: bool True if the $groupmode was updated.

set_coursemodule_idnumber($id, $idnumber)   X-Ref
No description

set_coursemodule_visible($id, $visible)   X-Ref
Set the visibility of a module and inherent properties.

Note: Do not forget to trigger the event \core\event\course_module_updated as it needs
to be triggered manually, refer to {@link \core\event\course_module_updated::create_from_cm()}.

From 2.4 the parameter $prevstateoverrides has been removed, the logic it triggered
has been moved to {@link set_section_visible()} which was the only place from which
the parameter was used.

param: int $id of the module
param: int $visible state of the module
return: bool false when the module was not found, true otherwise

course_delete_module($cmid)   X-Ref
This function will handle the whole deletion process of a module. This includes calling
the modules delete_instance function, deleting files, events, grades, conditional data,
the data in the course_module and course_sections table and adding a module deletion
event to the DB.

param: int $cmid the course module id

delete_mod_from_section($modid, $sectionid)   X-Ref
No description

move_section_to($course, $section, $destination)   X-Ref
Moves a section within a course, from a position to another.
Be very careful: $section and $destination refer to section number,
not id!.

param: object $course
param: int $section Section number (not id!!!)
param: int $destination
return: boolean Result

reorder_sections($sections, $origin_position, $target_position)   X-Ref
Reordering algorithm for course sections. Given an array of section->section indexed by section->id,
an original position number and a target position number, rebuilds the array so that the
move is made without any duplication of section positions.
Note: The target_position is the position AFTER WHICH the moved section will be inserted. If you want to
insert a section before the first one, you must give 0 as the target (section 0 can never be moved).

param: array $sections
param: int $origin_position
param: int $target_position
return: array

moveto_module($mod, $section, $beforemod=NULL)   X-Ref
Move the module object $mod to the specified $section
If $beforemod exists then that is the module
before which $modid should be inserted

param: stdClass|cm_info $mod
param: stdClass|section_info $section
param: int|stdClass $beforemod id or object with field id corresponding to the module
return: int new value for module visibility (0 or 1)

course_get_cm_edit_actions(cm_info $mod, $indent = -1, $sr = null)   X-Ref
Returns the list of all editing actions that current user can perform on the module

param: cm_info $mod The module to produce editing buttons for
param: int $indent The current indenting (default -1 means no move left-right actions)
param: int $sr The section to link back to (used for creating the links)
return: array array of action_link or pix_icon objects

course_get_cm_rename_action(cm_info $mod, $sr = null)   X-Ref
Returns the rename action.

param: cm_info $mod The module to produce editing buttons for
param: int $sr The section to link back to (used for creating the links)
return: The markup for the rename action, or an empty string if not available.

course_get_cm_move(cm_info $mod, $sr = null)   X-Ref
Returns the move action.

param: cm_info $mod The module to produce a move button for
param: int $sr The section to link back to (used for creating the links)
return: The markup for the move action, or an empty string if not available.

course_format_name($course,$max=100)   X-Ref
given a course object with shortname & fullname, this function will
truncate the the number of chars allowed and add ... if it was too long


course_allowed_module($course, $modname)   X-Ref
Is the user allowed to add this type of module to this course?

param: object $course the course settings. Only $course->id is used.
param: string $modname the module name. E.g. 'forum' or 'quiz'.
return: bool whether the current user is allowed to add this type of module to this course.

move_courses($courseids, $categoryid)   X-Ref
Efficiently moves many courses around while maintaining
sortorder in order.

param: array $courseids is an array of course ids
param: int $categoryid
return: bool success

get_section_name($courseorid, $section)   X-Ref
Returns the display name of the given section that the course prefers

Implementation of this function is provided by course format
param: int|stdClass $courseorid The course to get the section name for (object or just course id)
param: int|stdClass $section Section object from database or just field course_sections.section
return: string Display name that the course format prefers, e.g. "Week 2"

course_format_uses_sections($format)   X-Ref
Tells if current course format uses sections

param: string $format Course format ID e.g. 'weeks' $course->format
return: bool

course_format_ajax_support($format)   X-Ref
Returns the information about the ajax support in the given source format

The returned object's property (boolean)capable indicates that
the course format supports Moodle course ajax features.

param: string $format
return: stdClass

can_delete_course($courseid)   X-Ref
Can the current user delete this course?
Course creators have exception,
1 day after the creation they can sill delete the course.

param: int $courseid
return: boolean

save_local_role_names($courseid, $data)   X-Ref
Save the Your name for 'Some role' strings.

param: integer $courseid the id of this course.
param: array $data the data that came from the course settings form.

course_overviewfiles_options($course)   X-Ref
Returns options to use in course overviewfiles filemanager

param: null|stdClass|course_in_list|int $course either object that has 'id' property or just the course id;
return: array|null array of options such as maxfiles, maxbytes, accepted_types, etc.

create_course($data, $editoroptions = NULL)   X-Ref
Create a course and either return a $course object

Please note this functions does not verify any access control,
the calling code is responsible for all validation (usually it is the form definition).

param: array $editoroptions course description editor options
param: object $data  - all the data needed for an entry in the 'course' table
return: object new course instance

update_course($data, $editoroptions = NULL)   X-Ref
Update a course.

Please note this functions does not verify any access control,
the calling code is responsible for all validation (usually it is the form definition).

param: object $data  - all the data needed for an entry in the 'course' table
param: array $editoroptions course description editor options
return: void

average_number_of_participants()   X-Ref
Average number of participants

return: integer

average_number_of_courses_modules()   X-Ref
Average number of course modules

return: integer

Search This Site: