[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   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   * Support for external API
  19   *
  20   * @package    core_webservice
  21   * @copyright  2009 Petr Skodak
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  use core_external\util;
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  // Please note that this file and all of the classes and functions listed below will be deprecated from Moodle 4.6.
  30  // This deprecation is delayed to aid plugin developers when maintaining plugins for multiple Moodle versions.
  31  // See MDL-76583 for further information.
  32  
  33  // If including this file for unit testing, it _must_ be run in an isolated process to prevent
  34  // any side effect upon other tests.
  35  require_phpunit_isolation();
  36  
  37  class_alias(\core_external\external_api::class, 'external_api');
  38  class_alias(\core_external\restricted_context_exception::class, 'restricted_context_exception');
  39  class_alias(\core_external\external_description::class, 'external_description');
  40  class_alias(\core_external\external_value::class, 'external_value');
  41  class_alias(\core_external\external_format_value::class, 'external_format_value');
  42  class_alias(\core_external\external_single_structure::class, 'external_single_structure');
  43  class_alias(\core_external\external_multiple_structure::class, 'external_multiple_structure');
  44  class_alias(\core_external\external_function_parameters::class, 'external_function_parameters');
  45  class_alias(\core_external\util::class, 'external_util');
  46  class_alias(\core_external\external_files::class, 'external_files');
  47  class_alias(\core_external\external_warnings::class, 'external_warnings');
  48  class_alias(\core_external\external_settings::class, 'external_settings');
  49  
  50  /**
  51   * Generate a token
  52   *
  53   * @param string $tokentype EXTERNAL_TOKEN_EMBEDDED|EXTERNAL_TOKEN_PERMANENT
  54   * @param stdClass|int $serviceorid service linked to the token
  55   * @param int $userid user linked to the token
  56   * @param stdClass|int $contextorid
  57   * @param int $validuntil date when the token expired
  58   * @param string $iprestriction allowed ip - if 0 or empty then all ips are allowed
  59   * @return string generated token
  60   * @since Moodle 2.0
  61   */
  62  function external_generate_token($tokentype, $serviceorid, $userid, $contextorid, $validuntil = 0, $iprestriction = '') {
  63      if (is_numeric($serviceorid)) {
  64          $service = util::get_service_by_id($serviceorid);
  65      } else if (is_string($serviceorid)) {
  66          $service = util::get_service_by_name($serviceorid);
  67      } else {
  68          $service = $serviceorid;
  69      }
  70  
  71      if (!is_object($contextorid)) {
  72          $context = context::instance_by_id($contextorid, MUST_EXIST);
  73      } else {
  74          $context = $contextorid;
  75      }
  76  
  77      return util::generate_token(
  78          $tokentype,
  79          $service,
  80          $userid,
  81          $context,
  82          $validuntil,
  83          $iprestriction
  84      );
  85  }
  86  
  87  /**
  88   * Create and return a session linked token. Token to be used for html embedded client apps that want to communicate
  89   * with the Moodle server through web services. The token is linked to the current session for the current page request.
  90   * It is expected this will be called in the script generating the html page that is embedding the client app and that the
  91   * returned token will be somehow passed into the client app being embedded in the page.
  92   *
  93   * @param string $servicename name of the web service. Service name as defined in db/services.php
  94   * @param int $context context within which the web service can operate.
  95   * @return int returns token id.
  96   * @since Moodle 2.0
  97   */
  98  function external_create_service_token($servicename, $contextid) {
  99      global $USER;
 100  
 101      return util::generate_token(
 102          EXTERNAL_TOKEN_EMBEDDED,
 103          util::get_service_by_name($servicename),
 104          $USER->id,
 105          \context::instance_by_id($contextid)
 106      );
 107  }
 108  
 109  /**
 110   * Delete all pre-built services (+ related tokens) and external functions information defined in the specified component.
 111   *
 112   * @param string $component name of component (moodle, etc.)
 113   */
 114  function external_delete_descriptions($component) {
 115      util::delete_service_descriptions($component);
 116  }
 117  
 118  /**
 119   * Validate text field format against known FORMAT_XXX
 120   *
 121   * @param array $format the format to validate
 122   * @return the validated format
 123   * @throws coding_exception
 124   * @since Moodle 2.3
 125   */
 126  function external_validate_format($format) {
 127      return util::validate_format($format);
 128  }
 129  
 130  /**
 131   * Format the string to be returned properly as requested by the either the web service server,
 132   * either by an internally call.
 133   * The caller can change the format (raw) with the external_settings singleton
 134   * All web service servers must set this singleton when parsing the $_GET and $_POST.
 135   *
 136   * <pre>
 137   * Options are the same that in {@link format_string()} with some changes:
 138   *      filter      : Can be set to false to force filters off, else observes {@link external_settings}.
 139   * </pre>
 140   *
 141   * @param string $str The string to be filtered. Should be plain text, expect
 142   * possibly for multilang tags.
 143   * @param boolean $striplinks To strip any link in the result text. Moodle 1.8 default changed from false to true! MDL-8713
 144   * @param context|int $contextorid The id of the context for the string or the context (affects filters).
 145   * @param array $options options array/object or courseid
 146   * @return string text
 147   * @since Moodle 3.0
 148   */
 149  function external_format_string($str, $context, $striplinks = true, $options = []) {
 150      if (!$context instanceof context) {
 151          $context = context::instance_by_id($context);
 152      }
 153  
 154      return util::format_string($str, $context, $striplinks, $options);
 155  }
 156  
 157  /**
 158   * Format the text to be returned properly as requested by the either the web service server,
 159   * either by an internally call.
 160   * The caller can change the format (raw, filter, file, fileurl) with the external_settings singleton
 161   * All web service servers must set this singleton when parsing the $_GET and $_POST.
 162   *
 163   * <pre>
 164   * Options are the same that in {@link format_text()} with some changes in defaults to provide backwards compatibility:
 165   *      trusted     :   If true the string won't be cleaned. Default false.
 166   *      noclean     :   If true the string won't be cleaned only if trusted is also true. Default false.
 167   *      nocache     :   If true the string will not be cached and will be formatted every call. Default false.
 168   *      filter      :   Can be set to false to force filters off, else observes {@link external_settings}.
 169   *      para        :   If true then the returned string will be wrapped in div tags. Default (different from format_text) false.
 170   *                      Default changed because div tags are not commonly needed.
 171   *      newlines    :   If true then lines newline breaks will be converted to HTML newline breaks. Default true.
 172   *      context     :   Not used! Using contextid parameter instead.
 173   *      overflowdiv :   If set to true the formatted text will be encased in a div with the class no-overflow before being
 174   *                      returned. Default false.
 175   *      allowid     :   If true then id attributes will not be removed, even when using htmlpurifier. Default (different from
 176   *                      format_text) true. Default changed id attributes are commonly needed.
 177   *      blanktarget :   If true all <a> tags will have target="_blank" added unless target is explicitly specified.
 178   * </pre>
 179   *
 180   * @param string $text The content that may contain ULRs in need of rewriting.
 181   * @param int $textformat The text format.
 182   * @param context|int $context This parameter and the next two identify the file area to use.
 183   * @param string $component
 184   * @param string $filearea helps identify the file area.
 185   * @param int $itemid helps identify the file area.
 186   * @param object/array $options text formatting options
 187   * @return array text + textformat
 188   * @since Moodle 2.3
 189   * @since Moodle 3.2 component, filearea and itemid are optional parameters
 190   */
 191  function external_format_text($text, $textformat, $context, $component = null, $filearea = null, $itemid = null, $options = null) {
 192      if (!$context instanceof context) {
 193          $context = context::instance_by_id($context);
 194      }
 195  
 196      return util::format_text($text, $textformat, $context, $component, $filearea, $itemid, $options);
 197  }
 198  
 199  /**
 200   * Generate or return an existing token for the current authenticated user.
 201   * This function is used for creating a valid token for users authenticathing via login/token.php or admin/tool/mobile/launch.php.
 202   *
 203   * @param stdClass $service external service object
 204   * @return stdClass token object
 205   * @since Moodle 3.2
 206   */
 207  function external_generate_token_for_current_user($service) {
 208      return util::generate_token_for_current_user($service);
 209  }
 210  
 211  /**
 212   * Set the last time a token was sent and trigger the \core\event\webservice_token_sent event.
 213   *
 214   * This function is used when a token is generated by the user via login/token.php or admin/tool/mobile/launch.php.
 215   * In order to protect the privatetoken, we remove it from the event params.
 216   *
 217   * @param  stdClass $token token object
 218   * @since  Moodle 3.2
 219   */
 220  function external_log_token_request($token): void {
 221      util::log_token_request($token);
 222  }