View source for Manual:Parser.php

<languages />
{{Outdated2}}
{{MW file|Parser.php|includes/parser/|class1=Parser}}
<translate>
== Description == <!--T:1-->

<!--T:2-->
This file contains the class <tvar name=parser>'''<code>Parser</code>'''</tvar>, which contains the method <tvar name=parse><code>parse</code></tvar>, which converts [[<tvar name=wikitext>Special:MyLanguage/Wikitext</tvar>|Wikitext]] to HTML. It performs, among other things, the following actions:
</translate>

# <translate><!--T:3--> Call helper function <tvar name=internal>{{phpi|Parser::internalParse()}}</tvar>, which in turns calls</translate>
## <translate><!--T:4--> <tvar name=replace>{{phpi|Parser::replaceVariables}}</tvar>, which replaces magic variables, templates, and template arguments with the appropriate text.</translate>
###<translate><!--T:5--> It calls <tvar name=todom>{{phpi|Parser::preprocessToDom}}</tvar>, which preprocesses some wikitext and returns the document tree.</translate>
###<translate><!--T:6--> Next it creates a <tvar name=dom><code>[https://doc.wikimedia.org/mediawiki-core/master/php/interfacePPFrame.html PPFrame]</code></tvar> object and calls its <tvar name=expand><code>expand()</code></tvar> method to do the actual template magic.</translate>
## <translate><!--T:7--> <tvar name=sanitizer>{{phpi|Sanitizer::removeHTMLtags()}}</tvar>, which cleans up HTML, removes dangerous tags and attributes, and removes HTML comments.</translate>
## <translate><!--T:8--> <tvar name=stuff>{{phpi|Parser::doTableStuff}}</tvar>, which handles and renders the wikitext for tables.</translate>
## <translate><!--T:9--> <tvar name=underscore>{{phpi|Parser::doDoubleUnderscore}}</tvar>, which removes valid [[<tvar name=switches>Special:MyLanguage/Help:Magic_words#Behavior_switches</tvar>|double-underscore items]], like <tvar name=notoc><nowiki>__NOTOC__</nowiki></tvar>, and records them in array <tvar name=underscores>{{phpi|$Parser->mDoubleUnderscores}}</tvar>.</translate>
## <translate><!--T:10--> <tvar name=headings>{{phpi|Parser::doHeadings}}</tvar>, which parses  and renders section headers.</translate>
## <translate><!--T:11--> <tvar name=internal>{{phpi|Parser::replaceInternalLinks}}</tvar>, which processes internal links (<tvar name=brace><code>[[ ]]</code></tvar>) and stores them in <code>$Parser->mLinkHolders</code> (a [https://doc.wikimedia.org/mediawiki-core/master/php/classLinkHolderArray.html <code>LinkHolderArray</code> object]),</translate>
## <translate><!--T:12--> <tvar name=allquotes>{{phpi|Parser::doAllQuotes}}</tvar>, which replaces single quotes with HTML markup (<tvar name=1>{{tag|i|open}}</tvar>, <tvar name=2>{{tag|b|open}}</tvar>, etc).</translate>
## <translate><!--T:13--> <tvar name=extlinks>{{phpi|Parser::replaceExternalLinks}}</tvar>, which replaces and renders external links.</translate>
## <translate><!--T:14--> <tvar name=magiclinks>{{phpi|Parser::doMagicLinks}}</tvar>, which replaces special strings like "ISBN xxx" and "RFC xxx" with magic external links.</translate>
## <translate><!--T:15--> <tvar name=format>{{phpi|Parser::formatHeadings}}</tvar>, which:</translate>
##* <translate><!--T:16--> auto numbers headings if that options is enabled,</translate>
##* <translate><!--T:17--> adds an <tvar name=edit><nowiki>[edit]</nowiki></tvar> link to sections for users who have enabled the option and can edit the page,</translate>
##* <translate><!--T:18--> adds a Table of contents on the top for users who have enabled the option, and</translate>
##* <translate><!--T:19--> auto-anchors headings.</translate>
#<translate><!--T:20--> Next, <tvar name=parse><code>parse()</code></tvar> calls <tvar name=blocklevels>{{phpi|Parser::doBlockLevels}}</tvar>, which renders lists from lines starting with ':', '*', '#', etc.</translate>
#<translate><!--T:21--> <tvar name=holders>{{phpi|Parser::replaceLinkHolders}}</tvar> is called, which calls <tvar name=array>{{phpi|LinkHolderArray::replace}}</tvar> on <tvar name=mlink>{{phpi|$Parser->mLinkHolders}}</tvar> to replace link placeholders with actual links, in the buffer Placeholders created in <tvar name=makelink>Skin::makeLinkObj()</tvar></translate> <!-- Que? -->
#<translate><!--T:22--> Next, the text is language converted (when applicable) using the <tvar name=convert><code>convert</code></tvar> method of the appropriate <tvar name=lang>[https://doc.wikimedia.org/mediawiki-core/master/php/classLanguage.html Language]</tvar> object.</translate> 
#<translate><!--T:23--> <tvar name=transparent>{{phpi|Parser::replaceTransparentTags}}</tvar> is called, which replaces transparent tags with values which are provided by the callback functions in <tvar name=taghooks>{{phpi|$Parser->mTransparentTagHooks}}</tvar>. Transparent tag hooks are like regular XML-style tag hooks, except they operate late in the transformation sequence, on HTML instead of wikitext.</translate>
#<translate><!--T:24--> <tvar name=charref>{{phpi|Sanitizer::normalizeCharReferences}}</tvar> is called, which ensures that any entities and character references are legal for XML and XHTML specifically.</translate>
#<translate><!--T:25--> If [[<tvar name=htmltidy>Special:MyLanguage/Manual:$wgUseTidy</tvar>|HTML tidy]] is enabled, <tvar name=tidy>{{phpi|MWTidy::tidy}}</tvar> is called to do the tidying.</translate>
#<translate><!--T:26--> Finally the rendered HTML result of the parse process is stored in the <tvar name=parseroutput><code>[https://doc.wikimedia.org/mediawiki-core/master/php/classParserOutput.html ParserOutput]</code></tvar> object <tvar name=moutput>{{phpi|$Parser->mOutput}}</tvar>, which is returned to the caller of <tvar name=parse>{{phpi|Parser::parse}}</tvar>.</translate>

== How to get a new parser ==

Since MediaWiki 1.36 you can't construct a Parser class directly. You should use {{class|ParserFactory}} instead, and then call its <code>create</code> method.

The constructor of the ParserFactory takes several arguments. To create a ParserFactory with default options, use <code>MediaWikiServices::getInstance()->getParserFactory()</code>.

One-liner for getting a new Parser instance:

<syntaxhighlight lang="php">
$localParser = MediaWikiServices::getInstance()->getParserFactory()->create();
</syntaxhighlight>

==<translate><!--T:27--> [[<tvar name=hooks>Special:MyLanguage/Manual:Hooks</tvar>|Hooks]]</translate>==
{| class="wikitable" cellpadding="5" border="1"
! <translate><!--T:28--> Version</translate> !! <translate><!--T:29--> Hook</translate> !! <translate><!--T:30--> Description</translate>
|- 
| 1.5.0 || {{ll|Manual:Hooks/ParserAfterTidy|ParserAfterTidy}}
| <translate><!--T:32--> Used to add some final processing to the fully-rendered page output.</translate>
|-
| 1.6.0 || {{ll|Manual:Hooks/ParserBeforeInternalParse|ParserBeforeInternalParse}} ||
|-
| 1.6.0 || {{ll|Manual:Hooks/ParserClearState|ParserClearState}}
| <translate><!--T:35--> Called at the end of <tvar name=clearstate>Parser::clearState()</tvar>.</translate>
|-
| 1.6.0 || {{ll|Manual:Hooks/ParserGetVariableValueSwitch|ParserGetVariableValueSwitch}}
| <translate><!--T:36--> Assigns a value to a user defined variable.</translate>
|-
| 1.6.0 || {{ll|Manual:Hooks/ParserGetVariableValueTs|ParserGetVariableValueTs}}
| <translate><!--T:37--> Used to change the value of the time for the <tvar name=local><nowiki>{{LOCAL...}}</nowiki></tvar> magic word.</translate>
|-
| 1.6.0 || {{ll|Manual:Hooks/ParserGetVariableValueVarCache|ParserGetVariableValueVarCache}}
| <translate><!--T:38--> Used to change the value of the variable cache or return false to not use it.</translate>
|-
| 1.6.0 || {{ll|Manual:Hooks/ParserTestParser|ParserTestParser}}
| <translate><!--T:39--> Called when creating a new instance of Parser for parser tests.</translate>
|-
| 1.10.0 || {{ll|Manual:Hooks/InternalParseBeforeLinks|InternalParseBeforeLinks}}
| <translate><!--T:40--> Used to process the expanded wiki code after <tvar name=nowiki>&lt;nowiki></tvar>, HTML-comments, and templates have been treated.</translate>
|-
| 1.10.1 || {{ll|Manual:Hooks/BeforeParserFetchTemplateAndtitle|BeforeParserFetchTemplateAndtitle}}
| <translate><!--T:41--> Allows an extension to specify a version of a page to get for inclusion in a template.</translate>
|-
| 1.10.1 || {{ll|Manual:Hooks/BeforeParserrenderImageGallery|BeforeParserrenderImageGallery}}
| <translate><!--T:42--> Allows an extension to modify an image gallery before it is rendered.</translate>
|-
| 1.12.0 || {{ll|Manual:Hooks/ParserFirstCallInit|ParserFirstCallInit}}
| <translate><!--T:43--> Called when the parser initialises for the first time.</translate>
|-
| 1.12.0 || {{ll|Manual:Hooks/ParserMakeImageParams|ParserMakeImageParams}}
| <translate><!--T:45--> Alter the parameters used to generate an image before it is generated.</translate>
|-
| 1.18.0 || {{ll|Manual:Hooks/BeforeParserFetchFileAndTitle|BeforeParserFetchFileAndTitle}}
| <translate><!--T:46--> Before an image is rendered by Parser.</translate>
|-
| 1.19.0 || {{ll|Manual:Hooks/ParserSectionCreate|ParserSectionCreate}}
| <translate><!--T:47--> Called each time the parser creates a document section from wikitext.</translate>
|-
| 1.22.0 || {{ll|Manual:Hooks/ParserLimitReportFormat|ParserLimitReportFormat}}
| Replacement for deprecated ParserLimitReport
|-
| 1.22.0 || {{ll|Manual:Hooks/ParserLimitReportPrepare|ParserLimitReportPrepare}}
| Replacement for deprecated ParserLimitReport
|-
| 1.36.0 || {{ll|Manual:Hooks/BeforeParserFetchTemplateRevisionRecord|BeforeParserFetchTemplateRevisionRecord}}
| Replacement for deprecated BeforeParserFetchTemplateAndtitle
|}
<translate>

==Accessors== <!--T:48-->
</translate>
*<code>getCustomDefaultSort ()</code> <translate><!--T:49--> Accessor for <tvar name=msort>$mDefaultSort</tvar>. Unlike <tvar name=getsort>getDefaultSort()</tvar>, it will return false if none is set.</translate>
*<code>getDefaultSort ()</code> <translate><!--T:50--> Accessor for <tvar name=msort>$mDefaultSort</tvar>. Will use the empty string if none is set.</translate>
*<code>getOptions ()</code> <translate><!--T:51--> Get the <tvar name=1>{{ll|Manual:ParserOptions.php|ParserOptions}}</tvar> object.</translate>
*<code>getOutput ()</code> <translate><!--T:52--> Get the <tvar name=1>{{ll|Manual:ParserOutput.php|ParserOutput}}</tvar> object.</translate>
*<code>getPreprocessor ()</code> <translate><!--T:53--> Get a <tvar name=1>{{ll|Manual:Preprocessor.php|Preprocessor}}</tvar> object.</translate>
* Relating to [[Manual:Revision|revisions]]:
**<code>getRevisionId ()</code> <translate><!--T:54--> Get the ID of the revision we are parsing.</translate>
**<code>getRevisionTimestamp ()</code> <translate><!--T:55--> Get the timestamp associated with the current revision, adjusted for the default server-local timestamp.</translate>
**<code>getRevisionUser ()</code> <translate><!--T:56--> Get the name of the user that edited the last revision.</translate>
*<code>getTags ()</code> <translate><!--T:57--> Accessor.</translate>
*<code>getTargetLanguage ()</code> <translate><!--T:58--> Get the target language for the content being parsed.</translate>
*<code>getTitle ()</code> <translate><!--T:59--> Accessor for the <tvar name=1>{{ll|Manual:Title.php|Title}}</tvar> object.</translate>
*<code>getUser ()</code> <translate><!--T:60--> Get a <tvar name=1>{{ll|Manual:User.php|User}}</tvar> object either from <tvar name=2>$this->mUser</tvar>, if set, or from the <tvar name=3>ParserOptions</tvar> object otherwise.</translate>

<translate>
==Set== <!--T:61-->
</translate>
*<code>Parser::setFunctionHook()</code> <translate><!--T:62--> {{<tvar name=1>ll|Manual:Parser functions</tvar>|Create a parser function}}, e.g. <tvar name=2><code><nowiki>{{#expr: 1 + 1}}</nowiki></code></tvar> or <tvar name=example><code><nowiki>{{sum:1|2|3}}</nowiki></code></tvar>.</translate> <translate><!--T:68--> The callback function can have the form: <tvar name=code><code>function myParserFunction( &$parser, $arg1, $arg2, $arg3 ) { ... }</code>.</tvar></translate>
*<code>Parser::setHook()</code> <translate><!--T:64--> {{<tvar name=2>ll|Manual:Tag extensions</tvar>|Create an HTML-style tag}}, e.g. {{<tvar name=1>tmpl|0={{tag|yourtag|content=$1}}</tvar>|special text}}.</translate> <translate><!--T:69--> The callback should have the following form: <tvar name=code>{{phpi|function myParserHook( $text, $params, $parser, $frame ) { ... }}}</tvar></translate>

<translate>
==See also== <!--T:65-->
</translate>
* {{ll|Manual:Code}} – Overview of the key files and directories in the MediaWiki source code
* {{ll|Manual:ParserOptions.php}}
* {{ll|Manual:PPFrame.php}} - expansion frame interface

<translate>
== External links == <!--T:66-->

<!--T:67-->
*[<tvar name=uncovered>https://web.archive.org/web/20110709125138/http://musialek.org/?p=94</tvar> ''The MediaWiki parser, uncovered '']</translate>

[[Category:Parser{{#translation:}}| ]]