External functions API: Difference between revisions
From MoodleDocs
| Line 67: | Line 67: | ||
} | } | ||
</code> | </code> | ||
To go further, read the [[Creating_a_web_service_and_a_web_service_function|core developer tutorial]]. | |||
== Example == | == Example == | ||
Revision as of 09:21, 16 January 2012
Overview
The External functions API allows you to create fully parameterised methods that can be accessed by external programs (such as Web services).
externallib.php
- This file is located at the root of your plugin.
- This file is composed by a class that contains the external functions and their descriptions.
<?php
/**
* PLUGIN external file
*
* @package local_PLUGIN
* @copyright 2011 Moodle Pty Ltd (http://moodle.com)
* @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() {
return new external_function_parameters(
array('PARAM1' => new external_value(PARAM_TYPE, 'human description of PARAM1'))
);
}
/**
* The function itself
* @return string welcome message
*/
public static function FUNCTIONNAME($PARAM1) {
//Parameter validation
//REQUIRED
$params = self::validate_parameters(self::FUNCTIONNAME_parameters(),
array('PARAM1' => $PARAM1));
//Context validation
//OPTIONAL but in most web service it should present
$context = get_context_instance(CONTEXT_TYPE, $instanceid);
self::validate_context($context);
//Capability checking
//OPTIONAL but in most web service it should present
if (!has_capability('moodle/xxx:yyy', $context)) {
throw new moodle_exception('cannotrunfunctionname');
}
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.
