Manual:Hooks/InternalParseBeforeLinks

InternalParseBeforeLinks
Available from version 1.10.0 Used to process the expanded wiki code after <nowiki>, HTML-comments, and templates have been treated.
Define function:	public static function onInternalParseBeforeLinks( Parser &$parser, &$text, $stripState ) { ... }
Attach hook:	In extension.json: { "Hooks": { "InternalParseBeforeLinks": "MediaWiki\\Extension\\MyExtension\\Hooks::onInternalParseBeforeLinks" } }
Called from:	File(s): parser/Parser.php
Interface:	InternalParseBeforeLinksHook.php

For more information about attaching hooks, see Manual:Hooks .
For examples of extensions using this hook, see Category:InternalParseBeforeLinks extensions.

Details

$text will hold the text for the page. To change the page text, modify this value. Note that you should not access certain global variables during this hook, as is documented in Manual:Parser.php .

This hook is intended to enable extensions that provide additional syntax features. It is usually desirable that those features interact with templates, comments, and other special functions of wiki code. For instance, assume that some extension implements automatic linking of certain key-words, say names of known users. So whenever someone types "Markus Krötzsch" the extension transforms this into "[[User:Markus Krötzsch|Markus Krötzsch]]". Now consider the following example text:

1 Markus Krötzsch
2 <nowiki>Markus Krötzsch</nowiki>
3 Markus <!-- some comment --> Krötzsch
4 {{Inserttext|Markus}} Krötzsch

Where we assume that the template "Inserttext" just pastes the first parameter. In this case, users might expect the extension to transform line 1, 3, and 4, but not line 2.

However, other parser hooks (previously e.g. ParserBeforeStrip and ParserAfterStrip) run before the wiki code is processed, such that lines 1 and 2 would be transformed instead. This parser hook fixes this issue to some extent.

The downside is that some processing steps have been done before, and will no longer be performed on the output of the hook. So the hook should insert only simple wiki code with links, and safe HTML code that is allowed for any user.

Also note that this hook is called any time some parsing happens, not just for displaying article contents. For instance, edit disclaimer or image galleries also are piped through a parser. Thus, the hook must be very careful when adding contents to the text.

Furthermore, &$text will be sanitized already. This means dangerous/unwanted HTML tags are removed. If you inject user-defined data, you should make sure that it does not allow any HTML-injection. One way to make sure would be to run the sanitizer over the text which should be inserted or over the whole text (slower) for a second time:

$text = Sanitizer::removeHTMLtags(
		$text,
		array( &$parser, 'attributeStripCallback' ),
		false,
		array_keys( $parser->mTransparentTagHooks )
);

Details

See also