Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

External course API

Copyright: 2009 Petr Skodak
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 4507 lines (206 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 1 file
 course/lib.php

Defines 2 classes

core_course_external:: (45 methods):
  get_course_contents_parameters()
  get_course_contents()
  get_course_contents_returns()
  get_courses_parameters()
  get_courses()
  get_courses_returns()
  create_courses_parameters()
  create_courses()
  create_courses_returns()
  update_courses_parameters()
  update_courses()
  update_courses_returns()
  delete_courses_parameters()
  delete_courses()
  delete_courses_returns()
  duplicate_course_parameters()
  duplicate_course()
  duplicate_course_returns()
  import_course_parameters()
  import_course()
  import_course_returns()
  get_categories_parameters()
  get_categories()
  compare_categories_by_path()
  compare_categories_by_sortorder()
  get_categories_returns()
  create_categories_parameters()
  create_categories()
  create_categories_returns()
  update_categories_parameters()
  update_categories()
  update_categories_returns()
  delete_categories_parameters()
  delete_categories()
  delete_categories_returns()
  delete_modules_parameters()
  delete_modules()
  delete_modules_returns()
  view_course_parameters()
  view_course()
  view_course_returns()
  search_courses_parameters()
  get_course_public_information()
  search_courses()
  get_course_structure()

in:: (59 methods):
  search_courses_returns()
  get_course_module_parameters()
  get_course_module()
  get_course_module_returns()
  get_course_module_by_instance_parameters()
  get_course_module_by_instance()
  get_course_module_by_instance_returns()
  get_user_navigation_options_parameters()
  get_user_navigation_options()
  get_user_navigation_options_returns()
  get_user_administration_options_parameters()
  get_user_administration_options()
  get_user_administration_options_returns()
  get_courses_by_field_parameters()
  get_courses_by_field()
  get_courses_by_field_returns()
  check_updates_parameters()
  check_updates()
  check_updates_returns()
  get_updates_since_parameters()
  get_updates_since()
  get_updates_since_returns()
  edit_module_parameters()
  edit_module()
  edit_module_returns()
  get_module_parameters()
  get_module()
  get_module_returns()
  edit_section_parameters()
  edit_section()
  edit_section_returns()
  get_enrolled_courses_by_timeline_classification_parameters()
  get_enrolled_courses_by_timeline_classification()
  get_enrolled_courses_by_timeline_classification_returns()
  set_favourite_courses_parameters()
  set_favourite_courses()
  set_favourite_courses_returns()
  get_recent_courses_parameters()
  get_recent_courses()
  get_recent_courses_returns()
  get_enrolled_users_by_cmid_parameters()
  get_enrolled_users_by_cmid()
  get_enrolled_users_by_cmid_returns()
  user_description()
  add_content_item_to_user_favourites_parameters()
  add_content_item_to_user_favourites()
  add_content_item_to_user_favourites_returns()
  remove_content_item_from_user_favourites_parameters()
  remove_content_item_from_user_favourites()
  remove_content_item_from_user_favourites_returns()
  get_course_content_items_returns()
  get_course_content_items_parameters()
  get_course_content_items()
  toggle_activity_recommendation_parameters()
  toggle_activity_recommendation()
  toggle_activity_recommendation_returns()
  get_activity_chooser_footer_parameters()
  get_activity_chooser_footer()
  get_activity_chooser_footer_returns()


Class: core_course_external  - X-Ref

Course external functions

get_course_contents_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_course_contents($courseid, $options = array()   X-Ref
Get course contents

param: int $courseid course id
param: array $options Options for filtering the results, used since Moodle 2.9
return: array

get_course_contents_returns()   X-Ref
Returns description of method result value

return: external_description

get_courses_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_courses($options = array()   X-Ref
Get courses

param: array $options It contains an array (list of ids)
return: array

get_courses_returns()   X-Ref
Returns description of method result value

return: external_description

create_courses_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

create_courses($courses)   X-Ref
Create  courses

param: array $courses
return: array courses (id and shortname only)

create_courses_returns()   X-Ref
Returns description of method result value

return: external_description

update_courses_parameters()   X-Ref
Update courses

return: external_function_parameters

update_courses($courses)   X-Ref
Update courses

param: array $courses

update_courses_returns()   X-Ref
Returns description of method result value

return: external_description

delete_courses_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

delete_courses($courseids)   X-Ref
Delete courses

param: array $courseids A list of course ids

delete_courses_returns()   X-Ref
Returns description of method result value

return: external_description

duplicate_course_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

duplicate_course($courseid, $fullname, $shortname, $categoryid, $visible = 1, $options = array()   X-Ref
Duplicate a course

param: int $courseid
param: string $fullname Duplicated course fullname
param: string $shortname Duplicated course shortname
param: int $categoryid Duplicated course parent category id
param: int $visible Duplicated course availability
param: array $options List of backup options
return: array New course info

duplicate_course_returns()   X-Ref
Returns description of method result value

return: external_description

import_course_parameters()   X-Ref
Returns description of method parameters for import_course

return: external_function_parameters

import_course($importfrom, $importto, $deletecontent = 0, $options = array()   X-Ref
Imports a course

param: int $importfrom The id of the course we are importing from
param: int $importto The id of the course we are importing to
param: bool $deletecontent Whether to delete the course we are importing to content
param: array $options List of backup options
return: null

import_course_returns()   X-Ref
Returns description of method result value

return: external_description

get_categories_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_categories($criteria = array()   X-Ref
Get categories

param: array $criteria Criteria to match the results
param: booln $addsubcategories obtain only the category (false) or its subcategories (true - default)
return: array list of categories

compare_categories_by_path($category1, $category2)   X-Ref
Sort categories array by path
private function: only used by get_categories

param: array $category1
param: array $category2
return: int result of strcmp

compare_categories_by_sortorder($category1, $category2)   X-Ref
Sort categories array by sortorder
private function: only used by get_categories

param: array $category1
param: array $category2
return: int result of strcmp

get_categories_returns()   X-Ref
Returns description of method result value

return: external_description

create_categories_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

create_categories($categories)   X-Ref
Create categories

param: array $categories - see create_categories_parameters() for the array structure
return: array - see create_categories_returns() for the array structure

create_categories_returns()   X-Ref
Returns description of method parameters

return: external_function_parameters

update_categories_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

update_categories($categories)   X-Ref
Update categories

param: array $categories The list of categories to update
return: null

update_categories_returns()   X-Ref
Returns description of method result value

return: external_description

delete_categories_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

delete_categories($categories)   X-Ref
Delete categories

param: array $categories A list of category ids
return: array

delete_categories_returns()   X-Ref
Returns description of method parameters

return: external_function_parameters

delete_modules_parameters()   X-Ref
Describes the parameters for delete_modules.

return: external_function_parameters

delete_modules($cmids)   X-Ref
Deletes a list of provided module instances.

param: array $cmids the course module ids

delete_modules_returns()   X-Ref
Describes the delete_modules return value.

return: external_single_structure

view_course_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

view_course($courseid, $sectionnumber = 0)   X-Ref
Trigger the course viewed event.

param: int $courseid id of course
param: int $sectionnumber sectionnumber (0, 1, 2...)
return: array of warnings and status result

view_course_returns()   X-Ref
Returns description of method result value

return: external_description

search_courses_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_course_public_information(core_course_list_element $course, $coursecontext)   X-Ref
Return the course information that is public (visible by every one)

param: core_course_list_element $course        course in list object
param: stdClass       $coursecontext course context object
return: array the course information

search_courses($criterianame,$criteriavalue,$page=0,$perpage=0,$requiredcapabilities=array()   X-Ref
Search courses following the specified criteria.

param: string $criterianame  Criteria name (search, modulelist (only admins), blocklist (only admins), tagid)
param: string $criteriavalue Criteria value
param: int $page             Page number (for pagination)
param: int $perpage          Items per page
param: array $requiredcapabilities Optional list of required capabilities (used to filter the list).
param: int $limittoenrolled  Limit to only enrolled courses
param: int onlywithcompletion Limit to only courses where completion is enabled
return: array of course objects and warnings

get_course_structure($onlypublicdata = true)   X-Ref
Returns a course structure definition

param: boolean $onlypublicdata set to true, to retrieve only fields viewable by anyone when the course is visible
return: array the course structure

Class: in  - X-Ref

search_courses_returns()   X-Ref
Returns description of method result value

return: external_description

get_course_module_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_course_module($cmid)   X-Ref
Return information about a course module.

param: int $cmid the course module id
return: array of warnings and the course module

get_course_module_returns()   X-Ref
Returns description of method result value

return: external_description

get_course_module_by_instance_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_course_module_by_instance($module, $instance)   X-Ref
Return information about a course module.

param: string $module the module name
param: int $instance the activity instance id
return: array of warnings and the course module

get_course_module_by_instance_returns()   X-Ref
Returns description of method result value

return: external_description

get_user_navigation_options_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_user_navigation_options($courseids)   X-Ref
Return a list of navigation options in a set of courses that are avaialable or not for the current user.

param: array $courseids a list of course ids
return: array of warnings and the options availability

get_user_navigation_options_returns()   X-Ref
Returns description of method result value

return: external_description

get_user_administration_options_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_user_administration_options($courseids)   X-Ref
Return a list of administration options in a set of courses that are available or not for the current user.

param: array $courseids a list of course ids
return: array of warnings and the options availability

get_user_administration_options_returns()   X-Ref
Returns description of method result value

return: external_description

get_courses_by_field_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_courses_by_field($field = '', $value = '')   X-Ref
Get courses matching a specific field (id/s, shortname, idnumber, category)

param: string $field field name to search, or empty for all courses
param: string $value value to search
return: array list of courses and warnings

get_courses_by_field_returns()   X-Ref
Returns description of method result value

return: external_description

check_updates_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

check_updates($courseid, $tocheck, $filter = array()   X-Ref
Check if there is updates affecting the user for the given course and contexts.
Right now only modules are supported.
This WS calls mod_check_updates_since for each module to check if there is any update the user should we aware of.

param: int $courseid the list of modules to check
param: array $tocheck the list of modules to check
param: array $filter check only for updates in these areas
return: array list of updates and warnings

check_updates_returns()   X-Ref
Returns description of method result value

return: external_description

get_updates_since_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_updates_since($courseid, $since, $filter = array()   X-Ref
Check if there are updates affecting the user for the given course since the given time stamp.

This function is a wrapper of self::check_updates for retrieving all the updates since a given time for all the activities.

param: int $courseid the list of modules to check
param: int $since check updates since this time stamp
param: array $filter check only for updates in these areas
return: array list of updates and warnings

get_updates_since_returns()   X-Ref
Returns description of method result value

return: external_description

edit_module_parameters()   X-Ref
Parameters for function edit_module()

return: external_function_parameters

edit_module($action, $id, $sectionreturn = null)   X-Ref
Performs one of the edit module actions and return new html for AJAX

Returns html to replace the current module html with, for example:
- empty string for "delete" action,
- two modules html for "duplicate" action
- updated module html for everything else

Throws exception if operation is not permitted/possible

param: string $action
param: int $id
param: null|int $sectionreturn
return: string

edit_module_returns()   X-Ref
Return structure for edit_module()

return: external_description

get_module_parameters()   X-Ref
Parameters for function get_module()

return: external_function_parameters

get_module($id, $sectionreturn = null)   X-Ref
Returns html for displaying one activity module on course page

param: int $id
param: null|int $sectionreturn
return: string

get_module_returns()   X-Ref
Return structure for get_module()

return: external_description

edit_section_parameters()   X-Ref
Parameters for function edit_section()

return: external_function_parameters

edit_section($action, $id, $sectionreturn)   X-Ref
Performs one of the edit section actions

param: string $action
param: int $id section id
param: int $sectionreturn section to return to
return: string

edit_section_returns()   X-Ref
Return structure for edit_section()

return: external_description

get_enrolled_courses_by_timeline_classification_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_enrolled_courses_by_timeline_classification(string $classification,int $limit = 0,int $offset = 0,string $sort = null,string $customfieldname = null,string $customfieldvalue = null,string $searchvalue = null)   X-Ref
Get courses matching the given timeline classification.

NOTE: The offset applies to the unfiltered full set of courses before the classification
filtering is done.
E.g.
If the user is enrolled in 5 courses:
c1, c2, c3, c4, and c5
And c4 and c5 are 'future' courses

If a request comes in for future courses with an offset of 1 it will mean that
c1 is skipped (because the offset applies *before* the classification filtering)
and c4 and c5 will be return.

param: string $classification past, inprogress, or future
param: int $limit Result set limit
param: int $offset Offset the full course set before timeline classification is applied
param: string $sort SQL sort string for results
param: string $customfieldname
param: string $customfieldvalue
param: string $searchvalue
return: array list of courses and warnings

get_enrolled_courses_by_timeline_classification_returns()   X-Ref
No description

set_favourite_courses_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

set_favourite_courses(array $courses)   X-Ref
Set the course favourite status for an array of courses.

param: array $courses List with course id's and favourite status.
return: array Array with an array of favourite courses.

set_favourite_courses_returns()   X-Ref
Returns description of method result value

return: external_description

get_recent_courses_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_recent_courses(int $userid = 0, int $limit = 0, int $offset = 0, string $sort = null)   X-Ref
Get last accessed courses adding additional course information like images.

param: int $userid User id from which the courses will be obtained
param: int $limit Restrict result set to this amount
param: int $offset Skip this number of records from the start of the result set
param: string|null $sort SQL string for sorting
return: array List of courses

get_recent_courses_returns()   X-Ref
Returns description of method result value

return: external_description

get_enrolled_users_by_cmid_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_enrolled_users_by_cmid(int $cmid, int $groupid = 0, bool $onlyactive = false)   X-Ref
Get all users in a course for a given cmid.

param: int $cmid Course Module id from which the users will be obtained
param: int $groupid Group id from which the users will be obtained
param: bool $onlyactive Whether to return only the active enrolled users or all enrolled users in the course.
return: array List of users

get_enrolled_users_by_cmid_returns()   X-Ref
Returns description of method result value

return: external_description

user_description()   X-Ref
Create user return value description.

return: external_description

add_content_item_to_user_favourites_parameters()   X-Ref
Returns description of method parameters.

return: external_function_parameters

add_content_item_to_user_favourites(string $componentname, int $contentitemid)   X-Ref
Add a content item to a user's favourites.

param: string $componentname the name of the component from which this content item originates.
param: int $contentitemid the id of the content item.
return: stdClass the exporter content item.

add_content_item_to_user_favourites_returns()   X-Ref
Returns description of method result value.

return: external_description

remove_content_item_from_user_favourites_parameters()   X-Ref
Returns description of method parameters.

return: external_function_parameters

remove_content_item_from_user_favourites(string $componentname, int $contentitemid)   X-Ref
Remove a content item from a user's favourites.

param: string $componentname the name of the component from which this content item originates.
param: int $contentitemid the id of the content item.
return: stdClass the exported content item.

remove_content_item_from_user_favourites_returns()   X-Ref
Returns description of method result value.

return: external_description

get_course_content_items_returns()   X-Ref
Returns description of method result value

return: external_description

get_course_content_items_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_course_content_items(int $courseid)   X-Ref
Given a course ID fetch all accessible modules for that course

param: int $courseid The course we want to fetch the modules for
return: array Contains array of modules and their metadata

toggle_activity_recommendation_parameters()   X-Ref
Returns description of method parameters.

return: external_function_parameters

toggle_activity_recommendation(string $area, int $id)   X-Ref
Update the recommendation for an activity item.

param: string $area identifier for this activity.
param: int $id Associated id. This is needed in conjunction with the area to find the recommendation.
return: array some warnings or something.

toggle_activity_recommendation_returns()   X-Ref
Returns warnings.

return: external_description

get_activity_chooser_footer_parameters()   X-Ref
Returns description of method parameters

return: external_function_parameters

get_activity_chooser_footer(int $courseid, int $sectionid)   X-Ref
Given a course ID we need to build up a footre for the chooser.

param: int $courseid The course we want to fetch the modules for
param: int $sectionid The section we want to fetch the modules for
return: array

get_activity_chooser_footer_returns()   X-Ref
Returns description of method result value

return: external_description