Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.3.x will end 7 October 2024 (12 months).
  • Bug fixes for security issues in 4.3.x will end 21 April 2025 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.2.x is supported too.
/webservice/ -> lib.php (source)

Differences Between: [Versions 310 and 403] [Versions 311 and 403] [Versions 39 and 403] [Versions 400 and 403] [Versions 401 and 403] [Versions 402 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: 1832 lines (72 kb)
Included or required: 1 time
Referenced: 22 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
->tokenname
->firstname user firstname
->lastname
->externalserviceid
->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 call
This 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 classes

run()   X-Ref
Process request from client.


Class: 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.