Search moodle.org's
Developer Documentation
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]
Web services utility functions and classes
| Copyright: | 2009 Jerome Mouneyrac <jerome@moodle.com> |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 1845 lines (74 kb) |
| Included or required: | 1 time |
| Referenced: | 2 times |
| Includes or requires: | 0 files |
Defines 6 classes
webservice:: (31 methods):
authenticate_user()
update_token_lastaccess()
add_ws_authorised_user()
remove_ws_authorised_user()
update_ws_authorised_user()
get_ws_authorised_users()
get_ws_authorised_user()
generate_user_ws_tokens()
get_user_ws_tokens()
get_created_by_user_ws_token()
get_token_by_id_with_details()
get_token_by_id()
delete_user_ws_token()
delete_user_ws_tokens()
delete_service()
get_user_ws_token()
get_external_functions()
get_external_functions_by_enabled_services()
get_not_associated_external_functions()
get_service_required_capabilities()
get_user_capabilities()
get_missing_capabilities_by_users()
get_external_service_by_id()
get_external_service_by_shortname()
get_external_function_by_id()
add_external_function_to_service()
add_external_service()
update_external_service()
service_function_exists()
remove_external_function_from_service()
get_active_tokens()
webservice_access_exception:: (2 methods):
__construct()
webservice_protocol_is_enabled()
webservice_test_client_interface:: (1 method):
simpletest()
webservice_server_interface:: (1 method):
run()
webservice_server:: (4 methods):
__construct()
authenticate_user()
authenticate_by_token()
set_web_service_call_settings()
webservice_base_server:: (11 methods):
run()
exception_handler()
session_cleanup()
load_function_info()
execute()
init_service_class()
generate_simple_struct_class()
get_virtual_method_code()
get_phpdoc_type()
service_class_method_body()
early_ws_exception_handler()
Class: webservice - X-Ref
General web service library| authenticate_user($token) X-Ref |
| Authenticate user (used by download/upload file scripts) param: string $token return: array - contains the authenticated user, token and service objects |
| update_token_lastaccess($token, int $time = 0) X-Ref |
| Updates the last access time for a token. param: \stdClass $token Token object (must include id, lastaccess fields) param: int $time Time of access (0 = use current time) |
| add_ws_authorised_user($user) X-Ref |
| Allow user to call a service param: stdClass $user a user |
| remove_ws_authorised_user($user, $serviceid) X-Ref |
| Disallow a user to call a service param: stdClass $user a user param: int $serviceid |
| update_ws_authorised_user($user) X-Ref |
| Update allowed user settings (ip restriction, valid until...) param: stdClass $user |
| get_ws_authorised_users($serviceid) X-Ref |
| Return list of allowed users with their options (ip/timecreated / validuntil...) for a given service param: int $serviceid the service id to search against return: array $users |
| get_ws_authorised_user($serviceid, $userid) X-Ref |
| Return an authorised user with their options (ip/timecreated / validuntil...) param: int $serviceid the service id to search against param: int $userid the user to search against return: stdClass |
| generate_user_ws_tokens($userid) X-Ref |
| Generate all tokens of a specific user param: int $userid user id |
| get_user_ws_tokens($userid) X-Ref |
| Return all tokens of a specific user + the service state (enabled/disabled) + the authorised user mode (restricted/not restricted) param: int $userid user id return: array |
| get_created_by_user_ws_token($userid, $tokenid) X-Ref |
| Return a token that has been created by the user (i.e. to created by an admin) If no tokens exist an exception is thrown The returned value is a stdClass: ->id token id ->token ->firstname user firstname ->lastname ->name service name param: int $userid user id param: int $tokenid token id return: stdClass |
| get_token_by_id_with_details($tokenid) X-Ref |
| Return a token of an arbitrary user by tokenid, including details of the associated user and the service name. If no tokens exist an exception is thrown The returned value is a stdClass: ->id token id ->token ->firstname user firstname ->lastname ->name service name param: int $tokenid token id return: stdClass |
| get_token_by_id($tokenid) X-Ref |
| Return a database token record for a token id param: int $tokenid token id return: object token |
| delete_user_ws_token($tokenid) X-Ref |
| Delete a token param: int $tokenid token id |
| delete_user_ws_tokens($userid) X-Ref |
| Delete all the tokens belonging to a user. param: int $userid the user id whose tokens must be deleted |
| delete_service($serviceid) X-Ref |
| Delete a service Also delete function references and authorised user references. param: int $serviceid service id |
| get_user_ws_token($token) X-Ref |
| Get a full database token record for a given token value param: string $token |
| get_external_functions($serviceids) X-Ref |
| Get the functions list of a service list (by id) param: array $serviceids service ids return: array of functions |
| get_external_functions_by_enabled_services($serviceshortnames, $enabledonly = true) X-Ref |
| Get the functions of a service list (by shortname). It can return only enabled functions if required. param: array $serviceshortnames service shortnames param: bool $enabledonly if true then only return functions for services that have been enabled return: array functions |
| get_not_associated_external_functions($serviceid) X-Ref |
| Get functions not included in a service param: int $serviceid service id return: array functions |
| get_service_required_capabilities($serviceid) X-Ref |
| Get list of required capabilities of a service, sorted by functions Example of returned value: Array ( [core_group_create_groups] => Array ( [0] => moodle/course:managegroups ) [core_enrol_get_enrolled_users] => Array ( [0] => moodle/user:viewdetails [1] => moodle/user:viewhiddendetails [2] => moodle/course:useremail [3] => moodle/user:update [4] => moodle/site:accessallgroups ) ) param: int $serviceid service id return: array |
| get_user_capabilities($userid) X-Ref |
| Get user capabilities (with context) Only useful for documentation purpose WARNING: do not use this "broken" function. It was created in the goal to display some capabilities required by users. In theory we should not need to display this kind of information as the front end does not display it itself. In pratice, admins would like the info, for more info you can follow: MDL-29962 param: int $userid user id return: array |
| get_missing_capabilities_by_users(array $users, int $serviceid) X-Ref |
| Get missing user capabilities for the given service's functions. Every external function can declare some required capabilities to allow for easier setup of the web services. However, that is supposed to be used for informational admin report only. There is no automatic evaluation of the declared capabilities and the context of the capability evaluation is ignored. Also, actual capability evaluation is much more complex as it allows for overrides etc. Returned are capabilities that the given users do not seem to have assigned anywhere at the site and that should be checked by the admin. Do not use this method for anything else, particularly not for any security related checks. See MDL-29962 for the background of why we have this - there are arguments for dropping this feature completely. param: array $users List of users to check, consisting of objects, arrays or integer ids. param: int $serviceid The id of the external service to check. return: array List of missing capabilities: (int)userid => array of (string)capabilitynames |
| get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING) X-Ref |
| Get an external service for a given service id param: int $serviceid service id param: int $strictness IGNORE_MISSING, MUST_EXIST... return: stdClass external service |
| get_external_service_by_shortname($shortname, $strictness=IGNORE_MISSING) X-Ref |
| Get an external service for a given shortname param: string $shortname service shortname param: int $strictness IGNORE_MISSING, MUST_EXIST... return: stdClass external service |
| get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) X-Ref |
| Get an external function for a given function id param: int $functionid function id param: int $strictness IGNORE_MISSING, MUST_EXIST... return: stdClass external function |
| add_external_function_to_service($functionname, $serviceid) X-Ref |
| Add a function to a service param: string $functionname function name param: int $serviceid service id |
| add_external_service($service) X-Ref |
| Add a service It generates the timecreated field automatically. param: stdClass $service return: serviceid integer |
| update_external_service($service) X-Ref |
| Update a service It modifies the timemodified automatically. param: stdClass $service |
| service_function_exists($functionname, $serviceid) X-Ref |
| Test whether an external function is already linked to a service param: string $functionname function name param: int $serviceid service id return: bool true if a matching function exists for the service, else false. |
| remove_external_function_from_service($functionname, $serviceid) X-Ref |
| Remove a function from a service param: string $functionname function name param: int $serviceid service id |
| get_active_tokens($userid) X-Ref |
| Return a list with all the valid user tokens for the given user, it only excludes expired tokens. param: string $userid user id to retrieve tokens from return: array array of token entries |
Class: webservice_access_exception - X-Ref
Exception indicating access control problem in web service callThis exception should return general errors about web service setup.
Errors related to the user like wrong username/password should not use it,
you should not use this exception if you want to let the client implement
some code logic against an access error.
| __construct($debuginfo) X-Ref |
| Constructor param: string $debuginfo the debug info |
| webservice_protocol_is_enabled($protocol) X-Ref |
| Check if a protocol is enabled param: string $protocol name of WS protocol ('rest', 'soap', ...) return: bool true if the protocol is enabled |
Interface: webservice_test_client_interface - X-Ref
Mandatory interface for all test client classes.| simpletest($serverurl, $function, $params) X-Ref |
| Execute test client WS request param: string $serverurl server url (including the token param) param: string $function web service function name param: array $params parameters of the web service function return: mixed |
Interface: webservice_server_interface - X-Ref
Mandatory interface for all web service protocol classesClass: webservice_server - X-Ref
Abstract web service base class.| __construct($authmethod) X-Ref |
| Constructor param: integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* |
| authenticate_user() X-Ref |
| Authenticate user using username+password or token. This function sets up $USER global. It is safe to use has_capability() after this. This method also verifies user is allowed to use this server. |
| authenticate_by_token($tokentype) X-Ref |
| User authentication by token param: string $tokentype token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT) return: stdClass the authenticated user |
| set_web_service_call_settings() X-Ref |
| Intercept some moodlewssettingXXX $_GET and $_POST parameter that are related to the web service call and are not the function parameters |
Class: webservice_base_server - X-Ref
Web Service server base class.This class handles both simple and token authentication.
| run() X-Ref |
| Process request from client. |
| exception_handler($ex) X-Ref |
| Specialised exception handler, we can not use the standard one because it can not just print html to output. param: exception $ex |
| session_cleanup($exception=null) X-Ref |
| Future hook needed for emulated sessions. param: exception $exception null means normal termination, $exception received when WS call failed |
| load_function_info() X-Ref |
| Fetches the function description from database, verifies user is allowed to use this function and loads all paremeters and return descriptions. |
| execute() X-Ref |
| Execute previously loaded function using parameters parsed from the request data. |
| init_service_class() X-Ref |
| Load the virtual class needed for the web service. Initialises the virtual class that contains the web service functions that the user is allowed to use. The web service function will be available if the user: - is validly registered in the external_services_users table. - has the required capability. - meets the IP restriction requirement. This virtual class can be used by web service protocols such as SOAP, especially when generating WSDL. |
| generate_simple_struct_class(external_single_structure $structdesc) X-Ref |
| Generates a struct class. param: external_single_structure $structdesc The basis of the struct class to be generated. return: string The class name of the generated struct class. |
| get_virtual_method_code($function) X-Ref |
| Returns a virtual method code for a web service function. param: stdClass $function a record from external_function return: string The PHP code of the virtual method. |
| get_phpdoc_type($keydesc) X-Ref |
| No description |
| service_class_method_body($function, $params) X-Ref |
| Generates the method body of the virtual external function. param: stdClass $function a record from external_function. param: array $params web service function parameters. return: string body of the method for $function ie. everything within the {} of the method declaration. |
| early_ws_exception_handler(Exception $ex) X-Ref |
| Early WS exception handler. It handles exceptions during setup and returns the Exception text in the WS format. If a raise function is found nothing is returned. Throws Exception otherwise. param: Exception $ex Raised exception. |
