MDL-52073 enrol_guest: New Web Service enrol_guest_get_instance_info
[moodle.git] / enrol / guest / classes / external.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/>.
17 /**
18  * Guest enrolment method external API
19  *
20  * @package    enrol_guest
21  * @category   external
22  * @copyright  2015 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.1
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->libdir . '/enrollib.php');
32 /**
33  * Guest enrolment method external API
34  *
35  * @package    enrol_guest
36  * @category   external
37  * @copyright  2015 Juan Leyva <juan@moodle.com>
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  * @since      Moodle 3.1
40  */
41 class enrol_guest_external extends external_api {
43     /**
44      * Returns description of get_instance_info() parameters.
45      *
46      * @return external_function_parameters
47      * @since Moodle 3.1
48      */
49     public static function get_instance_info_parameters() {
50         return new external_function_parameters(
51                 array('instanceid' => new external_value(PARAM_INT, 'Instance id of guest enrolment plugin.'))
52             );
53     }
55     /**
56      * Return guest enrolment instance information.
57      *
58      * @param int $instanceid instance id of guest enrolment plugin.
59      * @return array warnings and instance information.
60      * @since Moodle 3.1
61      */
62     public static function get_instance_info($instanceid) {
63         global $DB;
65         $params = self::validate_parameters(self::get_instance_info_parameters(), array('instanceid' => $instanceid));
66         $warnings = array();
68         // Retrieve guest enrolment plugin.
69         $enrolplugin = enrol_get_plugin('guest');
70         if (empty($enrolplugin)) {
71             throw new moodle_exception('invaliddata', 'error');
72         }
74         require_login(null, false, null, false, true);
75         $enrolinstance = $DB->get_record('enrol', array('id' => $params['instanceid']), '*', MUST_EXIST);
77         $course = $DB->get_record('course', array('id' => $enrolinstance->courseid), '*', MUST_EXIST);
78         $context = context_course::instance($course->id);
79         if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $context)) {
80             throw new moodle_exception('coursehidden');
81         }
83         $instanceinfo = $enrolplugin->get_enrol_info($enrolinstance);
84         // Specific instance information.
85         $instanceinfo->passwordrequired = $instanceinfo->requiredparam->passwordrequired;
87         unset($instanceinfo->requiredparam);
89         $result = array();
90         $result['instanceinfo'] = $instanceinfo;
91         $result['warnings'] = $warnings;
92         return $result;
93     }
95     /**
96      * Returns description of get_instance_info() result value.
97      *
98      * @return external_description
99      * @since Moodle 3.1
100      */
101     public static function get_instance_info_returns() {
102         return new external_single_structure(
103             array(
104                 'instanceinfo' => new external_single_structure(
105                     array(
106                         'id' => new external_value(PARAM_INT, 'Id of course enrolment instance'),
107                         'courseid' => new external_value(PARAM_INT, 'Id of course'),
108                         'type' => new external_value(PARAM_PLUGIN, 'Type of enrolment plugin'),
109                         'name' => new external_value(PARAM_RAW, 'Name of enrolment plugin'),
110                         'status' => new external_value(PARAM_BOOL, 'Is the enrolment enabled?'),
111                         'passwordrequired' => new external_value(PARAM_BOOL, 'Is a password required?'),
112                     )
113                 ),
114                 'warnings' => new external_warnings()
115             )
116         );
117     }