source: moodle/trunk/fuentes/enrol/self/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: 9.9 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 * Self enrol plugin external functions
19 *
20 * @package    enrol_self
21 * @copyright  2013 Rajesh Taneja <rajesh@moodle.com>
22 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25defined('MOODLE_INTERNAL') || die();
26
27require_once("$CFG->libdir/externallib.php");
28
29/**
30 * Self enrolment external functions.
31 *
32 * @package   enrol_self
33 * @copyright 2012 Rajesh Taneja <rajesh@moodle.com>
34 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35 * @since     Moodle 2.6
36 */
37class enrol_self_external extends external_api {
38
39    /**
40     * Returns description of get_instance_info() parameters.
41     *
42     * @return external_function_parameters
43     */
44    public static function get_instance_info_parameters() {
45        return new external_function_parameters(
46                array('instanceid' => new external_value(PARAM_INT, 'instance id of self enrolment plugin.'))
47            );
48    }
49
50    /**
51     * Return self-enrolment instance information.
52     *
53     * @param int $instanceid instance id of self enrolment plugin.
54     * @return array instance information.
55     * @throws moodle_exception
56     */
57    public static function get_instance_info($instanceid) {
58        global $DB, $CFG;
59
60        require_once($CFG->libdir . '/enrollib.php');
61
62        $params = self::validate_parameters(self::get_instance_info_parameters(), array('instanceid' => $instanceid));
63
64        // Retrieve self enrolment plugin.
65        $enrolplugin = enrol_get_plugin('self');
66        if (empty($enrolplugin)) {
67            throw new moodle_exception('invaliddata', 'error');
68        }
69
70        // Note that we can't use validate_context because the user is not enrolled in the course.
71        require_login(null, false, null, false, true);
72
73        $enrolinstance = $DB->get_record('enrol', array('id' => $params['instanceid']), '*', MUST_EXIST);
74        $course = $DB->get_record('course', array('id' => $enrolinstance->courseid), '*', MUST_EXIST);
75        $context = context_course::instance($course->id);
76        if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $context)) {
77            throw new moodle_exception('coursehidden');
78        }
79
80        $instanceinfo = (array) $enrolplugin->get_enrol_info($enrolinstance);
81        if (isset($instanceinfo['requiredparam']->enrolpassword)) {
82            $instanceinfo['enrolpassword'] = $instanceinfo['requiredparam']->enrolpassword;
83        }
84        unset($instanceinfo->requiredparam);
85
86        return $instanceinfo;
87    }
88
89    /**
90     * Returns description of get_instance_info() result value.
91     *
92     * @return external_description
93     */
94    public static function get_instance_info_returns() {
95        return new external_single_structure(
96            array(
97                'id' => new external_value(PARAM_INT, 'id of course enrolment instance'),
98                'courseid' => new external_value(PARAM_INT, 'id of course'),
99                'type' => new external_value(PARAM_PLUGIN, 'type of enrolment plugin'),
100                'name' => new external_value(PARAM_RAW, 'name of enrolment plugin'),
101                'status' => new external_value(PARAM_RAW, 'status of enrolment plugin'),
102                'enrolpassword' => new external_value(PARAM_RAW, 'password required for enrolment', VALUE_OPTIONAL),
103            )
104        );
105    }
106
107    /**
108     * Returns description of method parameters
109     *
110     * @return external_function_parameters
111     * @since Moodle 3.0
112     */
113    public static function enrol_user_parameters() {
114        return new external_function_parameters(
115            array(
116                'courseid' => new external_value(PARAM_INT, 'Id of the course'),
117                'password' => new external_value(PARAM_RAW, 'Enrolment key', VALUE_DEFAULT, ''),
118                'instanceid' => new external_value(PARAM_INT, 'Instance id of self enrolment plugin.', VALUE_DEFAULT, 0)
119            )
120        );
121    }
122
123    /**
124     * Self enrol the current user in the given course.
125     *
126     * @param int $courseid id of course
127     * @param string $password enrolment key
128     * @param int $instanceid instance id of self enrolment plugin
129     * @return array of warnings and status result
130     * @since Moodle 3.0
131     * @throws moodle_exception
132     */
133    public static function enrol_user($courseid, $password = '', $instanceid = 0) {
134        global $CFG;
135
136        require_once($CFG->libdir . '/enrollib.php');
137
138        $params = self::validate_parameters(self::enrol_user_parameters(),
139                                            array(
140                                                'courseid' => $courseid,
141                                                'password' => $password,
142                                                'instanceid' => $instanceid
143                                            ));
144
145        $warnings = array();
146
147        $course = get_course($params['courseid']);
148        $context = context_course::instance($course->id);
149        // Note that we can't use validate_context because the user is not enrolled in the course.
150        require_login(null, false, null, false, true);
151
152        if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $context)) {
153            throw new moodle_exception('coursehidden');
154        }
155
156        // Retrieve the self enrolment plugin.
157        $enrol = enrol_get_plugin('self');
158        if (empty($enrol)) {
159            throw new moodle_exception('canntenrol', 'enrol_self');
160        }
161
162        // We can expect multiple self-enrolment instances.
163        $instances = array();
164        $enrolinstances = enrol_get_instances($course->id, true);
165        foreach ($enrolinstances as $courseenrolinstance) {
166            if ($courseenrolinstance->enrol == "self") {
167                // Instance specified.
168                if (!empty($params['instanceid'])) {
169                    if ($courseenrolinstance->id == $params['instanceid']) {
170                        $instances[] = $courseenrolinstance;
171                        break;
172                    }
173                } else {
174                    $instances[] = $courseenrolinstance;
175                }
176
177            }
178        }
179        if (empty($instances)) {
180            throw new moodle_exception('canntenrol', 'enrol_self');
181        }
182
183        // Try to enrol the user in the instance/s.
184        $enrolled = false;
185        foreach ($instances as $instance) {
186            $enrolstatus = $enrol->can_self_enrol($instance);
187            if ($enrolstatus === true) {
188                if ($instance->password and $params['password'] !== $instance->password) {
189
190                    // Check if we are using group enrolment keys.
191                    if ($instance->customint1) {
192                        require_once($CFG->dirroot . "/enrol/self/locallib.php");
193
194                        if (!enrol_self_check_group_enrolment_key($course->id, $params['password'])) {
195                            $warnings[] = array(
196                                'item' => 'instance',
197                                'itemid' => $instance->id,
198                                'warningcode' => '2',
199                                'message' => get_string('passwordinvalid', 'enrol_self')
200                            );
201                            continue;
202                        }
203                    } else {
204                        if ($enrol->get_config('showhint')) {
205                            $hint = core_text::substr($instance->password, 0, 1);
206                            $warnings[] = array(
207                                'item' => 'instance',
208                                'itemid' => $instance->id,
209                                'warningcode' => '3',
210                                'message' => s(get_string('passwordinvalidhint', 'enrol_self', $hint)) // message is PARAM_TEXT.
211                            );
212                            continue;
213                        } else {
214                            $warnings[] = array(
215                                'item' => 'instance',
216                                'itemid' => $instance->id,
217                                'warningcode' => '4',
218                                'message' => get_string('passwordinvalid', 'enrol_self')
219                            );
220                            continue;
221                        }
222                    }
223                }
224
225                // Do the enrolment.
226                $data = array('enrolpassword' => $params['password']);
227                $enrol->enrol_self($instance, (object) $data);
228                $enrolled = true;
229                break;
230            } else {
231                $warnings[] = array(
232                    'item' => 'instance',
233                    'itemid' => $instance->id,
234                    'warningcode' => '1',
235                    'message' => $enrolstatus
236                );
237            }
238        }
239
240        $result = array();
241        $result['status'] = $enrolled;
242        $result['warnings'] = $warnings;
243        return $result;
244    }
245
246    /**
247     * Returns description of method result value
248     *
249     * @return external_description
250     * @since Moodle 3.0
251     */
252    public static function enrol_user_returns() {
253        return new external_single_structure(
254            array(
255                'status' => new external_value(PARAM_BOOL, 'status: true if the user is enrolled, false otherwise'),
256                'warnings' => new external_warnings()
257            )
258        );
259    }
260}
Note: See TracBrowser for help on using the repository browser.