Search moodle.org's
Developer Documentation
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.
/lib/ -> externallib.php (source)
Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
