MDL-61576 mod_lti: remove allowinstructorcustom in lib/locallib.php
[moodle.git] / mod / lti / locallib.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/>.
16 //
17 // This file is part of BasicLTI4Moodle
18 //
19 // BasicLTI4Moodle is an IMS BasicLTI (Basic Learning Tools for Interoperability)
20 // consumer for Moodle 1.9 and Moodle 2.0. BasicLTI is a IMS Standard that allows web
21 // based learning tools to be easily integrated in LMS as native ones. The IMS BasicLTI
22 // specification is part of the IMS standard Common Cartridge 1.1 Sakai and other main LMS
23 // are already supporting or going to support BasicLTI. This project Implements the consumer
24 // for Moodle. Moodle is a Free Open source Learning Management System by Martin Dougiamas.
25 // BasicLTI4Moodle is a project iniciated and leaded by Ludo(Marc Alier) and Jordi Piguillem
26 // at the GESSI research group at UPC.
27 // SimpleLTI consumer for Moodle is an implementation of the early specification of LTI
28 // by Charles Severance (Dr Chuck) htp://dr-chuck.com , developed by Jordi Piguillem in a
29 // Google Summer of Code 2008 project co-mentored by Charles Severance and Marc Alier.
30 //
31 // BasicLTI4Moodle is copyright 2009 by Marc Alier Forment, Jordi Piguillem and Nikolas Galanis
32 // of the Universitat Politecnica de Catalunya http://www.upc.edu
33 // Contact info: Marc Alier Forment granludo @ gmail.com or marc.alier @ upc.edu.
35 /**
36  * This file contains the library of functions and constants for the lti module
37  *
38  * @package mod_lti
39  * @copyright  2009 Marc Alier, Jordi Piguillem, Nikolas Galanis
40  *  marc.alier@upc.edu
41  * @copyright  2009 Universitat Politecnica de Catalunya http://www.upc.edu
42  * @author     Marc Alier
43  * @author     Jordi Piguillem
44  * @author     Nikolas Galanis
45  * @author     Chris Scribner
46  * @copyright  2015 Vital Source Technologies http://vitalsource.com
47  * @author     Stephen Vickers
48  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
49  */
51 defined('MOODLE_INTERNAL') || die;
53 // TODO: Switch to core oauthlib once implemented - MDL-30149.
54 use moodle\mod\lti as lti;
56 require_once($CFG->dirroot.'/mod/lti/OAuth.php');
57 require_once($CFG->libdir.'/weblib.php');
58 require_once($CFG->dirroot . '/course/modlib.php');
59 require_once($CFG->dirroot . '/mod/lti/TrivialStore.php');
61 define('LTI_URL_DOMAIN_REGEX', '/(?:https?:\/\/)?(?:www\.)?([^\/]+)(?:\/|$)/i');
63 define('LTI_LAUNCH_CONTAINER_DEFAULT', 1);
64 define('LTI_LAUNCH_CONTAINER_EMBED', 2);
65 define('LTI_LAUNCH_CONTAINER_EMBED_NO_BLOCKS', 3);
66 define('LTI_LAUNCH_CONTAINER_WINDOW', 4);
67 define('LTI_LAUNCH_CONTAINER_REPLACE_MOODLE_WINDOW', 5);
69 define('LTI_TOOL_STATE_ANY', 0);
70 define('LTI_TOOL_STATE_CONFIGURED', 1);
71 define('LTI_TOOL_STATE_PENDING', 2);
72 define('LTI_TOOL_STATE_REJECTED', 3);
73 define('LTI_TOOL_PROXY_TAB', 4);
75 define('LTI_TOOL_PROXY_STATE_CONFIGURED', 1);
76 define('LTI_TOOL_PROXY_STATE_PENDING', 2);
77 define('LTI_TOOL_PROXY_STATE_ACCEPTED', 3);
78 define('LTI_TOOL_PROXY_STATE_REJECTED', 4);
80 define('LTI_SETTING_NEVER', 0);
81 define('LTI_SETTING_ALWAYS', 1);
82 define('LTI_SETTING_DELEGATE', 2);
84 define('LTI_COURSEVISIBLE_NO', 0);
85 define('LTI_COURSEVISIBLE_PRECONFIGURED', 1);
86 define('LTI_COURSEVISIBLE_ACTIVITYCHOOSER', 2);
88 define('LTI_VERSION_1', 'LTI-1p0');
89 define('LTI_VERSION_2', 'LTI-2p0');
91 /**
92  * Return the launch data required for opening the external tool.
93  *
94  * @param  stdClass $instance the external tool activity settings
95  * @return array the endpoint URL and parameters (including the signature)
96  * @since  Moodle 3.0
97  */
98 function lti_get_launch_data($instance) {
99     global $PAGE, $CFG;
101     if (empty($instance->typeid)) {
102         $tool = lti_get_tool_by_url_match($instance->toolurl, $instance->course);
103         if ($tool) {
104             $typeid = $tool->id;
105         } else {
106             $tool = lti_get_tool_by_url_match($instance->securetoolurl,  $instance->course);
107             if ($tool) {
108                 $typeid = $tool->id;
109             } else {
110                 $typeid = null;
111             }
112         }
113     } else {
114         $typeid = $instance->typeid;
115         $tool = lti_get_type($typeid);
116     }
118     if ($typeid) {
119         $typeconfig = lti_get_type_config($typeid);
120     } else {
121         // There is no admin configuration for this tool. Use configuration in the lti instance record plus some defaults.
122         $typeconfig = (array)$instance;
124         $typeconfig['sendname'] = $instance->instructorchoicesendname;
125         $typeconfig['sendemailaddr'] = $instance->instructorchoicesendemailaddr;
126         $typeconfig['customparameters'] = $instance->instructorcustomparameters;
127         $typeconfig['acceptgrades'] = $instance->instructorchoiceacceptgrades;
128         $typeconfig['allowroster'] = $instance->instructorchoiceallowroster;
129         $typeconfig['forcessl'] = '0';
130     }
132     // Default the organizationid if not specified.
133     if (empty($typeconfig['organizationid'])) {
134         $urlparts = parse_url($CFG->wwwroot);
136         $typeconfig['organizationid'] = $urlparts['host'];
137     }
139     if (isset($tool->toolproxyid)) {
140         $toolproxy = lti_get_tool_proxy($tool->toolproxyid);
141         $key = $toolproxy->guid;
142         $secret = $toolproxy->secret;
143     } else {
144         $toolproxy = null;
145         if (!empty($instance->resourcekey)) {
146             $key = $instance->resourcekey;
147         } else if (!empty($typeconfig['resourcekey'])) {
148             $key = $typeconfig['resourcekey'];
149         } else {
150             $key = '';
151         }
152         if (!empty($instance->password)) {
153             $secret = $instance->password;
154         } else if (!empty($typeconfig['password'])) {
155             $secret = $typeconfig['password'];
156         } else {
157             $secret = '';
158         }
159     }
161     $endpoint = !empty($instance->toolurl) ? $instance->toolurl : $typeconfig['toolurl'];
162     $endpoint = trim($endpoint);
164     // If the current request is using SSL and a secure tool URL is specified, use it.
165     if (lti_request_is_using_ssl() && !empty($instance->securetoolurl)) {
166         $endpoint = trim($instance->securetoolurl);
167     }
169     // If SSL is forced, use the secure tool url if specified. Otherwise, make sure https is on the normal launch URL.
170     if (isset($typeconfig['forcessl']) && ($typeconfig['forcessl'] == '1')) {
171         if (!empty($instance->securetoolurl)) {
172             $endpoint = trim($instance->securetoolurl);
173         }
175         $endpoint = lti_ensure_url_is_https($endpoint);
176     } else {
177         if (!strstr($endpoint, '://')) {
178             $endpoint = 'http://' . $endpoint;
179         }
180     }
182     $orgid = $typeconfig['organizationid'];
184     $course = $PAGE->course;
185     $islti2 = isset($tool->toolproxyid);
186     $allparams = lti_build_request($instance, $typeconfig, $course, $typeid, $islti2);
187     if ($islti2) {
188         $requestparams = lti_build_request_lti2($tool, $allparams);
189     } else {
190         $requestparams = $allparams;
191     }
192     $requestparams = array_merge($requestparams, lti_build_standard_request($instance, $orgid, $islti2));
193     $customstr = '';
194     if (isset($typeconfig['customparameters'])) {
195         $customstr = $typeconfig['customparameters'];
196     }
197     $requestparams = array_merge($requestparams, lti_build_custom_parameters($toolproxy, $tool, $instance, $allparams, $customstr,
198         $instance->instructorcustomparameters, $islti2));
200     $launchcontainer = lti_get_launch_container($instance, $typeconfig);
201     $returnurlparams = array('course' => $course->id,
202                              'launch_container' => $launchcontainer,
203                              'instanceid' => $instance->id,
204                              'sesskey' => sesskey());
206     // Add the return URL. We send the launch container along to help us avoid frames-within-frames when the user returns.
207     $url = new \moodle_url('/mod/lti/return.php', $returnurlparams);
208     $returnurl = $url->out(false);
210     if (isset($typeconfig['forcessl']) && ($typeconfig['forcessl'] == '1')) {
211         $returnurl = lti_ensure_url_is_https($returnurl);
212     }
214     $target = '';
215     switch($launchcontainer) {
216         case LTI_LAUNCH_CONTAINER_EMBED:
217         case LTI_LAUNCH_CONTAINER_EMBED_NO_BLOCKS:
218             $target = 'iframe';
219             break;
220         case LTI_LAUNCH_CONTAINER_REPLACE_MOODLE_WINDOW:
221             $target = 'frame';
222             break;
223         case LTI_LAUNCH_CONTAINER_WINDOW:
224             $target = 'window';
225             break;
226     }
227     if (!empty($target)) {
228         $requestparams['launch_presentation_document_target'] = $target;
229     }
231     $requestparams['launch_presentation_return_url'] = $returnurl;
233     // Allow request params to be updated by sub-plugins.
234     $plugins = core_component::get_plugin_list('ltisource');
235     foreach (array_keys($plugins) as $plugin) {
236         $pluginparams = component_callback('ltisource_'.$plugin, 'before_launch',
237             array($instance, $endpoint, $requestparams), array());
239         if (!empty($pluginparams) && is_array($pluginparams)) {
240             $requestparams = array_merge($requestparams, $pluginparams);
241         }
242     }
244     if (!empty($key) && !empty($secret)) {
245         $parms = lti_sign_parameters($requestparams, $endpoint, "POST", $key, $secret);
247         $endpointurl = new \moodle_url($endpoint);
248         $endpointparams = $endpointurl->params();
250         // Strip querystring params in endpoint url from $parms to avoid duplication.
251         if (!empty($endpointparams) && !empty($parms)) {
252             foreach (array_keys($endpointparams) as $paramname) {
253                 if (isset($parms[$paramname])) {
254                     unset($parms[$paramname]);
255                 }
256             }
257         }
259     } else {
260         // If no key and secret, do the launch unsigned.
261         $returnurlparams['unsigned'] = '1';
262         $parms = $requestparams;
263     }
265     return array($endpoint, $parms);
268 /**
269  * Launch an external tool activity.
270  *
271  * @param  stdClass $instance the external tool activity settings
272  * @return string The HTML code containing the javascript code for the launch
273  */
274 function lti_launch_tool($instance) {
276     list($endpoint, $parms) = lti_get_launch_data($instance);
277     $debuglaunch = ( $instance->debuglaunch == 1 );
279     $content = lti_post_launch_html($parms, $endpoint, $debuglaunch);
281     echo $content;
284 /**
285  * Prepares an LTI registration request message
286  *
287  * $param object $instance       Tool Proxy instance object
288  */
289 function lti_register($toolproxy) {
290     $endpoint = $toolproxy->regurl;
292     // Change the status to pending.
293     $toolproxy->state = LTI_TOOL_PROXY_STATE_PENDING;
294     lti_update_tool_proxy($toolproxy);
296     $requestparams = lti_build_registration_request($toolproxy);
298     $content = lti_post_launch_html($requestparams, $endpoint, false);
300     echo $content;
304 /**
305  * Gets the parameters for the regirstration request
306  *
307  * @param object $toolproxy Tool Proxy instance object
308  * @return array Registration request parameters
309  */
310 function lti_build_registration_request($toolproxy) {
311     $key = $toolproxy->guid;
312     $secret = $toolproxy->secret;
314     $requestparams = array();
315     $requestparams['lti_message_type'] = 'ToolProxyRegistrationRequest';
316     $requestparams['lti_version'] = 'LTI-2p0';
317     $requestparams['reg_key'] = $key;
318     $requestparams['reg_password'] = $secret;
319     $requestparams['reg_url'] = $toolproxy->regurl;
321     // Add the profile URL.
322     $profileservice = lti_get_service_by_name('profile');
323     $profileservice->set_tool_proxy($toolproxy);
324     $requestparams['tc_profile_url'] = $profileservice->parse_value('$ToolConsumerProfile.url');
326     // Add the return URL.
327     $returnurlparams = array('id' => $toolproxy->id, 'sesskey' => sesskey());
328     $url = new \moodle_url('/mod/lti/externalregistrationreturn.php', $returnurlparams);
329     $returnurl = $url->out(false);
331     $requestparams['launch_presentation_return_url'] = $returnurl;
333     return $requestparams;
336 /**
337  * Build source ID
338  *
339  * @param int $instanceid
340  * @param int $userid
341  * @param string $servicesalt
342  * @param null|int $typeid
343  * @param null|int $launchid
344  * @return stdClass
345  */
346 function lti_build_sourcedid($instanceid, $userid, $servicesalt, $typeid = null, $launchid = null) {
347     $data = new \stdClass();
349     $data->instanceid = $instanceid;
350     $data->userid = $userid;
351     $data->typeid = $typeid;
352     if (!empty($launchid)) {
353         $data->launchid = $launchid;
354     } else {
355         $data->launchid = mt_rand();
356     }
358     $json = json_encode($data);
360     $hash = hash('sha256', $json . $servicesalt, false);
362     $container = new \stdClass();
363     $container->data = $data;
364     $container->hash = $hash;
366     return $container;
369 /**
370  * This function builds the request that must be sent to the tool producer
371  *
372  * @param object    $instance       Basic LTI instance object
373  * @param array     $typeconfig     Basic LTI tool configuration
374  * @param object    $course         Course object
375  * @param int|null  $typeid         Basic LTI tool ID
376  * @param boolean   $islti2         True if an LTI 2 tool is being launched
377  *
378  * @return array                    Request details
379  */
380 function lti_build_request($instance, $typeconfig, $course, $typeid = null, $islti2 = false) {
381     global $USER, $CFG;
383     if (empty($instance->cmid)) {
384         $instance->cmid = 0;
385     }
387     $role = lti_get_ims_role($USER, $instance->cmid, $instance->course, $islti2);
389     $requestparams = array(
390         'user_id' => $USER->id,
391         'lis_person_sourcedid' => $USER->idnumber,
392         'roles' => $role,
393         'context_id' => $course->id,
394         'context_label' => trim(html_to_text($course->shortname, 0)),
395         'context_title' => trim(html_to_text($course->fullname, 0)),
396     );
397     if (!empty($instance->name)) {
398         $requestparams['resource_link_title'] = trim(html_to_text($instance->name, 0));
399     }
400     if (!empty($instance->cmid)) {
401         $intro = format_module_intro('lti', $instance, $instance->cmid);
402         $intro = trim(html_to_text($intro, 0, false));
404         // This may look weird, but this is required for new lines
405         // so we generate the same OAuth signature as the tool provider.
406         $intro = str_replace("\n", "\r\n", $intro);
407         $requestparams['resource_link_description'] = $intro;
408     }
409     if (!empty($instance->id)) {
410         $requestparams['resource_link_id'] = $instance->id;
411     }
412     if (!empty($instance->resource_link_id)) {
413         $requestparams['resource_link_id'] = $instance->resource_link_id;
414     }
415     if ($course->format == 'site') {
416         $requestparams['context_type'] = 'Group';
417     } else {
418         $requestparams['context_type'] = 'CourseSection';
419         $requestparams['lis_course_section_sourcedid'] = $course->idnumber;
420     }
422     if (!empty($instance->id) && !empty($instance->servicesalt) && ($islti2 ||
423             $typeconfig['acceptgrades'] == LTI_SETTING_ALWAYS ||
424             ($typeconfig['acceptgrades'] == LTI_SETTING_DELEGATE && $instance->instructorchoiceacceptgrades == LTI_SETTING_ALWAYS))
425     ) {
426         $placementsecret = $instance->servicesalt;
427         $sourcedid = json_encode(lti_build_sourcedid($instance->id, $USER->id, $placementsecret, $typeid));
428         $requestparams['lis_result_sourcedid'] = $sourcedid;
430         // Add outcome service URL.
431         $serviceurl = new \moodle_url('/mod/lti/service.php');
432         $serviceurl = $serviceurl->out();
434         $forcessl = false;
435         if (!empty($CFG->mod_lti_forcessl)) {
436             $forcessl = true;
437         }
439         if ((isset($typeconfig['forcessl']) && ($typeconfig['forcessl'] == '1')) or $forcessl) {
440             $serviceurl = lti_ensure_url_is_https($serviceurl);
441         }
443         $requestparams['lis_outcome_service_url'] = $serviceurl;
444     }
446     // Send user's name and email data if appropriate.
447     if ($islti2 || $typeconfig['sendname'] == LTI_SETTING_ALWAYS ||
448         ($typeconfig['sendname'] == LTI_SETTING_DELEGATE && isset($instance->instructorchoicesendname)
449             && $instance->instructorchoicesendname == LTI_SETTING_ALWAYS)
450     ) {
451         $requestparams['lis_person_name_given'] = $USER->firstname;
452         $requestparams['lis_person_name_family'] = $USER->lastname;
453         $requestparams['lis_person_name_full'] = $USER->firstname . ' ' . $USER->lastname;
454         $requestparams['ext_user_username'] = $USER->username;
455     }
457     if ($islti2 || $typeconfig['sendemailaddr'] == LTI_SETTING_ALWAYS ||
458         ($typeconfig['sendemailaddr'] == LTI_SETTING_DELEGATE && isset($instance->instructorchoicesendemailaddr)
459             && $instance->instructorchoicesendemailaddr == LTI_SETTING_ALWAYS)
460     ) {
461         $requestparams['lis_person_contact_email_primary'] = $USER->email;
462     }
464     return $requestparams;
467 /**
468  * This function builds the request that must be sent to an LTI 2 tool provider
469  *
470  * @param object    $tool           Basic LTI tool object
471  * @param array     $params         Custom launch parameters
472  *
473  * @return array                    Request details
474  */
475 function lti_build_request_lti2($tool, $params) {
477     $requestparams = array();
479     $capabilities = lti_get_capabilities();
480     $enabledcapabilities = explode("\n", $tool->enabledcapability);
481     foreach ($enabledcapabilities as $capability) {
482         if (array_key_exists($capability, $capabilities)) {
483             $val = $capabilities[$capability];
484             if ($val && (substr($val, 0, 1) != '$')) {
485                 if (isset($params[$val])) {
486                     $requestparams[$capabilities[$capability]] = $params[$capabilities[$capability]];
487                 }
488             }
489         }
490     }
492     return $requestparams;
496 /**
497  * This function builds the standard parameters for an LTI 1 or 2 request that must be sent to the tool producer
498  *
499  * @param stdClass  $instance       Basic LTI instance object
500  * @param string    $orgid          Organisation ID
501  * @param boolean   $islti2         True if an LTI 2 tool is being launched
502  * @param string    $messagetype    The request message type. Defaults to basic-lti-launch-request if empty.
503  *
504  * @return array                    Request details
505  */
506 function lti_build_standard_request($instance, $orgid, $islti2, $messagetype = 'basic-lti-launch-request') {
507     global $CFG;
509     $requestparams = array();
511     if ($instance) {
512         $requestparams['resource_link_id'] = $instance->id;
513         if (property_exists($instance, 'resource_link_id') and !empty($instance->resource_link_id)) {
514             $requestparams['resource_link_id'] = $instance->resource_link_id;
515         }
516     }
518     $requestparams['launch_presentation_locale'] = current_language();
520     // Make sure we let the tool know what LMS they are being called from.
521     $requestparams['ext_lms'] = 'moodle-2';
522     $requestparams['tool_consumer_info_product_family_code'] = 'moodle';
523     $requestparams['tool_consumer_info_version'] = strval($CFG->version);
525     // Add oauth_callback to be compliant with the 1.0A spec.
526     $requestparams['oauth_callback'] = 'about:blank';
528     if (!$islti2) {
529         $requestparams['lti_version'] = 'LTI-1p0';
530     } else {
531         $requestparams['lti_version'] = 'LTI-2p0';
532     }
533     $requestparams['lti_message_type'] = $messagetype;
535     if ($orgid) {
536         $requestparams["tool_consumer_instance_guid"] = $orgid;
537     }
538     if (!empty($CFG->mod_lti_institution_name)) {
539         $requestparams['tool_consumer_instance_name'] = trim(html_to_text($CFG->mod_lti_institution_name, 0));
540     } else {
541         $requestparams['tool_consumer_instance_name'] = get_site()->shortname;
542     }
543     $requestparams['tool_consumer_instance_description'] = trim(html_to_text(get_site()->fullname, 0));
545     return $requestparams;
548 /**
549  * This function builds the custom parameters
550  *
551  * @param object    $toolproxy      Tool proxy instance object
552  * @param object    $tool           Tool instance object
553  * @param object    $instance       Tool placement instance object
554  * @param array     $params         LTI launch parameters
555  * @param string    $customstr      Custom parameters defined for tool
556  * @param string    $instructorcustomstr      Custom parameters defined for this placement
557  * @param boolean   $islti2         True if an LTI 2 tool is being launched
558  *
559  * @return array                    Custom parameters
560  */
561 function lti_build_custom_parameters($toolproxy, $tool, $instance, $params, $customstr, $instructorcustomstr, $islti2) {
563     // Concatenate the custom parameters from the administrator and the instructor
564     // Instructor parameters are only taken into consideration if the administrator
565     // has given permission.
566     $custom = array();
567     if ($customstr) {
568         $custom = lti_split_custom_parameters($toolproxy, $tool, $params, $customstr, $islti2);
569     }
570     if ($instructorcustomstr) {
571         $custom = array_merge(lti_split_custom_parameters($toolproxy, $tool, $params,
572             $instructorcustomstr, $islti2), $custom);
573     }
574     if ($islti2) {
575         $custom = array_merge(lti_split_custom_parameters($toolproxy, $tool, $params,
576             $tool->parameter, true), $custom);
577         $settings = lti_get_tool_settings($tool->toolproxyid);
578         $custom = array_merge($custom, lti_get_custom_parameters($toolproxy, $tool, $params, $settings));
579         if (!empty($instance->course)) {
580             $settings = lti_get_tool_settings($tool->toolproxyid, $instance->course);
581             $custom = array_merge($custom, lti_get_custom_parameters($toolproxy, $tool, $params, $settings));
582             if (!empty($instance->id)) {
583                 $settings = lti_get_tool_settings($tool->toolproxyid, $instance->course, $instance->id);
584                 $custom = array_merge($custom, lti_get_custom_parameters($toolproxy, $tool, $params, $settings));
585             }
586         }
587     }
589     return $custom;
592 /**
593  * Builds a standard LTI Content-Item selection request.
594  *
595  * @param int $id The tool type ID.
596  * @param stdClass $course The course object.
597  * @param moodle_url $returnurl The return URL in the tool consumer (TC) that the tool provider (TP)
598  *                              will use to return the Content-Item message.
599  * @param string $title The tool's title, if available.
600  * @param string $text The text to display to represent the content item. This value may be a long description of the content item.
601  * @param array $mediatypes Array of MIME types types supported by the TC. If empty, the TC will support ltilink by default.
602  * @param array $presentationtargets Array of ways in which the selected content item(s) can be requested to be opened
603  *                                   (via the presentationDocumentTarget element for a returned content item).
604  *                                   If empty, "frame", "iframe", and "window" will be supported by default.
605  * @param bool $autocreate Indicates whether any content items returned by the TP would be automatically persisted without
606  * @param bool $multiple Indicates whether the user should be permitted to select more than one item. False by default.
607  *                         any option for the user to cancel the operation. False by default.
608  * @param bool $unsigned Indicates whether the TC is willing to accept an unsigned return message, or not.
609  *                       A signed message should always be required when the content item is being created automatically in the
610  *                       TC without further interaction from the user. False by default.
611  * @param bool $canconfirm Flag for can_confirm parameter. False by default.
612  * @param bool $copyadvice Indicates whether the TC is able and willing to make a local copy of a content item. False by default.
613  * @return stdClass The object containing the signed request parameters and the URL to the TP's Content-Item selection interface.
614  * @throws moodle_exception When the LTI tool type does not exist.`
615  * @throws coding_exception For invalid media type and presentation target parameters.
616  */
617 function lti_build_content_item_selection_request($id, $course, moodle_url $returnurl, $title = '', $text = '', $mediatypes = [],
618                                                   $presentationtargets = [], $autocreate = false, $multiple = false,
619                                                   $unsigned = false, $canconfirm = false, $copyadvice = false) {
620     $tool = lti_get_type($id);
621     // Validate parameters.
622     if (!$tool) {
623         throw new moodle_exception('errortooltypenotfound', 'mod_lti');
624     }
625     if (!is_array($mediatypes)) {
626         throw new coding_exception('The list of accepted media types should be in an array');
627     }
628     if (!is_array($presentationtargets)) {
629         throw new coding_exception('The list of accepted presentation targets should be in an array');
630     }
632     // Check title. If empty, use the tool's name.
633     if (empty($title)) {
634         $title = $tool->name;
635     }
637     $typeconfig = lti_get_type_config($id);
638     $key = '';
639     $secret = '';
640     $islti2 = false;
641     if (isset($tool->toolproxyid)) {
642         $islti2 = true;
643         $toolproxy = lti_get_tool_proxy($tool->toolproxyid);
644         $key = $toolproxy->guid;
645         $secret = $toolproxy->secret;
646     } else {
647         $toolproxy = null;
648         if (!empty($typeconfig['resourcekey'])) {
649             $key = $typeconfig['resourcekey'];
650         }
651         if (!empty($typeconfig['password'])) {
652             $secret = $typeconfig['password'];
653         }
654     }
655     $tool->enabledcapability = '';
656     if (!empty($typeconfig['enabledcapability_ContentItemSelectionRequest'])) {
657         $tool->enabledcapability = $typeconfig['enabledcapability_ContentItemSelectionRequest'];
658     }
660     $tool->parameter = '';
661     if (!empty($typeconfig['parameter_ContentItemSelectionRequest'])) {
662         $tool->parameter = $typeconfig['parameter_ContentItemSelectionRequest'];
663     }
665     // Set the tool URL.
666     if (!empty($typeconfig['toolurl_ContentItemSelectionRequest'])) {
667         $toolurl = new moodle_url($typeconfig['toolurl_ContentItemSelectionRequest']);
668     } else {
669         $toolurl = new moodle_url($typeconfig['toolurl']);
670     }
672     // Check if SSL is forced.
673     if (!empty($typeconfig['forcessl'])) {
674         // Make sure the tool URL is set to https.
675         if (strtolower($toolurl->get_scheme()) === 'http') {
676             $toolurl->set_scheme('https');
677         }
678         // Make sure the return URL is set to https.
679         if (strtolower($returnurl->get_scheme()) === 'http') {
680             $returnurl->set_scheme('https');
681         }
682     }
683     $toolurlout = $toolurl->out(false);
685     // Get base request parameters.
686     $instance = new stdClass();
687     $instance->course = $course->id;
688     $requestparams = lti_build_request($instance, $typeconfig, $course, $id, $islti2);
690     // Get LTI2-specific request parameters and merge to the request parameters if applicable.
691     if ($islti2) {
692         $lti2params = lti_build_request_lti2($tool, $requestparams);
693         $requestparams = array_merge($requestparams, $lti2params);
694     }
696     // Get standard request parameters and merge to the request parameters.
697     $orgid = !empty($typeconfig['organizationid']) ? $typeconfig['organizationid'] : '';
698     $standardparams = lti_build_standard_request(null, $orgid, $islti2, 'ContentItemSelectionRequest');
699     $requestparams = array_merge($requestparams, $standardparams);
701     // Get custom request parameters and merge to the request parameters.
702     $customstr = '';
703     if (!empty($typeconfig['customparameters'])) {
704         $customstr = $typeconfig['customparameters'];
705     }
706     $customparams = lti_build_custom_parameters($toolproxy, $tool, $instance, $requestparams, $customstr, '', $islti2);
707     $requestparams = array_merge($requestparams, $customparams);
709     // Allow request params to be updated by sub-plugins.
710     $plugins = core_component::get_plugin_list('ltisource');
711     foreach (array_keys($plugins) as $plugin) {
712         $pluginparams = component_callback('ltisource_' . $plugin, 'before_launch', [$instance, $toolurlout, $requestparams], []);
714         if (!empty($pluginparams) && is_array($pluginparams)) {
715             $requestparams = array_merge($requestparams, $pluginparams);
716         }
717     }
719     // Media types. Set to ltilink by default if empty.
720     if (empty($mediatypes)) {
721         $mediatypes = [
722             'application/vnd.ims.lti.v1.ltilink',
723         ];
724     }
725     $requestparams['accept_media_types'] = implode(',', $mediatypes);
727     // Presentation targets. Supports frame, iframe, window by default if empty.
728     if (empty($presentationtargets)) {
729         $presentationtargets = [
730             'frame',
731             'iframe',
732             'window',
733         ];
734     }
735     $requestparams['accept_presentation_document_targets'] = implode(',', $presentationtargets);
737     // Other request parameters.
738     $requestparams['accept_copy_advice'] = $copyadvice === true ? 'true' : 'false';
739     $requestparams['accept_multiple'] = $multiple === true ? 'true' : 'false';
740     $requestparams['accept_unsigned'] = $unsigned === true ? 'true' : 'false';
741     $requestparams['auto_create'] = $autocreate === true ? 'true' : 'false';
742     $requestparams['can_confirm'] = $canconfirm === true ? 'true' : 'false';
743     $requestparams['content_item_return_url'] = $returnurl->out(false);
744     $requestparams['title'] = $title;
745     $requestparams['text'] = $text;
746     $signedparams = lti_sign_parameters($requestparams, $toolurlout, 'POST', $key, $secret);
747     $toolurlparams = $toolurl->params();
749     // Strip querystring params in endpoint url from $signedparams to avoid duplication.
750     if (!empty($toolurlparams) && !empty($signedparams)) {
751         foreach (array_keys($toolurlparams) as $paramname) {
752             if (isset($signedparams[$paramname])) {
753                 unset($signedparams[$paramname]);
754             }
755         }
756     }
758     // Check for params that should not be passed. Unset if they are set.
759     $unwantedparams = [
760         'resource_link_id',
761         'resource_link_title',
762         'resource_link_description',
763         'launch_presentation_return_url',
764         'lis_result_sourcedid',
765     ];
766     foreach ($unwantedparams as $param) {
767         if (isset($signedparams[$param])) {
768             unset($signedparams[$param]);
769         }
770     }
772     // Prepare result object.
773     $result = new stdClass();
774     $result->params = $signedparams;
775     $result->url = $toolurlout;
777     return $result;
780 /**
781  * Processes the tool provider's response to the ContentItemSelectionRequest and builds the configuration data from the
782  * selected content item. This configuration data can be then used when adding a tool into the course.
783  *
784  * @param int $typeid The tool type ID.
785  * @param string $messagetype The value for the lti_message_type parameter.
786  * @param string $ltiversion The value for the lti_version parameter.
787  * @param string $consumerkey The consumer key.
788  * @param string $contentitemsjson The JSON string for the content_items parameter.
789  * @return stdClass The array of module information objects.
790  * @throws moodle_exception
791  * @throws lti\OAuthException
792  */
793 function lti_tool_configuration_from_content_item($typeid, $messagetype, $ltiversion, $consumerkey, $contentitemsjson) {
794     $tool = lti_get_type($typeid);
795     // Validate parameters.
796     if (!$tool) {
797         throw new moodle_exception('errortooltypenotfound', 'mod_lti');
798     }
799     // Check lti_message_type. Show debugging if it's not set to ContentItemSelection.
800     // No need to throw exceptions for now since lti_message_type does not seem to be used in this processing at the moment.
801     if ($messagetype !== 'ContentItemSelection') {
802         debugging("lti_message_type is invalid: {$messagetype}. It should be set to 'ContentItemSelection'.",
803             DEBUG_DEVELOPER);
804     }
806     $typeconfig = lti_get_type_config($typeid);
808     if (isset($tool->toolproxyid)) {
809         $islti2 = true;
810         $toolproxy = lti_get_tool_proxy($tool->toolproxyid);
811         $key = $toolproxy->guid;
812         $secret = $toolproxy->secret;
813     } else {
814         $islti2 = false;
815         $toolproxy = null;
816         if (!empty($typeconfig['resourcekey'])) {
817             $key = $typeconfig['resourcekey'];
818         } else {
819             $key = '';
820         }
821         if (!empty($typeconfig['password'])) {
822             $secret = $typeconfig['password'];
823         } else {
824             $secret = '';
825         }
826     }
828     // Check LTI versions from our side and the response's side. Show debugging if they don't match.
829     // No need to throw exceptions for now since LTI version does not seem to be used in this processing at the moment.
830     $expectedversion = LTI_VERSION_1;
831     if ($islti2) {
832         $expectedversion = LTI_VERSION_2;
833     }
834     if ($ltiversion !== $expectedversion) {
835         debugging("lti_version from response does not match the tool's configuration. Tool: {$expectedversion}," .
836             " Response: {$ltiversion}", DEBUG_DEVELOPER);
837     }
839     if ($consumerkey !== $key) {
840         throw new moodle_exception('errorincorrectconsumerkey', 'mod_lti');
841     }
843     $store = new lti\TrivialOAuthDataStore();
844     $store->add_consumer($key, $secret);
845     $server = new lti\OAuthServer($store);
846     $method = new lti\OAuthSignatureMethod_HMAC_SHA1();
847     $server->add_signature_method($method);
848     $request = lti\OAuthRequest::from_request();
849     try {
850         $server->verify_request($request);
851     } catch (lti\OAuthException $e) {
852         throw new lti\OAuthException("OAuth signature failed: " . $e->getMessage());
853     }
855     $items = json_decode($contentitemsjson);
856     if (empty($items)) {
857         throw new moodle_exception('errorinvaliddata', 'mod_lti', '', $contentitemsjson);
858     }
859     if ($items->{'@context'} !== 'http://purl.imsglobal.org/ctx/lti/v1/ContentItem') {
860         throw new moodle_exception('errorinvalidmediatype', 'mod_lti', '', $items->{'@context'});
861     }
862     if (!isset($items->{'@graph'}) || !is_array($items->{'@graph'}) || (count($items->{'@graph'}) > 1)) {
863         throw new moodle_exception('errorinvalidresponseformat', 'mod_lti');
864     }
866     $config = null;
867     if (!empty($items->{'@graph'})) {
868         $item = $items->{'@graph'}[0];
870         $config = new stdClass();
871         $config->name = '';
872         if (isset($item->title)) {
873             $config->name = $item->title;
874         }
875         if (empty($config->name)) {
876             $config->name = $tool->name;
877         }
878         if (isset($item->text)) {
879             $config->introeditor = [
880                 'text' => $item->text,
881                 'format' => FORMAT_PLAIN
882             ];
883         }
884         if (isset($item->icon->{'@id'})) {
885             $iconurl = new moodle_url($item->icon->{'@id'});
886             // Assign item's icon URL to secureicon or icon depending on its scheme.
887             if (strtolower($iconurl->get_scheme()) === 'https') {
888                 $config->secureicon = $iconurl->out(false);
889             } else {
890                 $config->icon = $iconurl->out(false);
891             }
892         }
893         if (isset($item->url)) {
894             $url = new moodle_url($item->url);
895             $config->toolurl = $url->out(false);
896             $config->typeid = 0;
897         } else {
898             $config->typeid = $typeid;
899         }
900         $config->instructorchoicesendname = LTI_SETTING_NEVER;
901         $config->instructorchoicesendemailaddr = LTI_SETTING_NEVER;
902         $config->instructorchoiceacceptgrades = LTI_SETTING_NEVER;
903         $config->launchcontainer = LTI_LAUNCH_CONTAINER_DEFAULT;
904         if (isset($item->placementAdvice->presentationDocumentTarget)) {
905             if ($item->placementAdvice->presentationDocumentTarget === 'window') {
906                 $config->launchcontainer = LTI_LAUNCH_CONTAINER_WINDOW;
907             } else if ($item->placementAdvice->presentationDocumentTarget === 'frame') {
908                 $config->launchcontainer = LTI_LAUNCH_CONTAINER_EMBED_NO_BLOCKS;
909             } else if ($item->placementAdvice->presentationDocumentTarget === 'iframe') {
910                 $config->launchcontainer = LTI_LAUNCH_CONTAINER_EMBED;
911             }
912         }
913         if (isset($item->custom)) {
914             $customparameters = [];
915             foreach ($item->custom as $key => $value) {
916                 $customparameters[] = "{$key}={$value}";
917             }
918             $config->instructorcustomparameters = implode("\n", $customparameters);
919         }
920     }
921     return $config;
924 function lti_get_tool_table($tools, $id) {
925     global $CFG, $OUTPUT, $USER;
926     $html = '';
928     $typename = get_string('typename', 'lti');
929     $baseurl = get_string('baseurl', 'lti');
930     $action = get_string('action', 'lti');
931     $createdon = get_string('createdon', 'lti');
933     if (!empty($tools)) {
934         $html .= "
935         <div id=\"{$id}_tools_container\" style=\"margin-top:.5em;margin-bottom:.5em\">
936             <table id=\"{$id}_tools\">
937                 <thead>
938                     <tr>
939                         <th>$typename</th>
940                         <th>$baseurl</th>
941                         <th>$createdon</th>
942                         <th>$action</th>
943                     </tr>
944                 </thead>
945         ";
947         foreach ($tools as $type) {
948             $date = userdate($type->timecreated, get_string('strftimedatefullshort', 'core_langconfig'));
949             $accept = get_string('accept', 'lti');
950             $update = get_string('update', 'lti');
951             $delete = get_string('delete', 'lti');
953             if (empty($type->toolproxyid)) {
954                 $baseurl = new \moodle_url('/mod/lti/typessettings.php', array(
955                         'action' => 'accept',
956                         'id' => $type->id,
957                         'sesskey' => sesskey(),
958                         'tab' => $id
959                     ));
960                 $ref = $type->baseurl;
961             } else {
962                 $baseurl = new \moodle_url('/mod/lti/toolssettings.php', array(
963                         'action' => 'accept',
964                         'id' => $type->id,
965                         'sesskey' => sesskey(),
966                         'tab' => $id
967                     ));
968                 $ref = $type->tpname;
969             }
971             $accepthtml = $OUTPUT->action_icon($baseurl,
972                     new \pix_icon('t/check', $accept, '', array('class' => 'iconsmall')), null,
973                     array('title' => $accept, 'class' => 'editing_accept'));
975             $deleteaction = 'delete';
977             if ($type->state == LTI_TOOL_STATE_CONFIGURED) {
978                 $accepthtml = '';
979             }
981             if ($type->state != LTI_TOOL_STATE_REJECTED) {
982                 $deleteaction = 'reject';
983                 $delete = get_string('reject', 'lti');
984             }
986             $updateurl = clone($baseurl);
987             $updateurl->param('action', 'update');
988             $updatehtml = $OUTPUT->action_icon($updateurl,
989                     new \pix_icon('t/edit', $update, '', array('class' => 'iconsmall')), null,
990                     array('title' => $update, 'class' => 'editing_update'));
992             if (($type->state != LTI_TOOL_STATE_REJECTED) || empty($type->toolproxyid)) {
993                 $deleteurl = clone($baseurl);
994                 $deleteurl->param('action', $deleteaction);
995                 $deletehtml = $OUTPUT->action_icon($deleteurl,
996                         new \pix_icon('t/delete', $delete, '', array('class' => 'iconsmall')), null,
997                         array('title' => $delete, 'class' => 'editing_delete'));
998             } else {
999                 $deletehtml = '';
1000             }
1001             $html .= "
1002             <tr>
1003                 <td>
1004                     {$type->name}
1005                 </td>
1006                 <td>
1007                     {$ref}
1008                 </td>
1009                 <td>
1010                     {$date}
1011                 </td>
1012                 <td align=\"center\">
1013                     {$accepthtml}{$updatehtml}{$deletehtml}
1014                 </td>
1015             </tr>
1016             ";
1017         }
1018         $html .= '</table></div>';
1019     } else {
1020         $html .= get_string('no_' . $id, 'lti');
1021     }
1023     return $html;
1026 /**
1027  * This function builds the tab for a category of tool proxies
1028  *
1029  * @param object    $toolproxies    Tool proxy instance objects
1030  * @param string    $id             Category ID
1031  *
1032  * @return string                   HTML for tab
1033  */
1034 function lti_get_tool_proxy_table($toolproxies, $id) {
1035     global $OUTPUT;
1037     if (!empty($toolproxies)) {
1038         $typename = get_string('typename', 'lti');
1039         $url = get_string('registrationurl', 'lti');
1040         $action = get_string('action', 'lti');
1041         $createdon = get_string('createdon', 'lti');
1043         $html = <<< EOD
1044         <div id="{$id}_tool_proxies_container" style="margin-top: 0.5em; margin-bottom: 0.5em">
1045             <table id="{$id}_tool_proxies">
1046                 <thead>
1047                     <tr>
1048                         <th>{$typename}</th>
1049                         <th>{$url}</th>
1050                         <th>{$createdon}</th>
1051                         <th>{$action}</th>
1052                     </tr>
1053                 </thead>
1054 EOD;
1055         foreach ($toolproxies as $toolproxy) {
1056             $date = userdate($toolproxy->timecreated, get_string('strftimedatefullshort', 'core_langconfig'));
1057             $accept = get_string('register', 'lti');
1058             $update = get_string('update', 'lti');
1059             $delete = get_string('delete', 'lti');
1061             $baseurl = new \moodle_url('/mod/lti/registersettings.php', array(
1062                     'action' => 'accept',
1063                     'id' => $toolproxy->id,
1064                     'sesskey' => sesskey(),
1065                     'tab' => $id
1066                 ));
1068             $registerurl = new \moodle_url('/mod/lti/register.php', array(
1069                     'id' => $toolproxy->id,
1070                     'sesskey' => sesskey(),
1071                     'tab' => 'tool_proxy'
1072                 ));
1074             $accepthtml = $OUTPUT->action_icon($registerurl,
1075                     new \pix_icon('t/check', $accept, '', array('class' => 'iconsmall')), null,
1076                     array('title' => $accept, 'class' => 'editing_accept'));
1078             $deleteaction = 'delete';
1080             if ($toolproxy->state != LTI_TOOL_PROXY_STATE_CONFIGURED) {
1081                 $accepthtml = '';
1082             }
1084             if (($toolproxy->state == LTI_TOOL_PROXY_STATE_CONFIGURED) || ($toolproxy->state == LTI_TOOL_PROXY_STATE_PENDING)) {
1085                 $delete = get_string('cancel', 'lti');
1086             }
1088             $updateurl = clone($baseurl);
1089             $updateurl->param('action', 'update');
1090             $updatehtml = $OUTPUT->action_icon($updateurl,
1091                     new \pix_icon('t/edit', $update, '', array('class' => 'iconsmall')), null,
1092                     array('title' => $update, 'class' => 'editing_update'));
1094             $deleteurl = clone($baseurl);
1095             $deleteurl->param('action', $deleteaction);
1096             $deletehtml = $OUTPUT->action_icon($deleteurl,
1097                     new \pix_icon('t/delete', $delete, '', array('class' => 'iconsmall')), null,
1098                     array('title' => $delete, 'class' => 'editing_delete'));
1099             $html .= <<< EOD
1100             <tr>
1101                 <td>
1102                     {$toolproxy->name}
1103                 </td>
1104                 <td>
1105                     {$toolproxy->regurl}
1106                 </td>
1107                 <td>
1108                     {$date}
1109                 </td>
1110                 <td align="center">
1111                     {$accepthtml}{$updatehtml}{$deletehtml}
1112                 </td>
1113             </tr>
1114 EOD;
1115         }
1116         $html .= '</table></div>';
1117     } else {
1118         $html = get_string('no_' . $id, 'lti');
1119     }
1121     return $html;
1124 /**
1125  * Extracts the enabled capabilities into an array, including those implicitly declared in a parameter
1126  *
1127  * @param object    $tool           Tool instance object
1128  *
1129  * @return Array of enabled capabilities
1130  */
1131 function lti_get_enabled_capabilities($tool) {
1132     if (!isset($tool)) {
1133         return array();
1134     }
1135     if (!empty($tool->enabledcapability)) {
1136         $enabledcapabilities = explode("\n", $tool->enabledcapability);
1137     } else {
1138         $enabledcapabilities = array();
1139     }
1140     $paramstr = str_replace("\r\n", "\n", $tool->parameter);
1141     $paramstr = str_replace("\n\r", "\n", $paramstr);
1142     $paramstr = str_replace("\r", "\n", $paramstr);
1143     $params = explode("\n", $paramstr);
1144     foreach ($params as $param) {
1145         $pos = strpos($param, '=');
1146         if (($pos === false) || ($pos < 1)) {
1147             continue;
1148         }
1149         $value = trim(core_text::substr($param, $pos + 1, strlen($param)));
1150         if (substr($value, 0, 1) == '$') {
1151             $value = substr($value, 1);
1152             if (!in_array($value, $enabledcapabilities)) {
1153                 $enabledcapabilities[] = $value;
1154             }
1155         }
1156     }
1157     return $enabledcapabilities;
1160 /**
1161  * Splits the custom parameters field to the various parameters
1162  *
1163  * @param object    $toolproxy      Tool proxy instance object
1164  * @param object    $tool           Tool instance object
1165  * @param array     $params         LTI launch parameters
1166  * @param string    $customstr      String containing the parameters
1167  * @param boolean   $islti2         True if an LTI 2 tool is being launched
1168  *
1169  * @return array of custom parameters
1170  */
1171 function lti_split_custom_parameters($toolproxy, $tool, $params, $customstr, $islti2 = false) {
1172     $customstr = str_replace("\r\n", "\n", $customstr);
1173     $customstr = str_replace("\n\r", "\n", $customstr);
1174     $customstr = str_replace("\r", "\n", $customstr);
1175     $lines = explode("\n", $customstr);  // Or should this split on "/[\n;]/"?
1176     $retval = array();
1177     foreach ($lines as $line) {
1178         $pos = strpos($line, '=');
1179         if ( $pos === false || $pos < 1 ) {
1180             continue;
1181         }
1182         $key = trim(core_text::substr($line, 0, $pos));
1183         $key = lti_map_keyname($key, false);
1184         $val = trim(core_text::substr($line, $pos + 1, strlen($line)));
1185         $val = lti_parse_custom_parameter($toolproxy, $tool, $params, $val, $islti2);
1186         $key2 = lti_map_keyname($key);
1187         $retval['custom_'.$key2] = $val;
1188         if ($key != $key2) {
1189             $retval['custom_'.$key] = $val;
1190         }
1191     }
1192     return $retval;
1195 /**
1196  * Adds the custom parameters to an array
1197  *
1198  * @param object    $toolproxy      Tool proxy instance object
1199  * @param object    $tool           Tool instance object
1200  * @param array     $params         LTI launch parameters
1201  * @param array     $parameters     Array containing the parameters
1202  *
1203  * @return array    Array of custom parameters
1204  */
1205 function lti_get_custom_parameters($toolproxy, $tool, $params, $parameters) {
1206     $retval = array();
1207     foreach ($parameters as $key => $val) {
1208         $key2 = lti_map_keyname($key);
1209         $val = lti_parse_custom_parameter($toolproxy, $tool, $params, $val, true);
1210         $retval['custom_'.$key2] = $val;
1211         if ($key != $key2) {
1212             $retval['custom_'.$key] = $val;
1213         }
1214     }
1215     return $retval;
1218 /**
1219  * Parse a custom parameter to replace any substitution variables
1220  *
1221  * @param object    $toolproxy      Tool proxy instance object
1222  * @param object    $tool           Tool instance object
1223  * @param array     $params         LTI launch parameters
1224  * @param string    $value          Custom parameter value
1225  * @param boolean   $islti2         True if an LTI 2 tool is being launched
1226  *
1227  * @return Parsed value of custom parameter
1228  */
1229 function lti_parse_custom_parameter($toolproxy, $tool, $params, $value, $islti2) {
1230     global $USER, $COURSE;
1232     if ($value) {
1233         if (substr($value, 0, 1) == '\\') {
1234             $value = substr($value, 1);
1235         } else if (substr($value, 0, 1) == '$') {
1236             $value1 = substr($value, 1);
1237             $enabledcapabilities = lti_get_enabled_capabilities($tool);
1238             if (!$islti2 || in_array($value1, $enabledcapabilities)) {
1239                 $capabilities = lti_get_capabilities();
1240                 if (array_key_exists($value1, $capabilities)) {
1241                     $val = $capabilities[$value1];
1242                     if ($val) {
1243                         if (substr($val, 0, 1) != '$') {
1244                             $value = $params[$val];
1245                         } else {
1246                             $valarr = explode('->', substr($val, 1), 2);
1247                             $value = "{${$valarr[0]}->{$valarr[1]}}";
1248                             $value = str_replace('<br />' , ' ', $value);
1249                             $value = str_replace('<br>' , ' ', $value);
1250                             $value = format_string($value);
1251                         }
1252                     } else {
1253                         $value = lti_calculate_custom_parameter($value1);
1254                     }
1255                 } else if ($islti2) {
1256                     $val = $value;
1257                     $services = lti_get_services();
1258                     foreach ($services as $service) {
1259                         $service->set_tool_proxy($toolproxy);
1260                         $value = $service->parse_value($val);
1261                         if ($val != $value) {
1262                             break;
1263                         }
1264                     }
1265                 }
1266             }
1267         }
1268     }
1269     return $value;
1272 /**
1273  * Calculates the value of a custom parameter that has not been specified earlier
1274  *
1275  * @param string    $value          Custom parameter value
1276  *
1277  * @return string Calculated value of custom parameter
1278  */
1279 function lti_calculate_custom_parameter($value) {
1280     global $USER, $COURSE;
1282     switch ($value) {
1283         case 'Moodle.Person.userGroupIds':
1284             return implode(",", groups_get_user_groups($COURSE->id, $USER->id)[0]);
1285     }
1286     return null;
1289 /**
1290  * Used for building the names of the different custom parameters
1291  *
1292  * @param string $key   Parameter name
1293  * @param bool $tolower Do we want to convert the key into lower case?
1294  * @return string       Processed name
1295  */
1296 function lti_map_keyname($key, $tolower = true) {
1297     $newkey = "";
1298     if ($tolower) {
1299         $key = core_text::strtolower(trim($key));
1300     }
1301     foreach (str_split($key) as $ch) {
1302         if ( ($ch >= 'a' && $ch <= 'z') || ($ch >= '0' && $ch <= '9') || (!$tolower && ($ch >= 'A' && $ch <= 'Z'))) {
1303             $newkey .= $ch;
1304         } else {
1305             $newkey .= '_';
1306         }
1307     }
1308     return $newkey;
1311 /**
1312  * Gets the IMS role string for the specified user and LTI course module.
1313  *
1314  * @param mixed    $user      User object or user id
1315  * @param int      $cmid      The course module id of the LTI activity
1316  * @param int      $courseid  The course id of the LTI activity
1317  * @param boolean  $islti2    True if an LTI 2 tool is being launched
1318  *
1319  * @return string A role string suitable for passing with an LTI launch
1320  */
1321 function lti_get_ims_role($user, $cmid, $courseid, $islti2) {
1322     $roles = array();
1324     if (empty($cmid)) {
1325         // If no cmid is passed, check if the user is a teacher in the course
1326         // This allows other modules to programmatically "fake" a launch without
1327         // a real LTI instance.
1328         $context = context_course::instance($courseid);
1330         if (has_capability('moodle/course:manageactivities', $context, $user)) {
1331             array_push($roles, 'Instructor');
1332         } else {
1333             array_push($roles, 'Learner');
1334         }
1335     } else {
1336         $context = context_module::instance($cmid);
1338         if (has_capability('mod/lti:manage', $context)) {
1339             array_push($roles, 'Instructor');
1340         } else {
1341             array_push($roles, 'Learner');
1342         }
1343     }
1345     if (is_siteadmin($user) || has_capability('mod/lti:admin', $context)) {
1346         // Make sure admins do not have the Learner role, then set admin role.
1347         $roles = array_diff($roles, array('Learner'));
1348         if (!$islti2) {
1349             array_push($roles, 'urn:lti:sysrole:ims/lis/Administrator', 'urn:lti:instrole:ims/lis/Administrator');
1350         } else {
1351             array_push($roles, 'http://purl.imsglobal.org/vocab/lis/v2/person#Administrator');
1352         }
1353     }
1355     return join(',', $roles);
1358 /**
1359  * Returns configuration details for the tool
1360  *
1361  * @param int $typeid   Basic LTI tool typeid
1362  *
1363  * @return array        Tool Configuration
1364  */
1365 function lti_get_type_config($typeid) {
1366     global $DB;
1368     $query = "SELECT name, value
1369                 FROM {lti_types_config}
1370                WHERE typeid = :typeid1
1371            UNION ALL
1372               SELECT 'toolurl' AS name, baseurl AS value
1373                 FROM {lti_types}
1374                WHERE id = :typeid2
1375            UNION ALL
1376               SELECT 'icon' AS name, icon AS value
1377                 FROM {lti_types}
1378                WHERE id = :typeid3
1379            UNION ALL
1380               SELECT 'secureicon' AS name, secureicon AS value
1381                 FROM {lti_types}
1382                WHERE id = :typeid4";
1384     $typeconfig = array();
1385     $configs = $DB->get_records_sql($query,
1386         array('typeid1' => $typeid, 'typeid2' => $typeid, 'typeid3' => $typeid, 'typeid4' => $typeid));
1388     if (!empty($configs)) {
1389         foreach ($configs as $config) {
1390             $typeconfig[$config->name] = $config->value;
1391         }
1392     }
1394     return $typeconfig;
1397 function lti_get_tools_by_url($url, $state, $courseid = null) {
1398     $domain = lti_get_domain_from_url($url);
1400     return lti_get_tools_by_domain($domain, $state, $courseid);
1403 function lti_get_tools_by_domain($domain, $state = null, $courseid = null) {
1404     global $DB, $SITE;
1406     $filters = array('tooldomain' => $domain);
1408     $statefilter = '';
1409     $coursefilter = '';
1411     if ($state) {
1412         $statefilter = 'AND state = :state';
1413     }
1415     if ($courseid && $courseid != $SITE->id) {
1416         $coursefilter = 'OR course = :courseid';
1417     }
1419     $query = "SELECT *
1420                 FROM {lti_types}
1421                WHERE tooldomain = :tooldomain
1422                  AND (course = :siteid $coursefilter)
1423                  $statefilter";
1425     return $DB->get_records_sql($query, array(
1426         'courseid' => $courseid,
1427         'siteid' => $SITE->id,
1428         'tooldomain' => $domain,
1429         'state' => $state
1430     ));
1433 /**
1434  * Returns all basicLTI tools configured by the administrator
1435  *
1436  */
1437 function lti_filter_get_types($course) {
1438     global $DB;
1440     if (!empty($course)) {
1441         $where = "WHERE t.course = :course";
1442         $params = array('course' => $course);
1443     } else {
1444         $where = '';
1445         $params = array();
1446     }
1447     $query = "SELECT t.id, t.name, t.baseurl, t.state, t.toolproxyid, t.timecreated, tp.name tpname
1448                 FROM {lti_types} t LEFT OUTER JOIN {lti_tool_proxies} tp ON t.toolproxyid = tp.id
1449                 {$where}";
1450     return $DB->get_records_sql($query, $params);
1453 /**
1454  * Given an array of tools, filter them based on their state
1455  *
1456  * @param array $tools An array of lti_types records
1457  * @param int $state One of the LTI_TOOL_STATE_* constants
1458  * @return array
1459  */
1460 function lti_filter_tool_types(array $tools, $state) {
1461     $return = array();
1462     foreach ($tools as $key => $tool) {
1463         if ($tool->state == $state) {
1464             $return[$key] = $tool;
1465         }
1466     }
1467     return $return;
1470 /**
1471  * Returns all lti types visible in this course
1472  *
1473  * @param int $courseid The id of the course to retieve types for
1474  * @param array $coursevisible options for 'coursevisible' field,
1475  *        default [LTI_COURSEVISIBLE_PRECONFIGURED, LTI_COURSEVISIBLE_ACTIVITYCHOOSER]
1476  * @return stdClass[] All the lti types visible in the given course
1477  */
1478 function lti_get_lti_types_by_course($courseid, $coursevisible = null) {
1479     global $DB, $SITE;
1481     if ($coursevisible === null) {
1482         $coursevisible = [LTI_COURSEVISIBLE_PRECONFIGURED, LTI_COURSEVISIBLE_ACTIVITYCHOOSER];
1483     }
1485     list($coursevisiblesql, $coursevisparams) = $DB->get_in_or_equal($coursevisible, SQL_PARAMS_NAMED, 'coursevisible');
1486     $query = "SELECT *
1487                 FROM {lti_types}
1488                WHERE coursevisible $coursevisiblesql
1489                  AND (course = :siteid OR course = :courseid)
1490                  AND state = :active";
1492     return $DB->get_records_sql($query,
1493         array('siteid' => $SITE->id, 'courseid' => $courseid, 'active' => LTI_TOOL_STATE_CONFIGURED) + $coursevisparams);
1496 /**
1497  * Returns tool types for lti add instance and edit page
1498  *
1499  * @return array Array of lti types
1500  */
1501 function lti_get_types_for_add_instance() {
1502     global $COURSE;
1503     $admintypes = lti_get_lti_types_by_course($COURSE->id);
1505     $types = array();
1506     $types[0] = (object)array('name' => get_string('automatic', 'lti'), 'course' => 0, 'toolproxyid' => null);
1508     foreach ($admintypes as $type) {
1509         $types[$type->id] = $type;
1510     }
1512     return $types;
1515 /**
1516  * Returns a list of configured types in the given course
1517  *
1518  * @param int $courseid The id of the course to retieve types for
1519  * @param int $sectionreturn section to return to for forming the URLs
1520  * @return array Array of lti types. Each element is object with properties: name, title, icon, help, helplink, link
1521  */
1522 function lti_get_configured_types($courseid, $sectionreturn = 0) {
1523     global $OUTPUT;
1524     $types = array();
1525     $admintypes = lti_get_lti_types_by_course($courseid, [LTI_COURSEVISIBLE_ACTIVITYCHOOSER]);
1527     foreach ($admintypes as $ltitype) {
1528         $type           = new stdClass();
1529         $type->modclass = MOD_CLASS_ACTIVITY;
1530         $type->name     = 'lti_type_' . $ltitype->id;
1531         // Clean the name. We don't want tags here.
1532         $type->title    = clean_param($ltitype->name, PARAM_NOTAGS);
1533         $trimmeddescription = trim($ltitype->description);
1534         if ($trimmeddescription != '') {
1535             // Clean the description. We don't want tags here.
1536             $type->help     = clean_param($trimmeddescription, PARAM_NOTAGS);
1537             $type->helplink = get_string('modulename_shortcut_link', 'lti');
1538         }
1539         if (empty($ltitype->icon)) {
1540             $type->icon = $OUTPUT->pix_icon('icon', '', 'lti', array('class' => 'icon'));
1541         } else {
1542             $type->icon = html_writer::empty_tag('img', array('src' => $ltitype->icon, 'alt' => $ltitype->name, 'class' => 'icon'));
1543         }
1544         $type->link = new moodle_url('/course/modedit.php', array('add' => 'lti', 'return' => 0, 'course' => $courseid,
1545             'sr' => $sectionreturn, 'typeid' => $ltitype->id));
1546         $types[] = $type;
1547     }
1548     return $types;
1551 function lti_get_domain_from_url($url) {
1552     $matches = array();
1554     if (preg_match(LTI_URL_DOMAIN_REGEX, $url, $matches)) {
1555         return $matches[1];
1556     }
1559 function lti_get_tool_by_url_match($url, $courseid = null, $state = LTI_TOOL_STATE_CONFIGURED) {
1560     $possibletools = lti_get_tools_by_url($url, $state, $courseid);
1562     return lti_get_best_tool_by_url($url, $possibletools, $courseid);
1565 function lti_get_url_thumbprint($url) {
1566     // Parse URL requires a schema otherwise everything goes into 'path'.  Fixed 5.4.7 or later.
1567     if (preg_match('/https?:\/\//', $url) !== 1) {
1568         $url = 'http://'.$url;
1569     }
1570     $urlparts = parse_url(strtolower($url));
1571     if (!isset($urlparts['path'])) {
1572         $urlparts['path'] = '';
1573     }
1575     if (!isset($urlparts['query'])) {
1576         $urlparts['query'] = '';
1577     }
1579     if (!isset($urlparts['host'])) {
1580         $urlparts['host'] = '';
1581     }
1583     if (substr($urlparts['host'], 0, 4) === 'www.') {
1584         $urlparts['host'] = substr($urlparts['host'], 4);
1585     }
1587     $urllower = $urlparts['host'] . '/' . $urlparts['path'];
1589     if ($urlparts['query'] != '') {
1590         $urllower .= '?' . $urlparts['query'];
1591     }
1593     return $urllower;
1596 function lti_get_best_tool_by_url($url, $tools, $courseid = null) {
1597     if (count($tools) === 0) {
1598         return null;
1599     }
1601     $urllower = lti_get_url_thumbprint($url);
1603     foreach ($tools as $tool) {
1604         $tool->_matchscore = 0;
1606         $toolbaseurllower = lti_get_url_thumbprint($tool->baseurl);
1608         if ($urllower === $toolbaseurllower) {
1609             // 100 points for exact thumbprint match.
1610             $tool->_matchscore += 100;
1611         } else if (substr($urllower, 0, strlen($toolbaseurllower)) === $toolbaseurllower) {
1612             // 50 points if tool thumbprint starts with the base URL thumbprint.
1613             $tool->_matchscore += 50;
1614         }
1616         // Prefer course tools over site tools.
1617         if (!empty($courseid)) {
1618             // Minus 10 points for not matching the course id (global tools).
1619             if ($tool->course != $courseid) {
1620                 $tool->_matchscore -= 10;
1621             }
1622         }
1623     }
1625     $bestmatch = array_reduce($tools, function($value, $tool) {
1626         if ($tool->_matchscore > $value->_matchscore) {
1627             return $tool;
1628         } else {
1629             return $value;
1630         }
1632     }, (object)array('_matchscore' => -1));
1634     // None of the tools are suitable for this URL.
1635     if ($bestmatch->_matchscore <= 0) {
1636         return null;
1637     }
1639     return $bestmatch;
1642 function lti_get_shared_secrets_by_key($key) {
1643     global $DB;
1645     // Look up the shared secret for the specified key in both the types_config table (for configured tools)
1646     // And in the lti resource table for ad-hoc tools.
1647     $query = "SELECT t2.value
1648                 FROM {lti_types_config} t1
1649                 JOIN {lti_types_config} t2 ON t1.typeid = t2.typeid
1650                 JOIN {lti_types} type ON t2.typeid = type.id
1651               WHERE t1.name = 'resourcekey'
1652                 AND t1.value = :key1
1653                 AND t2.name = 'password'
1654                 AND type.state = :configured1
1655                UNION
1656               SELECT tp.secret AS value
1657                 FROM {lti_tool_proxies} tp
1658                 JOIN {lti_types} t ON tp.id = t.toolproxyid
1659               WHERE tp.guid = :key2
1660                 AND t.state = :configured2
1661               UNION
1662              SELECT password AS value
1663                FROM {lti}
1664               WHERE resourcekey = :key3";
1666     $sharedsecrets = $DB->get_records_sql($query, array('configured1' => LTI_TOOL_STATE_CONFIGURED,
1667         'configured2' => LTI_TOOL_STATE_CONFIGURED, 'key1' => $key, 'key2' => $key, 'key3' => $key));
1669     $values = array_map(function($item) {
1670         return $item->value;
1671     }, $sharedsecrets);
1673     // There should really only be one shared secret per key. But, we can't prevent
1674     // more than one getting entered. For instance, if the same key is used for two tool providers.
1675     return $values;
1678 /**
1679  * Delete a Basic LTI configuration
1680  *
1681  * @param int $id   Configuration id
1682  */
1683 function lti_delete_type($id) {
1684     global $DB;
1686     // We should probably just copy the launch URL to the tool instances in this case... using a single query.
1687     /*
1688     $instances = $DB->get_records('lti', array('typeid' => $id));
1689     foreach ($instances as $instance) {
1690         $instance->typeid = 0;
1691         $DB->update_record('lti', $instance);
1692     }*/
1694     $DB->delete_records('lti_types', array('id' => $id));
1695     $DB->delete_records('lti_types_config', array('typeid' => $id));
1698 function lti_set_state_for_type($id, $state) {
1699     global $DB;
1701     $DB->update_record('lti_types', array('id' => $id, 'state' => $state));
1704 /**
1705  * Transforms a basic LTI object to an array
1706  *
1707  * @param object $ltiobject    Basic LTI object
1708  *
1709  * @return array Basic LTI configuration details
1710  */
1711 function lti_get_config($ltiobject) {
1712     $typeconfig = array();
1713     $typeconfig = (array)$ltiobject;
1714     $additionalconfig = lti_get_type_config($ltiobject->typeid);
1715     $typeconfig = array_merge($typeconfig, $additionalconfig);
1716     return $typeconfig;
1719 /**
1720  *
1721  * Generates some of the tool configuration based on the instance details
1722  *
1723  * @param int $id
1724  *
1725  * @return Instance configuration
1726  *
1727  */
1728 function lti_get_type_config_from_instance($id) {
1729     global $DB;
1731     $instance = $DB->get_record('lti', array('id' => $id));
1732     $config = lti_get_config($instance);
1734     $type = new \stdClass();
1735     $type->lti_fix = $id;
1736     if (isset($config['toolurl'])) {
1737         $type->lti_toolurl = $config['toolurl'];
1738     }
1739     if (isset($config['instructorchoicesendname'])) {
1740         $type->lti_sendname = $config['instructorchoicesendname'];
1741     }
1742     if (isset($config['instructorchoicesendemailaddr'])) {
1743         $type->lti_sendemailaddr = $config['instructorchoicesendemailaddr'];
1744     }
1745     if (isset($config['instructorchoiceacceptgrades'])) {
1746         $type->lti_acceptgrades = $config['instructorchoiceacceptgrades'];
1747     }
1748     if (isset($config['instructorchoiceallowroster'])) {
1749         $type->lti_allowroster = $config['instructorchoiceallowroster'];
1750     }
1752     if (isset($config['instructorcustomparameters'])) {
1753         $type->lti_allowsetting = $config['instructorcustomparameters'];
1754     }
1755     return $type;
1758 /**
1759  * Generates some of the tool configuration based on the admin configuration details
1760  *
1761  * @param int $id
1762  *
1763  * @return Configuration details
1764  */
1765 function lti_get_type_type_config($id) {
1766     global $DB;
1768     $basicltitype = $DB->get_record('lti_types', array('id' => $id));
1769     $config = lti_get_type_config($id);
1771     $type = new \stdClass();
1773     $type->lti_typename = $basicltitype->name;
1775     $type->typeid = $basicltitype->id;
1777     $type->toolproxyid = $basicltitype->toolproxyid;
1779     $type->lti_toolurl = $basicltitype->baseurl;
1781     $type->lti_description = $basicltitype->description;
1783     $type->lti_parameters = $basicltitype->parameter;
1785     $type->lti_icon = $basicltitype->icon;
1787     $type->lti_secureicon = $basicltitype->secureicon;
1789     if (isset($config['resourcekey'])) {
1790         $type->lti_resourcekey = $config['resourcekey'];
1791     }
1792     if (isset($config['password'])) {
1793         $type->lti_password = $config['password'];
1794     }
1796     if (isset($config['sendname'])) {
1797         $type->lti_sendname = $config['sendname'];
1798     }
1799     if (isset($config['instructorchoicesendname'])) {
1800         $type->lti_instructorchoicesendname = $config['instructorchoicesendname'];
1801     }
1802     if (isset($config['sendemailaddr'])) {
1803         $type->lti_sendemailaddr = $config['sendemailaddr'];
1804     }
1805     if (isset($config['instructorchoicesendemailaddr'])) {
1806         $type->lti_instructorchoicesendemailaddr = $config['instructorchoicesendemailaddr'];
1807     }
1808     if (isset($config['acceptgrades'])) {
1809         $type->lti_acceptgrades = $config['acceptgrades'];
1810     }
1811     if (isset($config['instructorchoiceacceptgrades'])) {
1812         $type->lti_instructorchoiceacceptgrades = $config['instructorchoiceacceptgrades'];
1813     }
1814     if (isset($config['allowroster'])) {
1815         $type->lti_allowroster = $config['allowroster'];
1816     }
1817     if (isset($config['instructorchoiceallowroster'])) {
1818         $type->lti_instructorchoiceallowroster = $config['instructorchoiceallowroster'];
1819     }
1821     if (isset($config['customparameters'])) {
1822         $type->lti_customparameters = $config['customparameters'];
1823     }
1825     if (isset($config['forcessl'])) {
1826         $type->lti_forcessl = $config['forcessl'];
1827     }
1829     if (isset($config['organizationid'])) {
1830         $type->lti_organizationid = $config['organizationid'];
1831     }
1832     if (isset($config['organizationurl'])) {
1833         $type->lti_organizationurl = $config['organizationurl'];
1834     }
1835     if (isset($config['organizationdescr'])) {
1836         $type->lti_organizationdescr = $config['organizationdescr'];
1837     }
1838     if (isset($config['launchcontainer'])) {
1839         $type->lti_launchcontainer = $config['launchcontainer'];
1840     }
1842     if (isset($config['coursevisible'])) {
1843         $type->lti_coursevisible = $config['coursevisible'];
1844     }
1846     if (isset($config['contentitem'])) {
1847         $type->lti_contentitem = $config['contentitem'];
1848     }
1850     if (isset($config['debuglaunch'])) {
1851         $type->lti_debuglaunch = $config['debuglaunch'];
1852     }
1854     if (isset($config['module_class_type'])) {
1855         $type->lti_module_class_type = $config['module_class_type'];
1856     }
1858     return $type;
1861 function lti_prepare_type_for_save($type, $config) {
1862     if (isset($config->lti_toolurl)) {
1863         $type->baseurl = $config->lti_toolurl;
1864         $type->tooldomain = lti_get_domain_from_url($config->lti_toolurl);
1865     }
1866     if (isset($config->lti_description)) {
1867         $type->description = $config->lti_description;
1868     }
1869     if (isset($config->lti_typename)) {
1870         $type->name = $config->lti_typename;
1871     }
1872     if (isset($config->lti_coursevisible)) {
1873         $type->coursevisible = $config->lti_coursevisible;
1874     }
1876     if (isset($config->lti_icon)) {
1877         $type->icon = $config->lti_icon;
1878     }
1879     if (isset($config->lti_secureicon)) {
1880         $type->secureicon = $config->lti_secureicon;
1881     }
1883     $type->forcessl = !empty($config->lti_forcessl) ? $config->lti_forcessl : 0;
1884     $config->lti_forcessl = $type->forcessl;
1885     if (isset($config->lti_contentitem)) {
1886         $type->contentitem = !empty($config->lti_contentitem) ? $config->lti_contentitem : 0;
1887         $config->lti_contentitem = $type->contentitem;
1888     }
1890     $type->timemodified = time();
1892     unset ($config->lti_typename);
1893     unset ($config->lti_toolurl);
1894     unset ($config->lti_description);
1895     unset ($config->lti_icon);
1896     unset ($config->lti_secureicon);
1899 function lti_update_type($type, $config) {
1900     global $DB, $CFG;
1902     lti_prepare_type_for_save($type, $config);
1904     $clearcache = false;
1905     if (lti_request_is_using_ssl() && !empty($type->secureicon)) {
1906         $clearcache = !isset($config->oldicon) || ($config->oldicon !== $type->secureicon);
1907     } else {
1908         $clearcache = isset($type->icon) && (!isset($config->oldicon) || ($config->oldicon !== $type->icon));
1909     }
1910     unset($config->oldicon);
1912     if ($DB->update_record('lti_types', $type)) {
1913         foreach ($config as $key => $value) {
1914             if (substr($key, 0, 4) == 'lti_' && !is_null($value)) {
1915                 $record = new \StdClass();
1916                 $record->typeid = $type->id;
1917                 $record->name = substr($key, 4);
1918                 $record->value = $value;
1919                 lti_update_config($record);
1920             }
1921         }
1922         require_once($CFG->libdir.'/modinfolib.php');
1923         if ($clearcache) {
1924             $sql = "SELECT DISTINCT course
1925                       FROM {lti}
1926                      WHERE typeid = ?";
1928             $courses = $DB->get_fieldset_sql($sql, array($type->id));
1930             foreach ($courses as $courseid) {
1931                 rebuild_course_cache($courseid, true);
1932             }
1933         }
1934     }
1937 function lti_add_type($type, $config) {
1938     global $USER, $SITE, $DB;
1940     lti_prepare_type_for_save($type, $config);
1942     if (!isset($type->state)) {
1943         $type->state = LTI_TOOL_STATE_PENDING;
1944     }
1946     if (!isset($type->timecreated)) {
1947         $type->timecreated = time();
1948     }
1950     if (!isset($type->createdby)) {
1951         $type->createdby = $USER->id;
1952     }
1954     if (!isset($type->course)) {
1955         $type->course = $SITE->id;
1956     }
1958     // Create a salt value to be used for signing passed data to extension services
1959     // The outcome service uses the service salt on the instance. This can be used
1960     // for communication with services not related to a specific LTI instance.
1961     $config->lti_servicesalt = uniqid('', true);
1963     $id = $DB->insert_record('lti_types', $type);
1965     if ($id) {
1966         foreach ($config as $key => $value) {
1967             if (substr($key, 0, 4) == 'lti_' && !is_null($value)) {
1968                 $record = new \StdClass();
1969                 $record->typeid = $id;
1970                 $record->name = substr($key, 4);
1971                 $record->value = $value;
1973                 lti_add_config($record);
1974             }
1975         }
1976     }
1978     return $id;
1981 /**
1982  * Given an array of tool proxies, filter them based on their state
1983  *
1984  * @param array $toolproxies An array of lti_tool_proxies records
1985  * @param int $state One of the LTI_TOOL_PROXY_STATE_* constants
1986  *
1987  * @return array
1988  */
1989 function lti_filter_tool_proxy_types(array $toolproxies, $state) {
1990     $return = array();
1991     foreach ($toolproxies as $key => $toolproxy) {
1992         if ($toolproxy->state == $state) {
1993             $return[$key] = $toolproxy;
1994         }
1995     }
1996     return $return;
1999 /**
2000  * Get the tool proxy instance given its GUID
2001  *
2002  * @param string  $toolproxyguid   Tool proxy GUID value
2003  *
2004  * @return object
2005  */
2006 function lti_get_tool_proxy_from_guid($toolproxyguid) {
2007     global $DB;
2009     $toolproxy = $DB->get_record('lti_tool_proxies', array('guid' => $toolproxyguid));
2011     return $toolproxy;
2014 /**
2015  * Get the tool proxy instance given its registration URL
2016  *
2017  * @param string $regurl Tool proxy registration URL
2018  *
2019  * @return array The record of the tool proxy with this url
2020  */
2021 function lti_get_tool_proxies_from_registration_url($regurl) {
2022     global $DB;
2024     return $DB->get_records_sql(
2025         'SELECT * FROM {lti_tool_proxies}
2026         WHERE '.$DB->sql_compare_text('regurl', 256).' = :regurl',
2027         array('regurl' => $regurl)
2028     );
2031 /**
2032  * Generates some of the tool proxy configuration based on the admin configuration details
2033  *
2034  * @param int $id
2035  *
2036  * @return Tool Proxy details
2037  */
2038 function lti_get_tool_proxy($id) {
2039     global $DB;
2041     $toolproxy = $DB->get_record('lti_tool_proxies', array('id' => $id));
2042     return $toolproxy;
2045 /**
2046  * Returns lti tool proxies.
2047  *
2048  * @param bool $orphanedonly Only retrieves tool proxies that have no type associated with them
2049  * @return array of basicLTI types
2050  */
2051 function lti_get_tool_proxies($orphanedonly) {
2052     global $DB;
2054     if ($orphanedonly) {
2055         $tools = $DB->get_records('lti_types');
2056         $usedproxyids = array_values($DB->get_fieldset_select('lti_types', 'toolproxyid', 'toolproxyid IS NOT NULL'));
2057         $proxies = $DB->get_records('lti_tool_proxies', null, 'state DESC, timemodified DESC');
2058         foreach ($proxies as $key => $value) {
2059             if (in_array($value->id, $usedproxyids)) {
2060                 unset($proxies[$key]);
2061             }
2062         }
2063         return $proxies;
2064     } else {
2065         return $DB->get_records('lti_tool_proxies', null, 'state DESC, timemodified DESC');
2066     }
2069 /**
2070  * Generates some of the tool proxy configuration based on the admin configuration details
2071  *
2072  * @param int $id
2073  *
2074  * @return Tool Proxy details
2075  */
2076 function lti_get_tool_proxy_config($id) {
2077     $toolproxy = lti_get_tool_proxy($id);
2079     $tp = new \stdClass();
2080     $tp->lti_registrationname = $toolproxy->name;
2081     $tp->toolproxyid = $toolproxy->id;
2082     $tp->state = $toolproxy->state;
2083     $tp->lti_registrationurl = $toolproxy->regurl;
2084     $tp->lti_capabilities = explode("\n", $toolproxy->capabilityoffered);
2085     $tp->lti_services = explode("\n", $toolproxy->serviceoffered);
2087     return $tp;
2090 /**
2091  * Update the database with a tool proxy instance
2092  *
2093  * @param object   $config    Tool proxy definition
2094  *
2095  * @return int  Record id number
2096  */
2097 function lti_add_tool_proxy($config) {
2098     global $USER, $DB;
2100     $toolproxy = new \stdClass();
2101     if (isset($config->lti_registrationname)) {
2102         $toolproxy->name = trim($config->lti_registrationname);
2103     }
2104     if (isset($config->lti_registrationurl)) {
2105         $toolproxy->regurl = trim($config->lti_registrationurl);
2106     }
2107     if (isset($config->lti_capabilities)) {
2108         $toolproxy->capabilityoffered = implode("\n", $config->lti_capabilities);
2109     } else {
2110         $toolproxy->capabilityoffered = implode("\n", array_keys(lti_get_capabilities()));
2111     }
2112     if (isset($config->lti_services)) {
2113         $toolproxy->serviceoffered = implode("\n", $config->lti_services);
2114     } else {
2115         $func = function($s) {
2116             return $s->get_id();
2117         };
2118         $servicenames = array_map($func, lti_get_services());
2119         $toolproxy->serviceoffered = implode("\n", $servicenames);
2120     }
2121     if (isset($config->toolproxyid) && !empty($config->toolproxyid)) {
2122         $toolproxy->id = $config->toolproxyid;
2123         if (!isset($toolproxy->state) || ($toolproxy->state != LTI_TOOL_PROXY_STATE_ACCEPTED)) {
2124             $toolproxy->state = LTI_TOOL_PROXY_STATE_CONFIGURED;
2125             $toolproxy->guid = random_string();
2126             $toolproxy->secret = random_string();
2127         }
2128         $id = lti_update_tool_proxy($toolproxy);
2129     } else {
2130         $toolproxy->state = LTI_TOOL_PROXY_STATE_CONFIGURED;
2131         $toolproxy->timemodified = time();
2132         $toolproxy->timecreated = $toolproxy->timemodified;
2133         if (!isset($toolproxy->createdby)) {
2134             $toolproxy->createdby = $USER->id;
2135         }
2136         $toolproxy->guid = random_string();
2137         $toolproxy->secret = random_string();
2138         $id = $DB->insert_record('lti_tool_proxies', $toolproxy);
2139     }
2141     return $id;
2144 /**
2145  * Updates a tool proxy in the database
2146  *
2147  * @param object  $toolproxy   Tool proxy
2148  *
2149  * @return int    Record id number
2150  */
2151 function lti_update_tool_proxy($toolproxy) {
2152     global $DB;
2154     $toolproxy->timemodified = time();
2155     $id = $DB->update_record('lti_tool_proxies', $toolproxy);
2157     return $id;
2160 /**
2161  * Delete a Tool Proxy
2162  *
2163  * @param int $id   Tool Proxy id
2164  */
2165 function lti_delete_tool_proxy($id) {
2166     global $DB;
2167     $DB->delete_records('lti_tool_settings', array('toolproxyid' => $id));
2168     $tools = $DB->get_records('lti_types', array('toolproxyid' => $id));
2169     foreach ($tools as $tool) {
2170         lti_delete_type($tool->id);
2171     }
2172     $DB->delete_records('lti_tool_proxies', array('id' => $id));
2175 /**
2176  * Add a tool configuration in the database
2177  *
2178  * @param object $config   Tool configuration
2179  *
2180  * @return int Record id number
2181  */
2182 function lti_add_config($config) {
2183     global $DB;
2185     return $DB->insert_record('lti_types_config', $config);
2188 /**
2189  * Updates a tool configuration in the database
2190  *
2191  * @param object  $config   Tool configuration
2192  *
2193  * @return Record id number
2194  */
2195 function lti_update_config($config) {
2196     global $DB;
2198     $return = true;
2199     $old = $DB->get_record('lti_types_config', array('typeid' => $config->typeid, 'name' => $config->name));
2201     if ($old) {
2202         $config->id = $old->id;
2203         $return = $DB->update_record('lti_types_config', $config);
2204     } else {
2205         $return = $DB->insert_record('lti_types_config', $config);
2206     }
2207     return $return;
2210 /**
2211  * Gets the tool settings
2212  *
2213  * @param int  $toolproxyid   Id of tool proxy record
2214  * @param int  $courseid      Id of course (null if system settings)
2215  * @param int  $instanceid    Id of course module (null if system or context settings)
2216  *
2217  * @return array  Array settings
2218  */
2219 function lti_get_tool_settings($toolproxyid, $courseid = null, $instanceid = null) {
2220     global $DB;
2222     $settings = array();
2223     $settingsstr = $DB->get_field('lti_tool_settings', 'settings', array('toolproxyid' => $toolproxyid,
2224         'course' => $courseid, 'coursemoduleid' => $instanceid));
2225     if ($settingsstr !== false) {
2226         $settings = json_decode($settingsstr, true);
2227     }
2228     return $settings;
2231 /**
2232  * Sets the tool settings (
2233  *
2234  * @param array  $settings      Array of settings
2235  * @param int    $toolproxyid   Id of tool proxy record
2236  * @param int    $courseid      Id of course (null if system settings)
2237  * @param int    $instanceid    Id of course module (null if system or context settings)
2238  */
2239 function lti_set_tool_settings($settings, $toolproxyid, $courseid = null, $instanceid = null) {
2240     global $DB;
2242     $json = json_encode($settings);
2243     $record = $DB->get_record('lti_tool_settings', array('toolproxyid' => $toolproxyid,
2244         'course' => $courseid, 'coursemoduleid' => $instanceid));
2245     if ($record !== false) {
2246         $DB->update_record('lti_tool_settings', array('id' => $record->id, 'settings' => $json, 'timemodified' => time()));
2247     } else {
2248         $record = new \stdClass();
2249         $record->toolproxyid = $toolproxyid;
2250         $record->course = $courseid;
2251         $record->coursemoduleid = $instanceid;
2252         $record->settings = $json;
2253         $record->timecreated = time();
2254         $record->timemodified = $record->timecreated;
2255         $DB->insert_record('lti_tool_settings', $record);
2256     }
2259 /**
2260  * Signs the petition to launch the external tool using OAuth
2261  *
2262  * @param $oldparms     Parameters to be passed for signing
2263  * @param $endpoint     url of the external tool
2264  * @param $method       Method for sending the parameters (e.g. POST)
2265  * @param $oauth_consumoer_key          Key
2266  * @param $oauth_consumoer_secret       Secret
2267  */
2268 function lti_sign_parameters($oldparms, $endpoint, $method, $oauthconsumerkey, $oauthconsumersecret) {
2270     $parms = $oldparms;
2272     $testtoken = '';
2274     // TODO: Switch to core oauthlib once implemented - MDL-30149.
2275     $hmacmethod = new lti\OAuthSignatureMethod_HMAC_SHA1();
2276     $testconsumer = new lti\OAuthConsumer($oauthconsumerkey, $oauthconsumersecret, null);
2277     $accreq = lti\OAuthRequest::from_consumer_and_token($testconsumer, $testtoken, $method, $endpoint, $parms);
2278     $accreq->sign_request($hmacmethod, $testconsumer, $testtoken);
2280     $newparms = $accreq->get_parameters();
2282     return $newparms;
2285 /**
2286  * Posts the launch petition HTML
2287  *
2288  * @param $newparms     Signed parameters
2289  * @param $endpoint     URL of the external tool
2290  * @param $debug        Debug (true/false)
2291  */
2292 function lti_post_launch_html($newparms, $endpoint, $debug=false) {
2293     $r = "<form action=\"" . $endpoint .
2294         "\" name=\"ltiLaunchForm\" id=\"ltiLaunchForm\" method=\"post\" encType=\"application/x-www-form-urlencoded\">\n";
2296     // Contruct html for the launch parameters.
2297     foreach ($newparms as $key => $value) {
2298         $key = htmlspecialchars($key);
2299         $value = htmlspecialchars($value);
2300         if ( $key == "ext_submit" ) {
2301             $r .= "<input type=\"submit\"";
2302         } else {
2303             $r .= "<input type=\"hidden\" name=\"{$key}\"";
2304         }
2305         $r .= " value=\"";
2306         $r .= $value;
2307         $r .= "\"/>\n";
2308     }
2310     if ( $debug ) {
2311         $r .= "<script language=\"javascript\"> \n";
2312         $r .= "  //<![CDATA[ \n";
2313         $r .= "function basicltiDebugToggle() {\n";
2314         $r .= "    var ele = document.getElementById(\"basicltiDebug\");\n";
2315         $r .= "    if (ele.style.display == \"block\") {\n";
2316         $r .= "        ele.style.display = \"none\";\n";
2317         $r .= "    }\n";
2318         $r .= "    else {\n";
2319         $r .= "        ele.style.display = \"block\";\n";
2320         $r .= "    }\n";
2321         $r .= "} \n";
2322         $r .= "  //]]> \n";
2323         $r .= "</script>\n";
2324         $r .= "<a id=\"displayText\" href=\"javascript:basicltiDebugToggle();\">";
2325         $r .= get_string("toggle_debug_data", "lti")."</a>\n";
2326         $r .= "<div id=\"basicltiDebug\" style=\"display:none\">\n";
2327         $r .= "<b>".get_string("basiclti_endpoint", "lti")."</b><br/>\n";
2328         $r .= $endpoint . "<br/>\n&nbsp;<br/>\n";
2329         $r .= "<b>".get_string("basiclti_parameters", "lti")."</b><br/>\n";
2330         foreach ($newparms as $key => $value) {
2331             $key = htmlspecialchars($key);
2332             $value = htmlspecialchars($value);
2333             $r .= "$key = $value<br/>\n";
2334         }
2335         $r .= "&nbsp;<br/>\n";
2336         $r .= "</div>\n";
2337     }
2338     $r .= "</form>\n";
2340     if ( ! $debug ) {
2341         $r .= " <script type=\"text/javascript\"> \n" .
2342             "  //<![CDATA[ \n" .
2343             "    document.ltiLaunchForm.submit(); \n" .
2344             "  //]]> \n" .
2345             " </script> \n";
2346     }
2347     return $r;
2350 function lti_get_type($typeid) {
2351     global $DB;
2353     return $DB->get_record('lti_types', array('id' => $typeid));
2356 function lti_get_launch_container($lti, $toolconfig) {
2357     if (empty($lti->launchcontainer)) {
2358         $lti->launchcontainer = LTI_LAUNCH_CONTAINER_DEFAULT;
2359     }
2361     if ($lti->launchcontainer == LTI_LAUNCH_CONTAINER_DEFAULT) {
2362         if (isset($toolconfig['launchcontainer'])) {
2363             $launchcontainer = $toolconfig['launchcontainer'];
2364         }
2365     } else {
2366         $launchcontainer = $lti->launchcontainer;
2367     }
2369     if (empty($launchcontainer) || $launchcontainer == LTI_LAUNCH_CONTAINER_DEFAULT) {
2370         $launchcontainer = LTI_LAUNCH_CONTAINER_EMBED_NO_BLOCKS;
2371     }
2373     $devicetype = core_useragent::get_device_type();
2375     // Scrolling within the object element doesn't work on iOS or Android
2376     // Opening the popup window also had some issues in testing
2377     // For mobile devices, always take up the entire screen to ensure the best experience.
2378     if ($devicetype === core_useragent::DEVICETYPE_MOBILE || $devicetype === core_useragent::DEVICETYPE_TABLET ) {
2379         $launchcontainer = LTI_LAUNCH_CONTAINER_REPLACE_MOODLE_WINDOW;
2380     }
2382     return $launchcontainer;
2385 function lti_request_is_using_ssl() {
2386     global $CFG;
2387     return (stripos($CFG->wwwroot, 'https://') === 0);
2390 function lti_ensure_url_is_https($url) {
2391     if (!strstr($url, '://')) {
2392         $url = 'https://' . $url;
2393     } else {
2394         // If the URL starts with http, replace with https.
2395         if (stripos($url, 'http://') === 0) {
2396             $url = 'https://' . substr($url, 7);
2397         }
2398     }
2400     return $url;
2403 /**
2404  * Determines if we should try to log the request
2405  *
2406  * @param string $rawbody
2407  * @return bool
2408  */
2409 function lti_should_log_request($rawbody) {
2410     global $CFG;
2412     if (empty($CFG->mod_lti_log_users)) {
2413         return false;
2414     }
2416     $logusers = explode(',', $CFG->mod_lti_log_users);
2417     if (empty($logusers)) {
2418         return false;
2419     }
2421     try {
2422         $xml = new \SimpleXMLElement($rawbody);
2423         $ns  = $xml->getNamespaces();
2424         $ns  = array_shift($ns);
2425         $xml->registerXPathNamespace('lti', $ns);
2426         $requestuserid = '';
2427         if ($node = $xml->xpath('//lti:userId')) {
2428             $node = $node[0];
2429             $requestuserid = clean_param((string) $node, PARAM_INT);
2430         } else if ($node = $xml->xpath('//lti:sourcedId')) {
2431             $node = $node[0];
2432             $resultjson = json_decode((string) $node);
2433             $requestuserid = clean_param($resultjson->data->userid, PARAM_INT);
2434         }
2435     } catch (Exception $e) {
2436         return false;
2437     }
2439     if (empty($requestuserid) or !in_array($requestuserid, $logusers)) {
2440         return false;
2441     }
2443     return true;
2446 /**
2447  * Logs the request to a file in temp dir.
2448  *
2449  * @param string $rawbody
2450  */
2451 function lti_log_request($rawbody) {
2452     if ($tempdir = make_temp_directory('mod_lti', false)) {
2453         if ($tempfile = tempnam($tempdir, 'mod_lti_request'.date('YmdHis'))) {
2454             $content  = "Request Headers:\n";
2455             foreach (moodle\mod\lti\OAuthUtil::get_headers() as $header => $value) {
2456                 $content .= "$header: $value\n";
2457             }
2458             $content .= "Request Body:\n";
2459             $content .= $rawbody;
2461             file_put_contents($tempfile, $content);
2462             chmod($tempfile, 0644);
2463         }
2464     }
2467 /**
2468  * Log an LTI response.
2469  *
2470  * @param string $responsexml The response XML
2471  * @param Exception $e If there was an exception, pass that too
2472  */
2473 function lti_log_response($responsexml, $e = null) {
2474     if ($tempdir = make_temp_directory('mod_lti', false)) {
2475         if ($tempfile = tempnam($tempdir, 'mod_lti_response'.date('YmdHis'))) {
2476             $content = '';
2477             if ($e instanceof Exception) {
2478                 $info = get_exception_info($e);
2480                 $content .= "Exception:\n";
2481                 $content .= "Message: $info->message\n";
2482                 $content .= "Debug info: $info->debuginfo\n";
2483                 $content .= "Backtrace:\n";
2484                 $content .= format_backtrace($info->backtrace, true);
2485                 $content .= "\n";
2486             }
2487             $content .= "Response XML:\n";
2488             $content .= $responsexml;
2490             file_put_contents($tempfile, $content);
2491             chmod($tempfile, 0644);
2492         }
2493     }
2496 /**
2497  * Fetches LTI type configuration for an LTI instance
2498  *
2499  * @param stdClass $instance
2500  * @return array Can be empty if no type is found
2501  */
2502 function lti_get_type_config_by_instance($instance) {
2503     $typeid = null;
2504     if (empty($instance->typeid)) {
2505         $tool = lti_get_tool_by_url_match($instance->toolurl, $instance->course);
2506         if ($tool) {
2507             $typeid = $tool->id;
2508         }
2509     } else {
2510         $typeid = $instance->typeid;
2511     }
2512     if (!empty($typeid)) {
2513         return lti_get_type_config($typeid);
2514     }
2515     return array();
2518 /**
2519  * Enforce type config settings onto the LTI instance
2520  *
2521  * @param stdClass $instance
2522  * @param array $typeconfig
2523  */
2524 function lti_force_type_config_settings($instance, array $typeconfig) {
2525     $forced = array(
2526         'instructorchoicesendname'      => 'sendname',
2527         'instructorchoicesendemailaddr' => 'sendemailaddr',
2528         'instructorchoiceacceptgrades'  => 'acceptgrades',
2529     );
2531     foreach ($forced as $instanceparam => $typeconfigparam) {
2532         if (array_key_exists($typeconfigparam, $typeconfig) && $typeconfig[$typeconfigparam] != LTI_SETTING_DELEGATE) {
2533             $instance->$instanceparam = $typeconfig[$typeconfigparam];
2534         }
2535     }
2538 /**
2539  * Initializes an array with the capabilities supported by the LTI module
2540  *
2541  * @return array List of capability names (without a dollar sign prefix)
2542  */
2543 function lti_get_capabilities() {
2545     $capabilities = array(
2546        'basic-lti-launch-request' => '',
2547        'ContentItemSelectionRequest' => '',
2548        'ToolProxyRegistrationRequest' => '',
2549        'Context.id' => 'context_id',
2550        'Context.title' => 'context_title',
2551        'Context.label' => 'context_label',
2552        'Context.sourcedId' => 'lis_course_section_sourcedid',
2553        'Context.longDescription' => '$COURSE->summary',
2554        'Context.timeFrame.begin' => '$COURSE->startdate',
2555        'CourseSection.title' => 'context_title',
2556        'CourseSection.label' => 'context_label',
2557        'CourseSection.sourcedId' => 'lis_course_section_sourcedid',
2558        'CourseSection.longDescription' => '$COURSE->summary',
2559        'CourseSection.timeFrame.begin' => '$COURSE->startdate',
2560        'ResourceLink.id' => 'resource_link_id',
2561        'ResourceLink.title' => 'resource_link_title',
2562        'ResourceLink.description' => 'resource_link_description',
2563        'User.id' => 'user_id',
2564        'User.username' => '$USER->username',
2565        'Person.name.full' => 'lis_person_name_full',
2566        'Person.name.given' => 'lis_person_name_given',
2567        'Person.name.family' => 'lis_person_name_family',
2568        'Person.email.primary' => 'lis_person_contact_email_primary',
2569        'Person.sourcedId' => 'lis_person_sourcedid',
2570        'Person.name.middle' => '$USER->middlename',
2571        'Person.address.street1' => '$USER->address',
2572        'Person.address.locality' => '$USER->city',
2573        'Person.address.country' => '$USER->country',
2574        'Person.address.timezone' => '$USER->timezone',
2575        'Person.phone.primary' => '$USER->phone1',
2576        'Person.phone.mobile' => '$USER->phone2',
2577        'Person.webaddress' => '$USER->url',
2578        'Membership.role' => 'roles',
2579        'Result.sourcedId' => 'lis_result_sourcedid',
2580        'Result.autocreate' => 'lis_outcome_service_url',
2581        'Moodle.Person.userGroupIds' => null);
2583     return $capabilities;
2587 /**
2588  * Initializes an array with the services supported by the LTI module
2589  *
2590  * @return array List of services
2591  */
2592 function lti_get_services() {
2594     $services = array();
2595     $definedservices = core_component::get_plugin_list('ltiservice');
2596     foreach ($definedservices as $name => $location) {
2597         $classname = "\\ltiservice_{$name}\\local\\service\\{$name}";
2598         $services[] = new $classname();
2599     }
2601     return $services;
2605 /**
2606  * Initializes an instance of the named service
2607  *
2608  * @param string $servicename Name of service
2609  *
2610  * @return mod_lti\local\ltiservice\service_base Service
2611  */
2612 function lti_get_service_by_name($servicename) {
2614     $service = false;
2615     $classname = "\\ltiservice_{$servicename}\\local\\service\\{$servicename}";
2616     if (class_exists($classname)) {
2617         $service = new $classname();
2618     }
2620     return $service;
2624 /**
2625  * Finds a service by id
2626  *
2627  * @param array  $services    Array of services
2628  * @param string $resourceid  ID of resource
2629  *
2630  * @return mod_lti\local\ltiservice\service_base Service
2631  */
2632 function lti_get_service_by_resource_id($services, $resourceid) {
2634     $service = false;
2635     foreach ($services as $aservice) {
2636         foreach ($aservice->get_resources() as $resource) {
2637             if ($resource->get_id() === $resourceid) {
2638                 $service = $aservice;
2639                 break 2;
2640             }
2641         }
2642     }
2644     return $service;
2648 /**
2649  * Extracts the named contexts from a tool proxy
2650  *
2651  * @param object $json
2652  *
2653  * @return array Contexts
2654  */
2655 function lti_get_contexts($json) {
2657     $contexts = array();
2658     if (isset($json->{'@context'})) {
2659         foreach ($json->{'@context'} as $context) {
2660             if (is_object($context)) {
2661                 $contexts = array_merge(get_object_vars($context), $contexts);
2662             }
2663         }
2664     }
2666     return $contexts;
2670 /**
2671  * Converts an ID to a fully-qualified ID
2672  *
2673  * @param array $contexts
2674  * @param string $id
2675  *
2676  * @return string Fully-qualified ID
2677  */
2678 function lti_get_fqid($contexts, $id) {
2680     $parts = explode(':', $id, 2);
2681     if (count($parts) > 1) {
2682         if (array_key_exists($parts[0], $contexts)) {
2683             $id = $contexts[$parts[0]] . $parts[1];
2684         }
2685     }
2687     return $id;
2691 /**
2692  * Returns the icon for the given tool type
2693  *
2694  * @param stdClass $type The tool type
2695  *
2696  * @return string The url to the tool type's corresponding icon
2697  */
2698 function get_tool_type_icon_url(stdClass $type) {
2699     global $OUTPUT;
2701     $iconurl = $type->secureicon;
2703     if (empty($iconurl)) {
2704         $iconurl = $type->icon;
2705     }
2707     if (empty($iconurl)) {
2708         $iconurl = $OUTPUT->image_url('icon', 'lti')->out();
2709     }
2711     return $iconurl;
2714 /**
2715  * Returns the edit url for the given tool type
2716  *
2717  * @param stdClass $type The tool type
2718  *
2719  * @return string The url to edit the tool type
2720  */
2721 function get_tool_type_edit_url(stdClass $type) {
2722     $url = new moodle_url('/mod/lti/typessettings.php',
2723                           array('action' => 'update', 'id' => $type->id, 'sesskey' => sesskey(), 'returnto' => 'toolconfigure'));
2724     return $url->out();
2727 /**
2728  * Returns the edit url for the given tool proxy.
2729  *
2730  * @param stdClass $proxy The tool proxy
2731  *
2732  * @return string The url to edit the tool type
2733  */
2734 function get_tool_proxy_edit_url(stdClass $proxy) {
2735     $url = new moodle_url('/mod/lti/registersettings.php',
2736                           array('action' => 'update', 'id' => $proxy->id, 'sesskey' => sesskey(), 'returnto' => 'toolconfigure'));
2737     return $url->out();
2740 /**
2741  * Returns the course url for the given tool type
2742  *
2743  * @param stdClass $type The tool type
2744  *
2745  * @return string|void The url to the course of the tool type, void if it is a site wide type
2746  */
2747 function get_tool_type_course_url(stdClass $type) {
2748     if ($type->course == 1) {
2749         return;
2750     } else {
2751         $url = new moodle_url('/course/view.php', array('id' => $type->course));
2752         return $url->out();
2753     }
2756 /**
2757  * Returns the icon and edit urls for the tool type and the course url if it is a course type.
2758  *
2759  * @param stdClass $type The tool type
2760  *
2761  * @return string The urls of the tool type
2762  */
2763 function get_tool_type_urls(stdClass $type) {
2764     $courseurl = get_tool_type_course_url($type);
2766     $urls = array(
2767         'icon' => get_tool_type_icon_url($type),
2768         'edit' => get_tool_type_edit_url($type),
2769     );
2771     if ($courseurl) {
2772         $urls['course'] = $courseurl;
2773     }
2775     return $urls;
2778 /**
2779  * Returns the icon and edit urls for the tool proxy.
2780  *
2781  * @param stdClass $proxy The tool proxy
2782  *
2783  * @return string The urls of the tool proxy
2784  */
2785 function get_tool_proxy_urls(stdClass $proxy) {
2786     global $OUTPUT;
2788     $urls = array(
2789         'icon' => $OUTPUT->image_url('icon', 'lti')->out(),
2790         'edit' => get_tool_proxy_edit_url($proxy),
2791     );
2793     return $urls;
2796 /**
2797  * Returns information on the current state of the tool type
2798  *
2799  * @param stdClass $type The tool type
2800  *
2801  * @return array An array with a text description of the state, and boolean for whether it is in each state:
2802  * pending, configured, rejected, unknown
2803  */
2804 function get_tool_type_state_info(stdClass $type) {
2805     $state = '';
2806     $isconfigured = false;
2807     $ispending = false;
2808     $isrejected = false;
2809     $isunknown = false;
2810     switch ($type->state) {
2811         case LTI_TOOL_STATE_CONFIGURED:
2812             $state = get_string('active', 'mod_lti');
2813             $isconfigured = true;
2814             break;
2815         case LTI_TOOL_STATE_PENDING:
2816             $state = get_string('pending', 'mod_lti');
2817             $ispending = true;
2818             break;
2819         case LTI_TOOL_STATE_REJECTED:
2820             $state = get_string('rejected', 'mod_lti');
2821             $isrejected = true;
2822             break;
2823         default:
2824             $state = get_string('unknownstate', 'mod_lti');
2825             $isunknown = true;
2826             break;
2827     }
2829     return array(
2830         'text' => $state,
2831         'pending' => $ispending,
2832         'configured' => $isconfigured,
2833         'rejected' => $isrejected,
2834         'unknown' => $isunknown
2835     );
2838 /**
2839  * Returns a summary of each LTI capability this tool type requires in plain language
2840  *
2841  * @param stdClass $type The tool type
2842  *
2843  * @return array An array of text descriptions of each of the capabilities this tool type requires
2844  */
2845 function get_tool_type_capability_groups($type) {
2846     $capabilities = lti_get_enabled_capabilities($type);
2847     $groups = array();
2848     $hascourse = false;
2849     $hasactivities = false;
2850     $hasuseraccount = false;
2851     $hasuserpersonal = false;
2853     foreach ($capabilities as $capability) {
2854         // Bail out early if we've already found all groups.
2855         if (count($groups) >= 4) {
2856             continue;
2857         }
2859         if (!$hascourse && preg_match('/^CourseSection/', $capability)) {
2860             $hascourse = true;
2861             $groups[] = get_string('courseinformation', 'mod_lti');
2862         } else if (!$hasactivities && preg_match('/^ResourceLink/', $capability)) {
2863             $hasactivities = true;
2864             $groups[] = get_string('courseactivitiesorresources', 'mod_lti');
2865         } else if (!$hasuseraccount && preg_match('/^User/', $capability) || preg_match('/^Membership/', $capability)) {
2866             $hasuseraccount = true;
2867             $groups[] = get_string('useraccountinformation', 'mod_lti');
2868         } else if (!$hasuserpersonal && preg_match('/^Person/', $capability)) {
2869             $hasuserpersonal = true;
2870             $groups[] = get_string('userpersonalinformation', 'mod_lti');
2871         }
2872     }
2874     return $groups;
2878 /**
2879  * Returns the ids of each instance of this tool type
2880  *
2881  * @param stdClass $type The tool type
2882  *
2883  * @return array An array of ids of the instances of this tool type
2884  */
2885 function get_tool_type_instance_ids($type) {
2886     global $DB;
2888     return array_keys($DB->get_fieldset_select('lti', 'id', 'typeid = ?', array($type->id)));
2891 /**
2892  * Serialises this tool type
2893  *
2894  * @param stdClass $type The tool type
2895  *
2896  * @return array An array of values representing this type
2897  */
2898 function serialise_tool_type(stdClass $type) {
2899     $capabilitygroups = get_tool_type_capability_groups($type);
2900     $instanceids = get_tool_type_instance_ids($type);
2901     // Clean the name. We don't want tags here.
2902     $name = clean_param($type->name, PARAM_NOTAGS);
2903     if (!empty($type->description)) {
2904         // Clean the description. We don't want tags here.
2905         $description = clean_param($type->description, PARAM_NOTAGS);
2906     } else {
2907         $description = get_string('editdescription', 'mod_lti');
2908     }
2909     return array(
2910         'id' => $type->id,
2911         'name' => $name,
2912         'description' => $description,
2913         'urls' => get_tool_type_urls($type),
2914         'state' => get_tool_type_state_info($type),
2915         'hascapabilitygroups' => !empty($capabilitygroups),
2916         'capabilitygroups' => $capabilitygroups,
2917         // Course ID of 1 means it's not linked to a course.
2918         'courseid' => $type->course == 1 ? 0 : $type->course,
2919         'instanceids' => $instanceids,
2920         'instancecount' => count($instanceids)
2921     );
2924 /**
2925  * Serialises this tool proxy.
2926  *
2927  * @param stdClass $proxy The tool proxy
2928  *
2929  * @return array An array of values representing this type
2930  */
2931 function serialise_tool_proxy(stdClass $proxy) {
2932     return array(
2933         'id' => $proxy->id,
2934         'name' => $proxy->name,
2935         'description' => get_string('activatetoadddescription', 'mod_lti'),
2936         'urls' => get_tool_proxy_urls($proxy),
2937         'state' => array(
2938             'text' => get_string('pending', 'mod_lti'),
2939             'pending' => true,
2940             'configured' => false,
2941             'rejected' => false,
2942             'unknown' => false
2943         ),
2944         'hascapabilitygroups' => true,
2945         'capabilitygroups' => array(),
2946         'courseid' => 0,
2947         'instanceids' => array(),
2948         'instancecount' => 0
2949     );
2952 /**
2953  * Loads the cartridge information into the tool type, if the launch url is for a cartridge file
2954  *
2955  * @param stdClass $type The tool type object to be filled in
2956  * @since Moodle 3.1
2957  */
2958 function lti_load_type_if_cartridge($type) {
2959     if (!empty($type->lti_toolurl) && lti_is_cartridge($type->lti_toolurl)) {
2960         lti_load_type_from_cartridge($type->lti_toolurl, $type);
2961     }
2964 /**
2965  * Loads the cartridge information into the new tool, if the launch url is for a cartridge file
2966  *
2967  * @param stdClass $lti The tools config
2968  * @since Moodle 3.1
2969  */
2970 function lti_load_tool_if_cartridge($lti) {
2971     if (!empty($lti->toolurl) && lti_is_cartridge($lti->toolurl)) {
2972         lti_load_tool_from_cartridge($lti->toolurl, $lti);
2973     }
2976 /**
2977  * Determines if the given url is for a IMS basic cartridge
2978  *
2979  * @param  string $url The url to be checked
2980  * @return True if the url is for a cartridge
2981  * @since Moodle 3.1
2982  */
2983 function lti_is_cartridge($url) {
2984     // If it is empty, it's not a cartridge.
2985     if (empty($url)) {
2986         return false;
2987     }
2988     // If it has xml at the end of the url, it's a cartridge.
2989     if (preg_match('/\.xml$/', $url)) {
2990         return true;
2991     }
2992     // Even if it doesn't have .xml, load the url to check if it's a cartridge..
2993     try {
2994         $toolinfo = lti_load_cartridge($url,
2995             array(
2996                 "launch_url" => "launchurl"
2997             )
2998         );
2999         if (!empty($toolinfo['launchurl'])) {
3000             return true;
3001         }
3002     } catch (moodle_exception $e) {
3003         return false; // Error loading the xml, so it's not a cartridge.
3004     }
3005     return false;
3008 /**
3009  * Allows you to load settings for an external tool type from an IMS cartridge.
3010  *
3011  * @param  string   $url     The URL to the cartridge
3012  * @param  stdClass $type    The tool type object to be filled in
3013  * @throws moodle_exception if the cartridge could not be loaded correctly
3014  * @since Moodle 3.1
3015  */
3016 function lti_load_type_from_cartridge($url, $type) {
3017     $toolinfo = lti_load_cartridge($url,
3018         array(
3019             "title" => "lti_typename",
3020             "launch_url" => "lti_toolurl",
3021             "description" => "lti_description",
3022             "icon" => "lti_icon",
3023             "secure_icon" => "lti_secureicon"
3024         ),
3025         array(
3026             "icon_url" => "lti_extension_icon",
3027             "secure_icon_url" => "lti_extension_secureicon"
3028         )
3029     );
3030     // If an activity name exists, unset the cartridge name so we don't override it.
3031     if (isset($type->lti_typename)) {
3032         unset($toolinfo['lti_typename']);
3033     }
3035     // Always prefer cartridge core icons first, then, if none are found, look at the extension icons.
3036     if (empty($toolinfo['lti_icon']) && !empty($toolinfo['lti_extension_icon'])) {
3037         $toolinfo['lti_icon'] = $toolinfo['lti_extension_icon'];
3038     }
3039     unset($toolinfo['lti_extension_icon']);
3041     if (empty($toolinfo['lti_secureicon']) && !empty($toolinfo['lti_extension_secureicon'])) {
3042         $toolinfo['lti_secureicon'] = $toolinfo['lti_extension_secureicon'];
3043     }
3044     unset($toolinfo['lti_extension_secureicon']);
3046     // Ensure Custom icons aren't overridden by cartridge params.
3047     if (!empty($type->lti_icon)) {
3048         unset($toolinfo['lti_icon']);
3049     }
3051     if (!empty($type->lti_secureicon)) {
3052         unset($toolinfo['lti_secureicon']);
3053     }
3055     foreach ($toolinfo as $property => $value) {
3056         $type->$property = $value;
3057     }
3060 /**
3061  * Allows you to load in the configuration for an external tool from an IMS cartridge.
3062  *
3063  * @param  string   $url    The URL to the cartridge
3064  * @param  stdClass $lti    LTI object
3065  * @throws moodle_exception if the cartridge could not be loaded correctly
3066  * @since Moodle 3.1
3067  */
3068 function lti_load_tool_from_cartridge($url, $lti) {
3069     $toolinfo = lti_load_cartridge($url,
3070         array(
3071             "title" => "name",
3072             "launch_url" => "toolurl",
3073             "secure_launch_url" => "securetoolurl",
3074             "description" => "intro",
3075             "icon" => "icon",
3076             "secure_icon" => "secureicon"
3077         ),
3078         array(
3079             "icon_url" => "extension_icon",
3080             "secure_icon_url" => "extension_secureicon"
3081         )
3082     );
3083     // If an activity name exists, unset the cartridge name so we don't override it.
3084     if (isset($lti->name)) {
3085         unset($toolinfo['name']);
3086     }
3088     // Always prefer cartridge core icons first, then, if none are found, look at the extension icons.
3089     if (empty($toolinfo['icon']) && !empty($toolinfo['extension_icon'])) {
3090         $toolinfo['icon'] = $toolinfo['extension_icon'];
3091     }
3092     unset($toolinfo['extension_icon']);
3094     if (empty($toolinfo['secureicon']) && !empty($toolinfo['extension_secureicon'])) {
3095         $toolinfo['secureicon'] = $toolinfo['extension_secureicon'];
3096     }
3097     unset($toolinfo['extension_secureicon']);
3099     foreach ($toolinfo as $property => $value) {
3100         $lti->$property = $value;
3101     }
3104 /**
3105  * Search for a tag within an XML DOMDocument
3106  *
3107  * @param  string $url The url of the cartridge to be loaded
3108  * @param  array  $map The map of tags to keys in the return array
3109  * @param  array  $propertiesmap The map of properties to keys in the return array
3110  * @return array An associative array with the given keys and their values from the cartridge
3111  * @throws moodle_exception if the cartridge could not be loaded correctly
3112  * @since Moodle 3.1
3113  */
3114 function lti_load_cartridge($url, $map, $propertiesmap = array()) {
3115     global $CFG;
3116     require_once($CFG->libdir. "/filelib.php");
3118     $curl = new curl();
3119     $response = $curl->get($url);
3121     // TODO MDL-46023 Replace this code with a call to the new library.
3122     $origerrors = libxml_use_internal_errors(true);
3123     $origentity = libxml_disable_entity_loader(true);
3124     libxml_clear_errors();
3126     $document = new DOMDocument();
3127     @$document->loadXML($response, LIBXML_DTDLOAD | LIBXML_DTDATTR);
3129     $cartridge = new DomXpath($document);
3131     $errors = libxml_get_errors();
3133     libxml_clear_errors();
3134     libxml_use_internal_errors($origerrors);
3135     libxml_disable_entity_loader($origentity);
3137     if (count($errors) > 0) {
3138         $message = 'Failed to load cartridge.';
3139         foreach ($errors as $error) {
3140             $message .= "\n" . trim($error->message, "\n\r\t .") . " at line " . $error->line;
3141         }
3142         throw new moodle_exception('errorreadingfile', '', '', $url, $message);
3143     }
3145     $toolinfo = array();
3146     foreach ($map as $tag => $key) {
3147         $value = get_tag($tag, $cartridge);
3148         if ($value) {
3149             $toolinfo[$key] = $value;
3150         }
3151     }
3152     if (!empty($propertiesmap)) {
3153         foreach ($propertiesmap as $property => $key) {
3154             $value = get_tag("property", $cartridge, $property);
3155             if ($value) {
3156                 $toolinfo[$key] = $value;
3157             }
3158         }
3159     }
3161     return $toolinfo;
3164 /**
3165  * Search for a tag within an XML DOMDocument
3166  *
3167  * @param  stdClass $tagname The name of the tag to search for
3168  * @param  XPath    $xpath   The XML to find the tag in
3169  * @param  XPath    $attribute The attribute to search for (if we should search for a child node with the given
3170  * value for the name attribute
3171  * @since Moodle 3.1
3172  */
3173 function get_tag($tagname, $xpath, $attribute = null) {
3174     if ($attribute) {
3175         $result = $xpath->query('//*[local-name() = \'' . $tagname . '\'][@name="' . $attribute . '"]');
3176     } else {
3177         $result = $xpath->query('//*[local-name() = \'' . $tagname . '\']');
3178     }
3179     if ($result->length > 0) {
3180         return $result->item(0)->nodeValue;
3181     }
3182     return null;