External functions API
Overview
The external functions API allows you to create fully parameterised methods that can be accessed by external programs (such as Web services API).
The external functions are located in externallib.php files. Each external function is implemented inside a class and is complemented by two description functions:
- FUNCTIONNAME_parameters() which describes the parameters of the functions
- FUNCTIONNAME_returns() which describes the return value
The description functions uses external_description classes that have been created for this purpose.
externallib.php
- This file is located at the root of your plugin (https://docs.moodle.org/dev/Frankenstyle#Plugin_types).
- This file is composed by a class that contains the external functions and their description functions.
<?php
/**
* PLUGIN external file
*
* @package local_PLUGIN
* @copyright 20XX YOURSELF
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once($CFG->libdir . "/externallib.php");
class local_PLUGIN_external extends external_api {
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function FUNCTIONNAME_parameters() {
// FUNCTIONNAME_parameters() always return an external_function_parameters().
// The external_function_parameters constructor expects an array of external_description.
return new external_function_parameters(
// a external_description can be: external_value, external_single_structure or external_multiple structure
array('PARAM1' => new external_value(PARAM_TYPE, 'human description of PARAM1'))
);
}
/**
* The function itself
* @return string welcome message
*/
public static function FUNCTIONNAME($PARAM1) {
//Parameters validation
$params = self::validate_parameters(self::FUNCTIONNAME_parameters(),
array('PARAM1' => $PARAM1));
//Note: don't forget to validate the context and check capabilities
return $returnedvalue;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function FUNCTIONNAME_returns() {
return new external_value(PARAM_TYPE, 'human description of the returned value');
}
}
To go further, read the core developer tutorial.
Example
You will find an example of an external.php file in the web service template plugin. This plugin contains a web service hello_world function. To make testing easy for you, the plugin is distributed with a test client in the folder /client.