source: moodle/trunk/fuentes/enrol/manual/externallib.php @ 1331

Last change on this file since 1331 was 1331, checked in by jrpelegrina, 3 years ago

Updated to moodle 3.0.3

File size: 11.0 KB
Line 
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 * External course participation api.
19 *
20 * This api is mostly read only, the actual enrol and unenrol
21 * support is in each enrol plugin.
22 *
23 * @package    enrol_manual
24 * @category   external
25 * @copyright  2011 Jerome Mouneyrac
26 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 */
28
29defined('MOODLE_INTERNAL') || die();
30
31require_once("$CFG->libdir/externallib.php");
32
33/**
34 * Manual enrolment external functions.
35 *
36 * @package    enrol_manual
37 * @category   external
38 * @copyright  2011 Jerome Mouneyrac
39 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 * @since Moodle 2.2
41 */
42class enrol_manual_external extends external_api {
43
44    /**
45     * Returns description of method parameters.
46     *
47     * @return external_function_parameters
48     * @since Moodle 2.2
49     */
50    public static function enrol_users_parameters() {
51        return new external_function_parameters(
52                array(
53                    'enrolments' => new external_multiple_structure(
54                            new external_single_structure(
55                                    array(
56                                        'roleid' => new external_value(PARAM_INT, 'Role to assign to the user'),
57                                        'userid' => new external_value(PARAM_INT, 'The user that is going to be enrolled'),
58                                        'courseid' => new external_value(PARAM_INT, 'The course to enrol the user role in'),
59                                        'timestart' => new external_value(PARAM_INT, 'Timestamp when the enrolment start', VALUE_OPTIONAL),
60                                        'timeend' => new external_value(PARAM_INT, 'Timestamp when the enrolment end', VALUE_OPTIONAL),
61                                        'suspend' => new external_value(PARAM_INT, 'set to 1 to suspend the enrolment', VALUE_OPTIONAL)
62                                    )
63                            )
64                    )
65                )
66        );
67    }
68
69    /**
70     * Enrolment of users.
71     *
72     * Function throw an exception at the first error encountered.
73     * @param array $enrolments  An array of user enrolment
74     * @since Moodle 2.2
75     */
76    public static function enrol_users($enrolments) {
77        global $DB, $CFG;
78
79        require_once($CFG->libdir . '/enrollib.php');
80
81        $params = self::validate_parameters(self::enrol_users_parameters(),
82                array('enrolments' => $enrolments));
83
84        $transaction = $DB->start_delegated_transaction(); // Rollback all enrolment if an error occurs
85                                                           // (except if the DB doesn't support it).
86
87        // Retrieve the manual enrolment plugin.
88        $enrol = enrol_get_plugin('manual');
89        if (empty($enrol)) {
90            throw new moodle_exception('manualpluginnotinstalled', 'enrol_manual');
91        }
92
93        foreach ($params['enrolments'] as $enrolment) {
94            // Ensure the current user is allowed to run this function in the enrolment context.
95            $context = context_course::instance($enrolment['courseid'], IGNORE_MISSING);
96            self::validate_context($context);
97
98            // Check that the user has the permission to manual enrol.
99            require_capability('enrol/manual:enrol', $context);
100
101            // Throw an exception if user is not able to assign the role.
102            $roles = get_assignable_roles($context);
103            if (!array_key_exists($enrolment['roleid'], $roles)) {
104                $errorparams = new stdClass();
105                $errorparams->roleid = $enrolment['roleid'];
106                $errorparams->courseid = $enrolment['courseid'];
107                $errorparams->userid = $enrolment['userid'];
108                throw new moodle_exception('wsusercannotassign', 'enrol_manual', '', $errorparams);
109            }
110
111            // Check manual enrolment plugin instance is enabled/exist.
112            $instance = null;
113            $enrolinstances = enrol_get_instances($enrolment['courseid'], true);
114            foreach ($enrolinstances as $courseenrolinstance) {
115              if ($courseenrolinstance->enrol == "manual") {
116                  $instance = $courseenrolinstance;
117                  break;
118              }
119            }
120            if (empty($instance)) {
121              $errorparams = new stdClass();
122              $errorparams->courseid = $enrolment['courseid'];
123              throw new moodle_exception('wsnoinstance', 'enrol_manual', $errorparams);
124            }
125
126            // Check that the plugin accept enrolment (it should always the case, it's hard coded in the plugin).
127            if (!$enrol->allow_enrol($instance)) {
128                $errorparams = new stdClass();
129                $errorparams->roleid = $enrolment['roleid'];
130                $errorparams->courseid = $enrolment['courseid'];
131                $errorparams->userid = $enrolment['userid'];
132                throw new moodle_exception('wscannotenrol', 'enrol_manual', '', $errorparams);
133            }
134
135            // Finally proceed the enrolment.
136            $enrolment['timestart'] = isset($enrolment['timestart']) ? $enrolment['timestart'] : 0;
137            $enrolment['timeend'] = isset($enrolment['timeend']) ? $enrolment['timeend'] : 0;
138            $enrolment['status'] = (isset($enrolment['suspend']) && !empty($enrolment['suspend'])) ?
139                    ENROL_USER_SUSPENDED : ENROL_USER_ACTIVE;
140
141            $enrol->enrol_user($instance, $enrolment['userid'], $enrolment['roleid'],
142                    $enrolment['timestart'], $enrolment['timeend'], $enrolment['status']);
143
144        }
145
146        $transaction->allow_commit();
147    }
148
149    /**
150     * Returns description of method result value.
151     *
152     * @return null
153     * @since Moodle 2.2
154     */
155    public static function enrol_users_returns() {
156        return null;
157    }
158
159    /**
160     * Returns description of method parameters.
161     *
162     * @return external_function_parameters
163     */
164    public static function unenrol_users_parameters() {
165        return new external_function_parameters(array(
166            'enrolments' => new external_multiple_structure(
167                new external_single_structure(
168                    array(
169                        'userid' => new external_value(PARAM_INT, 'The user that is going to be unenrolled'),
170                        'courseid' => new external_value(PARAM_INT, 'The course to unenrol the user from'),
171                        'roleid' => new external_value(PARAM_INT, 'The user role', VALUE_OPTIONAL),
172                    )
173                )
174            )
175        ));
176    }
177
178    /**
179     * Unenrolment of users.
180     *
181     * @param array $enrolments an array of course user and role ids
182     * @throws coding_exception
183     * @throws dml_transaction_exception
184     * @throws invalid_parameter_exception
185     * @throws moodle_exception
186     * @throws required_capability_exception
187     * @throws restricted_context_exception
188     */
189    public static function unenrol_users($enrolments) {
190        global $CFG, $DB;
191        $params = self::validate_parameters(self::unenrol_users_parameters(), array('enrolments' => $enrolments));
192        require_once($CFG->libdir . '/enrollib.php');
193        $transaction = $DB->start_delegated_transaction(); // Rollback all enrolment if an error occurs.
194        $enrol = enrol_get_plugin('manual');
195        if (empty($enrol)) {
196            throw new moodle_exception('manualpluginnotinstalled', 'enrol_manual');
197        }
198
199        foreach ($params['enrolments'] as $enrolment) {
200            $context = context_course::instance($enrolment['courseid']);
201            self::validate_context($context);
202            require_capability('enrol/manual:unenrol', $context);
203            $instance = $DB->get_record('enrol', array('courseid' => $enrolment['courseid'], 'enrol' => 'manual'));
204            if (!$instance) {
205                throw new moodle_exception('wsnoinstance', 'enrol_manual', $enrolment);
206            }
207            $user = $DB->get_record('user', array('id' => $enrolment['userid']));
208            if (!$user) {
209                throw new invalid_parameter_exception('User id not exist: '.$enrolment['userid']);
210            }
211            if (!$enrol->allow_unenrol($instance)) {
212                throw new moodle_exception('wscannotunenrol', 'enrol_manual', '', $enrolment);
213            }
214            $enrol->unenrol_user($instance, $enrolment['userid']);
215        }
216        $transaction->allow_commit();
217    }
218
219    /**
220     * Returns description of method result value.
221     *
222     * @return null
223     */
224    public static function unenrol_users_returns() {
225        return null;
226    }
227
228}
229
230/**
231 * Deprecated manual enrolment external functions.
232 *
233 * @package    enrol_manual
234 * @copyright  2011 Jerome Mouneyrac
235 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
236 * @since Moodle 2.0
237 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
238 * @see enrol_manual_external
239 */
240class moodle_enrol_manual_external extends external_api {
241
242    /**
243     * Returns description of method parameters.
244     *
245     * @return external_function_parameters
246     * @since Moodle 2.0
247     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
248     * @see enrol_manual_external::enrol_users_parameters()
249     */
250    public static function manual_enrol_users_parameters() {
251        return enrol_manual_external::enrol_users_parameters();
252    }
253
254    /**
255     * Enrolment of users
256     * Function throw an exception at the first error encountered.
257     *
258     * @param array $enrolments  An array of user enrolment
259     * @since Moodle 2.0
260     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
261     * @see enrol_manual_external::enrol_users()
262     */
263    public static function manual_enrol_users($enrolments) {
264        return enrol_manual_external::enrol_users($enrolments);
265    }
266
267    /**
268     * Returns description of method result value.
269     *
270     * @return nul
271     * @since Moodle 2.0
272     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
273     * @see enrol_manual_external::enrol_users_returns()
274     */
275    public static function manual_enrol_users_returns() {
276        return enrol_manual_external::enrol_users_returns();
277    }
278
279    /**
280     * Marking the method as deprecated.
281     *
282     * @return bool
283     */
284    public static function manual_enrol_users_is_deprecated() {
285        return true;
286    }
287}
Note: See TracBrowser for help on using the repository browser.