Merge branch 'MDL-64657-310' of git://github.com/jleyva/moodle into MOODLE_310_STABLE
[moodle.git] / h5p / classes / external.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * This is the external API for this component.
19  *
20  * @package    core_h5p
21  * @copyright  2019 Carlos Escobedo <carlos@moodle.com>
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core_h5p;
27 defined('MOODLE_INTERNAL') || die();
29 require_once($CFG->libdir . '/externallib.php');
31 use external_api;
32 use external_function_parameters;
33 use external_value;
34 use external_single_structure;
35 use external_files;
36 use external_warnings;
38 /**
39  * This is the external API for this component.
40  *
41  * @copyright  2019 Carlos Escobedo <carlos@moodle.com>
42  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43  */
44 class external extends external_api {
45     /**
46      * get_trusted_h5p_file parameters.
47      *
48      * @since  Moodle 3.8
49      * @return external_function_parameters
50      */
51     public static function get_trusted_h5p_file_parameters() {
52         return new external_function_parameters(
53             [
54                 'url' => new external_value(PARAM_URL, 'H5P file url.', VALUE_REQUIRED),
55                 'frame' => new external_value(PARAM_INT, 'The frame allow to show the bar options below the content', VALUE_DEFAULT, 0),
56                 'export' => new external_value(PARAM_INT, 'The export allow to download the package', VALUE_DEFAULT, 0),
57                 'embed' => new external_value(PARAM_INT, 'The embed allow to copy the code to your site', VALUE_DEFAULT, 0),
58                 'copyright' => new external_value(PARAM_INT, 'The copyright option', VALUE_DEFAULT, 0)
59             ]
60         );
61     }
63     /**
64      * Return the H5P file trusted.
65      *
66      * The Mobile App needs to work with an H5P package which can trust.
67      * And this H5P package is only trusted by the Mobile App once it's been processed
68      * by the core checking the right caps, validating the H5P package
69      * and doing any clean-up process involved.
70      *
71      * @since  Moodle 3.8
72      * @param  string $url H5P file url
73      * @param  int $frame The frame allow to show the bar options below the content
74      * @param  int $export The export allow to download the package
75      * @param  int $embed The embed allow to copy the code to your site
76      * @param  int $copyright The copyright option
77      * @return array
78      * @throws \moodle_exception
79      */
80     public static function get_trusted_h5p_file(string $url, int $frame, int $export, int $embed, int $copyright) {
82         $result = [];
83         $warnings = [];
84         $params = external_api::validate_parameters(self::get_trusted_h5p_file_parameters(), [
85             'url' => $url,
86             'frame' => $frame,
87             'export' => $export,
88             'embed' => $embed,
89             'copyright' => $copyright
90         ]);
91         $url = $params['url'];
92         $config = new \stdClass();
93         $config->frame = $params['frame'];
94         $config->export = $params['export'];
95         $config->embed = $params['embed'];
96         $config->copyright = $params['copyright'];
97         try {
98             $h5pplayer = new player($url, $config);
99             $messages = $h5pplayer->get_messages();
100         } catch (\moodle_exception $e) {
101             $messages = (object) [
102                 'code' => $e->getCode(),
103             ];
104             // To mantain the coherence between web coding error and Mobile coding errors.
105             // We need to return the same message error to Mobile.
106             // The 'out_al_local_url called on a non-local URL' error is provided by the \moodle_exception.
107             // We have to translate to h5pinvalidurl which is the same coding error showed in web.
108             if ($e->errorcode === 'codingerror' &&
109                     $e->a === 'out_as_local_url called on a non-local URL') {
110                 $messages->exception = get_string('h5pinvalidurl', 'core_h5p');
111             } else {
112                 $messages->exception = $e->getMessage();
113             }
114         }
116         if (empty($messages->error) && empty($messages->exception)) {
117             // Add H5P assets to the page.
118             $h5pplayer->add_assets_to_page();
119             // Check if there is some error when adding assets to the page.
120             $messages = $h5pplayer->get_messages();
121             if (empty($messages->error)) {
122                 $fileh5p = $h5pplayer->get_export_file();
123                 $result[] = $fileh5p;
124             }
125         }
126         if (!empty($messages->error)) {
127             foreach ($messages->error as $error) {
128                 // We have to apply clean_param because warningcode is a PARAM_ALPHANUM.
129                 // And H5P has some error code like 'not-in-whitelist'.
130                 $warnings[] = [
131                     'item' => $url,
132                     'warningcode' => clean_param($error->code, PARAM_ALPHANUM),
133                     'message' => $error->message
134                 ];
135             }
136         } else if (!empty($messages->exception)) {
137             $warnings[] = [
138                 'item' => $url,
139                 'warningcode' => $messages->code,
140                 'message' => $messages->exception
141             ];
142         }
144         return [
145             'files' => $result,
146             'warnings' => $warnings
147         ];
148     }
150     /**
151      * get_trusted_h5p_file return
152      *
153      * @since  Moodle 3.8
154      * @return external_description
155      */
156     public static function get_trusted_h5p_file_returns() {
157         return new external_single_structure(
158             [
159                 'files'    => new external_files('H5P file trusted.'),
160                 'warnings' => new external_warnings()
161             ]
162         );
163     }