exporter API（导出、输出器api）moodel3.3
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服务协议生成有效的结构
