外部函数/external

定义在moodle/lib/externallib.php

概观

外部函数API允许您创建可由外部程序（如Web服务API）访问的完全参数化的方法。

外部函数位于externallib.php文件中。每个外部函数都是在一个类中实现的，并辅之以两个描述函数：

• FUNCTIONNAME_parameters（）描述函数的参数
• FUNCTIONNAME_returns（）描述了返回值

描述函数使用为此目的而创建的external_description类。

externallib.php

• 该文件位于插件的根目录（https://docs.moodle.org/dev/Frankenstyle#Plugin_types）。如：moodle\calendar\externallib.php
• 该文件由包含外部函数及其描述函数的类组成。

<？PHP

/ **
 * PLUGIN外部文件
 *
 * @package local_PLUGIN
 * @copyright 20XX YOURSELF
 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3或更高版本
 * /
require_once($CFG->libdir . "/externallib.php");

class local_PLUGIN_external extends external_api {

    / **
     *返回方法参数的描述
     * @return external_function_parameters
     * /
    public static function FUNCTIONNAME_parameters() {
        // FUNCTIONNAME_parameters（）总是返回一个external_function_parameters（）。
        // external_function_parameters构造函数需要一个external_description数组。
        return new external_function_parameters(
                // external_description可以是：external_value，external_single_structure或external_multiple结构
                array('PARAM1' => new external_value(PARAM_TYPE, 'human description of PARAM1'))
        );
    }
    / **
     *功能本身
     * @返回字符串欢迎消息
     * /
    public static function FUNCTIONNAME($PARAM1) {

        //参数验证
        $params = self::validate_parameters(self::FUNCTIONNAME_parameters(),
                array('PARAM1' => $PARAM1));

        //注意：不要忘记验证上下文并检查功能

        return $returnedvalue;
    }

    / **
     *返回方法结果值的描述
     * @return external_description
     * /
    public static function FUNCTIONNAME_returns() {
        return new external_value(PARAM_TYPE, 'human description of the returned value');
    }

}

要进一步阅读这个核心开发者教程：Creating_a_web_service_and_a_web_service_function。

安全

在对外部函数中的任何数据进行操作之前，必须在数据最具体的上下文中调用external_api::validate_context()。这将执行一些理智和安全检查，以及为渲染内容设置正确的主题，语言和过滤器。如果你的函数只使用一个上下文，在你的外部函数启动时验证一次。如果您的函数在多个上下文（如课程列表）上运行，则必须在生成与该上下文相关的任何响应数据（例如调用任何 $OUTPUT 函数或$PAGE->get_renderer()）之前验证每个上下文。不要从外部函数调用require_login，该函数是为PHP脚本返回一个网页保留的。不要手动调用 $PAGE->set_context()，这会产生警告通知。

还要确保在使用external_api::validate_parameters()之前传递所有参数，以确保正确清理输入。

还要确保在任何地方执行适当的功能检查 - 外部功能是一个公共API。

例

您将在Web服务模板插件中找到external.php文件的示例。这个插件包含一个web服务hello_world函数。为了使测试变得容易，插件将在文件夹/客户端中与测试客户端一起分发