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/>.
  16
  17 namespace core_h5p;
  18
  19 use core_external\external_api;
  20 use core_external\external_files;
  21 use core_external\external_function_parameters;
  22 use core_external\external_single_structure;
  23 use core_external\external_value;
  24 use core_external\external_warnings;
  25
  26 /**
  27  * This is the external API for this component.
  28  *
  29  * @package    core_h5p
  30  * @copyright  2019 Carlos Escobedo <carlos@moodle.com>
  31  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  32  */
  33 class external extends external_api {
  34     /**
  35      * get_trusted_h5p_file parameters.
  36      *
  37      * @since  Moodle 3.8
  38      * @return external_function_parameters
  39      */
  40     public static function get_trusted_h5p_file_parameters() {
  41         return new external_function_parameters(
  42             [
  43                 'url' => new external_value(PARAM_URL, 'H5P file url.', VALUE_REQUIRED),
  44                 'frame' => new external_value(PARAM_INT, 'The frame allow to show the bar options below the content', VALUE_DEFAULT, 0),
  45                 'export' => new external_value(PARAM_INT, 'The export allow to download the package', VALUE_DEFAULT, 0),
  46                 'embed' => new external_value(PARAM_INT, 'The embed allow to copy the code to your site', VALUE_DEFAULT, 0),
  47                 'copyright' => new external_value(PARAM_INT, 'The copyright option', VALUE_DEFAULT, 0)
  48             ]
  49         );
  50     }
  51
  52     /**
  53      * Return the H5P file trusted.
  54      *
  55      * The Mobile App needs to work with an H5P package which can trust.
  56      * And this H5P package is only trusted by the Mobile App once it's been processed
  57      * by the core checking the right caps, validating the H5P package
  58      * and doing any clean-up process involved.
  59      *
  60      * @since  Moodle 3.8
  61      * @param  string $url H5P file url
  62      * @param  int $frame The frame allow to show the bar options below the content
  63      * @param  int $export The export allow to download the package
  64      * @param  int $embed The embed allow to copy the code to your site
  65      * @param  int $copyright The copyright option
  66      * @return array
  67      * @throws \moodle_exception
  68      */
  69     public static function get_trusted_h5p_file(string $url, int $frame, int $export, int $embed, int $copyright) {
  70
  71         $result = [];
  72         $warnings = [];
  73         $params = external_api::validate_parameters(self::get_trusted_h5p_file_parameters(), [
  74             'url' => $url,
  75             'frame' => $frame,
  76             'export' => $export,
  77             'embed' => $embed,
  78             'copyright' => $copyright
  79         ]);
  80         $url = $params['url'];
  81         $config = new \stdClass();
  82         $config->frame = $params['frame'];
  83         $config->export = $params['export'];
  84         $config->embed = $params['embed'];
  85         $config->copyright = $params['copyright'];
  86         try {
  87             $h5pplayer = new player($url, $config);
  88             $messages = $h5pplayer->get_messages();
  89         } catch (\moodle_exception $e) {
  90             $messages = (object) [
  91                 'code' => $e->getCode(),
  92             ];
  93             // To mantain the coherence between web coding error and Mobile coding errors.
  94             // We need to return the same message error to Mobile.
  95             // The 'out_al_local_url called on a non-local URL' error is provided by the \moodle_exception.
  96             // We have to translate to h5pinvalidurl which is the same coding error showed in web.
  97             if ($e->errorcode === 'codingerror' &&
  98                     $e->a === 'out_as_local_url called on a non-local URL') {
  99                 $messages->exception = get_string('h5pinvalidurl', 'core_h5p');
 100             } else {
 101                 $messages->exception = $e->getMessage();
 102             }
 103         }
 104
 105         if (empty($messages->error) && empty($messages->exception)) {
 106             // Add H5P assets to the page.
 107             $h5pplayer->add_assets_to_page();
 108             // Check if there is some error when adding assets to the page.
 109             $messages = $h5pplayer->get_messages();
 110             if (empty($messages->error)) {
 111                 $fileh5p = $h5pplayer->get_export_file();
 112                 $result[] = $fileh5p;
 113             }
 114         }
 115         if (!empty($messages->error)) {
 116             foreach ($messages->error as $error) {
 117                 // We have to apply clean_param because warningcode is a PARAM_ALPHANUM.
 118                 // And H5P has some error code like 'total-size-too-large'.
 119                 $warnings[] = [
 120                     'item' => $url,
 121                     'warningcode' => clean_param($error->code, PARAM_ALPHANUM),
 122                     'message' => $error->message
 123                 ];
 124             }
 125         } else if (!empty($messages->exception)) {
 126             $warnings[] = [
 127                 'item' => $url,
 128                 'warningcode' => $messages->code,
 129                 'message' => $messages->exception
 130             ];
 131         }
 132
 133         return [
 134             'files' => $result,
 135             'warnings' => $warnings
 136         ];
 137     }
 138
 139     /**
 140      * get_trusted_h5p_file return
 141      *
 142      * @since  Moodle 3.8
 143      * @return \core_external\external_description
 144      */
 145     public static function get_trusted_h5p_file_returns() {
 146         return new external_single_structure(
 147             [
 148                 'files'    => new external_files('H5P file trusted.'),
 149                 'warnings' => new external_warnings()
 150             ]
 151         );
 152     }
 153 }