Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

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

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

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  
  18  /**
  19   * Web services utility functions and classes
  20   *
  21   * @package    core_webservice
  22   * @copyright  2009 Jerome Mouneyrac <jerome@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  require_once($CFG->libdir.'/externallib.php');
  27  
  28  /**
  29   * WEBSERVICE_AUTHMETHOD_USERNAME - username/password authentication (also called simple authentication)
  30   */
  31  define('WEBSERVICE_AUTHMETHOD_USERNAME', 0);
  32  
  33  /**
  34   * WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN - most common token authentication (external app, mobile app...)
  35   */
  36  define('WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN', 1);
  37  
  38  /**
  39   * WEBSERVICE_AUTHMETHOD_SESSION_TOKEN - token for embedded application (requires Moodle session)
  40   */
  41  define('WEBSERVICE_AUTHMETHOD_SESSION_TOKEN', 2);
  42  
  43  /**
  44   * General web service library
  45   *
  46   * @package    core_webservice
  47   * @copyright  2010 Jerome Mouneyrac <jerome@moodle.com>
  48   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  49   */
  50  class webservice {
  51      /**
  52       * Only update token last access once per this many seconds. (This constant controls update of
  53       * the external tokens last access field. There is a similar define LASTACCESS_UPDATE_SECS
  54       * which controls update of the web site last access fields.)
  55       *
  56       * @var int
  57       */
  58      const TOKEN_LASTACCESS_UPDATE_SECS = 60;
  59  
  60      /**
  61       * Authenticate user (used by download/upload file scripts)
  62       *
  63       * @param string $token
  64       * @return array - contains the authenticated user, token and service objects
  65       */
  66      public function authenticate_user($token) {
  67          global $DB, $CFG;
  68  
  69          // web service must be enabled to use this script
  70          if (!$CFG->enablewebservices) {
  71              throw new webservice_access_exception('Web services are not enabled in Advanced features.');
  72          }
  73  
  74          // Obtain token record
  75          if (!$token = $DB->get_record('external_tokens', array('token' => $token))) {
  76              //client may want to display login form => moodle_exception
  77              throw new moodle_exception('invalidtoken', 'webservice');
  78          }
  79  
  80          $loginfaileddefaultparams = array(
  81              'other' => array(
  82                  'method' => WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN,
  83                  'reason' => null,
  84                  'tokenid' => $token->id
  85              )
  86          );
  87  
  88          // Validate token date
  89          if ($token->validuntil and $token->validuntil < time()) {
  90              $params = $loginfaileddefaultparams;
  91              $params['other']['reason'] = 'token_expired';
  92              $event = \core\event\webservice_login_failed::create($params);
  93              $event->add_record_snapshot('external_tokens', $token);
  94              $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '',
  95                  get_string('invalidtimedtoken', 'webservice'), 0));
  96              $event->trigger();
  97              $DB->delete_records('external_tokens', array('token' => $token->token));
  98              throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');
  99          }
 100  
 101          // Check ip
 102          if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
 103              $params = $loginfaileddefaultparams;
 104              $params['other']['reason'] = 'ip_restricted';
 105              $event = \core\event\webservice_login_failed::create($params);
 106              $event->add_record_snapshot('external_tokens', $token);
 107              $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '',
 108                  get_string('failedtolog', 'webservice') . ": " . getremoteaddr(), 0));
 109              $event->trigger();
 110              throw new webservice_access_exception('Invalid token - IP:' . getremoteaddr()
 111                      . ' is not supported');
 112          }
 113  
 114          //retrieve user link to the token
 115          $user = $DB->get_record('user', array('id' => $token->userid, 'deleted' => 0), '*', MUST_EXIST);
 116  
 117          // let enrol plugins deal with new enrolments if necessary
 118          enrol_check_plugins($user, false);
 119  
 120          // setup user session to check capability
 121          \core\session\manager::set_user($user);
 122          set_login_session_preferences();
 123  
 124          //assumes that if sid is set then there must be a valid associated session no matter the token type
 125          if ($token->sid) {
 126              if (!\core\session\manager::session_exists($token->sid)) {
 127                  $DB->delete_records('external_tokens', array('sid' => $token->sid));
 128                  throw new webservice_access_exception('Invalid session based token - session not found or expired');
 129              }
 130          }
 131  
 132          // Cannot authenticate unless maintenance access is granted.
 133          $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system::instance(), $user);
 134          if (!empty($CFG->maintenance_enabled) and !$hasmaintenanceaccess) {
 135              //this is usually temporary, client want to implement code logic  => moodle_exception
 136              throw new moodle_exception('sitemaintenance', 'admin');
 137          }
 138  
 139          //retrieve web service record
 140          $service = $DB->get_record('external_services', array('id' => $token->externalserviceid, 'enabled' => 1));
 141          if (empty($service)) {
 142              // will throw exception if no token found
 143              throw new webservice_access_exception('Web service is not available (it doesn\'t exist or might be disabled)');
 144          }
 145  
 146          //check if there is any required system capability
 147          if ($service->requiredcapability and !has_capability($service->requiredcapability, context_system::instance(), $user)) {
 148              throw new webservice_access_exception('The capability ' . $service->requiredcapability . ' is required.');
 149          }
 150  
 151          //specific checks related to user restricted service
 152          if ($service->restrictedusers) {
 153              $authoriseduser = $DB->get_record('external_services_users', array('externalserviceid' => $service->id, 'userid' => $user->id));
 154  
 155              if (empty($authoriseduser)) {
 156                  throw new webservice_access_exception(
 157                          'The user is not allowed for this service. First you need to allow this user on the '
 158                          . $service->name . '\'s allowed users administration page.');
 159              }
 160  
 161              if (!empty($authoriseduser->validuntil) and $authoriseduser->validuntil < time()) {
 162                  throw new webservice_access_exception('Invalid service - service expired - check validuntil time for this allowed user');
 163              }
 164  
 165              if (!empty($authoriseduser->iprestriction) and !address_in_subnet(getremoteaddr(), $authoriseduser->iprestriction)) {
 166                  throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()
 167                      . ' is not supported - check this allowed user');
 168              }
 169          }
 170  
 171          //only confirmed user should be able to call web service
 172          if (empty($user->confirmed)) {
 173              $params = $loginfaileddefaultparams;
 174              $params['other']['reason'] = 'user_unconfirmed';
 175              $event = \core\event\webservice_login_failed::create($params);
 176              $event->add_record_snapshot('external_tokens', $token);
 177              $event->set_legacy_logdata(array(SITEID, 'webservice', 'user unconfirmed', '', $user->username));
 178              $event->trigger();
 179              throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
 180          }
 181  
 182          //check the user is suspended
 183          if (!empty($user->suspended)) {
 184              $params = $loginfaileddefaultparams;
 185              $params['other']['reason'] = 'user_suspended';
 186              $event = \core\event\webservice_login_failed::create($params);
 187              $event->add_record_snapshot('external_tokens', $token);
 188              $event->set_legacy_logdata(array(SITEID, 'webservice', 'user suspended', '', $user->username));
 189              $event->trigger();
 190              throw new moodle_exception('wsaccessusersuspended', 'moodle', '', $user->username);
 191          }
 192  
 193          //check if the auth method is nologin (in this case refuse connection)
 194          if ($user->auth == 'nologin') {
 195              $params = $loginfaileddefaultparams;
 196              $params['other']['reason'] = 'nologin';
 197              $event = \core\event\webservice_login_failed::create($params);
 198              $event->add_record_snapshot('external_tokens', $token);
 199              $event->set_legacy_logdata(array(SITEID, 'webservice', 'nologin auth attempt with web service', '', $user->username));
 200              $event->trigger();
 201              throw new moodle_exception('wsaccessusernologin', 'moodle', '', $user->username);
 202          }
 203  
 204          //Check if the user password is expired
 205          $auth = get_auth_plugin($user->auth);
 206          if (!empty($auth->config->expiration) and $auth->config->expiration == 1) {
 207              $days2expire = $auth->password_expire($user->username);
 208              if (intval($days2expire) < 0) {
 209                  $params = $loginfaileddefaultparams;
 210                  $params['other']['reason'] = 'password_expired';
 211                  $event = \core\event\webservice_login_failed::create($params);
 212                  $event->add_record_snapshot('external_tokens', $token);
 213                  $event->set_legacy_logdata(array(SITEID, 'webservice', 'expired password', '', $user->username));
 214                  $event->trigger();
 215                  throw new moodle_exception('passwordisexpired', 'webservice');
 216              }
 217          }
 218  
 219          // log token access
 220          self::update_token_lastaccess($token);
 221  
 222          return array('user' => $user, 'token' => $token, 'service' => $service);
 223      }
 224  
 225      /**
 226       * Updates the last access time for a token.
 227       *
 228       * @param \stdClass $token Token object (must include id, lastaccess fields)
 229       * @param int $time Time of access (0 = use current time)
 230       * @throws dml_exception If database error
 231       */
 232      public static function update_token_lastaccess($token, int $time = 0) {
 233          global $DB;
 234  
 235          if (!$time) {
 236              $time = time();
 237          }
 238  
 239          // Only update the field if it is a different time from previous request,
 240          // so as not to waste database effort.
 241          if ($time >= $token->lastaccess + self::TOKEN_LASTACCESS_UPDATE_SECS) {
 242              $DB->set_field('external_tokens', 'lastaccess', $time, array('id' => $token->id));
 243          }
 244      }
 245  
 246      /**
 247       * Allow user to call a service
 248       *
 249       * @param stdClass $user a user
 250       */
 251      public function add_ws_authorised_user($user) {
 252          global $DB;
 253          $user->timecreated = time();
 254          $DB->insert_record('external_services_users', $user);
 255      }
 256  
 257      /**
 258       * Disallow a user to call a service
 259       *
 260       * @param stdClass $user a user
 261       * @param int $serviceid
 262       */
 263      public function remove_ws_authorised_user($user, $serviceid) {
 264          global $DB;
 265          $DB->delete_records('external_services_users',
 266                  array('externalserviceid' => $serviceid, 'userid' => $user->id));
 267      }
 268  
 269      /**
 270       * Update allowed user settings (ip restriction, valid until...)
 271       *
 272       * @param stdClass $user
 273       */
 274      public function update_ws_authorised_user($user) {
 275          global $DB;
 276          $DB->update_record('external_services_users', $user);
 277      }
 278  
 279      /**
 280       * Return list of allowed users with their options (ip/timecreated / validuntil...)
 281       * for a given service
 282       *
 283       * @param int $serviceid the service id to search against
 284       * @return array $users
 285       */
 286      public function get_ws_authorised_users($serviceid) {
 287          global $DB, $CFG;
 288  
 289          $params = array($CFG->siteguest, $serviceid);
 290  
 291          $userfields = \core_user\fields::for_identity(context_system::instance())->with_name()->excluding('id');
 292          $fieldsql = $userfields->get_sql('u');
 293  
 294          $sql = " SELECT u.id as id, esu.id as serviceuserid {$fieldsql->selects},
 295                          esu.iprestriction as iprestriction, esu.validuntil as validuntil,
 296                          esu.timecreated as timecreated
 297                     FROM {user} u
 298                     JOIN {external_services_users} esu ON esu.userid = u.id
 299                          {$fieldsql->joins}
 300                    WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
 301                          AND esu.externalserviceid = ?";
 302  
 303          $users = $DB->get_records_sql($sql, array_merge($fieldsql->params, $params));
 304  
 305          return $users;
 306      }
 307  
 308      /**
 309       * Return an authorised user with their options (ip/timecreated / validuntil...)
 310       *
 311       * @param int $serviceid the service id to search against
 312       * @param int $userid the user to search against
 313       * @return stdClass
 314       */
 315      public function get_ws_authorised_user($serviceid, $userid) {
 316          global $DB, $CFG;
 317          $params = array($CFG->siteguest, $serviceid, $userid);
 318          $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,
 319                          u.lastname as lastname,
 320                          esu.iprestriction as iprestriction, esu.validuntil as validuntil,
 321                          esu.timecreated as timecreated
 322                     FROM {user} u, {external_services_users} esu
 323                    WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
 324                          AND esu.userid = u.id
 325                          AND esu.externalserviceid = ?
 326                          AND u.id = ?";
 327          $user = $DB->get_record_sql($sql, $params);
 328          return $user;
 329      }
 330  
 331      /**
 332       * Generate all tokens of a specific user
 333       *
 334       * @param int $userid user id
 335       */
 336      public function generate_user_ws_tokens($userid) {
 337          global $CFG, $DB;
 338  
 339          // generate a token for non admin if web service are enable and the user has the capability to create a token
 340          if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', context_system::instance(), $userid) && !empty($CFG->enablewebservices)) {
 341              // for every service than the user is authorised on, create a token (if it doesn't already exist)
 342  
 343              // get all services which are set to all user (no restricted to specific users)
 344              $norestrictedservices = $DB->get_records('external_services', array('restrictedusers' => 0));
 345              $serviceidlist = array();
 346              foreach ($norestrictedservices as $service) {
 347                  $serviceidlist[] = $service->id;
 348              }
 349  
 350              // get all services which are set to the current user (the current user is specified in the restricted user list)
 351              $servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));
 352              foreach ($servicesusers as $serviceuser) {
 353                  if (!in_array($serviceuser->externalserviceid,$serviceidlist)) {
 354                       $serviceidlist[] = $serviceuser->externalserviceid;
 355                  }
 356              }
 357  
 358              // get all services which already have a token set for the current user
 359              $usertokens = $DB->get_records('external_tokens', array('userid' => $userid, 'tokentype' => EXTERNAL_TOKEN_PERMANENT));
 360              $tokenizedservice = array();
 361              foreach ($usertokens as $token) {
 362                      $tokenizedservice[]  = $token->externalserviceid;
 363              }
 364  
 365              // create a token for the service which have no token already
 366              foreach ($serviceidlist as $serviceid) {
 367                  if (!in_array($serviceid, $tokenizedservice)) {
 368                      // create the token for this service
 369                      $newtoken = new stdClass();
 370                      $newtoken->token = md5(uniqid(rand(),1));
 371                      // check that the user has capability on this service
 372                      $newtoken->tokentype = EXTERNAL_TOKEN_PERMANENT;
 373                      $newtoken->userid = $userid;
 374                      $newtoken->externalserviceid = $serviceid;
 375                      // TODO MDL-31190 find a way to get the context - UPDATE FOLLOWING LINE
 376                      $newtoken->contextid = context_system::instance()->id;
 377                      $newtoken->creatorid = $userid;
 378                      $newtoken->timecreated = time();
 379                      // Generate the private token, it must be transmitted only via https.
 380                      $newtoken->privatetoken = random_string(64);
 381  
 382                      $DB->insert_record('external_tokens', $newtoken);
 383                  }
 384              }
 385  
 386  
 387          }
 388      }
 389  
 390      /**
 391       * Return all tokens of a specific user
 392       * + the service state (enabled/disabled)
 393       * + the authorised user mode (restricted/not restricted)
 394       *
 395       * @param int $userid user id
 396       * @return array
 397       */
 398      public function get_user_ws_tokens($userid) {
 399          global $DB;
 400          //here retrieve token list (including linked users firstname/lastname and linked services name)
 401          $sql = "SELECT
 402                      t.id, t.creatorid, t.token, u.firstname, u.lastname, s.id as wsid, s.name, s.enabled, s.restrictedusers, t.validuntil
 403                  FROM
 404                      {external_tokens} t, {user} u, {external_services} s
 405                  WHERE
 406                      t.userid=? AND t.tokentype = ".EXTERNAL_TOKEN_PERMANENT." AND s.id = t.externalserviceid AND t.userid = u.id";
 407          $tokens = $DB->get_records_sql($sql, array( $userid));
 408          return $tokens;
 409      }
 410  
 411      /**
 412       * Return a token that has been created by the user (i.e. to created by an admin)
 413       * If no tokens exist an exception is thrown
 414       *
 415       * The returned value is a stdClass:
 416       * ->id token id
 417       * ->token
 418       * ->firstname user firstname
 419       * ->lastname
 420       * ->name service name
 421       *
 422       * @param int $userid user id
 423       * @param int $tokenid token id
 424       * @return stdClass
 425       */
 426      public function get_created_by_user_ws_token($userid, $tokenid) {
 427          global $DB;
 428          $sql = "SELECT
 429                          t.id, t.token, u.firstname, u.lastname, s.name
 430                      FROM
 431                          {external_tokens} t, {user} u, {external_services} s
 432                      WHERE
 433                          t.creatorid=? AND t.id=? AND t.tokentype = "
 434                  . EXTERNAL_TOKEN_PERMANENT
 435                  . " AND s.id = t.externalserviceid AND t.userid = u.id";
 436          //must be the token creator
 437          $token = $DB->get_record_sql($sql, array($userid, $tokenid), MUST_EXIST);
 438          return $token;
 439      }
 440  
 441      /**
 442       * Return a token of an arbitrary user by tokenid, including details of the associated user and the service name.
 443       * If no tokens exist an exception is thrown
 444       *
 445       * The returned value is a stdClass:
 446       * ->id token id
 447       * ->token
 448       * ->firstname user firstname
 449       * ->lastname
 450       * ->name service name
 451       *
 452       * @param int $tokenid token id
 453       * @return stdClass
 454       */
 455      public function get_token_by_id_with_details($tokenid) {
 456          global $DB;
 457          $sql = "SELECT t.id, t.token, u.id AS userid, u.firstname, u.lastname, s.name, t.creatorid
 458                  FROM {external_tokens} t, {user} u, {external_services} s
 459                  WHERE t.id=? AND t.tokentype = ? AND s.id = t.externalserviceid AND t.userid = u.id";
 460          $token = $DB->get_record_sql($sql, array($tokenid, EXTERNAL_TOKEN_PERMANENT), MUST_EXIST);
 461          return $token;
 462      }
 463  
 464      /**
 465       * Return a database token record for a token id
 466       *
 467       * @param int $tokenid token id
 468       * @return object token
 469       */
 470      public function get_token_by_id($tokenid) {
 471          global $DB;
 472          return $DB->get_record('external_tokens', array('id' => $tokenid));
 473      }
 474  
 475      /**
 476       * Delete a token
 477       *
 478       * @param int $tokenid token id
 479       */
 480      public function delete_user_ws_token($tokenid) {
 481          global $DB;
 482          $DB->delete_records('external_tokens', array('id'=>$tokenid));
 483      }
 484  
 485      /**
 486       * Delete all the tokens belonging to a user.
 487       *
 488       * @param int $userid the user id whose tokens must be deleted
 489       */
 490      public static function delete_user_ws_tokens($userid) {
 491          global $DB;
 492          $DB->delete_records('external_tokens', array('userid' => $userid));
 493      }
 494  
 495      /**
 496       * Delete a service
 497       * Also delete function references and authorised user references.
 498       *
 499       * @param int $serviceid service id
 500       */
 501      public function delete_service($serviceid) {
 502          global $DB;
 503          $DB->delete_records('external_services_users', array('externalserviceid' => $serviceid));
 504          $DB->delete_records('external_services_functions', array('externalserviceid' => $serviceid));
 505          $DB->delete_records('external_tokens', array('externalserviceid' => $serviceid));
 506          $DB->delete_records('external_services', array('id' => $serviceid));
 507      }
 508  
 509      /**
 510       * Get a full database token record for a given token value
 511       *
 512       * @param string $token
 513       * @throws moodle_exception if there is multiple result
 514       */
 515      public function get_user_ws_token($token) {
 516          global $DB;
 517          return $DB->get_record('external_tokens', array('token'=>$token), '*', MUST_EXIST);
 518      }
 519  
 520      /**
 521       * Get the functions list of a service list (by id)
 522       *
 523       * @param array $serviceids service ids
 524       * @return array of functions
 525       */
 526      public function get_external_functions($serviceids) {
 527          global $DB;
 528          if (!empty($serviceids)) {
 529              list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
 530              $sql = "SELECT f.*
 531                        FROM {external_functions} f
 532                       WHERE f.name IN (SELECT sf.functionname
 533                                          FROM {external_services_functions} sf
 534                                         WHERE sf.externalserviceid $serviceids)
 535                       ORDER BY f.name ASC";
 536              $functions = $DB->get_records_sql($sql, $params);
 537          } else {
 538              $functions = array();
 539          }
 540          return $functions;
 541      }
 542  
 543      /**
 544       * Get the functions of a service list (by shortname). It can return only enabled functions if required.
 545       *
 546       * @param array $serviceshortnames service shortnames
 547       * @param bool $enabledonly if true then only return functions for services that have been enabled
 548       * @return array functions
 549       */
 550      public function get_external_functions_by_enabled_services($serviceshortnames, $enabledonly = true) {
 551          global $DB;
 552          if (!empty($serviceshortnames)) {
 553              $enabledonlysql = $enabledonly?' AND s.enabled = 1 ':'';
 554              list($serviceshortnames, $params) = $DB->get_in_or_equal($serviceshortnames);
 555              $sql = "SELECT f.*
 556                        FROM {external_functions} f
 557                       WHERE f.name IN (SELECT sf.functionname
 558                                          FROM {external_services_functions} sf, {external_services} s
 559                                         WHERE s.shortname $serviceshortnames
 560                                               AND sf.externalserviceid = s.id
 561                                               " . $enabledonlysql . ")";
 562              $functions = $DB->get_records_sql($sql, $params);
 563          } else {
 564              $functions = array();
 565          }
 566          return $functions;
 567      }
 568  
 569      /**
 570       * Get functions not included in a service
 571       *
 572       * @param int $serviceid service id
 573       * @return array functions
 574       */
 575      public function get_not_associated_external_functions($serviceid) {
 576          global $DB;
 577          $select = "name NOT IN (SELECT s.functionname
 578                                    FROM {external_services_functions} s
 579                                   WHERE s.externalserviceid = :sid
 580                                 )";
 581  
 582          $functions = $DB->get_records_select('external_functions',
 583                          $select, array('sid' => $serviceid), 'name');
 584  
 585          return $functions;
 586      }
 587  
 588      /**
 589       * Get list of required capabilities of a service, sorted by functions
 590       * Example of returned value:
 591       *  Array
 592       *  (
 593       *    [core_group_create_groups] => Array
 594       *    (
 595       *       [0] => moodle/course:managegroups
 596       *    )
 597       *
 598       *    [core_enrol_get_enrolled_users] => Array
 599       *    (
 600       *       [0] => moodle/user:viewdetails
 601       *       [1] => moodle/user:viewhiddendetails
 602       *       [2] => moodle/course:useremail
 603       *       [3] => moodle/user:update
 604       *       [4] => moodle/site:accessallgroups
 605       *    )
 606       *  )
 607       * @param int $serviceid service id
 608       * @return array
 609       */
 610      public function get_service_required_capabilities($serviceid) {
 611          $functions = $this->get_external_functions(array($serviceid));
 612          $requiredusercaps = array();
 613          foreach ($functions as $function) {
 614              $functioncaps = explode(',', $function->capabilities);
 615              if (!empty($functioncaps) and !empty($functioncaps[0])) {
 616                  foreach ($functioncaps as $functioncap) {
 617                      $requiredusercaps[$function->name][] = trim($functioncap);
 618                  }
 619              }
 620          }
 621          return $requiredusercaps;
 622      }
 623  
 624      /**
 625       * Get user capabilities (with context)
 626       * Only useful for documentation purpose
 627       * WARNING: do not use this "broken" function. It was created in the goal to display some capabilities
 628       * required by users. In theory we should not need to display this kind of information
 629       * as the front end does not display it itself. In pratice,
 630       * admins would like the info, for more info you can follow: MDL-29962
 631       *
 632       * @deprecated since Moodle 3.11 in MDL-67748 without a replacement.
 633       * @todo MDL-70187 Please delete this method completely in Moodle 4.3, thank you.
 634       * @param int $userid user id
 635       * @return array
 636       */
 637      public function get_user_capabilities($userid) {
 638          global $DB;
 639  
 640          debugging('webservice::get_user_capabilities() has been deprecated.', DEBUG_DEVELOPER);
 641  
 642          //retrieve the user capabilities
 643          $sql = "SELECT DISTINCT rc.id, rc.capability FROM {role_capabilities} rc, {role_assignments} ra
 644              WHERE rc.roleid=ra.roleid AND ra.userid= ? AND rc.permission = ?";
 645          $dbusercaps = $DB->get_records_sql($sql, array($userid, CAP_ALLOW));
 646          $usercaps = array();
 647          foreach ($dbusercaps as $usercap) {
 648              $usercaps[$usercap->capability] = true;
 649          }
 650          return $usercaps;
 651      }
 652  
 653      /**
 654       * Get missing user capabilities for the given service's functions.
 655       *
 656       * Every external function can declare some required capabilities to allow for easier setup of the web services.
 657       * However, that is supposed to be used for informational admin report only. There is no automatic evaluation of
 658       * the declared capabilities and the context of the capability evaluation is ignored. Also, actual capability
 659       * evaluation is much more complex as it allows for overrides etc.
 660       *
 661       * Returned are capabilities that the given users do not seem to have assigned anywhere at the site and that should
 662       * be checked by the admin.
 663       *
 664       * Do not use this method for anything else, particularly not for any security related checks. See MDL-29962 for the
 665       * background of why we have this - there are arguments for dropping this feature completely.
 666       *
 667       * @param array $users List of users to check, consisting of objects, arrays or integer ids.
 668       * @param int $serviceid The id of the external service to check.
 669       * @return array List of missing capabilities: (int)userid => array of (string)capabilitynames
 670       */
 671      public function get_missing_capabilities_by_users(array $users, int $serviceid): array {
 672          global $DB;
 673  
 674          // The following are default capabilities for all authenticated users and we will assume them granted.
 675          $commoncaps = get_default_capabilities('user');
 676  
 677          // Get the list of additional capabilities required by the service.
 678          $servicecaps = [];
 679          foreach ($this->get_service_required_capabilities($serviceid) as $service => $caps) {
 680              foreach ($caps as $cap) {
 681                  if (empty($commoncaps[$cap])) {
 682                      $servicecaps[$cap] = true;
 683                  }
 684              }
 685          }
 686  
 687          // Bail out early if there's nothing to process.
 688          if (empty($users) || empty($servicecaps)) {
 689              return [];
 690          }
 691  
 692          // Prepare a list of user ids we want to check.
 693          $userids = [];
 694          foreach ($users as $user) {
 695              if (is_object($user) && isset($user->id)) {
 696                  $userids[$user->id] = true;
 697              } else if (is_array($user) && isset($user['id'])) {
 698                  $userids[$user['id']] = true;
 699              } else {
 700                  throw new coding_exception('Unexpected format of users list in webservice::get_missing_capabilities_by_users().');
 701              }
 702          }
 703  
 704          // Prepare a matrix of missing capabilities x users - consider them all missing by default.
 705          foreach (array_keys($userids) as $userid) {
 706              foreach (array_keys($servicecaps) as $capname) {
 707                  $matrix[$userid][$capname] = true;
 708              }
 709          }
 710  
 711          list($capsql, $capparams) = $DB->get_in_or_equal(array_keys($servicecaps), SQL_PARAMS_NAMED, 'paramcap');
 712          list($usersql, $userparams) = $DB->get_in_or_equal(array_keys($userids), SQL_PARAMS_NAMED, 'paramuser');
 713  
 714          $sql = "SELECT c.name AS capability, u.id AS userid
 715                    FROM {capabilities} c
 716                    JOIN {role_capabilities} rc ON c.name = rc.capability
 717                    JOIN {role_assignments} ra ON ra.roleid = rc.roleid
 718                    JOIN {user} u ON ra.userid = u.id
 719                   WHERE rc.permission = :capallow
 720                     AND c.name {$capsql}
 721                     AND u.id {$usersql}";
 722  
 723          $params = $capparams + $userparams + [
 724              'capallow' => CAP_ALLOW,
 725          ];
 726  
 727          $rs = $DB->get_recordset_sql($sql, $params);
 728  
 729          foreach ($rs as $record) {
 730              // If there was a potential role assignment found that might grant the user the given capability,
 731              // remove it from the matrix. Again, we ignore all the contexts, prohibits, prevents and other details
 732              // of the permissions evaluations. See the function docblock for details.
 733              unset($matrix[$record->userid][$record->capability]);
 734          }
 735  
 736          $rs->close();
 737  
 738          foreach ($matrix as $userid => $caps) {
 739              $matrix[$userid] = array_keys($caps);
 740              if (empty($matrix[$userid])) {
 741                  unset($matrix[$userid]);
 742              }
 743          }
 744  
 745          return $matrix;
 746      }
 747  
 748      /**
 749       * Get an external service for a given service id
 750       *
 751       * @param int $serviceid service id
 752       * @param int $strictness IGNORE_MISSING, MUST_EXIST...
 753       * @return stdClass external service
 754       */
 755      public function get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING) {
 756          global $DB;
 757          $service = $DB->get_record('external_services',
 758                          array('id' => $serviceid), '*', $strictness);
 759          return $service;
 760      }
 761  
 762      /**
 763       * Get an external service for a given shortname
 764       *
 765       * @param string $shortname service shortname
 766       * @param int $strictness IGNORE_MISSING, MUST_EXIST...
 767       * @return stdClass external service
 768       */
 769      public function get_external_service_by_shortname($shortname, $strictness=IGNORE_MISSING) {
 770          global $DB;
 771          $service = $DB->get_record('external_services',
 772                          array('shortname' => $shortname), '*', $strictness);
 773          return $service;
 774      }
 775  
 776      /**
 777       * Get an external function for a given function id
 778       *
 779       * @param int $functionid function id
 780       * @param int $strictness IGNORE_MISSING, MUST_EXIST...
 781       * @return stdClass external function
 782       */
 783      public function get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) {
 784          global $DB;
 785          $function = $DB->get_record('external_functions',
 786                              array('id' => $functionid), '*', $strictness);
 787          return $function;
 788      }
 789  
 790      /**
 791       * Add a function to a service
 792       *
 793       * @param string $functionname function name
 794       * @param int $serviceid service id
 795       */
 796      public function add_external_function_to_service($functionname, $serviceid) {
 797          global $DB;
 798          $addedfunction = new stdClass();
 799          $addedfunction->externalserviceid = $serviceid;
 800          $addedfunction->functionname = $functionname;
 801          $DB->insert_record('external_services_functions', $addedfunction);
 802      }
 803  
 804      /**
 805       * Add a service
 806       * It generates the timecreated field automatically.
 807       *
 808       * @param stdClass $service
 809       * @return serviceid integer
 810       */
 811      public function add_external_service($service) {
 812          global $DB;
 813          $service->timecreated = time();
 814          $serviceid = $DB->insert_record('external_services', $service);
 815          return $serviceid;
 816      }
 817  
 818      /**
 819       * Update a service
 820       * It modifies the timemodified automatically.
 821       *
 822       * @param stdClass $service
 823       */
 824      public function update_external_service($service) {
 825          global $DB;
 826          $service->timemodified = time();
 827          $DB->update_record('external_services', $service);
 828      }
 829  
 830      /**
 831       * Test whether an external function is already linked to a service
 832       *
 833       * @param string $functionname function name
 834       * @param int $serviceid service id
 835       * @return bool true if a matching function exists for the service, else false.
 836       * @throws dml_exception if error
 837       */
 838      public function service_function_exists($functionname, $serviceid) {
 839          global $DB;
 840          return $DB->record_exists('external_services_functions',
 841                              array('externalserviceid' => $serviceid,
 842                                  'functionname' => $functionname));
 843      }
 844  
 845      /**
 846       * Remove a function from a service
 847       *
 848       * @param string $functionname function name
 849       * @param int $serviceid service id
 850       */
 851      public function remove_external_function_from_service($functionname, $serviceid) {
 852          global $DB;
 853          $DB->delete_records('external_services_functions',
 854                      array('externalserviceid' => $serviceid, 'functionname' => $functionname));
 855  
 856      }
 857  
 858      /**
 859       * Return a list with all the valid user tokens for the given user, it only excludes expired tokens.
 860       *
 861       * @param  string $userid user id to retrieve tokens from
 862       * @return array array of token entries
 863       * @since Moodle 3.2
 864       */
 865      public static function get_active_tokens($userid) {
 866          global $DB;
 867  
 868          $sql = 'SELECT t.*, s.name as servicename FROM {external_tokens} t JOIN
 869                  {external_services} s ON t.externalserviceid = s.id WHERE
 870                  t.userid = :userid AND (COALESCE(t.validuntil, 0) = 0 OR t.validuntil > :now)';
 871          $params = array('userid' => $userid, 'now' => time());
 872          return $DB->get_records_sql($sql, $params);
 873      }
 874  }
 875  
 876  /**
 877   * Exception indicating access control problem in web service call
 878   * This exception should return general errors about web service setup.
 879   * Errors related to the user like wrong username/password should not use it,
 880   * you should not use this exception if you want to let the client implement
 881   * some code logic against an access error.
 882   *
 883   * @package    core_webservice
 884   * @copyright  2009 Petr Skodak
 885   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 886   */
 887  class webservice_access_exception extends moodle_exception {
 888  
 889      /**
 890       * Constructor
 891       *
 892       * @param string $debuginfo the debug info
 893       */
 894      function __construct($debuginfo) {
 895          parent::__construct('accessexception', 'webservice', '', null, $debuginfo);
 896      }
 897  }
 898  
 899  /**
 900   * Check if a protocol is enabled
 901   *
 902   * @param string $protocol name of WS protocol ('rest', 'soap', ...)
 903   * @return bool true if the protocol is enabled
 904   */
 905  function webservice_protocol_is_enabled($protocol) {
 906      global $CFG;
 907  
 908      if (empty($CFG->enablewebservices) || empty($CFG->webserviceprotocols)) {
 909          return false;
 910      }
 911  
 912      $active = explode(',', $CFG->webserviceprotocols);
 913  
 914      return(in_array($protocol, $active));
 915  }
 916  
 917  /**
 918   * Mandatory interface for all test client classes.
 919   *
 920   * @package    core_webservice
 921   * @copyright  2009 Petr Skodak
 922   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 923   */
 924  interface webservice_test_client_interface {
 925  
 926      /**
 927       * Execute test client WS request
 928       *
 929       * @param string $serverurl server url (including the token param)
 930       * @param string $function web service function name
 931       * @param array $params parameters of the web service function
 932       * @return mixed
 933       */
 934      public function simpletest($serverurl, $function, $params);
 935  }
 936  
 937  /**
 938   * Mandatory interface for all web service protocol classes
 939   *
 940   * @package    core_webservice
 941   * @copyright  2009 Petr Skodak
 942   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 943   */
 944  interface webservice_server_interface {
 945  
 946      /**
 947       * Process request from client.
 948       */
 949      public function run();
 950  }
 951  
 952  /**
 953   * Abstract web service base class.
 954   *
 955   * @package    core_webservice
 956   * @copyright  2009 Petr Skodak
 957   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 958   */
 959  abstract class webservice_server implements webservice_server_interface {
 960  
 961      /** @var string Name of the web server plugin */
 962      protected $wsname = null;
 963  
 964      /** @var string Name of local user */
 965      protected $username = null;
 966  
 967      /** @var string Password of the local user */
 968      protected $password = null;
 969  
 970      /** @var int The local user */
 971      protected $userid = null;
 972  
 973      /** @var integer Authentication method one of WEBSERVICE_AUTHMETHOD_* */
 974      protected $authmethod;
 975  
 976      /** @var string Authentication token*/
 977      protected $token = null;
 978  
 979      /** @var stdClass Restricted context */
 980      protected $restricted_context;
 981  
 982      /** @var int Restrict call to one service id*/
 983      protected $restricted_serviceid = null;
 984  
 985      /**
 986       * Constructor
 987       *
 988       * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
 989       */
 990      public function __construct($authmethod) {
 991          $this->authmethod = $authmethod;
 992      }
 993  
 994  
 995      /**
 996       * Authenticate user using username+password or token.
 997       * This function sets up $USER global.
 998       * It is safe to use has_capability() after this.
 999       * This method also verifies user is allowed to use this
1000       * server.
1001       */
1002      protected function authenticate_user() {
1003          global $CFG, $DB;
1004  
1005          if (!NO_MOODLE_COOKIES) {
1006              throw new coding_exception('Cookies must be disabled in WS servers!');
1007          }
1008  
1009          $loginfaileddefaultparams = array(
1010              'other' => array(
1011                  'method' => $this->authmethod,
1012                  'reason' => null
1013              )
1014          );
1015  
1016          if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1017  
1018              //we check that authentication plugin is enabled
1019              //it is only required by simple authentication
1020              if (!is_enabled_auth('webservice')) {
1021                  throw new webservice_access_exception('The web service authentication plugin is disabled.');
1022              }
1023  
1024              if (!$auth = get_auth_plugin('webservice')) {
1025                  throw new webservice_access_exception('The web service authentication plugin is missing.');
1026              }
1027  
1028              $this->restricted_context = context_system::instance();
1029  
1030              if (!$this->username) {
1031                  throw new moodle_exception('missingusername', 'webservice');
1032              }
1033  
1034              if (!$this->password) {
1035                  throw new moodle_exception('missingpassword', 'webservice');
1036              }
1037  
1038              if (!$auth->user_login_webservice($this->username, $this->password)) {
1039  
1040                  // Log failed login attempts.
1041                  $params = $loginfaileddefaultparams;
1042                  $params['other']['reason'] = 'password';
1043                  $params['other']['username'] = $this->username;
1044                  $event = \core\event\webservice_login_failed::create($params);
1045                  $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('simpleauthlog', 'webservice'), '' ,
1046                      get_string('failedtolog', 'webservice').": ".$this->username."/".$this->password." - ".getremoteaddr() , 0));
1047                  $event->trigger();
1048  
1049                  throw new moodle_exception('wrongusernamepassword', 'webservice');
1050              }
1051  
1052              $user = $DB->get_record('user', array('username'=>$this->username, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
1053  
1054          } else if ($this->authmethod == WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN){
1055              $user = $this->authenticate_by_token(EXTERNAL_TOKEN_PERMANENT);
1056          } else {
1057              $user = $this->authenticate_by_token(EXTERNAL_TOKEN_EMBEDDED);
1058          }
1059  
1060          // Cannot authenticate unless maintenance access is granted.
1061          $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system::instance(), $user);
1062          if (!empty($CFG->maintenance_enabled) and !$hasmaintenanceaccess) {
1063              throw new moodle_exception('sitemaintenance', 'admin');
1064          }
1065  
1066          //only confirmed user should be able to call web service
1067          if (!empty($user->deleted)) {
1068              $params = $loginfaileddefaultparams;
1069              $params['other']['reason'] = 'user_deleted';
1070              $params['other']['username'] = $user->username;
1071              $event = \core\event\webservice_login_failed::create($params);
1072              $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessuserdeleted', 'webservice',
1073                  $user->username) . " - ".getremoteaddr(), 0, $user->id));
1074              $event->trigger();
1075              throw new moodle_exception('wsaccessuserdeleted', 'webservice', '', $user->username);
1076          }
1077  
1078          //only confirmed user should be able to call web service
1079          if (empty($user->confirmed)) {
1080              $params = $loginfaileddefaultparams;
1081              $params['other']['reason'] = 'user_unconfirmed';
1082              $params['other']['username'] = $user->username;
1083              $event = \core\event\webservice_login_failed::create($params);
1084              $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessuserunconfirmed', 'webservice',
1085                  $user->username) . " - ".getremoteaddr(), 0, $user->id));
1086              $event->trigger();
1087              throw new moodle_exception('wsaccessuserunconfirmed', 'webservice', '', $user->username);
1088          }
1089  
1090          //check the user is suspended
1091          if (!empty($user->suspended)) {
1092              $params = $loginfaileddefaultparams;
1093              $params['other']['reason'] = 'user_unconfirmed';
1094              $params['other']['username'] = $user->username;
1095              $event = \core\event\webservice_login_failed::create($params);
1096              $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessusersuspended', 'webservice',
1097                  $user->username) . " - ".getremoteaddr(), 0, $user->id));
1098              $event->trigger();
1099              throw new moodle_exception('wsaccessusersuspended', 'webservice', '', $user->username);
1100          }
1101  
1102          //retrieve the authentication plugin if no previously done
1103          if (empty($auth)) {
1104            $auth  = get_auth_plugin($user->auth);
1105          }
1106  
1107          // check if credentials have expired
1108          if (!empty($auth->config->expiration) and $auth->config->expiration == 1) {
1109              $days2expire = $auth->password_expire($user->username);
1110              if (intval($days2expire) < 0 ) {
1111                  $params = $loginfaileddefaultparams;
1112                  $params['other']['reason'] = 'password_expired';
1113                  $params['other']['username'] = $user->username;
1114                  $event = \core\event\webservice_login_failed::create($params);
1115                  $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessuserexpired', 'webservice',
1116                      $user->username) . " - ".getremoteaddr(), 0, $user->id));
1117                  $event->trigger();
1118                  throw new moodle_exception('wsaccessuserexpired', 'webservice', '', $user->username);
1119              }
1120          }
1121  
1122          //check if the auth method is nologin (in this case refuse connection)
1123          if ($user->auth=='nologin') {
1124              $params = $loginfaileddefaultparams;
1125              $params['other']['reason'] = 'login';
1126              $params['other']['username'] = $user->username;
1127              $event = \core\event\webservice_login_failed::create($params);
1128              $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessusernologin', 'webservice',
1129                  $user->username) . " - ".getremoteaddr(), 0, $user->id));
1130              $event->trigger();
1131              throw new moodle_exception('wsaccessusernologin', 'webservice', '', $user->username);
1132          }
1133  
1134          // now fake user login, the session is completely empty too
1135          enrol_check_plugins($user, false);
1136          \core\session\manager::set_user($user);
1137          set_login_session_preferences();
1138          $this->userid = $user->id;
1139  
1140          if ($this->authmethod != WEBSERVICE_AUTHMETHOD_SESSION_TOKEN && !has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
1141              throw new webservice_access_exception("You are not allowed to use the {$this->wsname} protocol " .
1142                  "(missing capability: webservice/{$this->wsname}:use)");
1143          }
1144  
1145          external_api::set_context_restriction($this->restricted_context);
1146      }
1147  
1148      /**
1149       * User authentication by token
1150       *
1151       * @param string $tokentype token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT)
1152       * @return stdClass the authenticated user
1153       * @throws webservice_access_exception
1154       */
1155      protected function authenticate_by_token($tokentype){
1156          global $DB;
1157  
1158          $loginfaileddefaultparams = array(
1159              'other' => array(
1160                  'method' => $this->authmethod,
1161                  'reason' => null
1162              )
1163          );
1164  
1165          if (!$token = $DB->get_record('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype))) {
1166              // Log failed login attempts.
1167              $params = $loginfaileddefaultparams;
1168              $params['other']['reason'] = 'invalid_token';
1169              $event = \core\event\webservice_login_failed::create($params);
1170              $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '' ,
1171                  get_string('failedtolog', 'webservice').": ".$this->token. " - ".getremoteaddr() , 0));
1172              $event->trigger();
1173              throw new moodle_exception('invalidtoken', 'webservice');
1174          }
1175  
1176          if ($token->validuntil and $token->validuntil < time()) {
1177              $DB->delete_records('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype));
1178              throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');
1179          }
1180  
1181          if ($token->sid){//assumes that if sid is set then there must be a valid associated session no matter the token type
1182              if (!\core\session\manager::session_exists($token->sid)){
1183                  $DB->delete_records('external_tokens', array('sid'=>$token->sid));
1184                  throw new webservice_access_exception('Invalid session based token - session not found or expired');
1185              }
1186          }
1187  
1188          if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
1189              $params = $loginfaileddefaultparams;
1190              $params['other']['reason'] = 'ip_restricted';
1191              $params['other']['tokenid'] = $token->id;
1192              $event = \core\event\webservice_login_failed::create($params);
1193              $event->add_record_snapshot('external_tokens', $token);
1194              $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '' ,
1195                  get_string('failedtolog', 'webservice').": ".getremoteaddr() , 0));
1196              $event->trigger();
1197              throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()
1198                      . ' is not supported - check this allowed user');
1199          }
1200  
1201          $this->restricted_context = context::instance_by_id($token->contextid);
1202          $this->restricted_serviceid = $token->externalserviceid;
1203  
1204          $user = $DB->get_record('user', array('id'=>$token->userid), '*', MUST_EXIST);
1205  
1206          // log token access
1207          webservice::update_token_lastaccess($token);
1208  
1209          return $user;
1210  
1211      }
1212  
1213      /**
1214       * Intercept some moodlewssettingXXX $_GET and $_POST parameter
1215       * that are related to the web service call and are not the function parameters
1216       */
1217      protected function set_web_service_call_settings() {
1218          global $CFG;
1219  
1220          // Default web service settings.
1221          // Must be the same XXX key name as the external_settings::set_XXX function.
1222          // Must be the same XXX ws parameter name as 'moodlewssettingXXX'.
1223          $externalsettings = array(
1224              'raw' => array('default' => false, 'type' => PARAM_BOOL),
1225              'fileurl' => array('default' => true, 'type' => PARAM_BOOL),
1226              'filter' => array('default' => false, 'type' => PARAM_BOOL),
1227              'lang' => array('default' => '', 'type' => PARAM_LANG),
1228              'timezone' => array('default' => '', 'type' => PARAM_TIMEZONE),
1229          );
1230  
1231          // Load the external settings with the web service settings.
1232          $settings = external_settings::get_instance();
1233          foreach ($externalsettings as $name => $settingdata) {
1234  
1235              $wsparamname = 'moodlewssetting' . $name;
1236  
1237              // Retrieve and remove the setting parameter from the request.
1238              $value = optional_param($wsparamname, $settingdata['default'], $settingdata['type']);
1239              unset($_GET[$wsparamname]);
1240              unset($_POST[$wsparamname]);
1241  
1242              $functioname = 'set_' . $name;
1243              $settings->$functioname($value);
1244          }
1245  
1246      }
1247  }
1248  
1249  /**
1250   * Web Service server base class.
1251   *
1252   * This class handles both simple and token authentication.
1253   *
1254   * @package    core_webservice
1255   * @copyright  2009 Petr Skodak
1256   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1257   */
1258  abstract class webservice_base_server extends webservice_server {
1259  
1260      /** @var array The function parameters - the real values submitted in the request */
1261      protected $parameters = null;
1262  
1263      /** @var string The name of the function that is executed */
1264      protected $functionname = null;
1265  
1266      /** @var stdClass Full function description */
1267      protected $function = null;
1268  
1269      /** @var mixed Function return value */
1270      protected $returns = null;
1271  
1272      /** @var array List of methods and their information provided by the web service. */
1273      protected $servicemethods;
1274  
1275      /** @var  array List of struct classes generated for the web service methods. */
1276      protected $servicestructs;
1277  
1278      /**
1279       * This method parses the request input, it needs to get:
1280       *  1/ user authentication - username+password or token
1281       *  2/ function name
1282       *  3/ function parameters
1283       */
1284      abstract protected function parse_request();
1285  
1286      /**
1287       * Send the result of function call to the WS client.
1288       */
1289      abstract protected function send_response();
1290  
1291      /**
1292       * Send the error information to the WS client.
1293       *
1294       * @param exception $ex
1295       */
1296      abstract protected function send_error($ex=null);
1297  
1298      /**
1299       * Process request from client.
1300       *
1301       * @uses die
1302       */
1303      public function run() {
1304          global $CFG, $USER, $SESSION;
1305  
1306          // we will probably need a lot of memory in some functions
1307          raise_memory_limit(MEMORY_EXTRA);
1308  
1309          // set some longer timeout, this script is not sending any output,
1310          // this means we need to manually extend the timeout operations
1311          // that need longer time to finish
1312          external_api::set_timeout();
1313  
1314          // set up exception handler first, we want to sent them back in correct format that
1315          // the other system understands
1316          // we do not need to call the original default handler because this ws handler does everything
1317          set_exception_handler(array($this, 'exception_handler'));
1318  
1319          // init all properties from the request data
1320          $this->parse_request();
1321  
1322          // authenticate user, this has to be done after the request parsing
1323          // this also sets up $USER and $SESSION
1324          $this->authenticate_user();
1325  
1326          // find all needed function info and make sure user may actually execute the function
1327          $this->load_function_info();
1328  
1329          // Log the web service request.
1330          $params = array(
1331              'other' => array(
1332                  'function' => $this->functionname
1333              )
1334          );
1335          $event = \core\event\webservice_function_called::create($params);
1336          $event->set_legacy_logdata(array(SITEID, 'webservice', $this->functionname, '' , getremoteaddr() , 0, $this->userid));
1337          $event->trigger();
1338  
1339          // Do additional setup stuff.
1340          $settings = external_settings::get_instance();
1341          $sessionlang = $settings->get_lang();
1342          if (!empty($sessionlang)) {
1343              $SESSION->lang = $sessionlang;
1344          }
1345  
1346          setup_lang_from_browser();
1347  
1348          if (empty($CFG->lang)) {
1349              if (empty($SESSION->lang)) {
1350                  $CFG->lang = 'en';
1351              } else {
1352                  $CFG->lang = $SESSION->lang;
1353              }
1354          }
1355  
1356          // Change timezone only in sites where it isn't forced.
1357          $newtimezone = $settings->get_timezone();
1358          if (!empty($newtimezone) && (!isset($CFG->forcetimezone) || $CFG->forcetimezone == 99)) {
1359              $USER->timezone = $newtimezone;
1360          }
1361  
1362          // finally, execute the function - any errors are catched by the default exception handler
1363          $this->execute();
1364  
1365          // send the results back in correct format
1366          $this->send_response();
1367  
1368          // session cleanup
1369          $this->session_cleanup();
1370  
1371          die;
1372      }
1373  
1374      /**
1375       * Specialised exception handler, we can not use the standard one because
1376       * it can not just print html to output.
1377       *
1378       * @param exception $ex
1379       * $uses exit
1380       */
1381      public function exception_handler($ex) {
1382          // detect active db transactions, rollback and log as error
1383          abort_all_db_transactions();
1384  
1385          // some hacks might need a cleanup hook
1386          $this->session_cleanup($ex);
1387  
1388          // now let the plugin send the exception to client
1389          $this->send_error($ex);
1390  
1391          // not much else we can do now, add some logging later
1392          exit(1);
1393      }
1394  
1395      /**
1396       * Future hook needed for emulated sessions.
1397       *
1398       * @param exception $exception null means normal termination, $exception received when WS call failed
1399       */
1400      protected function session_cleanup($exception=null) {
1401          if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1402              // nothing needs to be done, there is no persistent session
1403          } else {
1404              // close emulated session if used
1405          }
1406      }
1407  
1408      /**
1409       * Fetches the function description from database,
1410       * verifies user is allowed to use this function and
1411       * loads all paremeters and return descriptions.
1412       */
1413      protected function load_function_info() {
1414          global $DB, $USER, $CFG;
1415  
1416          if (empty($this->functionname)) {
1417              throw new invalid_parameter_exception('Missing function name');
1418          }
1419  
1420          // function must exist
1421          $function = external_api::external_function_info($this->functionname);
1422  
1423          if ($this->restricted_serviceid) {
1424              $params = array('sid1'=>$this->restricted_serviceid, 'sid2'=>$this->restricted_serviceid);
1425              $wscond1 = 'AND s.id = :sid1';
1426              $wscond2 = 'AND s.id = :sid2';
1427          } else {
1428              $params = array();
1429              $wscond1 = '';
1430              $wscond2 = '';
1431          }
1432  
1433          // now let's verify access control
1434  
1435          // now make sure the function is listed in at least one service user is allowed to use
1436          // allow access only if:
1437          //  1/ entry in the external_services_users table if required
1438          //  2/ validuntil not reached
1439          //  3/ has capability if specified in service desc
1440          //  4/ iprestriction
1441  
1442          $sql = "SELECT s.*, NULL AS iprestriction
1443                    FROM {external_services} s
1444                    JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
1445                   WHERE s.enabled = 1 $wscond1
1446  
1447                   UNION
1448  
1449                  SELECT s.*, su.iprestriction
1450                    FROM {external_services} s
1451                    JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
1452                    JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1453                   WHERE s.enabled = 1 AND (su.validuntil IS NULL OR su.validuntil < :now) $wscond2";
1454          $params = array_merge($params, array('userid'=>$USER->id, 'name1'=>$function->name, 'name2'=>$function->name, 'now'=>time()));
1455  
1456          $rs = $DB->get_recordset_sql($sql, $params);
1457          // now make sure user may access at least one service
1458          $remoteaddr = getremoteaddr();
1459          $allowed = false;
1460          foreach ($rs as $service) {
1461              if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
1462                  continue; // cap required, sorry
1463              }
1464              if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
1465                  continue; // wrong request source ip, sorry
1466              }
1467              $allowed = true;
1468              break; // one service is enough, no need to continue
1469          }
1470          $rs->close();
1471          if (!$allowed) {
1472              throw new webservice_access_exception(
1473                      'Access to the function '.$this->functionname.'() is not allowed.
1474                       There could be multiple reasons for this:
1475                       1. The service linked to the user token does not contain the function.
1476                       2. The service is user-restricted and the user is not listed.
1477                       3. The service is IP-restricted and the user IP is not listed.
1478                       4. The service is time-restricted and the time has expired.
1479                       5. The token is time-restricted and the time has expired.
1480                       6. The service requires a specific capability which the user does not have.
1481                       7. The function is called with username/password (no user token is sent)
1482                       and none of the services has the function to allow the user.
1483                       These settings can be found in Administration > Site administration
1484                       > Server > Web services > External services and Manage tokens.');
1485          }
1486  
1487          // we have all we need now
1488          $this->function = $function;
1489      }
1490  
1491      /**
1492       * Execute previously loaded function using parameters parsed from the request data.
1493       */
1494      protected function execute() {
1495          // validate params, this also sorts the params properly, we need the correct order in the next part
1496          $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);
1497          $params = array_values($params);
1498  
1499          // Allow any Moodle plugin a chance to override this call. This is a convenient spot to
1500          // make arbitrary behaviour customisations, for example to affect the mobile app behaviour.
1501          // The overriding plugin could call the 'real' function first and then modify the results,
1502          // or it could do a completely separate thing.
1503          $callbacks = get_plugins_with_function('override_webservice_execution');
1504          foreach ($callbacks as $plugintype => $plugins) {
1505              foreach ($plugins as $plugin => $callback) {
1506                  $result = $callback($this->function, $params);
1507                  if ($result !== false) {
1508                      // If the callback returns anything other than false, we assume it replaces the
1509                      // real function.
1510                      $this->returns = $result;
1511                      return;
1512                  }
1513              }
1514          }
1515  
1516          // execute - yay!
1517          $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), $params);
1518      }
1519  
1520      /**
1521       * Load the virtual class needed for the web service.
1522       *
1523       * Initialises the virtual class that contains the web service functions that the user is allowed to use.
1524       * The web service function will be available if the user:
1525       * - is validly registered in the external_services_users table.
1526       * - has the required capability.
1527       * - meets the IP restriction requirement.
1528       * This virtual class can be used by web service protocols such as SOAP, especially when generating WSDL.
1529       */
1530      protected function init_service_class() {
1531          global $USER, $DB;
1532  
1533          // Initialise service methods and struct classes.
1534          $this->servicemethods = array();
1535          $this->servicestructs = array();
1536  
1537          $params = array();
1538          $wscond1 = '';
1539          $wscond2 = '';
1540          if ($this->restricted_serviceid) {
1541              $params = array('sid1' => $this->restricted_serviceid, 'sid2' => $this->restricted_serviceid);
1542              $wscond1 = 'AND s.id = :sid1';
1543              $wscond2 = 'AND s.id = :sid2';
1544          }
1545  
1546          $sql = "SELECT s.*, NULL AS iprestriction
1547                    FROM {external_services} s
1548                    JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
1549                   WHERE s.enabled = 1 $wscond1
1550  
1551                   UNION
1552  
1553                  SELECT s.*, su.iprestriction
1554                    FROM {external_services} s
1555                    JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
1556                    JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1557                   WHERE s.enabled = 1 AND (su.validuntil IS NULL OR su.validuntil < :now) $wscond2";
1558          $params = array_merge($params, array('userid' => $USER->id, 'now' => time()));
1559  
1560          $serviceids = array();
1561          $remoteaddr = getremoteaddr();
1562  
1563          // Query list of external services for the user.
1564          $rs = $DB->get_recordset_sql($sql, $params);
1565  
1566          // Check which service ID to include.
1567          foreach ($rs as $service) {
1568              if (isset($serviceids[$service->id])) {
1569                  continue; // Service already added.
1570              }
1571              if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
1572                  continue; // Cap required, sorry.
1573              }
1574              if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
1575                  continue; // Wrong request source ip, sorry.
1576              }
1577              $serviceids[$service->id] = $service->id;
1578          }
1579          $rs->close();
1580  
1581          // Generate the virtual class name.
1582          $classname = 'webservices_virtual_class_000000';
1583          while (class_exists($classname)) {
1584              $classname++;
1585          }
1586          $this->serviceclass = $classname;
1587  
1588          // Get the list of all available external functions.
1589          $wsmanager = new webservice();
1590          $functions = $wsmanager->get_external_functions($serviceids);
1591  
1592          // Generate code for the virtual methods for this web service.
1593          $methods = '';
1594          foreach ($functions as $function) {
1595              $methods .= $this->get_virtual_method_code($function);
1596          }
1597  
1598          $code = <<<EOD
1599  /**
1600   * Virtual class web services for user id $USER->id in context {$this->restricted_context->id}.
1601   */
1602  class $classname {
1603  $methods
1604  }
1605  EOD;
1606          // Load the virtual class definition into memory.
1607          eval($code);
1608      }
1609  
1610      /**
1611       * Generates a struct class.
1612       *
1613       * @param external_single_structure $structdesc The basis of the struct class to be generated.
1614       * @return string The class name of the generated struct class.
1615       */
1616      protected function generate_simple_struct_class(external_single_structure $structdesc) {
1617          global $USER;
1618  
1619          $propeties = array();
1620          $fields = array();
1621          foreach ($structdesc->keys as $name => $fieldsdesc) {
1622              $type = $this->get_phpdoc_type($fieldsdesc);
1623              $propertytype = array('type' => $type);
1624              if (empty($fieldsdesc->allownull) || $fieldsdesc->allownull == NULL_ALLOWED) {
1625                  $propertytype['nillable'] = true;
1626              }
1627              $propeties[$name] = $propertytype;
1628              $fields[] = '    /** @var ' . $type . ' $' . $name . '*/';
1629              $fields[] = '    public $' . $name .';';
1630          }
1631          $fieldsstr = implode("\n", $fields);
1632  
1633          // We do this after the call to get_phpdoc_type() to avoid duplicate class creation.
1634          $classname = 'webservices_struct_class_000000';
1635          while (class_exists($classname)) {
1636              $classname++;
1637          }
1638          $code = <<<EOD
1639  /**
1640   * Virtual struct class for web services for user id $USER->id in context {$this->restricted_context->id}.
1641   */
1642  class $classname {
1643  $fieldsstr
1644  }
1645  EOD;
1646          // Load into memory.
1647          eval($code);
1648  
1649          // Prepare struct info.
1650          $structinfo = new stdClass();
1651          $structinfo->classname = $classname;
1652          $structinfo->properties = $propeties;
1653          // Add the struct info the the list of service struct classes.
1654          $this->servicestructs[] = $structinfo;
1655  
1656          return $classname;
1657      }
1658  
1659      /**
1660       * Returns a virtual method code for a web service function.
1661       *
1662       * @param stdClass $function a record from external_function
1663       * @return string The PHP code of the virtual method.
1664       * @throws coding_exception
1665       * @throws moodle_exception
1666       */
1667      protected function get_virtual_method_code($function) {
1668          $function = external_api::external_function_info($function);
1669  
1670          // Parameters and their defaults for the method signature.
1671          $paramanddefaults = array();
1672          // Parameters for external lib call.
1673          $params = array();
1674          $paramdesc = array();
1675          // The method's input parameters and their respective types.
1676          $inputparams = array();
1677          // The method's output parameters and their respective types.
1678          $outputparams = array();
1679  
1680          foreach ($function->parameters_desc->keys as $name => $keydesc) {
1681              $param = '$' . $name;
1682              $paramanddefault = $param;
1683              if ($keydesc->required == VALUE_OPTIONAL) {
1684                  // It does not make sense to declare a parameter VALUE_OPTIONAL. VALUE_OPTIONAL is used only for array/object key.
1685                  throw new moodle_exception('erroroptionalparamarray', 'webservice', '', $name);
1686              } else if ($keydesc->required == VALUE_DEFAULT) {
1687                  // Need to generate the default, if there is any.
1688                  if ($keydesc instanceof external_value) {
1689                      if ($keydesc->default === null) {
1690                          $paramanddefault .= ' = null';
1691                      } else {
1692                          switch ($keydesc->type) {
1693                              case PARAM_BOOL:
1694                                  $default = (int)$keydesc->default;
1695                                  break;
1696                              case PARAM_INT:
1697                                  $default = $keydesc->default;
1698                                  break;
1699                              case PARAM_FLOAT;
1700                                  $default = $keydesc->default;
1701                                  break;
1702                              default:
1703                                  $default = "'$keydesc->default'";
1704                          }
1705                          $paramanddefault .= " = $default";
1706                      }
1707                  } else {
1708                      // Accept empty array as default.
1709                      if (isset($keydesc->default) && is_array($keydesc->default) && empty($keydesc->default)) {
1710                          $paramanddefault .= ' = array()';
1711                      } else {
1712                          // For the moment we do not support default for other structure types.
1713                          throw new moodle_exception('errornotemptydefaultparamarray', 'webservice', '', $name);
1714                      }
1715                  }
1716              }
1717  
1718              $params[] = $param;
1719              $paramanddefaults[] = $paramanddefault;
1720              $type = $this->get_phpdoc_type($keydesc);
1721              $inputparams[$name]['type'] = $type;
1722  
1723              $paramdesc[] = '* @param ' . $type . ' $' . $name . ' ' . $keydesc->desc;
1724          }
1725          $paramanddefaults = implode(', ', $paramanddefaults);
1726          $paramdescstr = implode("\n ", $paramdesc);
1727  
1728          $serviceclassmethodbody = $this->service_class_method_body($function, $params);
1729  
1730          if (empty($function->returns_desc)) {
1731              $return = '* @return void';
1732          } else {
1733              $type = $this->get_phpdoc_type($function->returns_desc);
1734              $outputparams['return']['type'] = $type;
1735              $return = '* @return ' . $type . ' ' . $function->returns_desc->desc;
1736          }
1737  
1738          // Now create the virtual method that calls the ext implementation.
1739          $code = <<<EOD
1740  /**
1741   * $function->description.
1742   *
1743   $paramdescstr
1744   $return
1745   */
1746  public function $function->name($paramanddefaults) {
1747  $serviceclassmethodbody
1748  }
1749  EOD;
1750  
1751          // Prepare the method information.
1752          $methodinfo = new stdClass();
1753          $methodinfo->name = $function->name;
1754          $methodinfo->inputparams = $inputparams;
1755          $methodinfo->outputparams = $outputparams;
1756          $methodinfo->description = $function->description;
1757          // Add the method information into the list of service methods.
1758          $this->servicemethods[] = $methodinfo;
1759  
1760          return $code;
1761      }
1762  
1763      /**
1764       * Get the phpdoc type for an external_description object.
1765       * external_value => int, double or string
1766       * external_single_structure => object|struct, on-fly generated stdClass name.
1767       * external_multiple_structure => array
1768       *
1769       * @param mixed $keydesc The type description.
1770       * @return string The PHP doc type of the external_description object.
1771       */
1772      protected function get_phpdoc_type($keydesc) {
1773          $type = null;
1774          if ($keydesc instanceof external_value) {
1775              switch ($keydesc->type) {
1776                  case PARAM_BOOL: // 0 or 1 only for now.
1777                  case PARAM_INT:
1778                      $type = 'int';
1779                      break;
1780                  case PARAM_FLOAT;
1781                      $type = 'double';
1782                      break;
1783                  default:
1784                      $type = 'string';
1785              }
1786          } else if ($keydesc instanceof external_single_structure) {
1787              $type = $this->generate_simple_struct_class($keydesc);
1788          } else if ($keydesc instanceof external_multiple_structure) {
1789              $type = 'array';
1790          }
1791  
1792          return $type;
1793      }
1794  
1795      /**
1796       * Generates the method body of the virtual external function.
1797       *
1798       * @param stdClass $function a record from external_function.
1799       * @param array $params web service function parameters.
1800       * @return string body of the method for $function ie. everything within the {} of the method declaration.
1801       */
1802      protected function service_class_method_body($function, $params) {
1803          // Cast the param from object to array (validate_parameters except array only).
1804          $castingcode = '';
1805          $paramsstr = '';
1806          if (!empty($params)) {
1807              foreach ($params as $paramtocast) {
1808                  // Clean the parameter from any white space.
1809                  $paramtocast = trim($paramtocast);
1810                  $castingcode .= "    $paramtocast = json_decode(json_encode($paramtocast), true);\n";
1811              }
1812              $paramsstr = implode(', ', $params);
1813          }
1814  
1815          $descriptionmethod = $function->methodname . '_returns()';
1816          $callforreturnvaluedesc = $function->classname . '::' . $descriptionmethod;
1817  
1818          $methodbody = <<<EOD
1819  $castingcode
1820      if ($callforreturnvaluedesc == null) {
1821          $function->classname::$function->methodname($paramsstr);
1822          return null;
1823      }
1824      return external_api::clean_returnvalue($callforreturnvaluedesc, $function->classname::$function->methodname($paramsstr));
1825  EOD;
1826          return $methodbody;
1827      }
1828  }
1829  
1830  /**
1831   * Early WS exception handler.
1832   * It handles exceptions during setup and returns the Exception text in the WS format.
1833   * If a raise function is found nothing is returned. Throws Exception otherwise.
1834   *
1835   * @param  Exception $ex Raised exception.
1836   * @throws Exception
1837   */
1838  function early_ws_exception_handler(Exception $ex): void {
1839      if (function_exists('raise_early_ws_exception')) {
1840          raise_early_ws_exception($ex);
1841          die;
1842      }
1843  
1844      throw $ex;
1845  }