MDL-51929 external: Apply new validate_courses to data/lti/survey
[moodle.git] / mod / lti / classes / external.php
CommitLineData
ae67efa8
JL
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 tool module external API
19 *
20 * @package mod_lti
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.0
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once($CFG->libdir . '/externallib.php');
30require_once($CFG->dirroot . '/mod/lti/lib.php');
31require_once($CFG->dirroot . '/mod/lti/locallib.php');
32
33/**
34 * External tool module external functions
35 *
36 * @package mod_lti
37 * @category external
38 * @copyright 2015 Juan Leyva <juan@moodle.com>
39 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 * @since Moodle 3.0
41 */
42class mod_lti_external extends external_api {
43
44 /**
45 * Returns description of method parameters
46 *
47 * @return external_function_parameters
48 * @since Moodle 3.0
49 */
50 public static function get_tool_launch_data_parameters() {
51 return new external_function_parameters(
52 array(
53 'toolid' => new external_value(PARAM_INT, 'external tool instance id')
54 )
55 );
56 }
57
58 /**
59 * Return the launch data for a given external tool.
60 *
61 * @param int $toolid the external tool instance id
62 * @return array of warnings and launch data
63 * @since Moodle 3.0
64 * @throws moodle_exception
65 */
66 public static function get_tool_launch_data($toolid) {
67 global $DB, $CFG;
68 require_once($CFG->dirroot . '/mod/lti/lib.php');
69
70 $params = self::validate_parameters(self::get_tool_launch_data_parameters(),
71 array(
72 'toolid' => $toolid
73 ));
74 $warnings = array();
75
76 // Request and permission validation.
77 $lti = $DB->get_record('lti', array('id' => $params['toolid']), '*', MUST_EXIST);
78 list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
79
80 $context = context_module::instance($cm->id);
81 self::validate_context($context);
82
83 require_capability('mod/lti:view', $context);
84
85 $lti->cmid = $cm->id;
86 list($endpoint, $parms) = lti_get_launch_data($lti);
87
88 $parameters = array();
89 foreach ($parms as $name => $value) {
90 $parameters[] = array(
91 'name' => $name,
92 'value' => $value
93 );
94 }
95
96 $result = array();
97 $result['endpoint'] = $endpoint;
98 $result['parameters'] = $parameters;
99 $result['warnings'] = $warnings;
100 return $result;
101 }
102
103 /**
104 * Returns description of method result value
105 *
106 * @return external_description
107 * @since Moodle 3.0
108 */
109 public static function get_tool_launch_data_returns() {
110 return new external_single_structure(
111 array(
112 'endpoint' => new external_value(PARAM_RAW, 'Endpoint URL'), // Using PARAM_RAW as is defined in the module.
113 'parameters' => new external_multiple_structure(
114 new external_single_structure(
115 array(
116 'name' => new external_value(PARAM_NOTAGS, 'Parameter name'),
117 'value' => new external_value(PARAM_RAW, 'Parameter value')
118 )
119 )
120 ),
121 'warnings' => new external_warnings()
122 )
123 );
124 }
dfcdec12
JL
125
126 /**
127 * Describes the parameters for get_ltis_by_courses.
128 *
129 * @return external_function_parameters
130 * @since Moodle 3.0
131 */
132 public static function get_ltis_by_courses_parameters() {
133 return new external_function_parameters (
134 array(
135 'courseids' => new external_multiple_structure(
136 new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
137 ),
138 )
139 );
140 }
141
142 /**
143 * Returns a list of external tools in a provided list of courses,
144 * if no list is provided all external tools that the user can view will be returned.
145 *
146 * @param array $courseids the course ids
147 * @return array the lti details
148 * @since Moodle 3.0
149 */
150 public static function get_ltis_by_courses($courseids = array()) {
151 global $CFG;
152
153 $returnedltis = array();
154 $warnings = array();
155
156 $params = self::validate_parameters(self::get_ltis_by_courses_parameters(), array('courseids' => $courseids));
157
052da730 158 $mycourses = array();
dfcdec12 159 if (empty($params['courseids'])) {
052da730
DP
160 $mycourses = enrol_get_my_courses();
161 $params['courseids'] = array_keys($mycourses);
dfcdec12
JL
162 }
163
164 // Ensure there are courseids to loop through.
165 if (!empty($params['courseids'])) {
166
052da730 167 list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
dfcdec12
JL
168
169 // Get the ltis in this course, this function checks users visibility permissions.
170 // We can avoid then additional validate_context calls.
171 $ltis = get_all_instances_in_courses("lti", $courses);
172
173 foreach ($ltis as $lti) {
174
175 $context = context_module::instance($lti->coursemodule);
176
177 // Entry to return.
178 $module = array();
179
180 // First, we return information that any user can see in (or can deduce from) the web interface.
181 $module['id'] = $lti->id;
182 $module['coursemodule'] = $lti->coursemodule;
183 $module['course'] = $lti->course;
184 $module['name'] = external_format_string($lti->name, $context->id);
185
186 $viewablefields = [];
187 if (has_capability('mod/lti:view', $context)) {
188 list($module['intro'], $module['introformat']) =
189 external_format_text($lti->intro, $lti->introformat, $context->id, 'mod_lti', 'intro', $lti->id);
190
191 $viewablefields = array('launchcontainer', 'showtitlelaunch', 'showdescriptionlaunch', 'icon', 'secureicon');
192 }
193
194 // Check additional permissions for returning optional private settings.
195 if (has_capability('moodle/course:manageactivities', $context)) {
196
197 $additionalfields = array('timecreated', 'timemodified', 'typeid', 'toolurl', 'securetoolurl',
198 'instructorchoicesendname', 'instructorchoicesendemailaddr', 'instructorchoiceallowroster',
199 'instructorchoiceallowsetting', 'instructorcustomparameters', 'instructorchoiceacceptgrades', 'grade',
200 'resourcekey', 'password', 'debuglaunch', 'servicesalt', 'visible', 'groupmode', 'groupingid');
201 $viewablefields = array_merge($viewablefields, $additionalfields);
202
203 }
204
205 foreach ($viewablefields as $field) {
206 $module[$field] = $lti->{$field};
207 }
208
209 $returnedltis[] = $module;
210 }
211 }
212
213 $result = array();
214 $result['ltis'] = $returnedltis;
215 $result['warnings'] = $warnings;
216 return $result;
217 }
218
219 /**
220 * Describes the get_ltis_by_courses return value.
221 *
222 * @return external_single_structure
223 * @since Moodle 3.0
224 */
225 public static function get_ltis_by_courses_returns() {
226
227 return new external_single_structure(
228 array(
229 'ltis' => new external_multiple_structure(
230 new external_single_structure(
231 array(
232 'id' => new external_value(PARAM_INT, 'External tool id'),
233 'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
234 'course' => new external_value(PARAM_INT, 'Course id'),
235 'name' => new external_value(PARAM_RAW, 'LTI name'),
236 'intro' => new external_value(PARAM_RAW, 'The LTI intro', VALUE_OPTIONAL),
237 'introformat' => new external_format_value('intro', VALUE_OPTIONAL),
238 'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL),
239 'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
240 'typeid' => new external_value(PARAM_INT, 'Type id', VALUE_OPTIONAL),
241 'toolurl' => new external_value(PARAM_URL, 'Tool url', VALUE_OPTIONAL),
242 'securetoolurl' => new external_value(PARAM_RAW, 'Secure tool url', VALUE_OPTIONAL),
243 'instructorchoicesendname' => new external_value(PARAM_TEXT, 'Instructor choice send name',
244 VALUE_OPTIONAL),
245 'instructorchoicesendemailaddr' => new external_value(PARAM_INT, 'instructor choice send mail address',
246 VALUE_OPTIONAL),
247 'instructorchoiceallowroster' => new external_value(PARAM_INT, 'Instructor choice allow roster',
248 VALUE_OPTIONAL),
249 'instructorchoiceallowsetting' => new external_value(PARAM_INT, 'Instructor choice allow setting',
250 VALUE_OPTIONAL),
251 'instructorcustomparameters' => new external_value(PARAM_RAW, 'instructor custom parameters',
252 VALUE_OPTIONAL),
253 'instructorchoiceacceptgrades' => new external_value(PARAM_INT, 'instructor choice accept grades',
254 VALUE_OPTIONAL),
255 'grade' => new external_value(PARAM_INT, 'Enable grades', VALUE_OPTIONAL),
256 'launchcontainer' => new external_value(PARAM_INT, 'Launch container mode', VALUE_OPTIONAL),
257 'resourcekey' => new external_value(PARAM_RAW, 'Resource key', VALUE_OPTIONAL),
258 'password' => new external_value(PARAM_RAW, 'Shared secret', VALUE_OPTIONAL),
259 'debuglaunch' => new external_value(PARAM_INT, 'Debug launch', VALUE_OPTIONAL),
260 'showtitlelaunch' => new external_value(PARAM_INT, 'Show title launch', VALUE_OPTIONAL),
261 'showdescriptionlaunch' => new external_value(PARAM_INT, 'Show description launch', VALUE_OPTIONAL),
262 'servicesalt' => new external_value(PARAM_RAW, 'Service salt', VALUE_OPTIONAL),
263 'icon' => new external_value(PARAM_URL, 'Alternative icon URL', VALUE_OPTIONAL),
264 'secureicon' => new external_value(PARAM_URL, 'Secure icon URL', VALUE_OPTIONAL),
265 'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL),
266 'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL),
267 'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
268 'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL),
269 ), 'Tool'
270 )
271 ),
272 'warnings' => new external_warnings(),
273 )
274 );
275 }
4bed1682
JL
276
277 /**
278 * Returns description of method parameters
279 *
280 * @return external_function_parameters
281 * @since Moodle 3.0
282 */
283 public static function view_lti_parameters() {
284 return new external_function_parameters(
285 array(
286 'ltiid' => new external_value(PARAM_INT, 'lti instance id')
287 )
288 );
289 }
290
291 /**
292 * Trigger the course module viewed event and update the module completion status.
293 *
294 * @param int $ltiid the lti instance id
295 * @return array of warnings and status result
296 * @since Moodle 3.0
297 * @throws moodle_exception
298 */
299 public static function view_lti($ltiid) {
300 global $DB;
301
302 $params = self::validate_parameters(self::view_lti_parameters(),
303 array(
304 'ltiid' => $ltiid
305 ));
306 $warnings = array();
307
308 // Request and permission validation.
309 $lti = $DB->get_record('lti', array('id' => $params['ltiid']), '*', MUST_EXIST);
310 list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
311
312 $context = context_module::instance($cm->id);
313 self::validate_context($context);
314 require_capability('mod/lti:view', $context);
315
316 // Trigger course_module_viewed event and completion.
317 lti_view($lti, $course, $cm, $context);
318
319 $result = array();
320 $result['status'] = true;
321 $result['warnings'] = $warnings;
322 return $result;
323 }
324
325 /**
326 * Returns description of method result value
327 *
328 * @return external_description
329 * @since Moodle 3.0
330 */
331 public static function view_lti_returns() {
332 return new external_single_structure(
333 array(
334 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
335 'warnings' => new external_warnings()
336 )
337 );
338 }
ae67efa8 339}