View source for Manual:Parser functions

<languages />
{{ExtensionTypes}}
[[File:MediaWiki-extensions-icon.svg|125px|alt=MediaWiki extensions|{{dir|{{pagelang}}|left|right}}]]
<translate><!--T:1--> Parser functions, added in MediaWiki 1.7, are a type of extension that integrate closely with the parser.</translate>
<translate><!--T:68--> The phrase "parser function" should not be confused with <tvar name=1>{{ll|Extension:ParserFunctions}}</tvar>, which is a collection of simple parser functions.</translate>
<translate><!--T:69--> (See <tvar name=1>{{ll|Help:Extension:ParserFunctions}}</tvar> for those.)</translate>

<translate>
== Description == <!--T:2-->

<!--T:3-->
Whereas a [[<tvar name=tag-ext>Special:MyLanguage/Manual:Tag extensions</tvar>|tag extension]] is expected to take unprocessed text and return HTML to the browser, a parser function can 'interact' with other wiki elements in the page. For example, the output of a parser function could be used as a [[<tvar name=hlp-param>Special:MyLanguage/Help:Templates#Parameters</tvar>|template parameter]] or in the construction of a [[<tvar name=links>Special:MyLanguage/Help:Link</tvar>|link]].

<!--T:4-->
The typical syntax for a parser function is:
</translate>

<blockquote><nowiki>
 {{ #functionname: param1 | param2 | param3 }}
</nowiki></blockquote>

<translate>
<!--T:5-->
For more information, see {{<tvar name=1>method doclink | class=Parser | anchor=a501ce7bb8f461a1b5fbd9f05970cab67</tvar>|method=the documentation}} for <tvar name=hook>{{phpi|Parser::setFunctionHook ( $id, $callback, $flags {{=}} 0 )}}</tvar>. This documentation states:
</translate>

:<translate><!--T:6--> The callback function should have the form:</translate>
::<code>function myParserFunction( $parser, $arg1, $arg2, $arg3 ) { ... }</code>
:<translate><!--T:7--> Or with</translate> <code>SFH_OBJECT_ARGS</code>:
:: <code>function myParserFunction( $parser, $frame, $args ) { ... }</code>

<translate><!--T:74--> The first variant of the call passes all arguments as plain text.</translate>
<translate><!--T:104--> The second passes all arguments as an array of <tvar name="1">{{ll|Manual:PPNode.php|PPNode}}</tvar>s, except for the first (<tvar name="2"><code>$args[0]</code></tvar>), which is currently text, though this may change in the future.</translate>
<translate><!--T:75--> These represent the unexpanded wikitext.</translate>
<translate><!--T:98--> The <tvar name="1"><code>{{ll|Manual:PPFrame.php|$frame}}</code></tvar> parameter can be used to expand these arguments as needed.</translate>
<translate><!--T:76--> This is commonly used for conditional processing so that only the <tvar name=1>{{phpi|true}}</tvar> case is evaluated with an <tvar name=2><code>if-</code></tvar> or <tvar name=3><code>switch-like</code></tvar> parser function.</translate>
<translate><!--T:77--> The frame object can also climb up the document tree to get information about the caller and has functions to determine and manage call depth, time-to-live, and whether the result of the parser function is volatile.</translate>

<translate>
<!--T:8-->
Creating a parser function is slightly more complicated than creating a new tag because the function name must be a [[<tvar name=magic>Special:MyLanguage/Help:Magic words</tvar>|magic word]], a keyword that supports aliases and localization.

== Simple example == <!--T:9-->

<!--T:10-->
Below is an example of an extension that creates a parser function.

<!--T:60-->
The registration goes into <tvar name=1>'''extension.json'''</tvar> and the code into <tvar name=2>'''src/ExampleExtensionHooks.php'''</tvar> respectively:
</translate>
{{ExtensionJsonFile
|type=parserhook
|extension=ExampleExtension
}}
<syntaxhighlight lang="php">
<?php
class ExampleExtensionHooks {
   // <translate nowrap><!--T:61--> Register any render callbacks with the parser</translate>
   public static function onParserFirstCallInit( Parser $parser ) {

      // <translate nowrap><!--T:62--> Create a function hook associating the <tvar name=1><code>example</code></tvar> magic word with <tvar name=2>renderExample()</tvar></translate>
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // <translate nowrap><!--T:63--> Render the output of <tvar name=1>{{#example:}}</tvar>.</translate>
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {

      // <translate nowrap><!--T:64--> The input parameters are wikitext with templates expanded.</translate>
      // <translate nowrap><!--T:65--> The output should be wikitext too.</translate>
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }
}
</syntaxhighlight>

<translate>
<!--T:12-->
Another file, <tvar name=example>'''ExampleExtension.i18n.php'''</tvar>, in your extension directory (Not in the <tvar name=1>src/</tvar> subdirectory) should contain:
</translate>

<syntaxhighlight lang="php">
<?php
/**
 * @license GPL-2.0-or-later
 * @author <translate nowrap><!--T:106--> Your Name</translate> (YourUserName)
 */

$magicWords = [];

/** English
 * @author <translate nowrap><!--T:107--> Your Name</translate> (YourUserName)
 */
$magicWords['en'] = [
   'example' => [ 0, 'example' ],
];
</syntaxhighlight>

<translate>
<!--T:13-->
With this extension enabled,
</translate>

* {{#example: hello | hi | hey}}

<translate><!--T:14--> produces:</translate>

* <translate><!--T:99--> <tvar name="1">param1</tvar> is <tvar name="2">hello</tvar> and <tvar name="3">param2</tvar> is <tvar name="4">hi</tvar> and <tvar name="5">param3</tvar> is <tvar name="6">hey</tvar></translate>

{{note|1=<translate><!--T:15--> This magicWords array is not optional. If it is omitted, the parser function simply will not work; the <tvar name=array>{{#example: hello | hi}}</tvar> will be rendered as though the extension were not installed.</translate> <translate><!--T:78--> If only the language-specific array is initialized and not the magicWords array itself, this can cause localization errors as translations from other extensions leak into yours.</translate> <translate><!--T:70--> You can associate magic words inline in PHP rather than through a i18n file.</translate> <translate><!--T:71--> This is useful when defining hooks in <tvar name=1><code>LocalSettings.php</code></tvar></translate>

<syntaxhighlight lang="php">
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
</syntaxhighlight> 
}}

<translate>
=== Within <tvar name=1>LocalSettings.php</tvar> === <!--T:100-->

<!--T:101-->
Magic words and their handling parser functions can be defined entirely in <tvar name="1">LocalSettings.php</tvar>.
</translate>

<syntaxhighlight lang="php">
$wgHooks['ParserFirstCallInit'][] = function ( Parser $parser ) 
{
	MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['wikicodeToHtml', 'wikicodeToHtml'];

	$parser->setFunctionHook( 'wikicodeToHtml', 'wikicodeToHtml' );
};
 
function wikicodeToHtml( Parser $parser, $code = '' ) 
{
	$title = $parser->getTitle();
	$options = $parser->Options();
	$options->enableLimitReport(false);
	$parser = $parser->getFreshParser();
	return [$parser->parse($code, $title, $options)->getText(), 'isHTML' => true];
}
</syntaxhighlight> 

<translate>
=== Longer functions === <!--T:16-->

<!--T:17-->
For longer functions, you may want to split the hook functions out to a <tvar name=1>_body.php</tvar> or <tvar name=2>.hooks.php</tvar> file and make them static functions of a class. Then you can load the class with <tvar name=AutoloadClasses>{{ll|Manual:$wgAutoloadClasses|$wgAutoloadClasses}}</tvar> and call the static functions in the hooks; e.g.:

<!--T:18-->
Put this in your <tvar name=myext><code>extension.json</code></tvar> file:</translate>
<syntaxhighlight lang="json">
"Hooks": {
	"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
},
"AutoloadClasses": {
	"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
}
</syntaxhighlight>
* <small><translate><!--T:19--> See: [[<tvar name=handler>Special:MyLanguage/Manual:Hooks#Writing_an_event_handler</tvar>|writing an event handler]] for other styles.</translate></small>

<translate>
<!--T:20-->
Then put this is in your <tvar name=myext><code>src/ExampleExtensionHooks.php</code></tvar> file:
</translate>

<syntaxhighlight lang="php">
class ExampleExtensionHooks {
      public static function onParserFirstCallInit( Parser $parser ) {
           $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
      }
}
</syntaxhighlight>

<translate>
== Parser interface == <!--T:23-->

=== Controlling the parsing of output === <!--T:24-->

<!--T:25-->
To have the wikitext returned by your parser function be fully parsed (including expansion of templates), set the <tvar name=noparse><code>noparse</code></tvar> option to <tvar name=1>{{phpi|false}}</tvar> when returning:
</translate>

<syntaxhighlight lang="php">
return [ $output, 'noparse' => false ];
</syntaxhighlight>

<translate>
<!--T:26-->
It seems the default value for <tvar name=noparse><code>noparse</code></tvar> changed from <tvar name=1>{{phpi|false}}</tvar> to <tvar name=2>{{phpi|true}}</tvar>, at least in some situations, sometime around version 1.12.

<!--T:27-->
Conversely, to have your parser function return HTML that remains unparsed, rather than returning wikitext, use this:
</translate>

<syntaxhighlight lang="php">
return [ $output, 'noparse' => true, 'isHTML' => true ];
</syntaxhighlight>

<translate>
=== Naming === <!--T:32-->
</translate>
<translate><!--T:33--> By default, MW adds a hash character (number sign, <tvar name=1><code>#</code></tvar>) to the name of each parser function.</translate>
<translate><!--T:72--> To suppress that addition (and obtain a parser function with no <tvar name=2><code>#</code></tvar> prefix), include the ''<tvar name=3>SFH_NO_HASH</tvar>'' constant in the optional <tvar name=4>flags</tvar> argument to <tvar name=5>setFunctionHook</tvar>, as described [[<tvar name=1>#The setFunctionHook hook</tvar>|below]].</translate>

<translate>
<!--T:34-->
When choosing a name without a hash prefix, note that transclusion of a page with a name starting with that function name followed by a colon is no longer possible. In particular, avoid function names equal to a namespace name. In the case that interwiki transclusion <tvar name=gmane>[https://lists.wikimedia.org/hyperkitty/list/mediawiki-l@lists.wikimedia.org/thread/3M53FBQ66B4EZNU6XMJQRFG3TVCW7WQO/]</tvar> is enabled, also avoid function names equal to an interwiki prefix.

=== The <tvar name=1>setFunctionHook</tvar> hook === <!--T:35-->
</translate>
<translate><!--T:36--> For more details of the interface into the parser, see the documentation for <tvar name=1>setFunctionHook</tvar> in <tvar name=2>includes/Parser.php</tvar>.</translate>
<translate><!--T:54--> Here's a (possibly dated) copy of those comments:</translate>

<translate>
<!--T:102-->
'''function <tvar name="1">setFunctionHook( $id, $callback, $flags = 0 )</tvar>'''

<!--T:37-->
'''Parameters:'''

<!--T:38-->
* string $id - The magic word ID</translate>
<translate>
<!--T:55-->
* mixed $callback - The callback function (and object) to use</translate>
<translate>
<!--T:56-->
* integer $flags - Optional. Values:</translate> 
:*<translate><!--T:118--> ''<tvar name=1>SFH_NO_HASH</tvar>'' (1) constant if you call the function without <tvar name=2><code>#</code></tvar>.</translate> 
:*<translate><!--T:119--> ''<tvar name=1>SFH_OBJECT_ARGS</tvar>'' (2) if you pass a PPFrame object and array of arguments instead of a series of function arguments, for which [<tvar name=2>[#Description</tvar>|see above]].</translate> 
:*<translate><!--T:120--> Defaults to 0 (no flags).</translate>

<translate>
<!--T:39-->
'''Return value:''' The old callback function for this name, if any

<!--T:40-->
Create a function, e.g., <tvar name=sum><code><nowiki>{{#sum:1|2|3}}</nowiki></code></tvar>. The callback function should have the form:
</translate>

<syntaxhighlight lang="php" style="overflow:auto;">
function myParserFunction( $parser, $arg1, $arg2, $arg3 ) { ... }
</syntaxhighlight>

<translate>
<!--T:41-->
The callback may either return the text result of the function, or an array with the text in element 0, and a number of flags in the other elements. The names of the flags are specified in the keys. Valid flags are:
</translate>

{| class="wikitable"
! <translate><!--T:121--> Name</translate> !! <translate><!--T:122--> Type</translate> !! <translate><!--T:123--> Default</translate>
! <translate><!--T:124--> Description</translate>
|-
| found || <translate><!--T:125--> Boolean</translate> || {{phpi|true}}
| <translate><!--T:42--> <tvar name=1>{{phpi|true}}</tvar> if the text returned is valid and processing of the template must stop.</translate>
|-
| text || ? || ?
| <translate><!--T:84--> The text to return from the function.</translate> <translate><!--T:85--> If <tvar name=1>isChildObj</tvar> or <tvar name=2>isLocalObj</tvar> are specified, this should be a DOM node instead.</translate>
|-
| noparse || {{Tunit|id=125|content=Boolean}} || {{phpi|true}}
| <translate><!--T:44--> <tvar name=1>{{phpi|true}}</tvar> if text should not be preprocessed to a DOM tree, e.g. unsafe HTML tags should not be stripped, etc.</translate>
|-
| isHTML || {{Tunit|id=125|content=Boolean}} || ?
| <translate><!--T:46--> <tvar name=1>{{phpi|true}}</tvar> if the returned text is HTML and must be armoured against wikitext transformation.</translate> <translate><!--T:103--> [[<tvar name="1">Manual talk:Parser functions#isHTML - almost but not _entirely</tvar>|But see discussion]]</translate>
|-
| nowiki || {{Tunit|id=125|content=Boolean}} || <translate><!--T:126--> usually <tvar name=1>{{phpi|false}}</tvar></translate>
| <translate><!--T:43--> <tvar name=1>{{phpi|true}}</tvar> if wiki markup in the return value (text) should be escaped.</translate>
|-
| isChildObj || {{Tunit|id=125|content=Boolean}} || ?
| <translate><!--T:80--> <tvar name=1>{{phpi|true}}</tvar> if the text is a DOM node needing expansion in a child frame.</translate>
|-
| isLocalObj || {{Tunit|id=125|content=Boolean}} || ?
| <translate><!--T:81--> <tvar name=1>{{phpi|true}}</tvar> if the text is a DOM node needing expansion in the current frame.</translate> <translate><!--T:105--> The default value depends on other values and outcomes.</translate>
|-
| preprocessFlags || ? || {{phpi|false}}
| <translate><!--T:82--> Optional <tvar name=1>{{ll|Manual:PPFrame.php|PPFrame}}</tvar> flags to use when parsing the returned text.</translate> <translate><!--T:83--> This only applies when <tvar name=1>noparse</tvar> is <tvar name=2>{{phpi|false}}</tvar>.</translate>
|-
| title || ? || {{phpi|false}}
| <translate><!--T:86--> The <tvar name=1>{{ll|Manual:Title.php|Title}}</tvar> object where the text came from.</translate>
|-
| forceRawInterwiki || {{Tunit|id=125|content=Boolean}} || ?
| <translate><!--T:79--> <tvar name=1>{{phpi|true}}</tvar> if interwiki transclusion must be forced to be done in raw mode and not rendered.</translate>
|}

<translate>
=== Expensive parser functions === <!--T:87-->
</translate>
<translate><!--T:88--> Some parser functions represent a significant use of a wiki's resources and should be marked as "expensive".</translate>
<translate><!--T:89--> The number of expensive parser functions on any given page is limited by the <tvar name=1>{{ll|Manual:$wgExpensiveParserFunctionLimit|$wgExpensiveParserFunctionLimit}}</tvar> setting.</translate>
<translate><!--T:90--> What counts as expensive is left up to the function itself, but typically, anything that is likely to cause a delay that extends beyond simple processing of data should be considered.</translate>
<translate><!--T:91--> This includes things like database reads and writes, launching a shell script synchronously, or file manipulation.</translate>
<translate><!--T:92--> On the other hand, not all such functions should necessarily be tagged.</translate>
<translate><!--T:93--> Semantic MediaWiki, for example, only marks a percentage of its database reads as expensive.</translate>
<translate><!--T:94--> This is due to the fact that on certain data-intensive pages, it could easily overflow the normal expensive parser function limits.</translate>
<translate><!--T:95--> In cases like this, the potential for noticeably slower performance that doesn't get flagged as expensive is a trade-off to having the functionality that SMW offers.</translate>

<translate><!--T:96--> To mark your parser function as expensive, from within the body of the function's code, use <tvar name=1><syntaxhighlight lang=php inline>$result = $parser->incrementExpensiveFunctionCount();</syntaxhighlight></tvar>.</translate>
<translate><!--T:97--> The return value will be <tvar name=1>{{phpi|false}}</tvar> if the expensive function limit has been reached or exceeded.</translate>

<translate>
==Named parameters== <!--T:47-->

<!--T:48-->
Parser functions do not support named parameters the way templates and tag extensions do, but it is occasionally useful to fake it. Users are often accustomed to using vertical bars ( <tvar name=1><code>|</code></tvar> ) to separate arguments, so it's nice to be able to do that in the parser function context, too. Here's a simple example of how to accomplish this:
</translate>

<syntaxhighlight lang="php" style="overflow:auto;">
function ExampleExtensionRenderParserFunction( &$parser ) {
	// <translate nowrap><!--T:108--> Suppose the user invoked the parser function like so:</translate>
	// {{#myparserfunction: foo=bar | apple=orange | banana }}

	$options = extractOptions( array_slice( func_get_args(), 1 ) );

	// <translate nowrap><!--T:109--> Now you've got an array that looks like this:</translate>
	// [foo] => 'bar'
	// [apple] => 'orange'
	// [banana] => true
	// <translate nowrap><!--T:110--> Continue writing your code...</translate>
}

/**
 * <translate nowrap><!--T:111--> Converts an array of values in form [0] => "name=value"</translate>
 * <translate nowrap><!--T:112--> into a real associative array in form [name] => value</translate>
 * <translate nowrap><!--T:113--> If no = is provided, true is assumed like this: [name] => true</translate>
 *
 * @param array string $options
 * @return array $results
 */
function extractOptions( array $options ) {
	$results = [];
	foreach ( $options as $option ) {
		$pair = array_map( 'trim', explode( '=', $option, 2 ) );
		if ( count( $pair ) === 2 ) {
			$results[ $pair[0] ] = $pair[1];
		}
		if ( count( $pair ) === 1 ) {
			$results[ $pair[0] ] = true;
		}
	}
	return $results;
}
</syntaxhighlight>

<translate>
==See also== <!--T:52-->

<!--T:114-->
General and related guides:
</translate>

* <translate><!--T:115--> <tvar name=1>{{ll|Manual:Developing extensions}}</tvar>, or for more general information about extensions, see <tvar name=2>{{ll|Manual:Extensions}}</tvar> and <tvar name=3>{{ll|Extensions FAQ}}</tvar>.</translate>
* {{ll|Manual:Tag extensions}}
* {{ll|Manual:Magic words}}

<translate><!--T:116--> Code:</translate>

* {{ll|Manual:Parser.php}}
* {{ll|Manual:Hooks/ParserFirstCallInit}}
* {{ll|Parser function hooks}} - <translate><!--T:73--> an (incomplete) list of parser functions provided by core and extensions</translate>
<translate>
<!--T:66-->
* The [<tvar name=url>https://github.com/JeroenDeDauw/ParserHooks#parserhooks</tvar> Parser Hooks] PHP library, which provides an object orientated interface for declarative parser hooks
</translate>
* {{ll|Manual:Extension data}}

<translate><!--T:117--> Examples:</translate>

* <translate><!--T:53--> The [[<tvar name=parser-func>Special:MyLanguage/Extension:ParserFunctions</tvar>|ParserFunctions extension]] is a well-known collection of parser functions.</translate>
* {{ll|Help:Extension:ParserFunctions}}
* {{ll|:Category:Parser function extensions}}

[[Category:MediaWiki development{{#translation:}}]]
[[Category:Parser extensions{{#translation:}}|*]]
[[Category:Wiki markup{{#translation:}}|Parser functions]]
[[Category:Customization techniques{{#translation:}}|Parser functions]]
[[Category:Sample code{{#translation:}}]]