2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
17 use core_external\external_api
;
18 use core_external\external_function_parameters
;
19 use core_external\external_multiple_structure
;
20 use core_external\external_single_structure
;
21 use core_external\external_value
;
24 * External course participation api.
26 * This api is mostly read only, the actual enrol and unenrol
27 * support is in each enrol plugin.
29 * @package enrol_manual
31 * @copyright 2011 Jerome Mouneyrac
32 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35 class enrol_manual_external
extends external_api
{
38 * Returns description of method parameters.
40 * @return external_function_parameters
43 public static function enrol_users_parameters() {
44 return new external_function_parameters(
46 'enrolments' => new external_multiple_structure(
47 new external_single_structure(
49 'roleid' => new external_value(PARAM_INT
, 'Role to assign to the user'),
50 'userid' => new external_value(PARAM_INT
, 'The user that is going to be enrolled'),
51 'courseid' => new external_value(PARAM_INT
, 'The course to enrol the user role in'),
52 'timestart' => new external_value(PARAM_INT
, 'Timestamp when the enrolment start', VALUE_OPTIONAL
),
53 'timeend' => new external_value(PARAM_INT
, 'Timestamp when the enrolment end', VALUE_OPTIONAL
),
54 'suspend' => new external_value(PARAM_INT
, 'set to 1 to suspend the enrolment', VALUE_OPTIONAL
)
65 * Function throw an exception at the first error encountered.
66 * @param array $enrolments An array of user enrolment
69 public static function enrol_users($enrolments) {
72 require_once($CFG->libdir
. '/enrollib.php');
74 $params = self
::validate_parameters(self
::enrol_users_parameters(),
75 array('enrolments' => $enrolments));
77 $transaction = $DB->start_delegated_transaction(); // Rollback all enrolment if an error occurs
78 // (except if the DB doesn't support it).
80 // Retrieve the manual enrolment plugin.
81 $enrol = enrol_get_plugin('manual');
83 throw new moodle_exception('manualpluginnotinstalled', 'enrol_manual');
86 foreach ($params['enrolments'] as $enrolment) {
87 // Ensure the current user is allowed to run this function in the enrolment context.
88 $context = context_course
::instance($enrolment['courseid'], IGNORE_MISSING
);
89 self
::validate_context($context);
91 // Check that the user has the permission to manual enrol.
92 require_capability('enrol/manual:enrol', $context);
94 // Throw an exception if user is not able to assign the role.
95 $roles = get_assignable_roles($context);
96 if (!array_key_exists($enrolment['roleid'], $roles)) {
97 $errorparams = new stdClass();
98 $errorparams->roleid
= $enrolment['roleid'];
99 $errorparams->courseid
= $enrolment['courseid'];
100 $errorparams->userid
= $enrolment['userid'];
101 throw new moodle_exception('wsusercannotassign', 'enrol_manual', '', $errorparams);
104 // Check manual enrolment plugin instance is enabled/exist.
106 $enrolinstances = enrol_get_instances($enrolment['courseid'], true);
107 foreach ($enrolinstances as $courseenrolinstance) {
108 if ($courseenrolinstance->enrol
== "manual") {
109 $instance = $courseenrolinstance;
113 if (empty($instance)) {
114 $errorparams = new stdClass();
115 $errorparams->courseid
= $enrolment['courseid'];
116 throw new moodle_exception('wsnoinstance', 'enrol_manual', $errorparams);
119 // Check that the plugin accept enrolment (it should always the case, it's hard coded in the plugin).
120 if (!$enrol->allow_enrol($instance)) {
121 $errorparams = new stdClass();
122 $errorparams->roleid
= $enrolment['roleid'];
123 $errorparams->courseid
= $enrolment['courseid'];
124 $errorparams->userid
= $enrolment['userid'];
125 throw new moodle_exception('wscannotenrol', 'enrol_manual', '', $errorparams);
128 // Finally proceed the enrolment.
129 $enrolment['timestart'] = isset($enrolment['timestart']) ?
$enrolment['timestart'] : 0;
130 $enrolment['timeend'] = isset($enrolment['timeend']) ?
$enrolment['timeend'] : 0;
131 $enrolment['status'] = (isset($enrolment['suspend']) && !empty($enrolment['suspend'])) ?
132 ENROL_USER_SUSPENDED
: ENROL_USER_ACTIVE
;
134 $enrol->enrol_user($instance, $enrolment['userid'], $enrolment['roleid'],
135 $enrolment['timestart'], $enrolment['timeend'], $enrolment['status']);
139 $transaction->allow_commit();
143 * Returns description of method result value.
148 public static function enrol_users_returns() {
153 * Returns description of method parameters.
155 * @return external_function_parameters
157 public static function unenrol_users_parameters() {
158 return new external_function_parameters(array(
159 'enrolments' => new external_multiple_structure(
160 new external_single_structure(
162 'userid' => new external_value(PARAM_INT
, 'The user that is going to be unenrolled'),
163 'courseid' => new external_value(PARAM_INT
, 'The course to unenrol the user from'),
164 'roleid' => new external_value(PARAM_INT
, 'The user role', VALUE_OPTIONAL
),
172 * Unenrolment of users.
174 * @param array $enrolments an array of course user and role ids
175 * @throws coding_exception
176 * @throws dml_transaction_exception
177 * @throws invalid_parameter_exception
178 * @throws moodle_exception
179 * @throws required_capability_exception
180 * @throws restricted_context_exception
182 public static function unenrol_users($enrolments) {
184 $params = self
::validate_parameters(self
::unenrol_users_parameters(), array('enrolments' => $enrolments));
185 require_once($CFG->libdir
. '/enrollib.php');
186 $transaction = $DB->start_delegated_transaction(); // Rollback all enrolment if an error occurs.
187 $enrol = enrol_get_plugin('manual');
189 throw new moodle_exception('manualpluginnotinstalled', 'enrol_manual');
192 foreach ($params['enrolments'] as $enrolment) {
193 $context = context_course
::instance($enrolment['courseid']);
194 self
::validate_context($context);
195 require_capability('enrol/manual:unenrol', $context);
196 $instance = $DB->get_record('enrol', array('courseid' => $enrolment['courseid'], 'enrol' => 'manual'));
198 throw new moodle_exception('wsnoinstance', 'enrol_manual', $enrolment);
200 $user = $DB->get_record('user', array('id' => $enrolment['userid']));
202 throw new invalid_parameter_exception('User id not exist: '.$enrolment['userid']);
204 if (!$enrol->allow_unenrol($instance)) {
205 throw new moodle_exception('wscannotunenrol', 'enrol_manual', '', $enrolment);
207 $enrol->unenrol_user($instance, $enrolment['userid']);
209 $transaction->allow_commit();
213 * Returns description of method result value.
217 public static function unenrol_users_returns() {