Moodle【导出器】是接收数据并将其序列化为一个简单的预定义结构的类。它们确保输出的数据格式统一，易于维护。它们也用于生成外部函数的签名（参数和返回值）
外部函数定义在moodle/lib/externallib.php
在处理外部函数（Ajax，Web服务，...）和渲染方法时，我们经常遇到同一个对象被使用并从多个位置输出的情况。当这种情况出现时，我们的对象的代码会被重复序列化，或者变得不一致我们用【导出器】来解决这个问题，它清楚地定义了它输出的数据，并包含将输入数据转换成输出数据的逻辑，它可以自动生成外部函数所需的结构，如果需要导出新属性，则只需将其添加到导出器类中，并且【导出器】的所有用法都会自动继承此添加的属性
基类被定义在：moodle33\lib\classes\external\exporter.php
protected $related 用于避免DB查询的相关对象的列表
protected $data 这个输出器的数据 （值：stdClass|array）
//保存持久对象和相关对象
public function __construct($data, $related = array())
//函数以适合于mustache模板的格式导出渲染器数据。这意味着原始记录是在to_record中生成的,但是，所有的字符串都是通过外部格式文本(或外部格式字符串)正确地传递的
final public function export(renderer_base $output)
//函数猜测正确的上下文，返回到系统上下文
protected function get_context()
//在导出时获得附加的值
protected function get_other_values(renderer_base $output)
//获取此导出器的读取属性定义。 Read属性将模型（persistent或stdClass）的默认属性与{@link self :: define_other_properties（）}定义的属性相结合
final public static function read_properties_definition()
//获取用于创建和更新结构的导出器的属性定义,读取结构由以下方式返回：{@link self :: read_properties_definition（）}
final public static function properties_definition()
//返回仅用于显示的附加属性列表
protected static function define_other_properties()
//返回属性列表。返回实例化导出器时所需的属性列表，以及它将同时导出的属性列表
protected static function define_properties()
//返回与此持久性相关的对象列表,只有在这里列出的对象可以缓存在这个对象中
protected static function define_related()
//获取上下文结构
final protected static function get_context_structure()
//获取格式字段名
final protected static function get_format_field($definitions, $property)
//得到结构格式
final protected static function get_format_structure($property, $definition, $required = VALUE_REQUIRED)
//返回创建的结构
final public static function get_create_structure()
//返回读取的结构
final public static function get_read_structure()
//从一组属性(递归)返回读取结构
final protected static function get_read_structure_from_properties($properties, $required = VALUE_REQUIRED, $default = null)
//返回更新的结构
final public static function get_update_structure()
定义属性
define_properties（）方法返回实例化导出器时所需的属性列表，以及它将同时导出的属性列表
protected static function define_properties() {
return array(
'id' => array(
'type' => PARAM_INT
),
'username' => array(
'type' => PARAM_ALPHANUMEXT
),
);
}
这些属性将允许我们为外部函数生成一个创建或更新结构，稍后再介绍。
哦，如果你使用持久性，你不需要这样做：瞧瞧这个-导出和持久。
如果你有一个持续的，你想要导出输出，所有的工作已经完成了。如果扩展class core\external\persistent_exporter，并添加方法define_class()，则所有持久性属性将自动添加到导出器
class status_exporter extends \core\external\persistent_exporter {
/**
* Returns the specific class the persistent should be an instance of.
*
* @return string
*/
protected static function define_class() {
return \some\namespace\status::class; // PHP 5.5+ only
}
}
属性特性
每个属性都使用以下属性进行配置：
- type
- 唯一的强制性属性。它必须是许多PARAM_ *常量之一，或者是一组属性。
- default
- 未提供值时的默认值。未指定时，需要一个值。
- null
- 无论是常量NULL_ALLOWED还是NULL_NOT_ALLOWED，都会告知是否接受空值。这个默认为NULL_NOT_ALLOWED。
- optional
- 该财产是否可以完全省略。默认为false。
- multiple
- 这个属性是否会有更多的条目。默认为false。
尽管这不是一个规则，但建议标准属性（通过与附加属性相反）仅使用上面的type属性，并且只使用PARAM_ *常量。
附加属性：
附加属性的列表被视为额外的属性，不需要给导出器输出它们。它们是从提供的数据（以及相关的对象，后面会详细介绍）中动态生成的。例如，如果我们希望我们的导出器将URL提供给用户的配置文件，我们不需要开发者事先传递它，我们可以基于已经提供的ID生成它。
附加属性只包含在对象的读取结构（get_read_structure和read_properties_definition）中，因为它们是动态生成的。不需要也不需要创建或更新对象
/**
* Return the list of additional properties. * @return array
*/
protected static function define_other_properties() {
return array(
'profileurl' => array(
'type' => PARAM_URL
),
'statuses' => array(
'type' => status_exporter::read_properties_definition(),
'multiple' => true,
'optional' => true
),
);
}
上面的代码片段定义了我们将始终在属性profileurl下导出一个URL ，并且我们将导出或不导出status_exporters的列表。正如你所看到的，这个类型可以使用另一个导出器的读取属性，它允许导出器被嵌套。
如果您定义了其他属性，则还必须添加逻辑来导出它们。这是通过将get_other_values（renderer_base $ output）方法添加到导出器来完成的。这是一个我们忽略状态的例子，因为它们是可选的
/**
* Get the additional values to inject while exporting.
*
* @param renderer_base $output The renderer.
* @return array Keys are the property names, values are their values.
*/
protected function get_other_values(renderer_base $output) {
$profileurl = new moodle_url('/user/profile.php', ['id' => $this->data->id]);
return [
'profileurl' => $profileurl->out(false)
];
}
重要说明：其他属性不能覆盖标准属性，所以请确保名称不冲突。
相关的对象
有时我们需要出口商内部的更多信息来导出。这可能与上下文一样简单，但在导出其他属性时也可以使用其他对象。尽可能避免调用API，或者在导出时查询数据库。出口商可以在循环中使用，因此后续查询可能会显着影响性能，因此需要相关的对象。
相关对象需要在出口商内部进行定义，即确保它们总是被提供并且是正确的类型。在一些情况下，通常当相关对象不存在时，它们可以被标记为可选的。例如，如果我们有一个问题导出器，可选的相关对象可能是同行评审者，因为我们并不总是有同行评审者。
使用方法protected static define_related（），如下所示。键是相关对象的任意名称，值是该类的完全限定名称。班级名称后面可以跟[]和/或？分别表示这些对象的列表，以及一个可选的相关内容
/**
* Returns a list of objects that are related.
*
* @return array
*/
protected static function define_related() {
return array(
'context' => 'context', // Must be an instance of context.
'statuses' => 'some\\namespace\\status[]', // Must be an array of status instances.
'mother' => 'family\\mother?', // Can be a mother instance, or null.
'brothers' => 'family\\brother[]?', // Can be null, or an array of brother instances.
);
}
实例化时，我们将相关的对象给导出者，如下所示：
$data = (object) ['id' => 123, 'username' => 'batman'];
$relateds = [
'context' => context_system::instance(),
'statuses' => [
new some\namespace\status('Hello'),
new some\namespace\status('World!'),
],
'mother' => null,
'brothers' => null
];
$ue = new user_exporter($data, $relateds);
使用导出器
一旦我们有一个简约的出口商设置，这里是如何使用它。
class user_exporter extends core\external\exporter {
/**
* Return the list of properties.
*
* @return array
*/
protected static function define_properties() {
return array(
'id' => array(
'type' => PARAM_INT
),
'username' => array(
'type' => PARAM_ALPHANUMEXT
),
);
}
}
导出数据
$data = (object) ['id' => 123, 'username' => 'batman']; // The only time we can give data to our exporter is when instantiating it.
$ue = new user_exporter($data); // To export, we must pass the reference to a renderer.
$data = $ue->export($OUTPUT);
如果我们打印$data的内容，我们将获得这个：
stdClass对象
（
[id] => 123
[username] =>蝙蝠侠
）
现在，我同意这并不令人印象深刻。但是等到你阅读了关于自动格式化文本①，以及在外部函数中的使用②。
①遵守文本格式规则： 如果我们在导出过程中必须通过$OUTPUT，那是因为我们正在为您自动处理文本格式。记住函数format_text（）和format_string（）？它们被用来对用户通常提交的内容应用过滤器，还可以将其从一些给定的格式转换为HTML。
导出时，导出器会查看所有属性的类型。当它找到PARAM_TEXT类型的属性时，它将使用format_string（）。但是，如果使用PARAM_RAW找到一个属性，并且存在另一个同名的属性，但以format结尾，则将使用format_text（）。如果您不熟悉在Moodle中输出文本的规则，请参阅输出函数和最常用的PARAM_ *类型
'description' => array(
'type' => PARAM_RAW,
),
'descriptionformat' => array(
'type' => PARAM_INT,
),
添加上面的两个属性，让我们看看当用户的描述是以Markdown格式，然后导出它时会发生什么
$data = (object) [
'id' => 123,
'username' => 'batman',
'description' => 'Hello __world__!',
'descriptionformat' => FORMAT_MARKDOWN
];
$ue = new user_exporter($data, ['context' => context_user::instance(123)]);
$data = $ue->export($OUTPUT);
不出所料，这就是它出来的结果：
stdClass Object
(
[id] => 123
[username] => 蝙蝠侠
[description] => <p>Hello <strong>world</strong>!</p>
[descriptionformat] => 1 // Corresponds to FORMAT_HTML.
)
Psst ...我们已经在上面作弊了。你有没有注意到我们已经通过了导出器的上下文？我们通过了一个相关的对象。
②外部函数里
假设我们有一个外部函数get_users，它返回一个用户列表。现在我们只想导出用户ID和他们的用户名，所以我们将使用我们的导出器。我们要求我们的导出器为我们创造外部结构：
public static function get_users_returns() {
return external_multiple_structure(
user_exporter::get_read_structure()
);
}
现在这样做了，我们必须使用我们的导出器来导出我们用户的数据
public static function get_users() {
global $DB, $PAGE;
$output = $PAGE->get_renderer('core');
$users = $DB->get_records('user', null, '', 'id, username', 0, 10); // Get 10 users.
$result = [];
foreach ($users as $userdata) {
$exporter = new user_exporter($userdata);
$result[] = $exporter->export($output);
}
return $result;
}
最后，如果您有另一个外部函数来创建用户，则可以使用导出器来获取传入数据的结构。如果你希望你的外部函数需要更多的信息来创建你的用户，这将有助于你的需求的增长。以下表示外部函数需要字段“username”在通过键“user”中传递。在创建和更新结构，包括所有的标准性能，而不是其他的附加属性。请注意，创建结构不包括id属性。使用user_exporter :: get_update_structure（）是否更新用户，从而接收ID。
public static function create_user_parameters() {
return new external_function_parameters([
'user' => user_exporter::get_create_structure()
]);
}
public static function create_user($user) {
// Mandatory parameters validation.
$params = self::validate_parameters(self::create_user_parameters(), ['user' => $user]);
$user = $params['user'];
...
}
重要提示：在参数中使用时，导出器的结构必须总是被包含在另一个关键字的下方，高于我们所使用的用户。否则这将不会灵活，并且可能不会为某些Web服务协议生成有效的结构