Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • 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 310 and 311] [Versions 311 and 400] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 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  /**
      19   * Support for external API
      20   *
      21   * @package    core_webservice
      22   * @copyright  2009 Petr Skodak
      23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      24   */
      25  
      26  defined('MOODLE_INTERNAL') || die();
      27  
      28  /**
      29   * Exception indicating user is not allowed to use external function in the current context.
      30   *
      31   * @package    core_webservice
      32   * @copyright  2009 Petr Skodak
      33   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      34   * @since Moodle 2.0
      35   */
      36  class restricted_context_exception extends moodle_exception {
      37      /**
      38       * Constructor
      39       *
      40       * @since Moodle 2.0
      41       */
      42      function __construct() {
      43          parent::__construct('restrictedcontextexception', 'error');
      44      }
      45  }
      46  
      47  /**
      48   * Base class for external api methods.
      49   *
      50   * @package    core_webservice
      51   * @copyright  2009 Petr Skodak
      52   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      53   * @since Moodle 2.0
      54   */
      55  class external_api {
      56  
      57      /** @var stdClass context where the function calls will be restricted */
      58      private static $contextrestriction;
      59  
      60      /**
      61       * Returns detailed function information
      62       *
      63       * @param string|object $function name of external function or record from external_function
      64       * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
      65       *                        MUST_EXIST means throw exception if no record or multiple records found
      66       * @return stdClass description or false if not found or exception thrown
      67       * @since Moodle 2.0
      68       */
      69      public static function external_function_info($function, $strictness=MUST_EXIST) {
      70          global $DB, $CFG;
      71  
      72          if (!is_object($function)) {
      73              if (!$function = $DB->get_record('external_functions', array('name' => $function), '*', $strictness)) {
      74                  return false;
      75              }
      76          }
      77  
      78          // First try class autoloading.
      79          if (!class_exists($function->classname)) {
      80              // Fallback to explicit include of externallib.php.
      81              if (empty($function->classpath)) {
      82                  $function->classpath = core_component::get_component_directory($function->component).'/externallib.php';
      83              } else {
      84                  $function->classpath = $CFG->dirroot.'/'.$function->classpath;
      85              }
      86              if (!file_exists($function->classpath)) {
      87                  throw new coding_exception('Cannot find file ' . $function->classpath .
      88                          ' with external function implementation');
      89              }
      90              require_once($function->classpath);
      91              if (!class_exists($function->classname)) {
      92                  throw new coding_exception('Cannot find external class ' . $function->classname);
      93              }
      94          }
      95  
      96          $function->ajax_method = $function->methodname.'_is_allowed_from_ajax';
      97          $function->parameters_method = $function->methodname.'_parameters';
      98          $function->returns_method    = $function->methodname.'_returns';
      99          $function->deprecated_method = $function->methodname.'_is_deprecated';
     100  
     101          // Make sure the implementaion class is ok.
     102          if (!method_exists($function->classname, $function->methodname)) {
     103              throw new coding_exception('Missing implementation method ' .
     104                      $function->classname . '::' . $function->methodname);
     105          }
     106          if (!method_exists($function->classname, $function->parameters_method)) {
     107              throw new coding_exception('Missing parameters description method ' .
     108                      $function->classname . '::' . $function->parameters_method);
     109          }
     110          if (!method_exists($function->classname, $function->returns_method)) {
     111              throw new coding_exception('Missing returned values description method ' .
     112                      $function->classname . '::' . $function->returns_method);
     113          }
     114          if (method_exists($function->classname, $function->deprecated_method)) {
     115              if (call_user_func(array($function->classname, $function->deprecated_method)) === true) {
     116                  $function->deprecated = true;
     117              }
     118          }
     119          $function->allowed_from_ajax = false;
     120  
     121          // Fetch the parameters description.
     122          $function->parameters_desc = call_user_func(array($function->classname, $function->parameters_method));
     123          if (!($function->parameters_desc instanceof external_function_parameters)) {
     124              throw new coding_exception($function->classname . '::' . $function->parameters_method .
     125                      ' did not return a valid external_function_parameters object.');
     126          }
     127  
     128          // Fetch the return values description.
     129          $function->returns_desc = call_user_func(array($function->classname, $function->returns_method));
     130          // Null means void result or result is ignored.
     131          if (!is_null($function->returns_desc) and !($function->returns_desc instanceof external_description)) {
     132              throw new coding_exception($function->classname . '::' . $function->returns_method .
     133                      ' did not return a valid external_description object');
     134          }
     135  
     136          // Now get the function description.
     137  
     138          // TODO MDL-31115 use localised lang pack descriptions, it would be nice to have
     139          // easy to understand descriptions in admin UI,
     140          // on the other hand this is still a bit in a flux and we need to find some new naming
     141          // conventions for these descriptions in lang packs.
     142          $function->description = null;
     143          $servicesfile = core_component::get_component_directory($function->component).'/db/services.php';
     144          if (file_exists($servicesfile)) {
     145              $functions = null;
     146              include($servicesfile);
     147              if (isset($functions[$function->name]['description'])) {
     148                  $function->description = $functions[$function->name]['description'];
     149              }
     150              if (isset($functions[$function->name]['testclientpath'])) {
     151                  $function->testclientpath = $functions[$function->name]['testclientpath'];
     152              }
     153              if (isset($functions[$function->name]['type'])) {
     154                  $function->type = $functions[$function->name]['type'];
     155              }
     156              if (isset($functions[$function->name]['ajax'])) {
     157                  $function->allowed_from_ajax = $functions[$function->name]['ajax'];
     158              } else if (method_exists($function->classname, $function->ajax_method)) {
     159                  if (call_user_func(array($function->classname, $function->ajax_method)) === true) {
     160                      debugging('External function ' . $function->ajax_method . '() function is deprecated.' .
     161                                'Set ajax=>true in db/service.php instead.', DEBUG_DEVELOPER);
     162                      $function->allowed_from_ajax = true;
     163                  }
     164              }
     165              if (isset($functions[$function->name]['loginrequired'])) {
     166                  $function->loginrequired = $functions[$function->name]['loginrequired'];
     167              } else {
     168                  $function->loginrequired = true;
     169              }
     170              if (isset($functions[$function->name]['readonlysession'])) {
     171                  $function->readonlysession = $functions[$function->name]['readonlysession'];
     172              } else {
     173                  $function->readonlysession = false;
     174              }
     175          }
     176  
     177          return $function;
     178      }
     179  
     180      /**
     181       * Call an external function validating all params/returns correctly.
     182       *
     183       * Note that an external function may modify the state of the current page, so this wrapper
     184       * saves and restores tha PAGE and COURSE global variables before/after calling the external function.
     185       *
     186       * @param string $function A webservice function name.
     187       * @param array $args Params array (named params)
     188       * @param boolean $ajaxonly If true, an extra check will be peformed to see if ajax is required.
     189       * @return array containing keys for error (bool), exception and data.
     190       */
     191      public static function call_external_function($function, $args, $ajaxonly=false) {
     192          global $PAGE, $COURSE, $CFG, $SITE;
     193  
     194          require_once($CFG->libdir . "/pagelib.php");
     195  
     196          $externalfunctioninfo = static::external_function_info($function);
     197  
     198          // Eventually this should shift into the various handlers and not be handled via config.
     199          $readonlysession = $externalfunctioninfo->readonlysession ?? false;
     200          if (!$readonlysession || empty($CFG->enable_read_only_sessions)) {
     201              \core\session\manager::restart_with_write_lock($readonlysession);
     202          }
     203  
     204          $currentpage = $PAGE;
     205          $currentcourse = $COURSE;
     206          $response = array();
     207  
     208          try {
     209              // Taken straight from from setup.php.
     210              if (!empty($CFG->moodlepageclass)) {
     211                  if (!empty($CFG->moodlepageclassfile)) {
     212                      require_once($CFG->moodlepageclassfile);
     213                  }
     214                  $classname = $CFG->moodlepageclass;
     215              } else {
     216                  $classname = 'moodle_page';
     217              }
     218              $PAGE = new $classname();
     219              $COURSE = clone($SITE);
     220  
     221              if ($ajaxonly && !$externalfunctioninfo->allowed_from_ajax) {
     222                  throw new moodle_exception('servicenotavailable', 'webservice');
     223              }
     224  
     225              // Do not allow access to write or delete webservices as a public user.
     226              if ($externalfunctioninfo->loginrequired && !WS_SERVER) {
     227                  if (defined('NO_MOODLE_COOKIES') && NO_MOODLE_COOKIES && !PHPUNIT_TEST) {
     228                      throw new moodle_exception('servicerequireslogin', 'webservice');
     229                  }
     230                  if (!isloggedin()) {
     231                      throw new moodle_exception('servicerequireslogin', 'webservice');
     232                  } else {
     233                      require_sesskey();
     234                  }
     235              }
     236              // Validate params, this also sorts the params properly, we need the correct order in the next part.
     237              $callable = array($externalfunctioninfo->classname, 'validate_parameters');
     238              $params = call_user_func($callable,
     239                                       $externalfunctioninfo->parameters_desc,
     240                                       $args);
     241              $params = array_values($params);
     242  
     243              // Allow any Moodle plugin a chance to override this call. This is a convenient spot to
     244              // make arbitrary behaviour customisations. The overriding plugin could call the 'real'
     245              // function first and then modify the results, or it could do a completely separate
     246              // thing.
     247              $callbacks = get_plugins_with_function('override_webservice_execution');
     248              $result = false;
     249              foreach ($callbacks as $plugintype => $plugins) {
     250                  foreach ($plugins as $plugin => $callback) {
     251                      $result = $callback($externalfunctioninfo, $params);
     252                      if ($result !== false) {
     253                          break 2;
     254                      }
     255                  }
     256              }
     257  
     258              // If the function was not overridden, call the real one.
     259              if ($result === false) {
     260                  $callable = array($externalfunctioninfo->classname, $externalfunctioninfo->methodname);
     261                  $result = call_user_func_array($callable, $params);
     262              }
     263  
     264              // Validate the return parameters.
     265              if ($externalfunctioninfo->returns_desc !== null) {
     266                  $callable = array($externalfunctioninfo->classname, 'clean_returnvalue');
     267                  $result = call_user_func($callable, $externalfunctioninfo->returns_desc, $result);
     268              }
     269  
     270              $response['error'] = false;
     271              $response['data'] = $result;
     272          } catch (Throwable $e) {
     273              $exception = get_exception_info($e);
     274              unset($exception->a);
     275              $exception->backtrace = format_backtrace($exception->backtrace, true);
     276              if (!debugging('', DEBUG_DEVELOPER)) {
     277                  unset($exception->debuginfo);
     278                  unset($exception->backtrace);
     279              }
     280              $response['error'] = true;
     281              $response['exception'] = $exception;
     282              // Do not process the remaining requests.
     283          }
     284  
     285          $PAGE = $currentpage;
     286          $COURSE = $currentcourse;
     287  
     288          return $response;
     289      }
     290  
     291      /**
     292       * Set context restriction for all following subsequent function calls.
     293       *
     294       * @param stdClass $context the context restriction
     295       * @since Moodle 2.0
     296       */
     297      public static function set_context_restriction($context) {
     298          self::$contextrestriction = $context;
     299      }
     300  
     301      /**
     302       * This method has to be called before every operation
     303       * that takes a longer time to finish!
     304       *
     305       * @param int $seconds max expected time the next operation needs
     306       * @since Moodle 2.0
     307       */
     308      public static function set_timeout($seconds=360) {
     309          $seconds = ($seconds < 300) ? 300 : $seconds;
     310          core_php_time_limit::raise($seconds);
     311      }
     312  
     313      /**
     314       * Validates submitted function parameters, if anything is incorrect
     315       * invalid_parameter_exception is thrown.
     316       * This is a simple recursive method which is intended to be called from
     317       * each implementation method of external API.
     318       *
     319       * @param external_description $description description of parameters
     320       * @param mixed $params the actual parameters
     321       * @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
     322       * @since Moodle 2.0
     323       */
     324      public static function validate_parameters(external_description $description, $params) {
     325          if ($description instanceof external_value) {
     326              if (is_array($params) or is_object($params)) {
     327                  throw new invalid_parameter_exception('Scalar type expected, array or object received.');
     328              }
     329  
     330              if ($description->type == PARAM_BOOL) {
     331                  // special case for PARAM_BOOL - we want true/false instead of the usual 1/0 - we can not be too strict here ;-)
     332                  if (is_bool($params) or $params === 0 or $params === 1 or $params === '0' or $params === '1') {
     333                      return (bool)$params;
     334                  }
     335              }
     336              $debuginfo = 'Invalid external api parameter: the value is "' . $params .
     337                      '", the server was expecting "' . $description->type . '" type';
     338              return validate_param($params, $description->type, $description->allownull, $debuginfo);
     339  
     340          } else if ($description instanceof external_single_structure) {
     341              if (!is_array($params)) {
     342                  throw new invalid_parameter_exception('Only arrays accepted. The bad value is: \''
     343                          . print_r($params, true) . '\'');
     344              }
     345              $result = array();
     346              foreach ($description->keys as $key=>$subdesc) {
     347                  if (!array_key_exists($key, $params)) {
     348                      if ($subdesc->required == VALUE_REQUIRED) {
     349                          throw new invalid_parameter_exception('Missing required key in single structure: '. $key);
     350                      }
     351                      if ($subdesc->required == VALUE_DEFAULT) {
     352                          try {
     353                              $result[$key] = static::validate_parameters($subdesc, $subdesc->default);
     354                          } catch (invalid_parameter_exception $e) {
     355                              //we are only interested by exceptions returned by validate_param() and validate_parameters()
     356                              //(in order to build the path to the faulty attribut)
     357                              throw new invalid_parameter_exception($key." => ".$e->getMessage() . ': ' .$e->debuginfo);
     358                          }
     359                      }
     360                  } else {
     361                      try {
     362                          $result[$key] = static::validate_parameters($subdesc, $params[$key]);
     363                      } catch (invalid_parameter_exception $e) {
     364                          //we are only interested by exceptions returned by validate_param() and validate_parameters()
     365                          //(in order to build the path to the faulty attribut)
     366                          throw new invalid_parameter_exception($key." => ".$e->getMessage() . ': ' .$e->debuginfo);
     367                      }
     368                  }
     369                  unset($params[$key]);
     370              }
     371              if (!empty($params)) {
     372                  throw new invalid_parameter_exception('Unexpected keys (' . implode(', ', array_keys($params)) . ') detected in parameter array.');
     373              }
     374              return $result;
     375  
     376          } else if ($description instanceof external_multiple_structure) {
     377              if (!is_array($params)) {
     378                  throw new invalid_parameter_exception('Only arrays accepted. The bad value is: \''
     379                          . print_r($params, true) . '\'');
     380              }
     381              $result = array();
     382              foreach ($params as $param) {
     383                  $result[] = static::validate_parameters($description->content, $param);
     384              }
     385              return $result;
     386  
     387          } else {
     388              throw new invalid_parameter_exception('Invalid external api description');
     389          }
     390      }
     391  
     392      /**
     393       * Clean response
     394       * If a response attribute is unknown from the description, we just ignore the attribute.
     395       * If a response attribute is incorrect, invalid_response_exception is thrown.
     396       * Note: this function is similar to validate parameters, however it is distinct because
     397       * parameters validation must be distinct from cleaning return values.
     398       *
     399       * @param external_description $description description of the return values
     400       * @param mixed $response the actual response
     401       * @return mixed response with added defaults for optional items, invalid_response_exception thrown if any problem found
     402       * @author 2010 Jerome Mouneyrac
     403       * @since Moodle 2.0
     404       */
     405      public static function clean_returnvalue(external_description $description, $response) {
     406          if ($description instanceof external_value) {
     407              if (is_array($response) or is_object($response)) {
     408                  throw new invalid_response_exception('Scalar type expected, array or object received.');
     409              }
     410  
     411              if ($description->type == PARAM_BOOL) {
     412                  // special case for PARAM_BOOL - we want true/false instead of the usual 1/0 - we can not be too strict here ;-)
     413                  if (is_bool($response) or $response === 0 or $response === 1 or $response === '0' or $response === '1') {
     414                      return (bool)$response;
     415                  }
     416              }
     417              $responsetype = gettype($response);
     418              $debuginfo = 'Invalid external api response: the value is "' . $response .
     419                      '" of PHP type "' . $responsetype . '", the server was expecting "' . $description->type . '" type';
     420              try {
     421                  return validate_param($response, $description->type, $description->allownull, $debuginfo);
     422              } catch (invalid_parameter_exception $e) {
     423                  //proper exception name, to be recursively catched to build the path to the faulty attribut
     424                  throw new invalid_response_exception($e->debuginfo);
     425              }
     426  
     427          } else if ($description instanceof external_single_structure) {
     428              if (!is_array($response) && !is_object($response)) {
     429                  throw new invalid_response_exception('Only arrays/objects accepted. The bad value is: \'' .
     430                          print_r($response, true) . '\'');
     431              }
     432  
     433              // Cast objects into arrays.
     434              if (is_object($response)) {
     435                  $response = (array) $response;
     436              }
     437  
     438              $result = array();
     439              foreach ($description->keys as $key=>$subdesc) {
     440                  if (!array_key_exists($key, $response)) {
     441                      if ($subdesc->required == VALUE_REQUIRED) {
     442                          throw new invalid_response_exception('Error in response - Missing following required key in a single structure: ' . $key);
     443                      }
     444                      if ($subdesc instanceof external_value) {
     445                          if ($subdesc->required == VALUE_DEFAULT) {
     446                              try {
     447                                      $result[$key] = static::clean_returnvalue($subdesc, $subdesc->default);
     448                              } catch (invalid_response_exception $e) {
     449                                  //build the path to the faulty attribut
     450                                  throw new invalid_response_exception($key." => ".$e->getMessage() . ': ' . $e->debuginfo);
     451                              }
     452                          }
     453                      }
     454                  } else {
     455                      try {
     456                          $result[$key] = static::clean_returnvalue($subdesc, $response[$key]);
     457                      } catch (invalid_response_exception $e) {
     458                          //build the path to the faulty attribut
     459                          throw new invalid_response_exception($key." => ".$e->getMessage() . ': ' . $e->debuginfo);
     460                      }
     461                  }
     462                  unset($response[$key]);
     463              }
     464  
     465              return $result;
     466  
     467          } else if ($description instanceof external_multiple_structure) {
     468              if (!is_array($response)) {
     469                  throw new invalid_response_exception('Only arrays accepted. The bad value is: \'' .
     470                          print_r($response, true) . '\'');
     471              }
     472              $result = array();
     473              foreach ($response as $param) {
     474                  $result[] = static::clean_returnvalue($description->content, $param);
     475              }
     476              return $result;
     477  
     478          } else {
     479              throw new invalid_response_exception('Invalid external api response description');
     480          }
     481      }
     482  
     483      /**
     484       * Makes sure user may execute functions in this context.
     485       *
     486       * @param stdClass $context
     487       * @since Moodle 2.0
     488       */
     489      public static function validate_context($context) {
     490          global $CFG, $PAGE;
     491  
     492          if (empty($context)) {
     493              throw new invalid_parameter_exception('Context does not exist');
     494          }
     495          if (empty(self::$contextrestriction)) {
     496              self::$contextrestriction = context_system::instance();
     497          }
     498          $rcontext = self::$contextrestriction;
     499  
     500          if ($rcontext->contextlevel == $context->contextlevel) {
     501              if ($rcontext->id != $context->id) {
     502                  throw new restricted_context_exception();
     503              }
     504          } else if ($rcontext->contextlevel > $context->contextlevel) {
     505              throw new restricted_context_exception();
     506          } else {
     507              $parents = $context->get_parent_context_ids();
     508              if (!in_array($rcontext->id, $parents)) {
     509                  throw new restricted_context_exception();
     510              }
     511          }
     512  
     513          $PAGE->reset_theme_and_output();
     514          list($unused, $course, $cm) = get_context_info_array($context->id);
     515          require_login($course, false, $cm, false, true);
     516          $PAGE->set_context($context);
     517      }
     518  
     519      /**
     520       * Get context from passed parameters.
     521       * The passed array must either contain a contextid or a combination of context level and instance id to fetch the context.
     522       * For example, the context level can be "course" and instanceid can be courseid.
     523       *
     524       * See context_helper::get_all_levels() for a list of valid context levels.
     525       *
     526       * @param array $param
     527       * @since Moodle 2.6
     528       * @throws invalid_parameter_exception
     529       * @return context
     530       */
     531      protected static function get_context_from_params($param) {
     532          $levels = context_helper::get_all_levels();
     533          if (!empty($param['contextid'])) {
     534              return context::instance_by_id($param['contextid'], IGNORE_MISSING);
     535          } else if (!empty($param['contextlevel']) && isset($param['instanceid'])) {
     536              $contextlevel = "context_".$param['contextlevel'];
     537              if (!array_search($contextlevel, $levels)) {
     538                  throw new invalid_parameter_exception('Invalid context level = '.$param['contextlevel']);
     539              }
     540             return $contextlevel::instance($param['instanceid'], IGNORE_MISSING);
     541          } else {
     542              // No valid context info was found.
     543              throw new invalid_parameter_exception('Missing parameters, please provide either context level with instance id or contextid');
     544          }
     545      }
     546  
     547      /**
     548       * Returns a prepared structure to use a context parameters.
     549       * @return external_single_structure
     550       */
     551      protected static function get_context_parameters() {
     552          $id = new external_value(
     553              PARAM_INT,
     554              'Context ID. Either use this value, or level and instanceid.',
     555              VALUE_DEFAULT,
     556              0
     557          );
     558          $level = new external_value(
     559              PARAM_ALPHA,
     560              'Context level. To be used with instanceid.',
     561              VALUE_DEFAULT,
     562              ''
     563          );
     564          $instanceid = new external_value(
     565              PARAM_INT,
     566              'Context instance ID. To be used with level',
     567              VALUE_DEFAULT,
     568              0
     569          );
     570          return new external_single_structure(array(
     571              'contextid' => $id,
     572              'contextlevel' => $level,
     573              'instanceid' => $instanceid,
     574          ));
     575      }
     576  
     577  }
     578  
     579  /**
     580   * Common ancestor of all parameter description classes
     581   *
     582   * @package    core_webservice
     583   * @copyright  2009 Petr Skodak
     584   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     585   * @since Moodle 2.0
     586   */
     587  abstract class external_description {
     588      /** @var string Description of element */
     589      public $desc;
     590  
     591      /** @var bool Element value required, null not allowed */
     592      public $required;
     593  
     594      /** @var mixed Default value */
     595      public $default;
     596  
     597      /**
     598       * Contructor
     599       *
     600       * @param string $desc
     601       * @param bool $required
     602       * @param mixed $default
     603       * @since Moodle 2.0
     604       */
     605      public function __construct($desc, $required, $default) {
     606          $this->desc = $desc;
     607          $this->required = $required;
     608          $this->default = $default;
     609      }
     610  }
     611  
     612  /**
     613   * Scalar value description class
     614   *
     615   * @package    core_webservice
     616   * @copyright  2009 Petr Skodak
     617   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     618   * @since Moodle 2.0
     619   */
     620  class external_value extends external_description {
     621  
     622      /** @var mixed Value type PARAM_XX */
     623      public $type;
     624  
     625      /** @var bool Allow null values */
     626      public $allownull;
     627  
     628      /**
     629       * Constructor
     630       *
     631       * @param mixed $type
     632       * @param string $desc
     633       * @param bool $required
     634       * @param mixed $default
     635       * @param bool $allownull
     636       * @since Moodle 2.0
     637       */
     638      public function __construct($type, $desc='', $required=VALUE_REQUIRED,
     639              $default=null, $allownull=NULL_ALLOWED) {
     640          parent::__construct($desc, $required, $default);
     641          $this->type      = $type;
     642          $this->allownull = $allownull;
     643      }
     644  }
     645  
     646  /**
     647   * Associative array description class
     648   *
     649   * @package    core_webservice
     650   * @copyright  2009 Petr Skodak
     651   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     652   * @since Moodle 2.0
     653   */
     654  class external_single_structure extends external_description {
     655  
     656       /** @var array Description of array keys key=>external_description */
     657      public $keys;
     658  
     659      /**
     660       * Constructor
     661       *
     662       * @param array $keys
     663       * @param string $desc
     664       * @param bool $required
     665       * @param array $default
     666       * @since Moodle 2.0
     667       */
     668      public function __construct(array $keys, $desc='',
     669              $required=VALUE_REQUIRED, $default=null) {
     670          parent::__construct($desc, $required, $default);
     671          $this->keys = $keys;
     672      }
     673  }
     674  
     675  /**
     676   * Bulk array description class.
     677   *
     678   * @package    core_webservice
     679   * @copyright  2009 Petr Skodak
     680   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     681   * @since Moodle 2.0
     682   */
     683  class external_multiple_structure extends external_description {
     684  
     685       /** @var external_description content */
     686      public $content;
     687  
     688      /**
     689       * Constructor
     690       *
     691       * @param external_description $content
     692       * @param string $desc
     693       * @param bool $required
     694       * @param array $default
     695       * @since Moodle 2.0
     696       */
     697      public function __construct(external_description $content, $desc='',
     698              $required=VALUE_REQUIRED, $default=null) {
     699          parent::__construct($desc, $required, $default);
     700          $this->content = $content;
     701      }
     702  }
     703  
     704  /**
     705   * Description of top level - PHP function parameters.
     706   *
     707   * @package    core_webservice
     708   * @copyright  2009 Petr Skodak
     709   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     710   * @since Moodle 2.0
     711   */
     712  class external_function_parameters extends external_single_structure {
     713  
     714      /**
     715       * Constructor - does extra checking to prevent top level optional parameters.
     716       *
     717       * @param array $keys
     718       * @param string $desc
     719       * @param bool $required
     720       * @param array $default
     721       */
     722      public function __construct(array $keys, $desc='', $required=VALUE_REQUIRED, $default=null) {
     723          global $CFG;
     724  
     725          if ($CFG->debugdeveloper) {
     726              foreach ($keys as $key => $value) {
     727                  if ($value instanceof external_value) {
     728                      if ($value->required == VALUE_OPTIONAL) {
     729                          debugging('External function parameters: invalid OPTIONAL value specified.', DEBUG_DEVELOPER);
     730                          break;
     731                      }
     732                  }
     733              }
     734          }
     735          parent::__construct($keys, $desc, $required, $default);
     736      }
     737  }
     738  
     739  /**
     740   * Generate a token
     741   *
     742   * @param string $tokentype EXTERNAL_TOKEN_EMBEDDED|EXTERNAL_TOKEN_PERMANENT
     743   * @param stdClass|int $serviceorid service linked to the token
     744   * @param int $userid user linked to the token
     745   * @param stdClass|int $contextorid
     746   * @param int $validuntil date when the token expired
     747   * @param string $iprestriction allowed ip - if 0 or empty then all ips are allowed
     748   * @return string generated token
     749   * @author  2010 Jamie Pratt
     750   * @since Moodle 2.0
     751   */
     752  function external_generate_token($tokentype, $serviceorid, $userid, $contextorid, $validuntil=0, $iprestriction=''){
     753      global $DB, $USER;
     754      // make sure the token doesn't exist (even if it should be almost impossible with the random generation)
     755      $numtries = 0;
     756      do {
     757          $numtries ++;
     758          $generatedtoken = md5(uniqid(rand(),1));
     759          if ($numtries > 5){
     760              throw new moodle_exception('tokengenerationfailed');
     761          }
     762      } while ($DB->record_exists('external_tokens', array('token'=>$generatedtoken)));
     763      $newtoken = new stdClass();
     764      $newtoken->token = $generatedtoken;
     765      if (!is_object($serviceorid)){
     766          $service = $DB->get_record('external_services', array('id' => $serviceorid));
     767      } else {
     768          $service = $serviceorid;
     769      }
     770      if (!is_object($contextorid)){
     771          $context = context::instance_by_id($contextorid, MUST_EXIST);
     772      } else {
     773          $context = $contextorid;
     774      }
     775      if (empty($service->requiredcapability) || has_capability($service->requiredcapability, $context, $userid)) {
     776          $newtoken->externalserviceid = $service->id;
     777      } else {
     778          throw new moodle_exception('nocapabilitytousethisservice');
     779      }
     780      $newtoken->tokentype = $tokentype;
     781      $newtoken->userid = $userid;
     782      if ($tokentype == EXTERNAL_TOKEN_EMBEDDED){
     783          $newtoken->sid = session_id();
     784      }
     785  
     786      $newtoken->contextid = $context->id;
     787      $newtoken->creatorid = $USER->id;
     788      $newtoken->timecreated = time();
     789      $newtoken->validuntil = $validuntil;
     790      if (!empty($iprestriction)) {
     791          $newtoken->iprestriction = $iprestriction;
     792      }
     793      // Generate the private token, it must be transmitted only via https.
     794      $newtoken->privatetoken = random_string(64);
     795      $DB->insert_record('external_tokens', $newtoken);
     796      return $newtoken->token;
     797  }
     798  
     799  /**
     800   * Create and return a session linked token. Token to be used for html embedded client apps that want to communicate
     801   * with the Moodle server through web services. The token is linked to the current session for the current page request.
     802   * It is expected this will be called in the script generating the html page that is embedding the client app and that the
     803   * returned token will be somehow passed into the client app being embedded in the page.
     804   *
     805   * @param string $servicename name of the web service. Service name as defined in db/services.php
     806   * @param int $context context within which the web service can operate.
     807   * @return int returns token id.
     808   * @since Moodle 2.0
     809   */
     810  function external_create_service_token($servicename, $context){
     811      global $USER, $DB;
     812      $service = $DB->get_record('external_services', array('name'=>$servicename), '*', MUST_EXIST);
     813      return external_generate_token(EXTERNAL_TOKEN_EMBEDDED, $service, $USER->id, $context, 0);
     814  }
     815  
     816  /**
     817   * Delete all pre-built services (+ related tokens) and external functions information defined in the specified component.
     818   *
     819   * @param string $component name of component (moodle, mod_assignment, etc.)
     820   */
     821  function external_delete_descriptions($component) {
     822      global $DB;
     823  
     824      $params = array($component);
     825  
     826      $DB->delete_records_select('external_tokens',
     827              "externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?)", $params);
     828      $DB->delete_records_select('external_services_users',
     829              "externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?)", $params);
     830      $DB->delete_records_select('external_services_functions',
     831              "functionname IN (SELECT name FROM {external_functions} WHERE component = ?)", $params);
     832      $DB->delete_records('external_services', array('component'=>$component));
     833      $DB->delete_records('external_functions', array('component'=>$component));
     834  }
     835  
     836  /**
     837   * Standard Moodle web service warnings
     838   *
     839   * @package    core_webservice
     840   * @copyright  2012 Jerome Mouneyrac
     841   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     842   * @since Moodle 2.3
     843   */
     844  class external_warnings extends external_multiple_structure {
     845  
     846      /**
     847       * Constructor
     848       *
     849       * @since Moodle 2.3
     850       */
     851      public function __construct($itemdesc = 'item', $itemiddesc = 'item id',
     852          $warningcodedesc = 'the warning code can be used by the client app to implement specific behaviour') {
     853  
     854          parent::__construct(
     855              new external_single_structure(
     856                  array(
     857                      'item' => new external_value(PARAM_TEXT, $itemdesc, VALUE_OPTIONAL),
     858                      'itemid' => new external_value(PARAM_INT, $itemiddesc, VALUE_OPTIONAL),
     859                      'warningcode' => new external_value(PARAM_ALPHANUM, $warningcodedesc),
     860                      'message' => new external_value(PARAM_TEXT,
     861                              'untranslated english message to explain the warning')
     862                  ), 'warning'),
     863              'list of warnings', VALUE_OPTIONAL);
     864      }
     865  }
     866  
     867  /**
     868   * A pre-filled external_value class for text format.
     869   *
     870   * Default is FORMAT_HTML
     871   * This should be used all the time in external xxx_params()/xxx_returns functions
     872   * as it is the standard way to implement text format param/return values.
     873   *
     874   * @package    core_webservice
     875   * @copyright  2012 Jerome Mouneyrac
     876   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
     877   * @since Moodle 2.3
     878   */
     879  class external_format_value extends external_value {
     880  
     881      /**
     882       * Constructor
     883       *
     884       * @param string $textfieldname Name of the text field
     885       * @param int $required if VALUE_REQUIRED then set standard default FORMAT_HTML
     886       * @param int $default Default value.
     887       * @since Moodle 2.3
     888       */
     889      public function __construct($textfieldname, $required = VALUE_REQUIRED, $default = null) {
     890  
     891          if ($default == null && $required == VALUE_DEFAULT) {
     892              $default = FORMAT_HTML;
     893          }
     894  
     895          $desc = $textfieldname . ' format (' . FORMAT_HTML . ' = HTML, '
     896                  . FORMAT_MOODLE . ' = MOODLE, '
     897                  . FORMAT_PLAIN . ' = PLAIN or '
     898                  . FORMAT_MARKDOWN . ' = MARKDOWN)';
     899  
     900          parent::__construct(PARAM_INT, $desc, $required, $default);
     901      }
     902  }
     903  
     904  /**
     905   * Validate text field format against known FORMAT_XXX
     906   *
     907   * @param array $format the format to validate
     908   * @return the validated format
     909   * @throws coding_exception
     910   * @since Moodle 2.3
     911   */
     912  function external_validate_format($format) {
     913      $allowedformats = array(FORMAT_HTML, FORMAT_MOODLE, FORMAT_PLAIN, FORMAT_MARKDOWN);
     914      if (!in_array($format, $allowedformats)) {
     915          throw new moodle_exception('formatnotsupported', 'webservice', '' , null,
     916                  'The format with value=' . $format . ' is not supported by this Moodle site');
     917      }
     918      return $format;
     919  }
     920  
     921  /**
     922   * Format the string to be returned properly as requested by the either the web service server,
     923   * either by an internally call.
     924   * The caller can change the format (raw) with the external_settings singleton
     925   * All web service servers must set this singleton when parsing the $_GET and $_POST.
     926   *
     927   * <pre>
     928   * Options are the same that in {@link format_string()} with some changes:
     929   *      filter      : Can be set to false to force filters off, else observes {@link external_settings}.
     930   * </pre>
     931   *
     932   * @param string $str The string to be filtered. Should be plain text, expect
     933   * possibly for multilang tags.
     934   * @param boolean $striplinks To strip any link in the result text. Moodle 1.8 default changed from false to true! MDL-8713
     935   * @param context|int $contextorid The id of the context for the string or the context (affects filters).
     936   * @param array $options options array/object or courseid
     937   * @return string text
     938   * @since Moodle 3.0
     939   */
     940  function external_format_string($str, $contextorid, $striplinks = true, $options = array()) {
     941  
     942      // Get settings (singleton).
     943      $settings = external_settings::get_instance();
     944      if (empty($contextorid)) {
     945          throw new coding_exception('contextid is required');
     946      }
     947  
     948      if (!$settings->get_raw()) {
     949          if (is_object($contextorid) && is_a($contextorid, 'context')) {
     950              $context = $contextorid;
     951          } else {
     952              $context = context::instance_by_id($contextorid);
     953          }
     954          $options['context'] = $context;
     955          $options['filter'] = isset($options['filter']) && !$options['filter'] ? false : $settings->get_filter();
     956          $str = format_string($str, $striplinks, $options);
     957      }
     958  
     959      return $str;
     960  }
     961  
     962  /**
     963   * Format the text to be returned properly as requested by the either the web service server,
     964   * either by an internally call.
     965   * The caller can change the format (raw, filter, file, fileurl) with the external_settings singleton
     966   * All web service servers must set this singleton when parsing the $_GET and $_POST.
     967   *
     968   * <pre>
     969   * Options are the same that in {@link format_text()} with some changes in defaults to provide backwards compatibility:
     970   *      trusted     :   If true the string won't be cleaned. Default false.
     971   *      noclean     :   If true the string won't be cleaned only if trusted is also true. Default false.
     972   *      nocache     :   If true the string will not be cached and will be formatted every call. Default false.
     973   *      filter      :   Can be set to false to force filters off, else observes {@link external_settings}.
     974   *      para        :   If true then the returned string will be wrapped in div tags. Default (different from format_text) false.
     975   *                      Default changed because div tags are not commonly needed.
     976   *      newlines    :   If true then lines newline breaks will be converted to HTML newline breaks. Default true.
     977   *      context     :   Not used! Using contextid parameter instead.
     978   *      overflowdiv :   If set to true the formatted text will be encased in a div with the class no-overflow before being
     979   *                      returned. Default false.
     980   *      allowid     :   If true then id attributes will not be removed, even when using htmlpurifier. Default (different from
     981   *                      format_text) true. Default changed id attributes are commonly needed.
     982   *      blanktarget :   If true all <a> tags will have target="_blank" added unless target is explicitly specified.
     983   * </pre>
     984   *
     985   * @param string $text The content that may contain ULRs in need of rewriting.
     986   * @param int $textformat The text format.
     987   * @param context|int $contextorid This parameter and the next two identify the file area to use.
     988   * @param string $component
     989   * @param string $filearea helps identify the file area.
     990   * @param int $itemid helps identify the file area.
     991   * @param object/array $options text formatting options
     992   * @return array text + textformat
     993   * @since Moodle 2.3
     994   * @since Moodle 3.2 component, filearea and itemid are optional parameters
     995   */
     996  function external_format_text($text, $textformat, $contextorid, $component = null, $filearea = null, $itemid = null,
     997                                  $options = null) {
     998      global $CFG;
     999  
    1000      // Get settings (singleton).
    1001      $settings = external_settings::get_instance();
    1002  
    1003      if (is_object($contextorid) && is_a($contextorid, 'context')) {
    1004          $context = $contextorid;
    1005          $contextid = $context->id;
    1006      } else {
    1007          $context = null;
    1008          $contextid = $contextorid;
    1009      }
    1010  
    1011      if ($component and $filearea and $settings->get_fileurl()) {
    1012          require_once($CFG->libdir . "/filelib.php");
    1013          $text = file_rewrite_pluginfile_urls($text, $settings->get_file(), $contextid, $component, $filearea, $itemid);
    1014      }
    1015  
    1016      // Note that $CFG->forceclean does not apply here if the client requests for the raw database content.
    1017      // This is consistent with web clients that are still able to load non-cleaned text into editors, too.
    1018  
    1019      if (!$settings->get_raw()) {
    1020          $options = (array)$options;
    1021  
    1022          // If context is passed in options, check that is the same to show a debug message.
    1023          if (isset($options['context'])) {
    1024              if ((is_object($options['context']) && $options['context']->id != $contextid)
    1025                      || (!is_object($options['context']) && $options['context'] != $contextid)) {
    1026                  debugging('Different contexts found in external_format_text parameters. $options[\'context\'] not allowed.
    1027                      Using $contextid parameter...', DEBUG_DEVELOPER);
    1028              }
    1029          }
    1030  
    1031          $options['filter'] = isset($options['filter']) && !$options['filter'] ? false : $settings->get_filter();
    1032          $options['para'] = isset($options['para']) ? $options['para'] : false;
    1033          $options['context'] = !is_null($context) ? $context : context::instance_by_id($contextid);
    1034          $options['allowid'] = isset($options['allowid']) ? $options['allowid'] : true;
    1035  
    1036          $text = format_text($text, $textformat, $options);
    1037          $textformat = FORMAT_HTML; // Once converted to html (from markdown, plain... lets inform consumer this is already HTML).
    1038      }
    1039  
    1040      return array($text, $textformat);
    1041  }
    1042  
    1043  /**
    1044   * Generate or return an existing token for the current authenticated user.
    1045   * This function is used for creating a valid token for users authenticathing via login/token.php or admin/tool/mobile/launch.php.
    1046   *
    1047   * @param stdClass $service external service object
    1048   * @return stdClass token object
    1049   * @since Moodle 3.2
    1050   * @throws moodle_exception
    1051   */
    1052  function external_generate_token_for_current_user($service) {
    1053      global $DB, $USER, $CFG;
    1054  
    1055      core_user::require_active_user($USER, true, true);
    1056  
    1057      // Check if there is any required system capability.
    1058      if ($service->requiredcapability and !has_capability($service->requiredcapability, context_system::instance())) {
    1059          throw new moodle_exception('missingrequiredcapability', 'webservice', '', $service->requiredcapability);
    1060      }
    1061  
    1062      // Specific checks related to user restricted service.
    1063      if ($service->restrictedusers) {
    1064          $authoriseduser = $DB->get_record('external_services_users',
    1065              array('externalserviceid' => $service->id, 'userid' => $USER->id));
    1066  
    1067          if (empty($authoriseduser)) {
    1068              throw new moodle_exception('usernotallowed', 'webservice', '', $service->shortname);
    1069          }
    1070  
    1071          if (!empty($authoriseduser->validuntil) and $authoriseduser->validuntil < time()) {
    1072              throw new moodle_exception('invalidtimedtoken', 'webservice');
    1073          }
    1074  
    1075          if (!empty($authoriseduser->iprestriction) and !address_in_subnet(getremoteaddr(), $authoriseduser->iprestriction)) {
    1076              throw new moodle_exception('invalidiptoken', 'webservice');
    1077          }
    1078      }
    1079  
    1080      // Check if a token has already been created for this user and this service.
    1081      $conditions = array(
    1082          'userid' => $USER->id,
    1083          'externalserviceid' => $service->id,
    1084          'tokentype' => EXTERNAL_TOKEN_PERMANENT
    1085      );
    1086      $tokens = $DB->get_records('external_tokens', $conditions, 'timecreated ASC');
    1087  
    1088      // A bit of sanity checks.
    1089      foreach ($tokens as $key => $token) {
    1090  
    1091          // Checks related to a specific token. (script execution continue).
    1092          $unsettoken = false;
    1093          // If sid is set then there must be a valid associated session no matter the token type.
    1094          if (!empty($token->sid)) {
    1095              if (!\core\session\manager::session_exists($token->sid)) {
    1096                  // This token will never be valid anymore, delete it.
    1097                  $DB->delete_records('external_tokens', array('sid' => $token->sid));
    1098                  $unsettoken = true;
    1099              }
    1100          }
    1101  
    1102          // Remove token is not valid anymore.
    1103          if (!empty($token->validuntil) and $token->validuntil < time()) {
    1104              $DB->delete_records('external_tokens', array('token' => $token->token, 'tokentype' => EXTERNAL_TOKEN_PERMANENT));
    1105              $unsettoken = true;
    1106          }
    1107  
    1108          // Remove token if its IP is restricted.
    1109          if (isset($token->iprestriction) and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
    1110              $unsettoken = true;
    1111          }
    1112  
    1113          if ($unsettoken) {
    1114              unset($tokens[$key]);
    1115          }
    1116      }
    1117  
    1118      // If some valid tokens exist then use the most recent.
    1119      if (count($tokens) > 0) {
    1120          $token = array_pop($tokens);
    1121      } else {
    1122          $context = context_system::instance();
    1123          $isofficialservice = $service->shortname == MOODLE_OFFICIAL_MOBILE_SERVICE;
    1124  
    1125          if (($isofficialservice and has_capability('moodle/webservice:createmobiletoken', $context)) or
    1126                  (!is_siteadmin($USER) && has_capability('moodle/webservice:createtoken', $context))) {
    1127  
    1128              // Create a new token.
    1129              $token = new stdClass;
    1130              $token->token = md5(uniqid(rand(), 1));
    1131              $token->userid = $USER->id;
    1132              $token->tokentype = EXTERNAL_TOKEN_PERMANENT;
    1133              $token->contextid = context_system::instance()->id;
    1134              $token->creatorid = $USER->id;
    1135              $token->timecreated = time();
    1136              $token->externalserviceid = $service->id;
    1137              // By default tokens are valid for 12 weeks.
    1138              $token->validuntil = $token->timecreated + $CFG->tokenduration;
    1139              $token->iprestriction = null;
    1140              $token->sid = null;
    1141              $token->lastaccess = null;
    1142              // Generate the private token, it must be transmitted only via https.
    1143              $token->privatetoken = random_string(64);
    1144              $token->id = $DB->insert_record('external_tokens', $token);
    1145  
    1146              $eventtoken = clone $token;
    1147              $eventtoken->privatetoken = null;
    1148              $params = array(
    1149                  'objectid' => $eventtoken->id,
    1150                  'relateduserid' => $USER->id,
    1151                  'other' => array(
    1152                      'auto' => true
    1153                  )
    1154              );
    1155              $event = \core\event\webservice_token_created::create($params);
    1156              $event->add_record_snapshot('external_tokens', $eventtoken);
    1157              $event->trigger();
    1158          } else {
    1159              throw new moodle_exception('cannotcreatetoken', 'webservice', '', $service->shortname);
    1160          }
    1161      }
    1162      return $token;
    1163  }
    1164  
    1165  /**
    1166   * Set the last time a token was sent and trigger the \core\event\webservice_token_sent event.
    1167   *
    1168   * This function is used when a token is generated by the user via login/token.php or admin/tool/mobile/launch.php.
    1169   * In order to protect the privatetoken, we remove it from the event params.
    1170   *
    1171   * @param  stdClass $token token object
    1172   * @since  Moodle 3.2
    1173   */
    1174  function external_log_token_request($token) {
    1175      global $DB;
    1176  
    1177      $token->privatetoken = null;
    1178  
    1179      // Log token access.
    1180      $DB->set_field('external_tokens', 'lastaccess', time(), array('id' => $token->id));
    1181  
    1182      $params = array(
    1183          'objectid' => $token->id,
    1184      );
    1185      $event = \core\event\webservice_token_sent::create($params);
    1186      $event->add_record_snapshot('external_tokens', $token);
    1187      $event->trigger();
    1188  }
    1189  
    1190  /**
    1191   * Singleton to handle the external settings.
    1192   *
    1193   * We use singleton to encapsulate the "logic"
    1194   *
    1195   * @package    core_webservice
    1196   * @copyright  2012 Jerome Mouneyrac
    1197   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
    1198   * @since Moodle 2.3
    1199   */
    1200  class external_settings {
    1201  
    1202      /** @var object the singleton instance */
    1203      public static $instance = null;
    1204  
    1205      /** @var boolean Should the external function return raw text or formatted */
    1206      private $raw = false;
    1207  
    1208      /** @var boolean Should the external function filter the text */
    1209      private $filter = false;
    1210  
    1211      /** @var boolean Should the external function rewrite plugin file url */
    1212      private $fileurl = true;
    1213  
    1214      /** @var string In which file should the urls be rewritten */
    1215      private $file = 'webservice/pluginfile.php';
    1216  
    1217      /** @var string The session lang */
    1218      private $lang = '';
    1219  
    1220      /** @var string The timezone to use during this WS request */
    1221      private $timezone = '';
    1222  
    1223      /**
    1224       * Constructor - protected - can not be instanciated
    1225       */
    1226      protected function __construct() {
    1227          if ((AJAX_SCRIPT == false) && (CLI_SCRIPT == false) && (WS_SERVER == false)) {
    1228              // For normal pages, the default should match the default for format_text.
    1229              $this->filter = true;
    1230              // Use pluginfile.php for web requests.
    1231              $this->file = 'pluginfile.php';
    1232          }
    1233      }
    1234  
    1235      /**
    1236       * Return only one instance
    1237       *
    1238       * @return \external_settings
    1239       */
    1240      public static function get_instance() {
    1241          if (self::$instance === null) {
    1242              self::$instance = new external_settings;
    1243          }
    1244  
    1245          return self::$instance;
    1246      }
    1247  
    1248      /**
    1249       * Set raw
    1250       *
    1251       * @param boolean $raw
    1252       */
    1253      public function set_raw($raw) {
    1254          $this->raw = $raw;
    1255      }
    1256  
    1257      /**
    1258       * Get raw
    1259       *
    1260       * @return boolean
    1261       */
    1262      public function get_raw() {
    1263          return $this->raw;
    1264      }
    1265  
    1266      /**
    1267       * Set filter
    1268       *
    1269       * @param boolean $filter
    1270       */
    1271      public function set_filter($filter) {
    1272          $this->filter = $filter;
    1273      }
    1274  
    1275      /**
    1276       * Get filter
    1277       *
    1278       * @return boolean
    1279       */
    1280      public function get_filter() {
    1281          return $this->filter;
    1282      }
    1283  
    1284      /**
    1285       * Set fileurl
    1286       *
    1287       * @param boolean $fileurl
    1288       */
    1289      public function set_fileurl($fileurl) {
    1290          $this->fileurl = $fileurl;
    1291      }
    1292  
    1293      /**
    1294       * Get fileurl
    1295       *
    1296       * @return boolean
    1297       */
    1298      public function get_fileurl() {
    1299          return $this->fileurl;
    1300      }
    1301  
    1302      /**
    1303       * Set file
    1304       *
    1305       * @param string $file
    1306       */
    1307      public function set_file($file) {
    1308          $this->file = $file;
    1309      }
    1310  
    1311      /**
    1312       * Get file
    1313       *
    1314       * @return string
    1315       */
    1316      public function get_file() {
    1317          return $this->file;
    1318      }
    1319  
    1320      /**
    1321       * Set lang
    1322       *
    1323       * @param string $lang
    1324       */
    1325      public function set_lang($lang) {
    1326          $this->lang = $lang;
    1327      }
    1328  
    1329      /**
    1330       * Get lang
    1331       *
    1332       * @return string
    1333       */
    1334      public function get_lang() {
    1335          return $this->lang;
    1336      }
    1337  
    1338      /**
    1339       * Set timezone
    1340       *
    1341       * @param string $timezone
    1342       */
    1343      public function set_timezone($timezone) {
    1344          $this->timezone = $timezone;
    1345      }
    1346  
    1347      /**
    1348       * Get timezone
    1349       *
    1350       * @return string
    1351       */
    1352      public function get_timezone() {
    1353          return $this->timezone;
    1354      }
    1355  }
    1356  
    1357  /**
    1358   * Utility functions for the external API.
    1359   *
    1360   * @package    core_webservice
    1361   * @copyright  2015 Juan Leyva
    1362   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
    1363   * @since Moodle 3.0
    1364   */
    1365  class external_util {
    1366  
    1367      /**
    1368       * Validate a list of courses, returning the complete course objects for valid courses.
    1369       *
    1370       * Each course has an additional 'contextvalidated' field, this will be set to true unless
    1371       * you set $keepfails, in which case it will be false if validation fails for a course.
    1372       *
    1373       * @param  array $courseids A list of course ids
    1374       * @param  array $courses   An array of courses already pre-fetched, indexed by course id.
    1375       * @param  bool $addcontext True if the returned course object should include the full context object.
    1376       * @param  bool $keepfails  True to keep all the course objects even if validation fails
    1377       * @return array            An array of courses and the validation warnings
    1378       */
    1379      public static function validate_courses($courseids, $courses = array(), $addcontext = false,
    1380              $keepfails = false) {
    1381          global $DB;
    1382  
    1383          // Delete duplicates.
    1384          $courseids = array_unique($courseids);
    1385          $warnings = array();
    1386  
    1387          // Remove courses which are not even requested.
    1388          $courses = array_intersect_key($courses, array_flip($courseids));
    1389  
    1390          // For any courses NOT loaded already, get them in a single query (and preload contexts)
    1391          // for performance. Preserve ordering because some tests depend on it.
    1392          $newcourseids = [];
    1393          foreach ($courseids as $cid) {
    1394              if (!array_key_exists($cid, $courses)) {
    1395                  $newcourseids[] = $cid;
    1396              }
    1397          }
    1398          if ($newcourseids) {
    1399              list ($listsql, $listparams) = $DB->get_in_or_equal($newcourseids);
    1400  
    1401              // Load list of courses, and preload associated contexts.
    1402              $contextselect = context_helper::get_preload_record_columns_sql('x');
    1403              $newcourses = $DB->get_records_sql("
    1404                              SELECT c.*, $contextselect
    1405                                FROM {course} c
    1406                                JOIN {context} x ON x.instanceid = c.id
    1407                               WHERE x.contextlevel = ? AND c.id $listsql",
    1408                      array_merge([CONTEXT_COURSE], $listparams));
    1409              foreach ($newcourseids as $cid) {
    1410                  if (array_key_exists($cid, $newcourses)) {
    1411                      $course = $newcourses[$cid];
    1412                      context_helper::preload_from_record($course);
    1413                      $courses[$course->id] = $course;
    1414                  }
    1415              }
    1416          }
    1417  
    1418          foreach ($courseids as $cid) {
    1419              // Check the user can function in this context.
    1420              try {
    1421                  $context = context_course::instance($cid);
    1422                  external_api::validate_context($context);
    1423  
    1424                  if ($addcontext) {
    1425                      $courses[$cid]->context = $context;
    1426                  }
    1427                  $courses[$cid]->contextvalidated = true;
    1428              } catch (Exception $e) {
    1429                  if ($keepfails) {
    1430                      $courses[$cid]->contextvalidated = false;
    1431                  } else {
    1432                      unset($courses[$cid]);
    1433                  }
    1434                  $warnings[] = array(
    1435                      'item' => 'course',
    1436                      'itemid' => $cid,
    1437                      'warningcode' => '1',
    1438                      'message' => 'No access rights in course context'
    1439                  );
    1440              }
    1441          }
    1442  
    1443          return array($courses, $warnings);
    1444      }
    1445  
    1446      /**
    1447       * Returns all area files (optionally limited by itemid).
    1448       *
    1449       * @param int $contextid context ID
    1450       * @param string $component component
    1451       * @param string $filearea file area
    1452       * @param int $itemid item ID or all files if not specified
    1453       * @param bool $useitemidinurl wether to use the item id in the file URL (modules intro don't use it)
    1454       * @return array of files, compatible with the external_files structure.
    1455       * @since Moodle 3.2
    1456       */
    1457      public static function get_area_files($contextid, $component, $filearea, $itemid = false, $useitemidinurl = true) {
    1458          $files = array();
    1459          $fs = get_file_storage();
    1460  
    1461          if ($areafiles = $fs->get_area_files($contextid, $component, $filearea, $itemid, 'itemid, filepath, filename', false)) {
    1462              foreach ($areafiles as $areafile) {
    1463                  $file = array();
    1464                  $file['filename'] = $areafile->get_filename();
    1465                  $file['filepath'] = $areafile->get_filepath();
    1466                  $file['mimetype'] = $areafile->get_mimetype();
    1467                  $file['filesize'] = $areafile->get_filesize();
    1468                  $file['timemodified'] = $areafile->get_timemodified();
    1469                  $file['isexternalfile'] = $areafile->is_external_file();
    1470                  if ($file['isexternalfile']) {
    1471                      $file['repositorytype'] = $areafile->get_repository_type();
    1472                  }
    1473                  $fileitemid = $useitemidinurl ? $areafile->get_itemid() : null;
    1474                  $file['fileurl'] = moodle_url::make_webservice_pluginfile_url($contextid, $component, $filearea,
    1475                                      $fileitemid, $areafile->get_filepath(), $areafile->get_filename())->out(false);
    1476                  $files[] = $file;
    1477              }
    1478          }
    1479          return $files;
    1480      }
    1481  }
    1482  
    1483  /**
    1484   * External structure representing a set of files.
    1485   *
    1486   * @package    core_webservice
    1487   * @copyright  2016 Juan Leyva
    1488   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
    1489   * @since      Moodle 3.2
    1490   */
    1491  class external_files extends external_multiple_structure {
    1492  
    1493      /**
    1494       * Constructor
    1495       * @param string $desc Description for the multiple structure.
    1496       * @param int $required The type of value (VALUE_REQUIRED OR VALUE_OPTIONAL).
    1497       */
    1498      public function __construct($desc = 'List of files.', $required = VALUE_REQUIRED) {
    1499  
    1500          parent::__construct(
    1501              new external_single_structure(
    1502                  array(
    1503                      'filename' => new external_value(PARAM_FILE, 'File name.', VALUE_OPTIONAL),
    1504                      'filepath' => new external_value(PARAM_PATH, 'File path.', VALUE_OPTIONAL),
    1505                      'filesize' => new external_value(PARAM_INT, 'File size.', VALUE_OPTIONAL),
    1506                      'fileurl' => new external_value(PARAM_URL, 'Downloadable file url.', VALUE_OPTIONAL),
    1507                      'timemodified' => new external_value(PARAM_INT, 'Time modified.', VALUE_OPTIONAL),
    1508                      'mimetype' => new external_value(PARAM_RAW, 'File mime type.', VALUE_OPTIONAL),
    1509                      'isexternalfile' => new external_value(PARAM_BOOL, 'Whether is an external file.', VALUE_OPTIONAL),
    1510                      'repositorytype' => new external_value(PARAM_PLUGIN, 'The repository type for external files.', VALUE_OPTIONAL),
    1511                  ),
    1512                  'File.'
    1513              ),
    1514              $desc,
    1515              $required
    1516          );
    1517      }
    1518  
    1519      /**
    1520       * Return the properties ready to be used by an exporter.
    1521       *
    1522       * @return array properties
    1523       * @since  Moodle 3.3
    1524       */
    1525      public static function get_properties_for_exporter() {
    1526          return [
    1527              'filename' => array(
    1528                  'type' => PARAM_FILE,
    1529                  'description' => 'File name.',
    1530                  'optional' => true,
    1531                  'null' => NULL_NOT_ALLOWED,
    1532              ),
    1533              'filepath' => array(
    1534                  'type' => PARAM_PATH,
    1535                  'description' => 'File path.',
    1536                  'optional' => true,
    1537                  'null' => NULL_NOT_ALLOWED,
    1538              ),
    1539              'filesize' => array(
    1540                  'type' => PARAM_INT,
    1541                  'description' => 'File size.',
    1542                  'optional' => true,
    1543                  'null' => NULL_NOT_ALLOWED,
    1544              ),
    1545              'fileurl' => array(
    1546                  'type' => PARAM_URL,
    1547                  'description' => 'Downloadable file url.',
    1548                  'optional' => true,
    1549                  'null' => NULL_NOT_ALLOWED,
    1550              ),
    1551              'timemodified' => array(
    1552                  'type' => PARAM_INT,
    1553                  'description' => 'Time modified.',
    1554                  'optional' => true,
    1555                  'null' => NULL_NOT_ALLOWED,
    1556              ),
    1557              'mimetype' => array(
    1558                  'type' => PARAM_RAW,
    1559                  'description' => 'File mime type.',
    1560                  'optional' => true,
    1561                  'null' => NULL_NOT_ALLOWED,
    1562              ),
    1563              'isexternalfile' => array(
    1564                  'type' => PARAM_BOOL,
    1565                  'description' => 'Whether is an external file.',
    1566                  'optional' => true,
    1567                  'null' => NULL_NOT_ALLOWED,
    1568              ),
    1569              'repositorytype' => array(
    1570                  'type' => PARAM_PLUGIN,
    1571                  'description' => 'The repository type for the external files.',
    1572                  'optional' => true,
    1573                  'null' => NULL_ALLOWED,
    1574              ),
    1575          ];
    1576      }
    1577  }