external function/external

Defined in moodle/lib/externallib.php

Overview

The external function API allows you to create fully parameterized methods that can be accessed by external programs such as a web service API .

External functions are located in the externallib.php file. Each external function is implemented in a class, supplemented by two description functions:

• FUNCTIONNAME_parameters() describes the parameters of the function
• FUNCTIONNAME_returns() describes the return value

The describe function uses the external_description class created for this purpose.

externallib.php

• This file is located in the root directory of the plugin ( https://docs.moodle.org/dev/Frankenstyle#Plugin_types ). Such as: moodle\calendar\externallib.php
• The file consists of classes that contain 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 a description of the method parameters
      * @return external_function_parameters */ 
     public static function FUNCTIONNAME_parameters() {
         // FUNCTIONNAME_parameters() always returns an external_function_parameters() .
       
        // external_function_parameters constructor expects an external_description array. 
        return  new external_function_parameters(
                 // external_description can be: external_value, external_single_structure or external_multiple structure 
                array ('PARAM1' => new external_value(PARAM_TYPE, 'human description of PARAM1' ))
        );
    }
    / **
     * function itself
      * @return string welcome message
      */ 
     public  static  function FUNCTIONNAME( $PARAM1 ) {
 
        // Parameter validation 
        $params = self::validate_parameters(self::FUNCTIONNAME_parameters(),
                 array ('PARAM1' => $PARAM1 ));
 
        // NOTE: don't forget to validate the context and check the functionality
 
        return $returnedvalue;
    }
 
    / **
     * Description of return method result value
      * @ return external_description
      */ 
     public  static  function FUNCTIONNAME_returns() {
         return  new external_value(PARAM_TYPE, 'human description of the returned value' );
    }
 
 
 
}

 

To read further this core developer tutorial: Creating_a_web_service_and_a_web_service_function .

Safety

Before operating on any data in the external function, external_api::validate_context() must be called in the context most specific to the data. This will perform some sanity and safety checks, as well as set the correct theme, language and filters for the rendered content. If your function only uses one context, verify once when your outer function starts. If your function operates on multiple contexts (such as a course list), each context must be validated before generating any response data related to that context (such as calling any $OUTPUT functions or $PAGE->get_renderer() ). Do not call require_login from an external function, which is reserved for PHP scripts to return a web page. Do not call $PAGE->set_context() manually, this will generate a warning notice.

Also make sure to pass all parameters before using external_api::validate_parameters() to ensure input is properly sanitized.

Also make sure to perform proper function checks everywhere - the external function is a public API.

example

You will find an example of the external.php file in the Web Service Templates plugin . This plugin contains a web service hello_world function. To make testing easy, the plugin will be distributed with the test client in the folder /client