|
|
| (15 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| ==Overview==
| | {{Template:Migrated|newDocId=/docs/apis/subsystems/external/functions}} |
| The external functions API allows you to create fully parameterised methods that can be accessed by external programs (such as [[Web services]]).
| |
| | |
| For each external function you must create:
| |
| * FUNCTIONNAME_parameters() which describes the parameters of the functions
| |
| * FUNCTIONNAME() which is the external function itself
| |
| * 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.
| |
| * This file is composed by a class that contains the external functions and their description functions.
| |
| | |
| <code php>
| |
| <?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) {
| |
|
| |
| //Parameter validation
| |
| //REQUIRED
| |
| $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');
| |
| }
| |
| | |
| | |
| | |
| } | |
| </code>
| |
| | |
| To go further, read the [[Creating_a_web_service_and_a_web_service_function|core developer tutorial]].
| |
| | |
| == Example ==
| |
| You will find an example of an external.php file in the [https://github.com/moodlehq/moodle-local_wstemplate 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.
| |
| | |
| ==See also==
| |
| | |
| * [[Core APIs]]
| |
| * [[Web services API]]
| |
| | |
| [[Category:Web_Services]]
| |
