Manual:Extension data

Work in progress

Extension data (ExtensionData) are small pieces of arbitrary data that an extension can add to, and later retrieve from, the ParserOutput . For instance, you can use it to register metadata around the use of your parser function on a page. Then when a hook is called for special pre-processing of the page output, it allows you to check for any metadata that might be relevant.

Extension data are now intended as an alternative to destructive updates in the ParserOutput and to the use of dynamic properties.

Methods

Setters

ParserOutput comes with two relevant setters:

• ParserOutput::setExtensionData( $key, $value ) - lets you assign a key-value pair to the array.
  • The value can be data of any type.
  • A special restriction is that the value is expected to remain stable: you should not attempt to modify or reset the value previously stored under a key. While it is still possible to do so, this approach is deprecated and later versions of MediaWiki will give a warning and ultimately remove support for it.
• ParserOutput::appendExtensionData( $key, $value ) (since MW 1.38) - lets you use keys to attach extension data to the ParserOutput and lets you merge multiple pieces of data by reusing the method under the same key.
  • The $value is stored as an array key. This means that the value must be either a value or integer and it must be suitable for re-use as an array key, which imposes some restrictions on the characters you can use.

Getter

• ParserOutput::getExtensionData() - lets you retrieve data by key. The result returned, if not null, depends on the setter method you used, appendExtensionData() or setExtensionData(), for which see above.

Caching and storage

Extension data are cached along with the ParserOutput object. Unlike page properties, they are not recorded in the database.

Examples

Simple example

Say you have written a parser function and need to use a MediaWiki hook to do some processing on the parser only if the parser function is used any number of times. In the code for your parser function, you could have something like:

$parserOutput = $parser->getOutput();
$parserOutput->appendExtensionData( "myextension", "my-parser-function" );

Then when the hook is called, you can create a condition:

$myExtData = $parser->getOutput()->getExtensionData( "myextension" );
if ( $myExtData !== null && array_key_exists( "my-parser-function", $myExtData ) ) {
   $counter = $myExtData["my-parser-function"];
   // do stuff
}

Advanced

The two setters can be used together. For instance, you can use appendExtensionData() to store a unique ID and use setExtensionData() to store your data under a new key, reusing the same ID for the key, as shown below.

$myData = ...; // whatever
// create a unique ID
$id = ... ;

// register the ID with your extension
$parserOutput->appendExtensionData( "myextension", $id );

// register your data under a new key that includes our ID
$parserOutput->setExtensionData( "myextension-$id", $myData );

If you require the latest data added, you would first retrieve the latest ID that got added under "myextension" and use the ID to retrieve the value from "myextension-$id".

It may be helpful to create helper methods as follows :

	/**
	 * Add extension data to ParserOutput with the required key.
	 */
	public static function addExtensionData( Parser $parser, mixed $data, string $id, string $key = "myextension" ): void {
		$parserOutput = $parser->getOutput();
		$parserOutput->appendExtensionData( $key, $id );
		$parserOutput->setExtensionData( "$key-$id", $data );
	}

	/**
	 * Fetch latest extension data from ParserOutput under the relevant key.
	 */
	public static function fetchExtensionData( Parser $parser, string $key = "myextension" ): mixed {
		$parserOutput = $parser->getOutput();
		$ids = $parserOutput->getExtensionData( $key );
		// We require the key, not its value:
		if ( $ids !== null ) {
			$lastId = array_key_last( $ids );
			$data = $parserOutput->getExtensionData( "$key-$lastId" );
			return $data;
		}
		return null;
	}