enrol/externallib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * External course participation api.
  20  *
  21  * This api is mostly read only, the actual enrol and unenrol
  22  * support is in each enrol plugin.
  23  *
  24  * @package    core_enrol
  25  * @category   external
  26  * @copyright  2010 Jerome Mouneyrac
  27  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  28  */
  29
  30 defined('MOODLE_INTERNAL') || die();
  31
  32 require_once("$CFG->libdir/externallib.php");
  33
  34 /**
  35  * Enrol external functions
  36  *
  37  * @package    core_enrol
  38  * @category   external
  39  * @copyright  2011 Jerome Mouneyrac
  40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41  * @since Moodle 2.2
  42  */
  43 class core_enrol_external extends external_api {
  44
  45     /**
  46      * Returns description of method parameters
  47      *
  48      * @return external_function_parameters
  49      * @since Moodle 2.4
  50      */
  51     public static function get_enrolled_users_with_capability_parameters() {
  52         return new external_function_parameters(
  53             array (
  54                 'coursecapabilities' => new external_multiple_structure(
  55                     new external_single_structure(
  56                         array (
  57                             'courseid' => new external_value(PARAM_INT, 'Course ID number in the Moodle course table'),
  58                             'capabilities' => new external_multiple_structure(
  59                                 new external_value(PARAM_CAPABILITY, 'Capability name, such as mod/forum:viewdiscussion')),
  60                         )
  61                     )
  62                 , 'course id and associated capability name'),
  63                  'options'  => new external_multiple_structure(
  64                     new external_single_structure(
  65                         array(
  66                             'name'  => new external_value(PARAM_ALPHANUMEXT, 'option name'),
  67                             'value' => new external_value(PARAM_RAW, 'option value')
  68                         )
  69                     ), 'Option names:
  70                             * groupid (integer) return only users in this group id. Requires \'moodle/site:accessallgroups\' .
  71                             * onlyactive (integer) only users with active enrolments. Requires \'moodle/course:enrolreview\' .
  72                             * userfields (\'string, string, ...\') return only the values of these user fields.
  73                             * limitfrom (integer) sql limit from.
  74                             * limitnumber (integer) max number of users per course and capability.', VALUE_DEFAULT, array())
  75             )
  76         );
  77     }
  78
  79     /**
  80      * Return users that have the capabilities for each course specified. For each course and capability specified,
  81      * a list of the users that are enrolled in the course and have that capability are returned.
  82      *
  83      * @param array $coursecapabilities array of course ids and associated capability names {courseid, {capabilities}}
  84      * @return array An array of arrays describing users for each associated courseid and capability
  85      * @since  Moodle 2.4
  86      */
  87     public static function get_enrolled_users_with_capability($coursecapabilities, $options) {
  88         global $CFG, $DB;
  89
  90         require_once($CFG->dirroot . '/course/lib.php');
  91         require_once($CFG->dirroot . "/user/lib.php");
  92
  93         if (empty($coursecapabilities)) {
  94             throw new invalid_parameter_exception('Parameter can not be empty');
  95         }
  96         $params = self::validate_parameters(self::get_enrolled_users_with_capability_parameters(),
  97             array ('coursecapabilities' => $coursecapabilities,  'options'=>$options));
  98         $result = array();
  99         $userlist = array();
 100         $groupid        = 0;
 101         $onlyactive     = false;
 102         $userfields     = array();
 103         $limitfrom = 0;
 104         $limitnumber = 0;
 105         foreach ($params['options'] as $option) {
 106             switch ($option['name']) {
 107                 case 'groupid':
 108                     $groupid = (int)$option['value'];
 109                     break;
 110                 case 'onlyactive':
 111                     $onlyactive = !empty($option['value']);
 112                     break;
 113                 case 'userfields':
 114                     $thefields = explode(',', $option['value']);
 115                     foreach ($thefields as $f) {
 116                         $userfields[] = clean_param($f, PARAM_ALPHANUMEXT);
 117                     }
 118                     break;
 119                 case 'limitfrom' :
 120                     $limitfrom = clean_param($option['value'], PARAM_INT);
 121                     break;
 122                 case 'limitnumber' :
 123                     $limitnumber = clean_param($option['value'], PARAM_INT);
 124                     break;
 125             }
 126         }
 127
 128         foreach ($params['coursecapabilities'] as $coursecapability) {
 129             $courseid = $coursecapability['courseid'];
 130             $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
 131             $coursecontext = context_course::instance($courseid);
 132             if (!$coursecontext) {
 133                 throw new moodle_exception('cannotfindcourse', 'error', '', null,
 134                         'The course id ' . $courseid . ' doesn\'t exist.');
 135             }
 136             if ($courseid == SITEID) {
 137                 $context = context_system::instance();
 138             } else {
 139                 $context = $coursecontext;
 140             }
 141             try {
 142                 self::validate_context($context);
 143             } catch (Exception $e) {
 144                 $exceptionparam = new stdClass();
 145                 $exceptionparam->message = $e->getMessage();
 146                 $exceptionparam->courseid = $params['courseid'];
 147                 throw new moodle_exception(get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
 148             }
 149
 150             course_require_view_participants($context);
 151
 152             // The accessallgroups capability is needed to use this option.
 153             if (!empty($groupid) && groups_is_member($groupid)) {
 154                 require_capability('moodle/site:accessallgroups', $coursecontext);
 155             }
 156             // The course:enrolereview capability is needed to use this option.
 157             if ($onlyactive) {
 158                 require_capability('moodle/course:enrolreview', $coursecontext);
 159             }
 160
 161             // To see the permissions of others role:review capability is required.
 162             require_capability('moodle/role:review', $coursecontext);
 163             foreach ($coursecapability['capabilities'] as $capability) {
 164                 $courseusers['courseid'] = $courseid;
 165                 $courseusers['capability'] = $capability;
 166
 167                 list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $capability, $groupid, $onlyactive);
 168                 $enrolledparams['courseid'] = $courseid;
 169
 170                 $sql = "SELECT u.*, COALESCE(ul.timeaccess, 0) AS lastcourseaccess
 171                           FROM {user} u
 172                      LEFT JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = :courseid)
 173                          WHERE u.id IN ($enrolledsql)
 174                       ORDER BY u.id ASC";
 175
 176                 $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
 177                 $users = array();
 178                 foreach ($enrolledusers as $courseuser) {
 179                     if ($userdetails = user_get_user_details($courseuser, $course, $userfields)) {
 180                         $users[] = $userdetails;
 181                     }
 182                 }
 183                 $enrolledusers->close();
 184                 $courseusers['users'] = $users;
 185                 $result[] = $courseusers;
 186             }
 187         }
 188         return $result;
 189     }
 190
 191     /**
 192      * Returns description of method result value
 193      *
 194      * @return external_multiple_structure
 195      * @since Moodle 2.4
 196      */
 197     public static function get_enrolled_users_with_capability_returns() {
 198         return  new external_multiple_structure( new external_single_structure (
 199                 array (
 200                     'courseid' => new external_value(PARAM_INT, 'Course ID number in the Moodle course table'),
 201                     'capability' => new external_value(PARAM_CAPABILITY, 'Capability name'),
 202                     'users' => new external_multiple_structure(
 203                         new external_single_structure(
 204                 array(
 205                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 206                     'username'    => new external_value(PARAM_RAW, 'Username', VALUE_OPTIONAL),
 207                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 208                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 209                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 210                     'email'       => new external_value(PARAM_TEXT, 'Email address', VALUE_OPTIONAL),
 211                     'address'     => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
 212                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 213                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 214                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 215                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 216                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 217                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 218                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 219                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 220                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 221                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 222                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 223                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 224                     'lastcourseaccess'  => new external_value(PARAM_INT, 'last access to the course (0 if never)', VALUE_OPTIONAL),
 225                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 226                     'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
 227                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 228                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 229                     'country'     => new external_value(PARAM_ALPHA, 'Country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 230                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small', VALUE_OPTIONAL),
 231                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big', VALUE_OPTIONAL),
 232                     'customfields' => new external_multiple_structure(
 233                         new external_single_structure(
 234                             array(
 235                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field'),
 236                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 237                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 238                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field'),
 239                             )
 240                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 241                     'groups' => new external_multiple_structure(
 242                         new external_single_structure(
 243                             array(
 244                                 'id'  => new external_value(PARAM_INT, 'group id'),
 245                                 'name' => new external_value(PARAM_RAW, 'group name'),
 246                                 'description' => new external_value(PARAM_RAW, 'group description'),
 247                             )
 248                         ), 'user groups', VALUE_OPTIONAL),
 249                     'roles' => new external_multiple_structure(
 250                         new external_single_structure(
 251                             array(
 252                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 253                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 254                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 255                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 256                             )
 257                         ), 'user roles', VALUE_OPTIONAL),
 258                     'preferences' => new external_multiple_structure(
 259                         new external_single_structure(
 260                             array(
 261                                 'name'  => new external_value(PARAM_RAW, 'The name of the preferences'),
 262                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 263                             )
 264                     ), 'User preferences', VALUE_OPTIONAL),
 265                     'enrolledcourses' => new external_multiple_structure(
 266                         new external_single_structure(
 267                             array(
 268                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 269                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 270                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 271                             )
 272                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 273                 )
 274                         ), 'List of users that are enrolled in the course and have the specified capability'),
 275                     )
 276                 )
 277             );
 278     }
 279
 280     /**
 281      * Returns description of method parameters
 282      *
 283      * @return external_function_parameters
 284      */
 285     public static function get_users_courses_parameters() {
 286         return new external_function_parameters(
 287             array(
 288                 'userid' => new external_value(PARAM_INT, 'user id'),
 289                 'returnusercount' => new external_value(PARAM_BOOL,
 290                         'Include count of enrolled users for each course? This can add several seconds to the response time'
 291                             . ' if a user is on several large courses, so set this to false if the value will not be used to'
 292                             . ' improve performance.',
 293                         VALUE_DEFAULT, true),
 294             )
 295         );
 296     }
 297
 298     /**
 299      * Get list of courses user is enrolled in (only active enrolments are returned).
 300      * Please note the current user must be able to access the course, otherwise the course is not included.
 301      *
 302      * @param int $userid
 303      * @param bool $returnusercount
 304      * @return array of courses
 305      */
 306     public static function get_users_courses($userid, $returnusercount = true) {
 307         global $CFG, $USER, $DB;
 308
 309         require_once($CFG->dirroot . '/course/lib.php');
 310         require_once($CFG->libdir . '/completionlib.php');
 311
 312         // Do basic automatic PARAM checks on incoming data, using params description
 313         // If any problems are found then exceptions are thrown with helpful error messages
 314         $params = self::validate_parameters(self::get_users_courses_parameters(),
 315                 ['userid' => $userid, 'returnusercount' => $returnusercount]);
 316         $userid = $params['userid'];
 317         $returnusercount = $params['returnusercount'];
 318
 319         $courses = enrol_get_users_courses($userid, true, '*');
 320         $result = array();
 321
 322         // Get user data including last access to courses.
 323         $user = get_complete_user_data('id', $userid);
 324         $sameuser = $USER->id == $userid;
 325
 326         // Retrieve favourited courses (starred).
 327         $favouritecourseids = array();
 328         if ($sameuser) {
 329             $ufservice = \core_favourites\service_factory::get_service_for_user_context(\context_user::instance($userid));
 330             $favourites = $ufservice->find_favourites_by_type('core_course', 'courses');
 331
 332             if ($favourites) {
 333                 $favouritecourseids = array_flip(array_map(
 334                     function($favourite) {
 335                         return $favourite->itemid;
 336                     }, $favourites));
 337             }
 338         }
 339
 340         foreach ($courses as $course) {
 341             $context = context_course::instance($course->id, IGNORE_MISSING);
 342             try {
 343                 self::validate_context($context);
 344             } catch (Exception $e) {
 345                 // current user can not access this course, sorry we can not disclose who is enrolled in this course!
 346                 continue;
 347             }
 348
 349             if (!$sameuser and !course_can_view_participants($context)) {
 350                 // we need capability to view participants
 351                 continue;
 352             }
 353
 354             if ($returnusercount) {
 355                 list($enrolledsqlselect, $enrolledparams) = get_enrolled_sql($context);
 356                 $enrolledsql = "SELECT COUNT('x') FROM ($enrolledsqlselect) enrolleduserids";
 357                 $enrolledusercount = $DB->count_records_sql($enrolledsql, $enrolledparams);
 358             }
 359
 360             $displayname = external_format_string(get_course_display_name_for_list($course), $context->id);
 361             list($course->summary, $course->summaryformat) =
 362                 external_format_text($course->summary, $course->summaryformat, $context->id, 'course', 'summary', null);
 363             $course->fullname = external_format_string($course->fullname, $context->id);
 364             $course->shortname = external_format_string($course->shortname, $context->id);
 365
 366             $progress = null;
 367             $completed = null;
 368             $completionhascriteria = false;
 369             $completionusertracked = false;
 370
 371             // Return only private information if the user should be able to see it.
 372             if ($sameuser || completion_can_view_data($userid, $course)) {
 373                 if ($course->enablecompletion) {
 374                     $completion = new completion_info($course);
 375                     $completed = $completion->is_course_complete($userid);
 376                     $completionhascriteria = $completion->has_criteria();
 377                     $completionusertracked = $completion->is_tracked_user($userid);
 378                     $progress = \core_completion\progress::get_course_progress_percentage($course, $userid);
 379                 }
 380             }
 381
 382             $lastaccess = null;
 383             // Check if last access is a hidden field.
 384             $hiddenfields = array_flip(explode(',', $CFG->hiddenuserfields));
 385             $canviewlastaccess = $sameuser || !isset($hiddenfields['lastaccess']);
 386             if (!$canviewlastaccess) {
 387                 $canviewlastaccess = has_capability('moodle/course:viewhiddenuserfields', $context);
 388             }
 389
 390             if ($canviewlastaccess && isset($user->lastcourseaccess[$course->id])) {
 391                 $lastaccess = $user->lastcourseaccess[$course->id];
 392             }
 393
 394             $hidden = false;
 395             if ($sameuser) {
 396                 $hidden = boolval(get_user_preferences('block_myoverview_hidden_course_' . $course->id, 0));
 397             }
 398
 399             // Retrieve course overview used files.
 400             $courselist = new core_course_list_element($course);
 401             $overviewfiles = array();
 402             foreach ($courselist->get_course_overviewfiles() as $file) {
 403                 $fileurl = moodle_url::make_webservice_pluginfile_url($file->get_contextid(), $file->get_component(),
 404                                                                         $file->get_filearea(), null, $file->get_filepath(),
 405                                                                         $file->get_filename())->out(false);
 406                 $overviewfiles[] = array(
 407                     'filename' => $file->get_filename(),
 408                     'fileurl' => $fileurl,
 409                     'filesize' => $file->get_filesize(),
 410                     'filepath' => $file->get_filepath(),
 411                     'mimetype' => $file->get_mimetype(),
 412                     'timemodified' => $file->get_timemodified(),
 413                 );
 414             }
 415
 416             $courseresult = [
 417                 'id' => $course->id,
 418                 'shortname' => $course->shortname,
 419                 'fullname' => $course->fullname,
 420                 'displayname' => $displayname,
 421                 'idnumber' => $course->idnumber,
 422                 'visible' => $course->visible,
 423                 'summary' => $course->summary,
 424                 'summaryformat' => $course->summaryformat,
 425                 'format' => $course->format,
 426                 'showgrades' => $course->showgrades,
 427                 'lang' => clean_param($course->lang, PARAM_LANG),
 428                 'enablecompletion' => $course->enablecompletion,
 429                 'completionhascriteria' => $completionhascriteria,
 430                 'completionusertracked' => $completionusertracked,
 431                 'category' => $course->category,
 432                 'progress' => $progress,
 433                 'completed' => $completed,
 434                 'startdate' => $course->startdate,
 435                 'enddate' => $course->enddate,
 436                 'marker' => $course->marker,
 437                 'lastaccess' => $lastaccess,
 438                 'isfavourite' => isset($favouritecourseids[$course->id]),
 439                 'hidden' => $hidden,
 440                 'overviewfiles' => $overviewfiles,
 441             ];
 442             if ($returnusercount) {
 443                 $courseresult['enrolledusercount'] = $enrolledusercount;
 444             }
 445             $result[] = $courseresult;
 446         }
 447
 448         return $result;
 449     }
 450
 451     /**
 452      * Returns description of method result value
 453      *
 454      * @return external_description
 455      */
 456     public static function get_users_courses_returns() {
 457         return new external_multiple_structure(
 458             new external_single_structure(
 459                 array(
 460                     'id'        => new external_value(PARAM_INT, 'id of course'),
 461                     'shortname' => new external_value(PARAM_RAW, 'short name of course'),
 462                     'fullname'  => new external_value(PARAM_RAW, 'long name of course'),
 463                     'displayname' => new external_value(PARAM_RAW, 'course display name for lists.', VALUE_OPTIONAL),
 464                     'enrolledusercount' => new external_value(PARAM_INT, 'Number of enrolled users in this course',
 465                             VALUE_OPTIONAL),
 466                     'idnumber'  => new external_value(PARAM_RAW, 'id number of course'),
 467                     'visible'   => new external_value(PARAM_INT, '1 means visible, 0 means not yet visible course'),
 468                     'summary'   => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 469                     'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL),
 470                     'format'    => new external_value(PARAM_PLUGIN, 'course format: weeks, topics, social, site', VALUE_OPTIONAL),
 471                     'showgrades' => new external_value(PARAM_BOOL, 'true if grades are shown, otherwise false', VALUE_OPTIONAL),
 472                     'lang'      => new external_value(PARAM_LANG, 'forced course language', VALUE_OPTIONAL),
 473                     'enablecompletion' => new external_value(PARAM_BOOL, 'true if completion is enabled, otherwise false',
 474                                                                 VALUE_OPTIONAL),
 475                     'completionhascriteria' => new external_value(PARAM_BOOL, 'If completion criteria is set.', VALUE_OPTIONAL),
 476                     'completionusertracked' => new external_value(PARAM_BOOL, 'If the user is completion tracked.', VALUE_OPTIONAL),
 477                     'category' => new external_value(PARAM_INT, 'course category id', VALUE_OPTIONAL),
 478                     'progress' => new external_value(PARAM_FLOAT, 'Progress percentage', VALUE_OPTIONAL),
 479                     'completed' => new external_value(PARAM_BOOL, 'Whether the course is completed.', VALUE_OPTIONAL),
 480                     'startdate' => new external_value(PARAM_INT, 'Timestamp when the course start', VALUE_OPTIONAL),
 481                     'enddate' => new external_value(PARAM_INT, 'Timestamp when the course end', VALUE_OPTIONAL),
 482                     'marker' => new external_value(PARAM_INT, 'Course section marker.', VALUE_OPTIONAL),
 483                     'lastaccess' => new external_value(PARAM_INT, 'Last access to the course (timestamp).', VALUE_OPTIONAL),
 484                     'isfavourite' => new external_value(PARAM_BOOL, 'If the user marked this course a favourite.', VALUE_OPTIONAL),
 485                     'hidden' => new external_value(PARAM_BOOL, 'If the user hide the course from the dashboard.', VALUE_OPTIONAL),
 486                     'overviewfiles' => new external_files('Overview files attached to this course.', VALUE_OPTIONAL),
 487                 )
 488             )
 489         );
 490     }
 491
 492     /**
 493      * Returns description of method parameters value
 494      *
 495      * @return external_description
 496      */
 497     public static function get_potential_users_parameters() {
 498         return new external_function_parameters(
 499             array(
 500                 'courseid' => new external_value(PARAM_INT, 'course id'),
 501                 'enrolid' => new external_value(PARAM_INT, 'enrolment id'),
 502                 'search' => new external_value(PARAM_RAW, 'query'),
 503                 'searchanywhere' => new external_value(PARAM_BOOL, 'find a match anywhere, or only at the beginning'),
 504                 'page' => new external_value(PARAM_INT, 'Page number'),
 505                 'perpage' => new external_value(PARAM_INT, 'Number per page'),
 506             )
 507         );
 508     }
 509
 510     /**
 511      * Get potential users.
 512      *
 513      * @param int $courseid Course id
 514      * @param int $enrolid Enrolment id
 515      * @param string $search The query
 516      * @param boolean $searchanywhere Match anywhere in the string
 517      * @param int $page Page number
 518      * @param int $perpage Max per page
 519      * @return array An array of users
 520      */
 521     public static function get_potential_users($courseid, $enrolid, $search, $searchanywhere, $page, $perpage) {
 522         global $PAGE, $DB, $CFG;
 523
 524         require_once($CFG->dirroot.'/enrol/locallib.php');
 525         require_once($CFG->dirroot.'/user/lib.php');
 526
 527         $params = self::validate_parameters(
 528             self::get_potential_users_parameters(),
 529             array(
 530                 'courseid' => $courseid,
 531                 'enrolid' => $enrolid,
 532                 'search' => $search,
 533                 'searchanywhere' => $searchanywhere,
 534                 'page' => $page,
 535                 'perpage' => $perpage
 536             )
 537         );
 538         $context = context_course::instance($params['courseid']);
 539         try {
 540             self::validate_context($context);
 541         } catch (Exception $e) {
 542             $exceptionparam = new stdClass();
 543             $exceptionparam->message = $e->getMessage();
 544             $exceptionparam->courseid = $params['courseid'];
 545             throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 546         }
 547         require_capability('moodle/course:enrolreview', $context);
 548
 549         $course = $DB->get_record('course', array('id' => $params['courseid']));
 550         $manager = new course_enrolment_manager($PAGE, $course);
 551
 552         $users = $manager->get_potential_users($params['enrolid'],
 553                                                $params['search'],
 554                                                $params['searchanywhere'],
 555                                                $params['page'],
 556                                                $params['perpage']);
 557
 558         $results = array();
 559         // Add also extra user fields.
 560         $requiredfields = array_merge(
 561             ['id', 'fullname', 'profileimageurl', 'profileimageurlsmall'],
 562             get_extra_user_fields($context)
 563         );
 564         foreach ($users['users'] as $id => $user) {
 565             // Note: We pass the course here to validate that the current user can at least view user details in this course.
 566             // The user we are looking at is not in this course yet though - but we only fetch the minimal set of
 567             // user records, and the user has been validated to have course:enrolreview in this course. Otherwise
 568             // there is no way to find users who aren't in the course in order to enrol them.
 569             if ($userdetails = user_get_user_details($user, $course, $requiredfields)) {
 570                 $results[] = $userdetails;
 571             }
 572         }
 573         return $results;
 574     }
 575
 576     /**
 577      * Returns description of method result value
 578      *
 579      * @return external_description
 580      */
 581     public static function get_potential_users_returns() {
 582         global $CFG;
 583         require_once($CFG->dirroot . '/user/externallib.php');
 584         return new external_multiple_structure(core_user_external::user_description());
 585     }
 586
 587     /**
 588      * Returns description of method parameters
 589      *
 590      * @return external_function_parameters
 591      */
 592     public static function search_users_parameters(): external_function_parameters {
 593         return new external_function_parameters(
 594             [
 595                 'courseid' => new external_value(PARAM_INT, 'course id'),
 596                 'search' => new external_value(PARAM_RAW, 'query'),
 597                 'searchanywhere' => new external_value(PARAM_BOOL, 'find a match anywhere, or only at the beginning'),
 598                 'page' => new external_value(PARAM_INT, 'Page number'),
 599                 'perpage' => new external_value(PARAM_INT, 'Number per page'),
 600             ]
 601         );
 602     }
 603
 604     /**
 605      * Search course participants.
 606      *
 607      * @param int $courseid Course id
 608      * @param string $search The query
 609      * @param bool $searchanywhere Match anywhere in the string
 610      * @param int $page Page number
 611      * @param int $perpage Max per page
 612      * @return array An array of users
 613      * @throws moodle_exception
 614      */
 615     public static function search_users(int $courseid, string $search, bool $searchanywhere, int $page, int $perpage): array {
 616         global $PAGE, $DB, $CFG;
 617
 618         require_once($CFG->dirroot.'/enrol/locallib.php');
 619         require_once($CFG->dirroot.'/user/lib.php');
 620
 621         $params = self::validate_parameters(
 622                 self::search_users_parameters(),
 623                 [
 624                     'courseid'       => $courseid,
 625                     'search'         => $search,
 626                     'searchanywhere' => $searchanywhere,
 627                     'page'           => $page,
 628                     'perpage'        => $perpage
 629                 ]
 630         );
 631         $context = context_course::instance($params['courseid']);
 632         try {
 633             self::validate_context($context);
 634         } catch (Exception $e) {
 635             $exceptionparam = new stdClass();
 636             $exceptionparam->message = $e->getMessage();
 637             $exceptionparam->courseid = $params['courseid'];
 638             throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 639         }
 640         course_require_view_participants($context);
 641
 642         $course = get_course($params['courseid']);
 643         $manager = new course_enrolment_manager($PAGE, $course);
 644
 645         $users = $manager->search_users($params['search'],
 646                                         $params['searchanywhere'],
 647                                         $params['page'],
 648                                         $params['perpage']);
 649
 650         $results = [];
 651         // Add also extra user fields.
 652         $requiredfields = array_merge(
 653                 ['id', 'fullname', 'profileimageurl', 'profileimageurlsmall'],
 654                 get_extra_user_fields($context)
 655         );
 656         foreach ($users['users'] as $user) {
 657             if ($userdetails = user_get_user_details($user, $course, $requiredfields)) {
 658                 $results[] = $userdetails;
 659             }
 660         }
 661         return $results;
 662     }
 663
 664     /**
 665      * Returns description of method result value
 666      *
 667      * @return external_multiple_structure
 668      */
 669     public static function search_users_returns(): external_multiple_structure {
 670         global $CFG;
 671         require_once($CFG->dirroot . '/user/externallib.php');
 672         return new external_multiple_structure(core_user_external::user_description());
 673     }
 674
 675     /**
 676      * Returns description of method parameters
 677      *
 678      * @return external_function_parameters
 679      */
 680     public static function get_enrolled_users_parameters() {
 681         return new external_function_parameters(
 682             array(
 683                 'courseid' => new external_value(PARAM_INT, 'course id'),
 684                 'options'  => new external_multiple_structure(
 685                     new external_single_structure(
 686                         array(
 687                             'name'  => new external_value(PARAM_ALPHANUMEXT, 'option name'),
 688                             'value' => new external_value(PARAM_RAW, 'option value')
 689                         )
 690                     ), 'Option names:
 691                             * withcapability (string) return only users with this capability. This option requires \'moodle/role:review\' on the course context.
 692                             * groupid (integer) return only users in this group id. If the course has groups enabled and this param
 693                                                 isn\'t defined, returns all the viewable users.
 694                                                 This option requires \'moodle/site:accessallgroups\' on the course context if the
 695                                                 user doesn\'t belong to the group.
 696                             * onlyactive (integer) return only users with active enrolments and matching time restrictions. This option requires \'moodle/course:enrolreview\' on the course context.
 697                             * userfields (\'string, string, ...\') return only the values of these user fields.
 698                             * limitfrom (integer) sql limit from.
 699                             * limitnumber (integer) maximum number of returned users.
 700                             * sortby (string) sort by id, firstname or lastname. For ordering like the site does, use siteorder.
 701                             * sortdirection (string) ASC or DESC',
 702                             VALUE_DEFAULT, array()),
 703             )
 704         );
 705     }
 706
 707     /**
 708      * Get course participants details
 709      *
 710      * @param int $courseid  course id
 711      * @param array $options options {
 712      *                                'name' => option name
 713      *                                'value' => option value
 714      *                               }
 715      * @return array An array of users
 716      */
 717     public static function get_enrolled_users($courseid, $options = array()) {
 718         global $CFG, $USER, $DB;
 719
 720         require_once($CFG->dirroot . '/course/lib.php');
 721         require_once($CFG->dirroot . "/user/lib.php");
 722
 723         $params = self::validate_parameters(
 724             self::get_enrolled_users_parameters(),
 725             array(
 726                 'courseid'=>$courseid,
 727                 'options'=>$options
 728             )
 729         );
 730         $withcapability = '';
 731         $groupid        = 0;
 732         $onlyactive     = false;
 733         $userfields     = array();
 734         $limitfrom = 0;
 735         $limitnumber = 0;
 736         $sortby = 'us.id';
 737         $sortparams = array();
 738         $sortdirection = 'ASC';
 739         foreach ($options as $option) {
 740             switch ($option['name']) {
 741             case 'withcapability':
 742                 $withcapability = $option['value'];
 743                 break;
 744             case 'groupid':
 745                 $groupid = (int)$option['value'];
 746                 break;
 747             case 'onlyactive':
 748                 $onlyactive = !empty($option['value']);
 749                 break;
 750             case 'userfields':
 751                 $thefields = explode(',', $option['value']);
 752                 foreach ($thefields as $f) {
 753                     $userfields[] = clean_param($f, PARAM_ALPHANUMEXT);
 754                 }
 755                 break;
 756             case 'limitfrom' :
 757                 $limitfrom = clean_param($option['value'], PARAM_INT);
 758                 break;
 759             case 'limitnumber' :
 760                 $limitnumber = clean_param($option['value'], PARAM_INT);
 761                 break;
 762             case 'sortby':
 763                 $sortallowedvalues = array('id', 'firstname', 'lastname', 'siteorder');
 764                 if (!in_array($option['value'], $sortallowedvalues)) {
 765                     throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $option['value'] . '),' .
 766                         'allowed values are: ' . implode(',', $sortallowedvalues));
 767                 }
 768                 if ($option['value'] == 'siteorder') {
 769                     list($sortby, $sortparams) = users_order_by_sql('us');
 770                 } else {
 771                     $sortby = 'us.' . $option['value'];
 772                 }
 773                 break;
 774             case 'sortdirection':
 775                 $sortdirection = strtoupper($option['value']);
 776                 $directionallowedvalues = array('ASC', 'DESC');
 777                 if (!in_array($sortdirection, $directionallowedvalues)) {
 778                     throw new invalid_parameter_exception('Invalid value for sortdirection parameter
 779                         (value: ' . $sortdirection . '),' . 'allowed values are: ' . implode(',', $directionallowedvalues));
 780                 }
 781                 break;
 782             }
 783         }
 784
 785         $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
 786         $coursecontext = context_course::instance($courseid, IGNORE_MISSING);
 787         if ($courseid == SITEID) {
 788             $context = context_system::instance();
 789         } else {
 790             $context = $coursecontext;
 791         }
 792         try {
 793             self::validate_context($context);
 794         } catch (Exception $e) {
 795             $exceptionparam = new stdClass();
 796             $exceptionparam->message = $e->getMessage();
 797             $exceptionparam->courseid = $params['courseid'];
 798             throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 799         }
 800
 801         course_require_view_participants($context);
 802
 803         // to overwrite this parameter, you need role:review capability
 804         if ($withcapability) {
 805             require_capability('moodle/role:review', $coursecontext);
 806         }
 807         // need accessallgroups capability if you want to overwrite this option
 808         if (!empty($groupid) && !groups_is_member($groupid)) {
 809             require_capability('moodle/site:accessallgroups', $coursecontext);
 810         }
 811         // to overwrite this option, you need course:enrolereview permission
 812         if ($onlyactive) {
 813             require_capability('moodle/course:enrolreview', $coursecontext);
 814         }
 815
 816         list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
 817         $ctxselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 818         $ctxjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)";
 819         $enrolledparams['contextlevel'] = CONTEXT_USER;
 820
 821         $groupjoin = '';
 822         if (empty($groupid) && groups_get_course_groupmode($course) == SEPARATEGROUPS &&
 823                 !has_capability('moodle/site:accessallgroups', $coursecontext)) {
 824             // Filter by groups the user can view.
 825             $usergroups = groups_get_user_groups($course->id);
 826             if (!empty($usergroups['0'])) {
 827                 list($groupsql, $groupparams) = $DB->get_in_or_equal($usergroups['0'], SQL_PARAMS_NAMED);
 828                 $groupjoin = "JOIN {groups_members} gm ON (u.id = gm.userid AND gm.groupid $groupsql)";
 829                 $enrolledparams = array_merge($enrolledparams, $groupparams);
 830             } else {
 831                 // User doesn't belong to any group, so he can't see any user. Return an empty array.
 832                 return array();
 833             }
 834         }
 835         $sql = "SELECT us.*, COALESCE(ul.timeaccess, 0) AS lastcourseaccess
 836                   FROM {user} us
 837                   JOIN (
 838                       SELECT DISTINCT u.id $ctxselect
 839                         FROM {user} u $ctxjoin $groupjoin
 840                        WHERE u.id IN ($enrolledsql)
 841                   ) q ON q.id = us.id
 842              LEFT JOIN {user_lastaccess} ul ON (ul.userid = us.id AND ul.courseid = :courseid)
 843                 ORDER BY $sortby $sortdirection";
 844         $enrolledparams = array_merge($enrolledparams, $sortparams);
 845         $enrolledparams['courseid'] = $courseid;
 846
 847         $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
 848         $users = array();
 849         foreach ($enrolledusers as $user) {
 850             context_helper::preload_from_record($user);
 851             if ($userdetails = user_get_user_details($user, $course, $userfields)) {
 852                 $users[] = $userdetails;
 853             }
 854         }
 855         $enrolledusers->close();
 856
 857         return $users;
 858     }
 859
 860     /**
 861      * Returns description of method result value
 862      *
 863      * @return external_description
 864      */
 865     public static function get_enrolled_users_returns() {
 866         return new external_multiple_structure(
 867             new external_single_structure(
 868                 array(
 869                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 870                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 871                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 872                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 873                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 874                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 875                     'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
 876                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 877                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 878                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 879                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 880                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 881                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 882                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 883                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 884                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 885                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 886                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 887                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 888                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 889                     'lastcourseaccess'  => new external_value(PARAM_INT, 'last access to the course (0 if never)', VALUE_OPTIONAL),
 890                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 891                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 892                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 893                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 894                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 895                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version', VALUE_OPTIONAL),
 896                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version', VALUE_OPTIONAL),
 897                     'customfields' => new external_multiple_structure(
 898                         new external_single_structure(
 899                             array(
 900                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 901                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 902                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 903                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 904                             )
 905                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 906                     'groups' => new external_multiple_structure(
 907                         new external_single_structure(
 908                             array(
 909                                 'id'  => new external_value(PARAM_INT, 'group id'),
 910                                 'name' => new external_value(PARAM_RAW, 'group name'),
 911                                 'description' => new external_value(PARAM_RAW, 'group description'),
 912                                 'descriptionformat' => new external_format_value('description'),
 913                             )
 914                         ), 'user groups', VALUE_OPTIONAL),
 915                     'roles' => new external_multiple_structure(
 916                         new external_single_structure(
 917                             array(
 918                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 919                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 920                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 921                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 922                             )
 923                         ), 'user roles', VALUE_OPTIONAL),
 924                     'preferences' => new external_multiple_structure(
 925                         new external_single_structure(
 926                             array(
 927                                 'name'  => new external_value(PARAM_RAW, 'The name of the preferences'),
 928                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 929                             )
 930                     ), 'User preferences', VALUE_OPTIONAL),
 931                     'enrolledcourses' => new external_multiple_structure(
 932                         new external_single_structure(
 933                             array(
 934                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 935                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 936                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 937                             )
 938                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 939                 )
 940             )
 941         );
 942     }
 943
 944     /**
 945      * Returns description of get_course_enrolment_methods() parameters
 946      *
 947      * @return external_function_parameters
 948      */
 949     public static function get_course_enrolment_methods_parameters() {
 950         return new external_function_parameters(
 951             array(
 952                 'courseid' => new external_value(PARAM_INT, 'Course id')
 953             )
 954         );
 955     }
 956
 957     /**
 958      * Get list of active course enrolment methods for current user.
 959      *
 960      * @param int $courseid
 961      * @return array of course enrolment methods
 962      * @throws moodle_exception
 963      */
 964     public static function get_course_enrolment_methods($courseid) {
 965         global $DB;
 966
 967         $params = self::validate_parameters(self::get_course_enrolment_methods_parameters(), array('courseid' => $courseid));
 968         self::validate_context(context_system::instance());
 969
 970         $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
 971         if (!core_course_category::can_view_course_info($course) && !can_access_course($course)) {
 972             throw new moodle_exception('coursehidden');
 973         }
 974
 975         $result = array();
 976         $enrolinstances = enrol_get_instances($params['courseid'], true);
 977         foreach ($enrolinstances as $enrolinstance) {
 978             if ($enrolplugin = enrol_get_plugin($enrolinstance->enrol)) {
 979                 if ($instanceinfo = $enrolplugin->get_enrol_info($enrolinstance)) {
 980                     $result[] = (array) $instanceinfo;
 981                 }
 982             }
 983         }
 984         return $result;
 985     }
 986
 987     /**
 988      * Returns description of get_course_enrolment_methods() result value
 989      *
 990      * @return external_description
 991      */
 992     public static function get_course_enrolment_methods_returns() {
 993         return new external_multiple_structure(
 994             new external_single_structure(
 995                 array(
 996                     'id' => new external_value(PARAM_INT, 'id of course enrolment instance'),
 997                     'courseid' => new external_value(PARAM_INT, 'id of course'),
 998                     'type' => new external_value(PARAM_PLUGIN, 'type of enrolment plugin'),
 999                     'name' => new external_value(PARAM_RAW, 'name of enrolment plugin'),
1000                     'status' => new external_value(PARAM_RAW, 'status of enrolment plugin'),
1001                     'wsfunction' => new external_value(PARAM_ALPHANUMEXT, 'webservice function to get more information', VALUE_OPTIONAL),
1002                 )
1003             )
1004         );
1005     }
1006
1007     /**
1008      * Returns description of edit_user_enrolment() parameters
1009      *
1010      * @deprecated since 3.8
1011      * @return external_function_parameters
1012      */
1013     public static function edit_user_enrolment_parameters() {
1014         return new external_function_parameters(
1015             array(
1016                 'courseid' => new external_value(PARAM_INT, 'User enrolment ID'),
1017                 'ueid' => new external_value(PARAM_INT, 'User enrolment ID'),
1018                 'status' => new external_value(PARAM_INT, 'Enrolment status'),
1019                 'timestart' => new external_value(PARAM_INT, 'Enrolment start timestamp', VALUE_DEFAULT, 0),
1020                 'timeend' => new external_value(PARAM_INT, 'Enrolment end timestamp', VALUE_DEFAULT, 0),
1021             )
1022         );
1023     }
1024
1025     /**
1026      * External function that updates a given user enrolment.
1027      *
1028      * @deprecated since 3.8
1029      * @param int $courseid The course ID.
1030      * @param int $ueid The user enrolment ID.
1031      * @param int $status The enrolment status.
1032      * @param int $timestart Enrolment start timestamp.
1033      * @param int $timeend Enrolment end timestamp.
1034      * @return array An array consisting of the processing result, errors and form output, if available.
1035      */
1036     public static function edit_user_enrolment($courseid, $ueid, $status, $timestart = 0, $timeend = 0) {
1037         global $CFG, $DB, $PAGE;
1038
1039         $params = self::validate_parameters(self::edit_user_enrolment_parameters(), [
1040             'courseid' => $courseid,
1041             'ueid' => $ueid,
1042             'status' => $status,
1043             'timestart' => $timestart,
1044             'timeend' => $timeend,
1045         ]);
1046
1047         $course = get_course($courseid);
1048         $context = context_course::instance($course->id);
1049         self::validate_context($context);
1050
1051         $userenrolment = $DB->get_record('user_enrolments', ['id' => $params['ueid']], '*', MUST_EXIST);
1052         $userenroldata = [
1053             'status' => $params['status'],
1054             'timestart' => $params['timestart'],
1055             'timeend' => $params['timeend'],
1056         ];
1057
1058         $result = false;
1059         $errors = [];
1060
1061         // Validate data against the edit user enrolment form.
1062         $instance = $DB->get_record('enrol', ['id' => $userenrolment->enrolid], '*', MUST_EXIST);
1063         $plugin = enrol_get_plugin($instance->enrol);
1064         require_once("$CFG->dirroot/enrol/editenrolment_form.php");
1065         $customformdata = [
1066             'ue' => $userenrolment,
1067             'modal' => true,
1068             'enrolinstancename' => $plugin->get_instance_name($instance)
1069         ];
1070         $mform = new \enrol_user_enrolment_form(null, $customformdata, 'post', '', null, true, $userenroldata);
1071         $mform->set_data($userenroldata);
1072         $validationerrors = $mform->validation($userenroldata, null);
1073         if (empty($validationerrors)) {
1074             require_once($CFG->dirroot . '/enrol/locallib.php');
1075             $manager = new course_enrolment_manager($PAGE, $course);
1076             $result = $manager->edit_enrolment($userenrolment, (object)$userenroldata);
1077         } else {
1078             foreach ($validationerrors as $key => $errormessage) {
1079                 $errors[] = (object)[
1080                     'key' => $key,
1081                     'message' => $errormessage
1082                 ];
1083             }
1084         }
1085
1086         return [
1087             'result' => $result,
1088             'errors' => $errors,
1089         ];
1090     }
1091
1092     /**
1093      * Returns description of edit_user_enrolment() result value
1094      *
1095      * @deprecated since 3.8
1096      * @return external_description
1097      */
1098     public static function edit_user_enrolment_returns() {
1099         return new external_single_structure(
1100             array(
1101                 'result' => new external_value(PARAM_BOOL, 'True if the user\'s enrolment was successfully updated'),
1102                 'errors' => new external_multiple_structure(
1103                     new external_single_structure(
1104                         array(
1105                             'key' => new external_value(PARAM_TEXT, 'The data that failed the validation'),
1106                             'message' => new external_value(PARAM_TEXT, 'The error message'),
1107                         )
1108                     ), 'List of validation errors'
1109                 ),
1110             )
1111         );
1112     }
1113
1114     /**
1115      * Mark the edit_user_enrolment web service as deprecated.
1116      *
1117      * @return  bool
1118      */
1119     public static function edit_user_enrolment_is_deprecated() {
1120         return true;
1121     }
1122
1123     /**
1124      * Returns description of submit_user_enrolment_form parameters.
1125      *
1126      * @return external_function_parameters.
1127      */
1128     public static function submit_user_enrolment_form_parameters() {
1129         return new external_function_parameters([
1130             'formdata' => new external_value(PARAM_RAW, 'The data from the event form'),
1131         ]);
1132     }
1133
1134     /**
1135      * External function that handles the user enrolment form submission.
1136      *
1137      * @param string $formdata The user enrolment form data in s URI encoded param string
1138      * @return array An array consisting of the processing result and error flag, if available
1139      */
1140     public static function submit_user_enrolment_form($formdata) {
1141         global $CFG, $DB, $PAGE;
1142
1143         // Parameter validation.
1144         $params = self::validate_parameters(self::submit_user_enrolment_form_parameters(), ['formdata' => $formdata]);
1145
1146         $data = [];
1147         parse_str($params['formdata'], $data);
1148
1149         $userenrolment = $DB->get_record('user_enrolments', ['id' => $data['ue']], '*', MUST_EXIST);
1150         $instance = $DB->get_record('enrol', ['id' => $userenrolment->enrolid], '*', MUST_EXIST);
1151         $plugin = enrol_get_plugin($instance->enrol);
1152         $course = get_course($instance->courseid);
1153         $context = context_course::instance($course->id);
1154         self::validate_context($context);
1155
1156         require_once("$CFG->dirroot/enrol/editenrolment_form.php");
1157         $customformdata = [
1158             'ue' => $userenrolment,
1159             'modal' => true,
1160             'enrolinstancename' => $plugin->get_instance_name($instance)
1161         ];
1162         $mform = new enrol_user_enrolment_form(null, $customformdata, 'post', '', null, true, $data);
1163
1164         if ($validateddata = $mform->get_data()) {
1165             if (!empty($validateddata->duration) && $validateddata->timeend == 0) {
1166                 $validateddata->timeend = $validateddata->timestart + $validateddata->duration;
1167             }
1168             require_once($CFG->dirroot . '/enrol/locallib.php');
1169             $manager = new course_enrolment_manager($PAGE, $course);
1170             $result = $manager->edit_enrolment($userenrolment, $validateddata);
1171
1172             return ['result' => $result];
1173         } else {
1174             return ['result' => false, 'validationerror' => true];
1175         }
1176     }
1177
1178     /**
1179      * Returns description of submit_user_enrolment_form() result value
1180      *
1181      * @return external_description
1182      */
1183     public static function submit_user_enrolment_form_returns() {
1184         return new external_single_structure([
1185             'result' => new external_value(PARAM_BOOL, 'True if the user\'s enrolment was successfully updated'),
1186             'validationerror' => new external_value(PARAM_BOOL, 'Indicates invalid form data', VALUE_DEFAULT, false),
1187         ]);
1188     }
1189
1190     /**
1191      * Returns description of unenrol_user_enrolment() parameters
1192      *
1193      * @return external_function_parameters
1194      */
1195     public static function unenrol_user_enrolment_parameters() {
1196         return new external_function_parameters(
1197             array(
1198                 'ueid' => new external_value(PARAM_INT, 'User enrolment ID')
1199             )
1200         );
1201     }
1202
1203     /**
1204      * External function that unenrols a given user enrolment.
1205      *
1206      * @param int $ueid The user enrolment ID.
1207      * @return array An array consisting of the processing result, errors.
1208      */
1209     public static function unenrol_user_enrolment($ueid) {
1210         global $CFG, $DB, $PAGE;
1211
1212         $params = self::validate_parameters(self::unenrol_user_enrolment_parameters(), [
1213             'ueid' => $ueid
1214         ]);
1215
1216         $result = false;
1217         $errors = [];
1218
1219         $userenrolment = $DB->get_record('user_enrolments', ['id' => $params['ueid']], '*');
1220         if ($userenrolment) {
1221             $userid = $userenrolment->userid;
1222             $enrolid = $userenrolment->enrolid;
1223             $enrol = $DB->get_record('enrol', ['id' => $enrolid], '*', MUST_EXIST);
1224             $courseid = $enrol->courseid;
1225             $course = get_course($courseid);
1226             $context = context_course::instance($course->id);
1227             self::validate_context($context);
1228         } else {
1229             $validationerrors['invalidrequest'] = get_string('invalidrequest', 'enrol');
1230         }
1231
1232         // If the userenrolment exists, unenrol the user.
1233         if (!isset($validationerrors)) {
1234             require_once($CFG->dirroot . '/enrol/locallib.php');
1235             $manager = new course_enrolment_manager($PAGE, $course);
1236             $result = $manager->unenrol_user($userenrolment);
1237         } else {
1238             foreach ($validationerrors as $key => $errormessage) {
1239                 $errors[] = (object)[
1240                     'key' => $key,
1241                     'message' => $errormessage
1242                 ];
1243             }
1244         }
1245
1246         return [
1247             'result' => $result,
1248             'errors' => $errors,
1249         ];
1250     }
1251
1252     /**
1253      * Returns description of unenrol_user_enrolment() result value
1254      *
1255      * @return external_description
1256      */
1257     public static function unenrol_user_enrolment_returns() {
1258         return new external_single_structure(
1259             array(
1260                 'result' => new external_value(PARAM_BOOL, 'True if the user\'s enrolment was successfully updated'),
1261                 'errors' => new external_multiple_structure(
1262                     new external_single_structure(
1263                         array(
1264                             'key' => new external_value(PARAM_TEXT, 'The data that failed the validation'),
1265                             'message' => new external_value(PARAM_TEXT, 'The error message'),
1266                         )
1267                     ), 'List of validation errors'
1268                 ),
1269             )
1270         );
1271     }
1272 }
1273
1274 /**
1275  * Role external functions
1276  *
1277  * @package    core_role
1278  * @category   external
1279  * @copyright  2011 Jerome Mouneyrac
1280  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1281  * @since Moodle 2.2
1282  */
1283 class core_role_external extends external_api {
1284
1285     /**
1286      * Returns description of method parameters
1287      *
1288      * @return external_function_parameters
1289      */
1290     public static function assign_roles_parameters() {
1291         return new external_function_parameters(
1292             array(
1293                 'assignments' => new external_multiple_structure(
1294                     new external_single_structure(
1295                         array(
1296                             'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
1297                             'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
1298                             'contextid' => new external_value(PARAM_INT, 'The context to assign the user role in', VALUE_OPTIONAL),
1299                             'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to assign the user role in
1300                                     (block, course, coursecat, system, user, module)', VALUE_OPTIONAL),
1301                             'instanceid' => new external_value(PARAM_INT, 'The Instance id of item where the role needs to be assigned', VALUE_OPTIONAL),
1302                         )
1303                     )
1304                 )
1305             )
1306         );
1307     }
1308
1309     /**
1310      * Manual role assignments to users
1311      *
1312      * @param array $assignments An array of manual role assignment
1313      */
1314     public static function assign_roles($assignments) {
1315         global $DB;
1316
1317         // Do basic automatic PARAM checks on incoming data, using params description
1318         // If any problems are found then exceptions are thrown with helpful error messages
1319         $params = self::validate_parameters(self::assign_roles_parameters(), array('assignments'=>$assignments));
1320
1321         $transaction = $DB->start_delegated_transaction();
1322
1323         foreach ($params['assignments'] as $assignment) {
1324             // Ensure correct context level with a instance id or contextid is passed.
1325             $context = self::get_context_from_params($assignment);
1326
1327             // Ensure the current user is allowed to run this function in the enrolment context.
1328             self::validate_context($context);
1329             require_capability('moodle/role:assign', $context);
1330
1331             // throw an exception if user is not able to assign the role in this context
1332             $roles = get_assignable_roles($context, ROLENAME_SHORT);
1333
1334             if (!array_key_exists($assignment['roleid'], $roles)) {
1335                 throw new invalid_parameter_exception('Can not assign roleid='.$assignment['roleid'].' in contextid='.$assignment['contextid']);
1336             }
1337
1338             role_assign($assignment['roleid'], $assignment['userid'], $context->id);
1339         }
1340
1341         $transaction->allow_commit();
1342     }
1343
1344     /**
1345      * Returns description of method result value
1346      *
1347      * @return null
1348      */
1349     public static function assign_roles_returns() {
1350         return null;
1351     }
1352
1353
1354     /**
1355      * Returns description of method parameters
1356      *
1357      * @return external_function_parameters
1358      */
1359     public static function unassign_roles_parameters() {
1360         return new external_function_parameters(
1361             array(
1362                 'unassignments' => new external_multiple_structure(
1363                     new external_single_structure(
1364                         array(
1365                             'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
1366                             'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
1367                             'contextid' => new external_value(PARAM_INT, 'The context to unassign the user role from', VALUE_OPTIONAL),
1368                             'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to unassign the user role in
1369 +                                    (block, course, coursecat, system, user, module)', VALUE_OPTIONAL),
1370                             'instanceid' => new external_value(PARAM_INT, 'The Instance id of item where the role needs to be unassigned', VALUE_OPTIONAL),
1371                         )
1372                     )
1373                 )
1374             )
1375         );
1376     }
1377
1378      /**
1379      * Unassign roles from users
1380      *
1381      * @param array $unassignments An array of unassignment
1382      */
1383     public static function unassign_roles($unassignments) {
1384          global $DB;
1385
1386         // Do basic automatic PARAM checks on incoming data, using params description
1387         // If any problems are found then exceptions are thrown with helpful error messages
1388         $params = self::validate_parameters(self::unassign_roles_parameters(), array('unassignments'=>$unassignments));
1389
1390         $transaction = $DB->start_delegated_transaction();
1391
1392         foreach ($params['unassignments'] as $unassignment) {
1393             // Ensure the current user is allowed to run this function in the unassignment context
1394             $context = self::get_context_from_params($unassignment);
1395             self::validate_context($context);
1396             require_capability('moodle/role:assign', $context);
1397
1398             // throw an exception if user is not able to unassign the role in this context
1399             $roles = get_assignable_roles($context, ROLENAME_SHORT);
1400             if (!array_key_exists($unassignment['roleid'], $roles)) {
1401                 throw new invalid_parameter_exception('Can not unassign roleid='.$unassignment['roleid'].' in contextid='.$unassignment['contextid']);
1402             }
1403
1404             role_unassign($unassignment['roleid'], $unassignment['userid'], $context->id);
1405         }
1406
1407         $transaction->allow_commit();
1408     }
1409
1410    /**
1411      * Returns description of method result value
1412      *
1413      * @return null
1414      */
1415     public static function unassign_roles_returns() {
1416         return null;
1417     }
1418 }