{{Moodle 3.3}}Moodle exporters are classes which receive data and serialise it to a simple pre-defined structure. They ensure that the format of the data exported is uniform and easily maintainable. They are also used to generate the signature (parameters and return values) of [[External functions API|external functions]].

== Introduction ==

When dealing with external functions (Ajax, web services, ...) and rendering methods we often hit a situation where the same object is used, and exported, from multiple places. When that situation arises, the code that serialises our objects gets duplicated, or becomes inconsistent.

We made the exporters to remedy to this situation. An exporter clearly defines what data it exports, and contains the logic which transform the incoming data into the exported data. As it knows everything, it can generate the structure required by external functions automatically.

This means that not only developers have less code to maintain, but they also have a more robust structure which can easily evolve with their needs. If a new property needs to be exported, it is simply added to the exporter class, and automatically all usage of the exporter inherits this added property.

== Defining properties ==

The method ''define_properties()'' returns a list of the properties expected for the incoming data, and for the exported data. This also means that to create (or update) you will require those properties.

<code php>
/**
* Return the list of properties.
*
* @return array
*/
protected static function define_properties() {
return array(
'id' => array(
'type' => PARAM_INT
),
'username' => array(
'type' => PARAM_ALPHANUMEXT
),
);
}
</code>

=== Property attributes ===

Each property is configured using the following attributes:

;type
: The only mandatory attribute. It must either be one of the many PARAM_* constants, or an array of properties.
;default
: The default value when the value was not provided. When not specified, a value is required.
;null
: Either of the constants NULL_ALLOWED or NULL_NOT_ALLOWED telling if the null value is accepted. This defaults to NULL_NOT_ALLOWED.
;optional
: Whether the property can be omitted completely. Defaults to false.
;multiple
: Whether there will be more one or more entries under this property. Defaults to false.

Although this is not a ''rule'', it is recommended that the ''standard properties'' (by opposition to [[#Additional_properties|additional properties]]) only use the ''type'' [[#Property_attributes|attribute]], and only with ''PARAM_*'' constants.

== Using an exporter ==

Once we've got a [[#Minimalist|minimalist exporter]] set-up, here is how to use it.

=== Exporting the data ===

<code php>
$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);
</code>

If we print the content of ''$data'', we will obtain this:

<code>
stdClass Object
(
[id] => 123
[username] => batman
)
</code>

Now, I agree that this is not quite impressive. But wait until you read about [[#Abiding_to_text_formatting_rules|automatically formatting text]], and [[#In_external_functions|usage in external functions]].

=== In external functions ===

Let's imagine that we have an external function ''get_users'' which returns a list of users. For now we only want to export the user ID and their user name, so we'll use our exporter. Let's ask our exporter to create the external structure for us:

<code php>
public static function get_users_returns() {
return external_multiple_structure(
user_exporter::get_read_structure()
);
}
</code>

Now that this is done, we must use our exporter to export our users' data.

<code php>
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;
}
</code>

Lastly, if you had another external function to create users, you could use the exporter to get the structure of the incoming data. That helps if you want your external functions to require more information to create your ''users'' as your needs grow. The following indicates that the external function requires the fields 'id' and 'username' to be passed in the key 'user'.

<code php>
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'];
...
}
</code>

Important note: when used in the ''parameters'', the exporter's structure must always be included under another key, above we used ''user''. Else this would not flexible, and may not generate a valid structure for some protocols. You should also checkout ''get_update_structure()'' which is essentially the same except that it does requires an ''ID''.

== Abiding to text formatting rules ==

If we had to pass the ''$OUTPUT'' during export as seen previously, that is because we are handling the text formatting automatically for you. Remember the functions ''format_text()'' and ''format_string()''? They are used to apply [[Filters|filters]] on the content typically submitted by users, but also to convert it from a few given formats to HTML.

Upon export, the exporter looks at the ''type'' of all your properties. When it finds a property of type ''PARAM_TEXT'', it will use ''format_string()''. However, if it finds a property using ''PARAM_RAW'' and there is another property of the same name but ending with ''format'' it will use ''format_text()''.

<code php>
'description' => array(
'type' => PARAM_RAW,
),
'descriptionformat' => array(
'type' => PARAM_INT,
),
</code>

With the two above properties (not [[#Additional_properties|other properties]]) added, let's see what happens when the user's description is in the Markdown format and we export it.

<code php>
$data = (object) [
'id' => 123,
'username' => 'batman',
'description' => 'Hello __world__!',
'descriptionformat' => FORMAT_MARKDOWN
];
$ue = new user_exporter($data);
$data = $ue->export($OUTPUT);
</code>

Unsurprisingly, this is what comes out of it:

<code>
stdClass Object
(
[id] => 123
[username] => batman
[description] => Hello world!
[descriptionformat] => 1 // Corresponds to FORMAT_HTML.
)
</code>

Psst... If you're wondering where we get the ''context'' from, look at [[#Related_objects|related objects]].

== Additional properties ==

The list of ''other'' properties are to be seen as ''additional'' properties which do not need to be given to the exporter for it to export them. They are dynamically generated from the data provided (and the [[#Related objects|related objects]], more on that later). For example, if we wanted our exporter to provide the URL to a user's profile, we wouldn't need the developer to pass it beforehand, we could generate it based on the ID which was already provided.

''Other'' properties are only included in the ''read'' structure of an object (''get_read_structure'' and ''read_properties_definition'') as they are dynamically generated. They are not required, nor needed, to ''create'' or ''update'' an object.

<code php>
/**
* 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
),
);
}
</code>

The snippet above defines that we will always export a URL under the property ''profileurl'', and that we will either export a list of ''status_exporters'', or not. As you can see, the ''type'' can use the ''read'' properties of another exporter which allows exporters to be nested.

If you have defined ''other'' properties, then you must also add the logic to export them. This is done by adding the method ''get_other_values(renderer_base $output)'' to your exporter. Here is an example in which we ignored the ''statuses'' as they are optional.

<code php>
/**
* 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)
];
}
</code>

== Related objects ==

There are times we need more information inside the exporter in order to export it. That may be as simple as the ''context'', but it can also be other objects to be used when exporting ''other'' properties.

Related objects need to be defined within the exporter, that is to ensure that they are always provided and are of the right type. In some occasions they can be marked as optional, generally when the related object does not exist. For instance, if we had an issue exporter, an optional related object could be the peer reviewer, as we don't always have a peer reviewer.

Use the method ''protected static define_related()'' as follows. The keys are an arbitrary name for the related object, and the values are the fully qualified name of the class. The name of the class can be followed by ''[]'' and/or ''?'' to respectively indicate a list of these objects, and an optional related.

<code php>
/**
* Returns a list of objects that are related.
*
* @return array
*/
protected static function define_related() {
return array(
'context' => 'context',
'statuses' => 'some\\namespace\\status[]',
'mother' => 'family\\mother?',
'brothers' => 'family\\brother[]?',
);
}
</code>

We give the related objects to the ''exporter'' when we instantiate it, like this:

<code php>
$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);
</code>

Note that optional related must still be provided but as ''null''.

== Common pitfalls ==

# Exporters must not extend other exporters. They would become too unpredictable.
# Exporters do not validate your data. They use the properties' attributes to generate the structure required by the [[External functions API]], the latter is responsible for using the structure to validate the data.
# When exporters are nested, the ''type'' to use should be ''other_exporter::read_properties_definition()'' and not ''other_exporter::get_read_structure()''.

== Examples ==

=== Minimalist ===

<code php>
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
),
);
}

}
</code>

=== More advanced ===

<code php>
namespace example\external;

use core\external\exporter;
use renderer_base;
use moodle_url;

class user_exporter extends 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
),
'description' => array(
'type' => PARAM_RAW,
),
'descriptionformat' => array(
'type' => PARAM_INT,
),
);
}

/**
* 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
),
);
}

/**
* Returns a list of objects that are related.
*
* @return array
*/
protected static function define_related() {
return array(
'context' => 'context',
'statuses' => 'some\\namespace\\status[]',
);
}

/**
* 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) {
$statuses = [];
foreach ($this->related['statuses'] as $status) {
$exporter = new status_exporter($status);
$statuses[] = $exporter->export($output);
}

$profileurl = new moodle_url('/user/profile.php', ['id' => $this->data->id]);

return [
'profileurl' => $profileurl->out(false),
'statuses' => $statuses
];
}
}
</code>

User:Frédéric Massart

2016-12-14T09:26:38Z

Fmcorz:

{{Moodle 3.3}}Moodle exporters are classes which receive data and serialise it to a simple pre-defined structure. They ensure that the format of the data exported is uniform and easily maintainable. They are also used to generate the signature (parameters and return values) of [[External functions API|external functions]].

== Introduction ==

When dealing with external functions (Ajax, web services, ...) and rendering methods we often hit a situation where the same object is used, and exported, from multiple places. When that situation arises, the code that serialises our objects gets duplicated, or becomes inconsistent.

We made the exporters to remedy to this situation. An exporter clearly defines what data it exports, and contains the logic which transform the incoming data into the exported data. As it knows everything, it can generate the structure required by external functions automatically.

This means that not only developers have less code to maintain, but they also have a more robust structure which can easily evolve with their needs. If a new property needs to be exported, it is simply added to the exporter class, and automatically all usage of the exporter inherits this added property.

== Defining properties ==

The method ''define_properties()'' returns a list of the properties expected for the incoming data, and for the exported data. This also means that to create (or update) you will require those properties.

<code php>
/**
* Return the list of properties.
*
* @return array
*/
protected static function define_properties() {
return array(
'id' => array(
'type' => PARAM_INT
),
'username' => array(
'type' => PARAM_ALPHANUMEXT
),
);
}
</code>

=== Property attributes ===

Each property is configured using the following attributes:

;type
: The only mandatory attribute. It must either be one of the many PARAM_* constants, or an array of properties.
;default
: The default value when the value was not provided. When not specified, a value is required.
;null
: Either of the constants NULL_ALLOWED or NULL_NOT_ALLOWED telling if the null value is accepted. This defaults to NULL_NOT_ALLOWED.
;optional
: Whether the property can be omitted completely. Defaults to false.
;multiple
; Whether there will be more one or more entries under this property. Defaults to false.

Although this is not a ''rule'', it is recommended that the ''standard properties'' (by opposition to [[#Additional_properties|additional properties]]) only use the ''type'' [[#Property_attributes|attribute]], and only with ''PARAM_*'' constants.

== Using an exporter ==

Once we've got a [[#Minimalist|minimalist exporter]] set-up, here is how to use it.

=== Exporting the data ===

<code php>
$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);
</code>

If we print the content of ''$data'', we will obtain this:

<code>
stdClass Object
(
[id] => 123
[username] => batman
)
</code>

Now, I agree that this is not quite impressive. But wait until you read about [[#Abiding_to_text_formatting_rules|automatically formatting text]], and [[#In_external_functions|usage in external functions]].

=== In external functions ===

Let's imagine that we have an external function ''get_users'' which returns a list of users. For now we only want to export the user ID and their user name, so we'll use our exporter. Let's ask our exporter to create the external structure for us:

<code php>
public static function get_users_returns() {
return external_multiple_structure(
user_exporter::get_read_structure()
);
}
</code>

Now that this is done, we must use our exporter to export our users' data.

<code php>
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;
}
</code>

Lastly, if you had another external function to create users, you could use the exporter to get the structure of the incoming data. That helps if you want your external functions to require more information to create your ''users'' as your needs grow. The following indicates that the external function requires the fields 'id' and 'username' to be passed in the key 'user'.

<code php>
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'];
...
}
</code>

Important note: when used in the ''parameters'', the exporter's structure must always be included under another key, above we used ''user''. Else this would not flexible, and may not generate a valid structure for some protocols. You should also checkout ''get_update_structure()'' which is essentially the same except that it does requires an ''ID''.

== Abiding to text formatting rules ==

If we had to pass the ''$OUTPUT'' during export as seen previously, that is because we are handling the text formatting automatically for you. Remember the functions ''format_text()'' and ''format_string()''? They are used to apply [[Filters|filters]] on the content typically submitted by users, but also to convert it from a few given formats to HTML.

Upon export, the exporter looks at the ''type'' of all your properties. When it finds a property of type ''PARAM_TEXT'', it will use ''format_string()''. However, if it finds a property using ''PARAM_RAW'' and there is another property of the same name but ending with ''format'' it will use ''format_text()''.

<code php>
'description' => array(
'type' => PARAM_RAW,
),
'descriptionformat' => array(
'type' => PARAM_INT,
),
</code>

With the two above properties (not [[#Additional_properties|other properties]]) added, let's see what happens when the user's description is in the Markdown format and we export it.

<code php>
$data = (object) [
'id' => 123,
'username' => 'batman',
'description' => 'Hello __world__!',
'descriptionformat' => FORMAT_MARKDOWN
];
$ue = new user_exporter($data);
$data = $ue->export($OUTPUT);
</code>

Unsurprisingly, this is what comes out of it:

<code>
stdClass Object
(
[id] => 123
[username] => batman
[description] => Hello world!
[descriptionformat] => 1 // Corresponds to FORMAT_HTML.
)
</code>

Psst... If you're wondering where we get the ''context'' from, look at [[#Related_objects|related objects]].

== Additional properties ==

The list of ''other'' properties are to be seen as ''additional'' properties which do not need to be given to the exporter for it to export them. They are dynamically generated from the data provided (and the [[#Related objects|related objects]], more on that later). For example, if we wanted our exporter to provide the URL to a user's profile, we wouldn't need the developer to pass it beforehand, we could generate it based on the ID which was already provided.

''Other'' properties are only included in the ''read'' structure of an object (''get_read_structure'' and ''read_properties_definition'') as they are dynamically generated. They are not required, nor needed, to ''create'' or ''update'' an object.

<code php>
/**
* 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
),
);
}
</code>

The snippet above defines that we will always export a URL under the property ''profileurl'', and that we will either export a list of ''status_exporters'', or not. As you can see, the ''type'' can use the ''read'' properties of another exporter which allows exporters to be nested.

If you have defined ''other'' properties, then you must also add the logic to export them. This is done by adding the method ''get_other_values(renderer_base $output)'' to your exporter. Here is an example in which we ignored the ''statuses'' as they are optional.

<code php>
/**
* 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)
];
}
</code>

== Related objects ==

There are times we need more information inside the exporter in order to export it. That may be as simple as the ''context'', but it can also be other objects to be used when exporting ''other'' properties.

Related objects need to be defined within the exporter, that is to ensure that they are always provided and are of the right type. In some occasions they can be marked as optional, generally when the related object does not exist. For instance, if we had an issue exporter, an optional related object could be the peer reviewer, as we don't always have a peer reviewer.

Use the method ''protected static define_related()'' as follows. The keys are an arbitrary name for the related object, and the values are the fully qualified name of the class. The name of the class can be followed by ''[]'' and/or ''?'' to respectively indicate a list of these objects, and an optional related.

<code php>
/**
* Returns a list of objects that are related.
*
* @return array
*/
protected static function define_related() {
return array(
'context' => 'context',
'statuses' => 'some\\namespace\\status[]',
'mother' => 'family\\mother?',
'brothers' => 'family\\brother[]?',
);
}
</code>

We give the related objects to the ''exporter'' when we instantiate it, like this:

<code php>
$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);
</code>

Note that optional related must still be provided but as ''null''.

== Common pitfalls ==

# Exporters must not extend other exporters. They would become too unpredictable.
# Exporters do not validate your data. They use the properties' attributes to generate the structure required by the [[External functions API]], the latter is responsible for using the structure to validate the data.
# When exporters are nested, the ''type'' to use should be ''other_exporter::read_properties_definition()'' and not ''other_exporter::get_read_structure()''.

== Examples ==

=== Minimalist ===

<code php>
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
),
);
}

}
</code>

=== More advanced ===

<code php>
namespace example\external;

use core\external\exporter;
use renderer_base;
use moodle_url;

class user_exporter extends 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
),
'description' => array(
'type' => PARAM_RAW,
),
'descriptionformat' => array(
'type' => PARAM_INT,
),
);
}

/**
* 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
),
);
}

/**
* Returns a list of objects that are related.
*
* @return array
*/
protected static function define_related() {
return array(
'context' => 'context',
'statuses' => 'some\\namespace\\status[]',
);
}

/**
* 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) {
$statuses = [];
foreach ($this->related['statuses'] as $status) {
$exporter = new status_exporter($status);
$statuses[] = $exporter->export($output);
}

$profileurl = new moodle_url('/user/profile.php', ['id' => $this->data->id]);

return [
'profileurl' => $profileurl->out(false),
'statuses' => $statuses
];
}
}
</code>

User:Frédéric Massart

2016-12-14T08:15:50Z

Fmcorz: