Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

External functions API

From MoodleDocs

Overview

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.

<?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');
   }


}

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.

See also