Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/lib/external/classes/ -> external_api.php (source)

[Source view]

Differences Between: [Versions 402 and 403]

(no description)

File Size: 580 lines (26 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

external_api:: (9 methods):
  external_function_info()
  call_external_function()
  set_context_restriction()
  set_timeout()
  validate_parameters()
  clean_returnvalue()
  validate_context()
  get_context_from_params()
  get_context_parameters()


Class: external_api  - X-Ref

Base class for external api methods.

external_function_info($function, $strictness = MUST_EXIST)   X-Ref
Returns detailed function information

param: string|\stdClass $function name of external function or record from external_function
param: int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
return: \stdClass|bool description or false if not found or exception thrown

call_external_function($function, $args, $ajaxonly = false)   X-Ref
Call an external function validating all params/returns correctly.

Note that an external function may modify the state of the current page, so this wrapper
saves and restores tha PAGE and COURSE global variables before/after calling the external function.

param: string $function A webservice function name.
param: array $args Params array (named params)
param: boolean $ajaxonly If true, an extra check will be peformed to see if ajax is required.
return: array containing keys for error (bool), exception and data.

set_context_restriction($context)   X-Ref
Set context restriction for all following subsequent function calls.

param: \stdClass $context the context restriction

set_timeout($seconds = 360)   X-Ref
This method has to be called before every operation
that takes a longer time to finish!

param: int $seconds max expected time the next operation needs

validate_parameters(external_description $description, $params)   X-Ref
Validates submitted function parameters, if anything is incorrect
invalid_parameter_exception is thrown.
This is a simple recursive method which is intended to be called from
each implementation method of external API.

param: external_description $description description of parameters
param: mixed $params the actual parameters
return: mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found

clean_returnvalue(external_description $description, $response)   X-Ref
Clean response
If a response attribute is unknown from the description, we just ignore the attribute.
If a response attribute is incorrect, invalid_response_exception is thrown.
Note: this function is similar to validate parameters, however it is distinct because
parameters validation must be distinct from cleaning return values.

param: external_description $description description of the return values
param: mixed $response the actual response
return: mixed response with added defaults for optional items, invalid_response_exception thrown if any problem found
author: 2010 Jerome Mouneyrac

validate_context($context)   X-Ref
Makes sure user may execute functions in this context.

param: context $context

get_context_from_params($param)   X-Ref
Get context from passed parameters.
The passed array must either contain a contextid or a combination of context level and instance id to fetch the context.
For example, the context level can be "course" and instanceid can be courseid.

See context_helper::get_all_levels() for a list of valid numeric context levels,
legacy short names such as 'system', 'user', 'course' are not supported in new
plugin capabilities.

param: array $param
return: context

get_context_parameters()   X-Ref
Returns a prepared structure to use a context parameters.

return: external_single_structure