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: 4080 lines (159 kb)
Included or required: 11 times
Referenced: 52 times
Includes or requires: 0 files

Defines 1 class

Defines 31 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.

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

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

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

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

return: mixed
param: string $key

__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

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

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

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

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

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

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

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

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

return: bool
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:

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

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

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

return: moodle_url The url of course
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:

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

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

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

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

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

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

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

return: Object containing:
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)

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

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

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.

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

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.

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

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

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

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.

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

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.

return: bool
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.

course_view($context, $sectionnumber = 0)   X-Ref
Trigger course viewed event. This API function is used when course view actions happens,
usually in course/view.php but also in external functions.

param: stdClass  $context course context object
param: int $sectionnumber section number

course_get_tagged_courses($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0)   X-Ref
Returns courses tagged with a specified tag.

return: \core_tag\output\tagindex
param: core_tag_tag $tag
param: bool $exclusivemode if set to true it means that no other entities tagged with this tag
param: int $fromctx context id where the link was displayed, may be used by callbacks
param: int $ctx context id where to search for records
param: bool $rec search in subcontexts as well
param: int $page 0-based number of page being displayed

core_course_inplace_editable($itemtype, $itemid, $newvalue)   X-Ref
Implements callback inplace_editable() allowing to edit values in-place

return: \core\output\inplace_editable
param: string $itemtype
param: int $itemid
param: mixed $newvalue

course_get_tagged_course_modules($tag, $exclusivemode = false, $fromcontextid = 0, $contextid = 0,$recursivecontext = 1, $page = 0)   X-Ref
Returns course modules tagged with a specified tag ready for output on tag/index.php page

This is a callback used by the tag area core/course_modules to search for course modules
tagged with a specific tag.

return: \core_tag\output\tagindex
param: core_tag_tag $tag
param: bool $exclusivemode if set to true it means that no other entities tagged with this tag
param: int $fromcontextid context id where the link was displayed, may be used by callbacks
param: int $contextid context id where to search for records
param: bool $recursivecontext search in subcontexts as well
param: int $page 0-based number of page being displayed

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

return: array array of messages with found problems. Empty output means everything is ok
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.

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

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

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

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

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

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

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

return: array A list of stdClass objects containing metadata about each
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

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.

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

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?

return: boolean has_any_capability(array(...), ...); in the appropriate context.
param: integer $categoryid The id of the category we are showing, or 0 for system 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

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

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.

return: int The course_sections ID where the module is inserted
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

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

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

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.

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

set_coursemodule_name($id, $name)   X-Ref
Changes the course module name

return: bool whether a change was made
param: int $id course module id
param: string $name new value for a name

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, $ignorenumsections = false)   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!.

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

course_delete_section($course, $section, $forcedeleteifnotempty = true)   X-Ref
This method will delete a course section and may delete all modules inside it.

No permissions are checked here, use {@link course_can_delete_section()} to
check if section can actually be deleted.

return: bool whether section was deleted
param: int|stdClass $course
param: int|stdClass|section_info $section
param: bool $forcedeleteifnotempty if set to false section will not be deleted if it has modules in it.

course_update_section($course, $section, $data)   X-Ref
Updates the course section

This function does not check permissions or clean values - this has to be done prior to calling it.

param: int|stdClass $course
param: stdClass $section record from course_sections table - it will be updated with the new values
param: array|stdClass $data

course_can_delete_section($course, $section)   X-Ref
Checks if the current user can delete a section (if course format allows it and user has proper permissions).

return: bool
param: int|stdClass $course
param: int|stdClass|section_info $section

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

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

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

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

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

return: array array of action_link or pix_icon objects
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)

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

return: The markup for the move action, or an empty string if not available.
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)

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?

return: bool whether the current user is 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'.

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

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

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
return: string Display name that the course format prefers, e.g. "Week 2"
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

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

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

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.

return: stdClass
param: string $format

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.

return: boolean
param: int $courseid

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

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

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

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

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

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

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: