en>HyperNervie: Should this be translated?

2026-03-19T08:07:16Z

Should this be translated?

New page

<languages />
{{Magic words}}
[[File:MediaWiki-extensions-icon.svg|125px|alt=MediaWiki extensions|{{dir|{{pagelang}}|left|right}}]]
<translate> Parser functions, added in MediaWiki 1.7, are a type of extension that integrate closely with the parser.</translate>
<translate> 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> (See <tvar name=1>{{ll|Help:Extension:ParserFunctions}}</tvar> for those.)</translate>

<translate>
== Description == 


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]].


The typical syntax for a parser function is:
</translate>

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

<translate> For more information, see {{<tvar name=2>tmpl|0={{method doclink | class=MediaWiki\Parser\Parser | anchor=a34da5613dad9dd0a5e921aa7bceba3cf|method=$1}}</tvar>|the documentation}} for <tvar name=hook>{{phpi|Parser::setFunctionHook ( $id, $callback, $flags {{=}} 0 )}}</tvar>.</translate>
<translate> This documentation states:</translate>

:<translate> The callback function should have the form:</translate>
::<code>function myParserFunction( $parser, $arg1, $arg2, $arg3 ) { ... }</code>
:<translate> Or with <tvar name=1><code>SFH_OBJECT_ARGS</code></tvar>:</translate>
::<code>function myParserFunction( $parser, $frame, $args ) { ... }</code>

<translate> The first variant of the call passes all arguments as plain text.</translate>
<translate> 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> These represent the unexpanded wikitext.</translate>
<translate> The <tvar name="1"><code>{{ll|Manual:PPFrame.php|$frame}}</code></tvar> parameter can be used to expand these arguments as needed.</translate>
<translate> 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</code></tvar>-like parser function.</translate>
<translate> 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>

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 == 


Below is an example of an extension that creates a parser function.


The registration goes into <tvar name=1>'''extension.json'''</tvar> and the code into <tvar name=2>'''src/ExampleExtensionHooks.php'''</tvar> respectively:
</translate>

{| class="wikitable"
|-
! <translate> Standard:</translate>
! <translate> Using the <tvar name=1>HookHandler</tvar> interface:</translate>
|-
!colspan="2"| extension.json
|-
| {{ExtensionJsonFile
|type=parserhook
|extension=ExampleExtension
}}
|
{{Code
|lang=json
|
{
"name": "ExampleExtension",
"author": "Me",
"version": "1.0.0",
"url": "https://www.mediawiki.org/wiki/Extension:ExampleExtension",
"descriptionmsg": "{{lc:ExampleExtension}}-desc",
"license-name": "GPL-2.0-or-later",
"type": "parserhook",
"MessagesDirs": {
"ExampleExtension": [
"i18n"
]
},
"AutoloadClasses": {
"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
},
"ExtensionMessagesFiles": {
"ExampleExtensionMagic": "ExampleExtension.i18n.php"
},
"Hooks": {
"ParserFirstCallInit": "onParserFirstCallInit"
},
"HookHandlers": {
"ExampleExtensionHooks": {
"class": "MediaWiki\\Extension\\ExampleExtension\\Hooks"
}
},
"manifest_version": 1
}
}}

|-
!colspan="2"| ExampleExtensionHooks.php
|-
|<syntaxhighlight lang="php">
<?php

class ExampleExtensionHooks {

// <translate nowrap> Register any render callbacks with the parser</translate>
public static function onParserFirstCallInit( Parser $parser ) {
// <translate nowrap> 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> Render the output of <tvar name=1>{{#example:}}</tvar>.</translate>
public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {
// <translate nowrap> The input parameters are wikitext with templates expanded.</translate>
// <translate nowrap> The output should be wikitext too.</translate>
$output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

return $output;
}

}
</syntaxhighlight>
| <syntaxhighlight lang="php">
<?php

class ExampleExtensionHooks implements ParserFirstCallInitHook {

// <translate nowrap> Register any render callbacks with the parser</translate>
public function onParserFirstCallInit( $parser ) {
// Create a function hook associating the example magic word with renderExample()
$parser->setFunctionHook( 'example', [ $this, 'renderExample' ] );
}

// <translate nowrap> Render the output of <tvar name=1>{{#example:}}</tvar>.</translate>
public function renderExample( $parser, $param1 = '', $param2 = '', $param3 = '' ) {
// <translate nowrap> The input parameters are wikitext with templates expanded.</translate>
// <translate nowrap> The output should be wikitext too.</translate>
$output = "param1 is $param1 and param2 is $param2 and param3 is $param3";
return $output;
}

}
</syntaxhighlight>
|}

<translate>

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> Your Name</translate> (YourUserName)
*/

$magicWords = [];

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

<translate>

With this extension enabled,
</translate>

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

<translate> produces:</translate>

* param1 is hello and param2 is hi and param3 is hey

{{note|1=<translate> 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> 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> You can associate magic words inline in PHP rather than through a i18n file.</translate> <translate> 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> === 


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 === 


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.:


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> See: [[<tvar name=handler>Special:MyLanguage/Manual:Hooks#Writing_an_event_handler</tvar>|writing an event handler]] for other styles.</translate></small>

<translate>

Then put this 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 == 

=== Controlling the parsing of output === 


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>

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.


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 === 
</translate>
<translate> By default, MW adds a hash character (number sign, <tvar name=1><code>#</code></tvar>) to the name of each parser function.</translate>
<translate> 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>

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 === 
</translate>
<translate> 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> Here's a (possibly dated) copy of those comments:</translate>

'''function setFunctionHook( $id, $callback, $flags = 0 )'''

<translate>

'''Parameters:'''
</translate>

* string $id – <translate> The magic word ID</translate>
* mixed $callback – <translate> The callback function (and object) to use</translate>
* integer $flags – <translate> Optional. Values:</translate>
:* <code>SFH_NO_HASH</code> (1) – <translate> constant if you call the function without <tvar name=2><code>#</code></tvar>.</translate>
:* <code>SFH_OBJECT_ARGS</code> (2) – <translate> 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> Defaults to 0 (no flags).</translate>

<translate>

'''Return value:''' The old callback function for this name, if any


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>

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> Name</translate> !! <translate> Type</translate> !! <translate> Default</translate>
! <translate> Description</translate>
|-
| found || <translate> Boolean</translate> || {{phpi|true}}
| <translate> <tvar name=1>{{phpi|true}}</tvar> if the text returned is valid and processing of the template must stop.</translate>
|-
| text || ? || ?
| <translate> The text to return from the function.</translate> <translate> 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> <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> <tvar name=1>{{phpi|true}}</tvar> if the returned text is HTML and must be armoured against wikitext transformation.</translate> <translate> [[<tvar name="1">Manual talk:Parser functions#isHTML - almost but not _entirely</tvar>|But see discussion]]</translate>
|-
| nowiki || {{Tunit|id=125|content=Boolean}} || <translate> usually <tvar name=1>{{phpi|false}}</tvar></translate>
| <translate> <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> <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> <tvar name=1>{{phpi|true}}</tvar> if the text is a DOM node needing expansion in the current frame.</translate> <translate> The default value depends on other values and outcomes.</translate>
|-
| preprocessFlags || ? || {{phpi|false}}
| <translate> Optional <tvar name=1>{{ll|Manual:PPFrame.php|PPFrame}}</tvar> flags to use when parsing the returned text.</translate> <translate> This only applies when <tvar name=1>noparse</tvar> is <tvar name=2>{{phpi|false}}</tvar>.</translate>
|-
| title || ? || {{phpi|false}}
| <translate> The <tvar name=1>{{ll|Manual:Title.php|Title}}</tvar> object where the text came from.</translate>
|-
| forceRawInterwiki || {{Tunit|id=125|content=Boolean}} || ?
| <translate> <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 === 
</translate>
{{see also|Manual:Template limits#Expensive parser function calls}}

<translate> Some parser functions represent a significant use of a wiki's resources and should be marked as "expensive".</translate>
<translate> 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> 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> This includes things like database reads and writes, launching a shell script synchronously, or file manipulation.</translate>
<translate> On the other hand, not all such functions should necessarily be tagged.</translate>
<translate> Semantic MediaWiki, for example, only marks a percentage of its database reads as expensive.</translate>
<translate> This is due to the fact that on certain data-intensive pages, it could easily overflow the normal expensive parser function limits.</translate>
<translate> 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> 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> 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== 


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> 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> Now you've got an array that looks like this:</translate>
// [foo] => 'bar'
// [apple] => 'orange'
// [banana] => true
// <translate nowrap> Continue writing your code...</translate>
}

/**
* <translate nowrap> Converts an array of values in form [0] => "name=value" into a real associative array in form [name] => value</translate>
* <translate nowrap> 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== 


General and related guides:
</translate>

* <translate> <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> Code:</translate>

* {{ll|Manual:Parser.php}}
* {{ll|Manual:Hooks/ParserFirstCallInit}}
* {{ll|Parser function hooks}} – <translate> an (incomplete) list of parser functions provided by core and extensions</translate>
<translate>

* 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> Examples:</translate>

* <translate> 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}}

{{Extension development}}

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

Manual:Parser functions - Revision history

Majestix: 1 revision imported: Initial Setup

en>HyperNervie: Should this be translated?

← Older revision	Revision as of 12:05, 12 April 2026
(No difference)