External functions API - Revision history

Devdocsbot: Protected "External functions API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-12-22T06:12:25Z

Protected "External functions API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 06:12, 22 December 2022
(No difference)

Devdocsbot: Update migration status and path

2022-12-22T06:10:42Z

Update migration status and path

← Older revision		Revision as of 06:10, 22 December 2022
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 API]]).~~

	The external functions are located under every component\external\[optional\sub\] namespace (previously in externallib.php files). Each external function is implemented inside an individual 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.~~

	=~~= component\external\something.php ==~~
	* This file is located under the classes/external dir of your plugin (https://docs~~.moodle.org~~/~~dev~~/~~Frankenstyle#Plugin_types). And it's namespaced accordingly.~~
	* This file is composed by a class that contains the external functions and their description functions.

	~~<syntaxhighlight lang="php">~~
	~~<?php~~

	/**
	* PLUGIN external file
	*
	* @package component
	* @category external
	* @copyright 20XX YOURSELF
	* @license http:/~~/www.gnu.org/copyleft/gpl.html GNU GPL v3 or later~~
	*/

	~~defined('MOODLE_INTERNAL') \|\| die();~~

	~~require_once($CFG->libdir . "/externallib.php");~~

	~~class something 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');~~
	}



	}
	~~</syntaxhighlight>~~

	~~To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].~~

	~~== Security ==~~
	Before operating on any data in an external function, you must call external_api::validate_context() on the most specific context for the data. This will perform some sanity and security checks, as well as setup the correct theme, language and filters for rendering content. If your function only uses one context, validate it once at the start of your external function. If your function operates on multiple contexts (like a list of courses), you must validate each context right before generating any response data related to that context (e.g. calling any $OUTPUT functions or $PAGE->get_renderer() ). Do not call require_login from an external function, that function is reserved for php scripts returning a web page. Do not call $PAGE->set_context() manually, this will generate warning notices. validate_context() is the only correct way to write external functions.

	~~Also make sure you pass all arguments through external_api::validate_parameters() before using them to ensure proper cleaning/sanitisation of the input.~~

	~~Also be sure to enforce proper capability checks everywhere - external functions are a public API.~~

	~~== 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]]~~
	~~[[Category:API]]~~

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:33:08Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:33, 14 July 2021
				
Line 12:
Line 12:
* This file is composed by a class that contains the external functions and their description functions. * This file is composed by a class that contains the external functions and their description functions.



<code php> <syntaxhighlight lang="php">
<?php <?php

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:09:20Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:09, 14 July 2021
Line 69:		Line 69:

	}		}
	</~~code~~>		</syntaxhighlight>

	To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].		To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].

Stronk7: /* component\external\something.php */

2020-05-03T17:39:09Z

component\external\something.php

← Older revision		Revision as of 17:39, 3 May 2020
Line 19:		Line 19:
	*		*
	* @package component		* @package component
	* @category. external		* @category external
	* @copyright 20XX YOURSELF		* @copyright 20XX YOURSELF
	* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later		* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Stronk7: tweaks

2020-05-03T17:36:21Z

tweaks

← Older revision		Revision as of 17:36, 3 May 2020
Line 2:		Line 2:
	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 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 under every component\external\ namespace (previously in externallib.php files). Each external function is implemented inside a class and is complemented by two description functions:		The external functions are located under every component\external\[optional\sub\] namespace (previously in externallib.php files). Each external function is implemented inside an individual class and is complemented by two description functions:
	* FUNCTIONNAME_parameters() which describes the parameters of the functions		* FUNCTIONNAME_parameters() which describes the parameters of the functions
	* FUNCTIONNAME_returns() which describes the return value		* FUNCTIONNAME_returns() which describes the return value

Stronk7: MDLSITE-6096 - new location for external function definitions (take II)

2020-05-03T17:33:19Z

MDLSITE-6096 - new location for external function definitions (take II)

← Older revision		Revision as of 17:33, 3 May 2020
Line 18:		Line 18:
	* PLUGIN external file		* PLUGIN external file
	*		*
	* @package ~~local_PLUGIN~~		* @package component
			* @category. external
	* @copyright 20XX YOURSELF		* @copyright 20XX YOURSELF
	* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later		* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Line 27:		Line 28:
	require_once($CFG->libdir . "/externallib.php");		require_once($CFG->libdir . "/externallib.php");

	class ~~local_PLUGIN_external~~ extends external_api {		class something extends external_api {

	/**		/**

Stronk7: MDLSITE-6096 - new location for external function definitions

2020-05-03T17:31:55Z

MDLSITE-6096 - new location for external function definitions

Damyon at 02:18, 12 April 2016

2016-04-12T02:18:46Z

← Older revision		Revision as of 02:18, 12 April 2016
Line 68:		Line 68:

	To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].		To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].

			== Security ==
			Before operating on any data in an external function, you must call external_api::validate_context() on the most specific context for the data. This will perform some sanity and security checks, as well as setup the correct theme, language and filters for rendering content. If your function only uses one context, validate it once at the start of your external function. If your function operates on multiple contexts (like a list of courses), you must validate each context right before generating any response data related to that context (e.g. calling any $OUTPUT functions or $PAGE->get_renderer() ). Do not call require_login from an external function, that function is reserved for php scripts returning a web page. Do not call $PAGE->set_context() manually, this will generate warning notices. validate_context() is the only correct way to write external functions.

			Also make sure you pass all arguments through external_api::validate_parameters() before using them to ensure proper cleaning/sanitisation of the input.

			Also be sure to enforce proper capability checks everywhere - external functions are a public API.

	== Example ==		== Example ==

Dougiamas: /* externallib.php */

2012-01-25T08:57:05Z

externallib.php

← Older revision		Revision as of 08:57, 25 January 2012
Line 67:		Line 67:
	</code>		</code>

	To go further, read ~~the~~ [[Creating_a_web_service_and_a_web_service_function~~\|core developer tutorial~~]].		To go further, read this core developer tutorial: [[Creating_a_web_service_and_a_web_service_function]].

	== Example ==		== Example ==

← Older revision		Revision as of 13:33, 14 July 2021
Line 12:		Line 12:
	* This file is composed by a class that contains the external functions and their description functions.		* This file is composed by a class that contains the external functions and their description functions.

	<~~code~~ php>		<syntaxhighlight lang="php">
	<?php		<?php

← Older revision		Revision as of 17:31, 3 May 2020
Line 2:		Line 2:
	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 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:		The external functions are located under every component\external\ namespace (previously 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_parameters() which describes the parameters of the functions
	* FUNCTIONNAME_returns() which describes the return value		* FUNCTIONNAME_returns() which describes the return value
Line 8:		Line 8:
	The description functions uses external_description classes that have been created for this purpose.		The description functions uses external_description classes that have been created for this purpose.

	== ~~externallib~~.php ==		== component\external\something.php ==
	* This file is located at the ~~root~~ of your plugin (https://docs.moodle.org/dev/Frankenstyle#Plugin_types).		* This file is located under the classes/external dir of your plugin (https://docs.moodle.org/dev/Frankenstyle#Plugin_types). And it's namespaced accordingly.
	* This file is composed by a class that contains the external functions and their description functions.		* This file is composed by a class that contains the external functions and their description functions.

Line 22:		Line 22:
	* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later		* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
	*/		*/

			defined('MOODLE_INTERNAL') \|\| die();

	require_once($CFG->libdir . "/externallib.php");		require_once($CFG->libdir . "/externallib.php");