Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 9 May 2022 (12 months).
  • Bug fixes for security issues in 3.11.x will end 14 November 2022 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 38 and 311]

       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  }