Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * 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   */
  24  
  25  namespace core_h5p;
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  
  29  require_once($CFG->libdir . '/externallib.php');
  30  
  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;
  37  
  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      }
  62  
  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) {
  81  
  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          }
 115  
 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 'total-size-too-large'.
 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          }
 143  
 144          return [
 145              'files' => $result,
 146              'warnings' => $warnings
 147          ];
 148      }
 149  
 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      }
 164  }