Reset RequestContext between tests
[mediawiki.git] / includes / parser / ParserOutput.php
blob09f714f53cf192aed55fd5b8a7f541ae5dcf3aeb
1 <?php
3 /**
4 * Output of the PHP parser.
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 * http://www.gnu.org/copyleft/gpl.html
21 * @file
22 * @ingroup Parser
24 class ParserOutput extends CacheTime {
25 var $mText, # The output text
26 $mLanguageLinks, # List of the full text of language links, in the order they appear
27 $mCategories, # Map of category names to sort keys
28 $mTitleText, # title text of the chosen language variant
29 $mLinks = array(), # 2-D map of NS/DBK to ID for the links in the document. ID=zero for broken.
30 $mTemplates = array(), # 2-D map of NS/DBK to ID for the template references. ID=zero for broken.
31 $mTemplateIds = array(), # 2-D map of NS/DBK to rev ID for the template references. ID=zero for broken.
32 $mImages = array(), # DB keys of the images used, in the array key only
33 $mFileSearchOptions = array(), # DB keys of the images used mapped to sha1 and MW timestamp
34 $mExternalLinks = array(), # External link URLs, in the key only
35 $mInterwikiLinks = array(), # 2-D map of prefix/DBK (in keys only) for the inline interwiki links in the document.
36 $mNewSection = false, # Show a new section link?
37 $mHideNewSection = false, # Hide the new section link?
38 $mNoGallery = false, # No gallery on category page? (__NOGALLERY__)
39 $mHeadItems = array(), # Items to put in the <head> section
40 $mModules = array(), # Modules to be loaded by the resource loader
41 $mModuleScripts = array(), # Modules of which only the JS will be loaded by the resource loader
42 $mModuleStyles = array(), # Modules of which only the CSSS will be loaded by the resource loader
43 $mModuleMessages = array(), # Modules of which only the messages will be loaded by the resource loader
44 $mJsConfigVars = array(), # JavaScript config variable for mw.config combined with this page
45 $mOutputHooks = array(), # Hook tags as per $wgParserOutputHooks
46 $mWarnings = array(), # Warning text to be returned to the user. Wikitext formatted, in the key only
47 $mSections = array(), # Table of contents
48 $mEditSectionTokens = false, # prefix/suffix markers if edit sections were output as tokens
49 $mProperties = array(), # Name/value pairs to be cached in the DB
50 $mTOCHTML = '', # HTML of the TOC
51 $mTimestamp, # Timestamp of the revision
52 $mTOCEnabled = true; # Whether TOC should be shown, can't override __NOTOC__
53 private $mIndexPolicy = ''; # 'index' or 'noindex'? Any other value will result in no change.
54 private $mAccessedOptions = array(); # List of ParserOptions (stored in the keys)
55 private $mSecondaryDataUpdates = array(); # List of DataUpdate, used to save info from the page somewhere else.
56 private $mExtensionData = array(); # extra data used by extensions
57 private $mLimitReportData = array(); # Parser limit report data
58 private $mParseStartTime = array(); # Timestamps for getTimeSinceStart()
60 const EDITSECTION_REGEX =
61 '#<(?:mw:)?editsection page="(.*?)" section="(.*?)"(?:/>|>(.*?)(</(?:mw:)?editsection>))#';
63 function __construct( $text = '', $languageLinks = array(), $categoryLinks = array(),
64 $containsOldMagic = false, $titletext = ''
65 ) {
66 $this->mText = $text;
67 $this->mLanguageLinks = $languageLinks;
68 $this->mCategories = $categoryLinks;
69 $this->mContainsOldMagic = $containsOldMagic;
70 $this->mTitleText = $titletext;
73 function getText() {
74 wfProfileIn( __METHOD__ );
75 $text = $this->mText;
76 if ( $this->mEditSectionTokens ) {
77 $text = preg_replace_callback( ParserOutput::EDITSECTION_REGEX,
78 array( &$this, 'replaceEditSectionLinksCallback' ), $text );
79 } else {
80 $text = preg_replace( ParserOutput::EDITSECTION_REGEX, '', $text );
83 // If you have an old cached version of this class - sorry, you can't disable the TOC
84 if ( isset( $this->mTOCEnabled ) && $this->mTOCEnabled ) {
85 $text = str_replace( array( Parser::TOC_START, Parser::TOC_END ), '', $text );
86 } else {
87 $text = preg_replace(
88 '#' . preg_quote( Parser::TOC_START ) . '.*?' . preg_quote( Parser::TOC_END ) . '#s',
89 '',
90 $text
93 wfProfileOut( __METHOD__ );
94 return $text;
97 /**
98 * callback used by getText to replace editsection tokens
99 * @private
100 * @param array $m
101 * @throws MWException
102 * @return mixed
104 function replaceEditSectionLinksCallback( $m ) {
105 global $wgOut, $wgLang;
106 $args = array(
107 htmlspecialchars_decode( $m[1] ),
108 htmlspecialchars_decode( $m[2] ),
109 isset( $m[4] ) ? $m[3] : null,
111 $args[0] = Title::newFromText( $args[0] );
112 if ( !is_object( $args[0] ) ) {
113 throw new MWException( "Bad parser output text." );
115 $args[] = $wgLang->getCode();
116 $skin = $wgOut->getSkin();
117 return call_user_func_array( array( $skin, 'doEditSectionLink' ), $args );
120 function &getLanguageLinks() {
121 return $this->mLanguageLinks;
124 function getInterwikiLinks() {
125 return $this->mInterwikiLinks;
128 function getCategoryLinks() {
129 return array_keys( $this->mCategories );
132 function &getCategories() {
133 return $this->mCategories;
136 function getTitleText() {
137 return $this->mTitleText;
140 function getSections() {
141 return $this->mSections;
144 function getEditSectionTokens() {
145 return $this->mEditSectionTokens;
148 function &getLinks() {
149 return $this->mLinks;
152 function &getTemplates() {
153 return $this->mTemplates;
156 function &getTemplateIds() {
157 return $this->mTemplateIds;
160 function &getImages() {
161 return $this->mImages;
164 function &getFileSearchOptions() {
165 return $this->mFileSearchOptions;
168 function &getExternalLinks() {
169 return $this->mExternalLinks;
172 function getNoGallery() {
173 return $this->mNoGallery;
176 function getHeadItems() {
177 return $this->mHeadItems;
180 function getModules() {
181 return $this->mModules;
184 function getModuleScripts() {
185 return $this->mModuleScripts;
188 function getModuleStyles() {
189 return $this->mModuleStyles;
192 function getModuleMessages() {
193 return $this->mModuleMessages;
196 /** @since 1.23 */
197 function getJsConfigVars() {
198 return $this->mJsConfigVars;
201 function getOutputHooks() {
202 return (array)$this->mOutputHooks;
205 function getWarnings() {
206 return array_keys( $this->mWarnings );
209 function getIndexPolicy() {
210 return $this->mIndexPolicy;
213 function getTOCHTML() {
214 return $this->mTOCHTML;
217 function getTimestamp() {
218 return $this->mTimestamp;
221 function getLimitReportData() {
222 return $this->mLimitReportData;
225 function getTOCEnabled() {
226 return $this->mTOCEnabled;
229 function setText( $text ) {
230 return wfSetVar( $this->mText, $text );
233 function setLanguageLinks( $ll ) {
234 return wfSetVar( $this->mLanguageLinks, $ll );
237 function setCategoryLinks( $cl ) {
238 return wfSetVar( $this->mCategories, $cl );
241 function setTitleText( $t ) {
242 return wfSetVar( $this->mTitleText, $t );
245 function setSections( $toc ) {
246 return wfSetVar( $this->mSections, $toc );
249 function setEditSectionTokens( $t ) {
250 return wfSetVar( $this->mEditSectionTokens, $t );
253 function setIndexPolicy( $policy ) {
254 return wfSetVar( $this->mIndexPolicy, $policy );
257 function setTOCHTML( $tochtml ) {
258 return wfSetVar( $this->mTOCHTML, $tochtml );
261 function setTimestamp( $timestamp ) {
262 return wfSetVar( $this->mTimestamp, $timestamp );
265 function setTOCEnabled( $flag ) {
266 return wfSetVar( $this->mTOCEnabled, $flag );
269 function addCategory( $c, $sort ) {
270 $this->mCategories[$c] = $sort;
273 function addLanguageLink( $t ) {
274 $this->mLanguageLinks[] = $t;
277 function addWarning( $s ) {
278 $this->mWarnings[$s] = 1;
281 function addOutputHook( $hook, $data = false ) {
282 $this->mOutputHooks[] = array( $hook, $data );
285 function setNewSection( $value ) {
286 $this->mNewSection = (bool)$value;
288 function hideNewSection( $value ) {
289 $this->mHideNewSection = (bool)$value;
291 function getHideNewSection() {
292 return (bool)$this->mHideNewSection;
294 function getNewSection() {
295 return (bool)$this->mNewSection;
299 * Checks, if a url is pointing to the own server
301 * @param string $internal The server to check against
302 * @param string $url The url to check
303 * @return bool
305 static function isLinkInternal( $internal, $url ) {
306 return (bool)preg_match( '/^' .
307 # If server is proto relative, check also for http/https links
308 ( substr( $internal, 0, 2 ) === '//' ? '(?:https?:)?' : '' ) .
309 preg_quote( $internal, '/' ) .
310 # check for query/path/anchor or end of link in each case
311 '(?:[\?\/\#]|$)/i',
312 $url
316 function addExternalLink( $url ) {
317 # We don't register links pointing to our own server, unless... :-)
318 global $wgServer, $wgRegisterInternalExternals;
320 $registerExternalLink = true;
321 if ( !$wgRegisterInternalExternals ) {
322 $registerExternalLink = !self::isLinkInternal( $wgServer, $url );
324 if ( $registerExternalLink ) {
325 $this->mExternalLinks[$url] = 1;
330 * Record a local or interwiki inline link for saving in future link tables.
332 * @param Title $title
333 * @param int|null $id Optional known page_id so we can skip the lookup
335 function addLink( Title $title, $id = null ) {
336 if ( $title->isExternal() ) {
337 // Don't record interwikis in pagelinks
338 $this->addInterwikiLink( $title );
339 return;
341 $ns = $title->getNamespace();
342 $dbk = $title->getDBkey();
343 if ( $ns == NS_MEDIA ) {
344 // Normalize this pseudo-alias if it makes it down here...
345 $ns = NS_FILE;
346 } elseif ( $ns == NS_SPECIAL ) {
347 // We don't record Special: links currently
348 // It might actually be wise to, but we'd need to do some normalization.
349 return;
350 } elseif ( $dbk === '' ) {
351 // Don't record self links - [[#Foo]]
352 return;
354 if ( !isset( $this->mLinks[$ns] ) ) {
355 $this->mLinks[$ns] = array();
357 if ( is_null( $id ) ) {
358 $id = $title->getArticleID();
360 $this->mLinks[$ns][$dbk] = $id;
364 * Register a file dependency for this output
365 * @param string $name Title dbKey
366 * @param string $timestamp MW timestamp of file creation (or false if non-existing)
367 * @param string $sha1 Base 36 SHA-1 of file (or false if non-existing)
368 * @return void
370 function addImage( $name, $timestamp = null, $sha1 = null ) {
371 $this->mImages[$name] = 1;
372 if ( $timestamp !== null && $sha1 !== null ) {
373 $this->mFileSearchOptions[$name] = array( 'time' => $timestamp, 'sha1' => $sha1 );
378 * Register a template dependency for this output
379 * @param Title $title
380 * @param int $page_id
381 * @param int $rev_id
382 * @return void
384 function addTemplate( $title, $page_id, $rev_id ) {
385 $ns = $title->getNamespace();
386 $dbk = $title->getDBkey();
387 if ( !isset( $this->mTemplates[$ns] ) ) {
388 $this->mTemplates[$ns] = array();
390 $this->mTemplates[$ns][$dbk] = $page_id;
391 if ( !isset( $this->mTemplateIds[$ns] ) ) {
392 $this->mTemplateIds[$ns] = array();
394 $this->mTemplateIds[$ns][$dbk] = $rev_id; // For versioning
398 * @param Title $title Title object, must be an interwiki link
399 * @throws MWException if given invalid input
401 function addInterwikiLink( $title ) {
402 if ( !$title->isExternal() ) {
403 throw new MWException( 'Non-interwiki link passed, internal parser error.' );
405 $prefix = $title->getInterwiki();
406 if ( !isset( $this->mInterwikiLinks[$prefix] ) ) {
407 $this->mInterwikiLinks[$prefix] = array();
409 $this->mInterwikiLinks[$prefix][$title->getDBkey()] = 1;
413 * Add some text to the "<head>".
414 * If $tag is set, the section with that tag will only be included once
415 * in a given page.
416 * @param string $section
417 * @param string|bool $tag
419 function addHeadItem( $section, $tag = false ) {
420 if ( $tag !== false ) {
421 $this->mHeadItems[$tag] = $section;
422 } else {
423 $this->mHeadItems[] = $section;
427 public function addModules( $modules ) {
428 $this->mModules = array_merge( $this->mModules, (array)$modules );
431 public function addModuleScripts( $modules ) {
432 $this->mModuleScripts = array_merge( $this->mModuleScripts, (array)$modules );
435 public function addModuleStyles( $modules ) {
436 $this->mModuleStyles = array_merge( $this->mModuleStyles, (array)$modules );
439 public function addModuleMessages( $modules ) {
440 $this->mModuleMessages = array_merge( $this->mModuleMessages, (array)$modules );
444 * Add one or more variables to be set in mw.config in JavaScript.
446 * @param string|array $keys Key or array of key/value pairs.
447 * @param mixed $value [optional] Value of the configuration variable.
448 * @since 1.23
450 public function addJsConfigVars( $keys, $value = null ) {
451 if ( is_array( $keys ) ) {
452 foreach ( $keys as $key => $value ) {
453 $this->mJsConfigVars[$key] = $value;
455 return;
458 $this->mJsConfigVars[$keys] = $value;
462 * Copy items from the OutputPage object into this one
464 * @param OutputPage $out
466 public function addOutputPageMetadata( OutputPage $out ) {
467 $this->addModules( $out->getModules() );
468 $this->addModuleScripts( $out->getModuleScripts() );
469 $this->addModuleStyles( $out->getModuleStyles() );
470 $this->addModuleMessages( $out->getModuleMessages() );
471 $this->addJsConfigVars( $out->getJsConfigVars() );
473 $this->mHeadItems = array_merge( $this->mHeadItems, $out->getHeadItemsArray() );
477 * Override the title to be used for display
478 * -- this is assumed to have been validated
479 * (check equal normalisation, etc.)
481 * @param string $text desired title text
483 public function setDisplayTitle( $text ) {
484 $this->setTitleText( $text );
485 $this->setProperty( 'displaytitle', $text );
489 * Get the title to be used for display
491 * @return string
493 public function getDisplayTitle() {
494 $t = $this->getTitleText();
495 if ( $t === '' ) {
496 return false;
498 return $t;
502 * Fairly generic flag setter thingy.
504 public function setFlag( $flag ) {
505 $this->mFlags[$flag] = true;
508 public function getFlag( $flag ) {
509 return isset( $this->mFlags[$flag] );
513 * Set a property to be stored in the page_props database table.
515 * page_props is a key value store indexed by the page ID. This allows
516 * the parser to set a property on a page which can then be quickly
517 * retrieved given the page ID or via a DB join when given the page
518 * title.
520 * Since 1.23, page_props are also indexed by numeric value, to allow
521 * for efficient "top k" queries of pages wrt a given property.
523 * setProperty() is thus used to propagate properties from the parsed
524 * page to request contexts other than a page view of the currently parsed
525 * article.
527 * Some applications examples:
529 * * To implement hidden categories, hiding pages from category listings
530 * by storing a property.
532 * * Overriding the displayed article title.
533 * @see ParserOutput::setDisplayTitle()
535 * * To implement image tagging, for example displaying an icon on an
536 * image thumbnail to indicate that it is listed for deletion on
537 * Wikimedia Commons.
538 * This is not actually implemented, yet but would be pretty cool.
540 * @note: Do not use setProperty() to set a property which is only used
541 * in a context where the ParserOutput object itself is already available,
542 * for example a normal page view. There is no need to save such a property
543 * in the database since the text is already parsed. You can just hook
544 * OutputPageParserOutput and get your data out of the ParserOutput object.
546 * If you are writing an extension where you want to set a property in the
547 * parser which is used by an OutputPageParserOutput hook, you have to
548 * associate the extension data directly with the ParserOutput object.
549 * Since MediaWiki 1.21, you can use setExtensionData() to do this:
551 * @par Example:
552 * @code
553 * $parser->getOutput()->setExtensionData( 'my_ext_foo', '...' );
554 * @endcode
556 * And then later, in OutputPageParserOutput or similar:
558 * @par Example:
559 * @code
560 * $output->getExtensionData( 'my_ext_foo' );
561 * @endcode
563 * In MediaWiki 1.20 and older, you have to use a custom member variable
564 * within the ParserOutput object:
566 * @par Example:
567 * @code
568 * $parser->getOutput()->my_ext_foo = '...';
569 * @endcode
572 public function setProperty( $name, $value ) {
573 $this->mProperties[$name] = $value;
577 * @param string $name The property name to look up.
579 * @return mixed|false The value previously set using setProperty(). False if null or no value
580 * was set for the given property name.
582 * @note You need to use getProperties() to check for boolean and null properties.
584 public function getProperty( $name ) {
585 return isset( $this->mProperties[$name] ) ? $this->mProperties[$name] : false;
588 public function unsetProperty( $name ) {
589 unset( $this->mProperties[$name] );
592 public function getProperties() {
593 if ( !isset( $this->mProperties ) ) {
594 $this->mProperties = array();
596 return $this->mProperties;
600 * Returns the options from its ParserOptions which have been taken
601 * into account to produce this output or false if not available.
602 * @return array
604 public function getUsedOptions() {
605 if ( !isset( $this->mAccessedOptions ) ) {
606 return array();
608 return array_keys( $this->mAccessedOptions );
612 * Tags a parser option for use in the cache key for this parser output.
613 * Registered as a watcher at ParserOptions::registerWatcher() by Parser::clearState().
615 * @see ParserCache::getKey
616 * @see ParserCache::save
617 * @see ParserOptions::addExtraKey
618 * @see ParserOptions::optionsHash
619 * @param string $option
621 public function recordOption( $option ) {
622 $this->mAccessedOptions[$option] = true;
626 * Adds an update job to the output. Any update jobs added to the output will
627 * eventually be executed in order to store any secondary information extracted
628 * from the page's content. This is triggered by calling getSecondaryDataUpdates()
629 * and is used for forward links updates on edit and backlink updates by jobs.
631 * @since 1.20
633 * @param DataUpdate $update
635 public function addSecondaryDataUpdate( DataUpdate $update ) {
636 $this->mSecondaryDataUpdates[] = $update;
640 * Returns any DataUpdate jobs to be executed in order to store secondary information
641 * extracted from the page's content, including a LinksUpdate object for all links stored in
642 * this ParserOutput object.
644 * @note Avoid using this method directly, use ContentHandler::getSecondaryDataUpdates()
645 * instead! The content handler may provide additional update objects.
647 * @since 1.20
649 * @param Title $title The title of the page we're updating. If not given, a title object will
650 * be created based on $this->getTitleText()
651 * @param bool $recursive Queue jobs for recursive updates?
653 * @return array An array of instances of DataUpdate
655 public function getSecondaryDataUpdates( Title $title = null, $recursive = true ) {
656 if ( is_null( $title ) ) {
657 $title = Title::newFromText( $this->getTitleText() );
660 $linksUpdate = new LinksUpdate( $title, $this, $recursive );
662 return array_merge( $this->mSecondaryDataUpdates, array( $linksUpdate ) );
666 * Attaches arbitrary data to this ParserObject. This can be used to store some information in
667 * the ParserOutput object for later use during page output. The data will be cached along with
668 * the ParserOutput object, but unlike data set using setProperty(), it is not recorded in the
669 * database.
671 * This method is provided to overcome the unsafe practice of attaching extra information to a
672 * ParserObject by directly assigning member variables.
674 * To use setExtensionData() to pass extension information from a hook inside the parser to a
675 * hook in the page output, use this in the parser hook:
677 * @par Example:
678 * @code
679 * $parser->getOutput()->setExtensionData( 'my_ext_foo', '...' );
680 * @endcode
682 * And then later, in OutputPageParserOutput or similar:
684 * @par Example:
685 * @code
686 * $output->getExtensionData( 'my_ext_foo' );
687 * @endcode
689 * In MediaWiki 1.20 and older, you have to use a custom member variable
690 * within the ParserOutput object:
692 * @par Example:
693 * @code
694 * $parser->getOutput()->my_ext_foo = '...';
695 * @endcode
697 * @since 1.21
699 * @param string $key The key for accessing the data. Extensions should take care to avoid
700 * conflicts in naming keys. It is suggested to use the extension's name as a prefix.
702 * @param mixed $value The value to set. Setting a value to null is equivalent to removing
703 * the value.
705 public function setExtensionData( $key, $value ) {
706 if ( $value === null ) {
707 unset( $this->mExtensionData[$key] );
708 } else {
709 $this->mExtensionData[$key] = $value;
714 * Gets extensions data previously attached to this ParserOutput using setExtensionData().
715 * Typically, such data would be set while parsing the page, e.g. by a parser function.
717 * @since 1.21
719 * @param string $key The key to look up.
721 * @return mixed|null The value previously set for the given key using setExtensionData()
722 * or null if no value was set for this key.
724 public function getExtensionData( $key ) {
725 if ( isset( $this->mExtensionData[$key] ) ) {
726 return $this->mExtensionData[$key];
729 return null;
732 private static function getTimes( $clock = null ) {
733 $ret = array();
734 if ( !$clock || $clock === 'wall' ) {
735 $ret['wall'] = microtime( true );
737 if ( ( !$clock || $clock === 'cpu' ) && function_exists( 'getrusage' ) ) {
738 $ru = getrusage();
739 $ret['cpu'] = $ru['ru_utime.tv_sec'] + $ru['ru_utime.tv_usec'] / 1e6;
740 $ret['cpu'] += $ru['ru_stime.tv_sec'] + $ru['ru_stime.tv_usec'] / 1e6;
742 return $ret;
746 * Resets the parse start timestamps for future calls to getTimeSinceStart()
747 * @since 1.22
749 function resetParseStartTime() {
750 $this->mParseStartTime = self::getTimes();
754 * Returns the time since resetParseStartTime() was last called
756 * Clocks available are:
757 * - wall: Wall clock time
758 * - cpu: CPU time (requires getrusage)
760 * @since 1.22
761 * @param string $clock
762 * @return float|null
764 function getTimeSinceStart( $clock ) {
765 if ( !isset( $this->mParseStartTime[$clock] ) ) {
766 return null;
769 $end = self::getTimes( $clock );
770 return $end[$clock] - $this->mParseStartTime[$clock];
774 * Sets parser limit report data for a key
776 * The key is used as the prefix for various messages used for formatting:
777 * - $key: The label for the field in the limit report
778 * - $key-value-text: Message used to format the value in the "NewPP limit
779 * report" HTML comment. If missing, uses $key-format.
780 * - $key-value-html: Message used to format the value in the preview
781 * limit report table. If missing, uses $key-format.
782 * - $key-value: Message used to format the value. If missing, uses "$1".
784 * Note that all values are interpreted as wikitext, and so should be
785 * encoded with htmlspecialchars() as necessary, but should avoid complex
786 * HTML for sanity of display in the "NewPP limit report" comment.
788 * @since 1.22
789 * @param string $key Message key
790 * @param mixed $value Appropriate for Message::params()
792 function setLimitReportData( $key, $value ) {
793 $this->mLimitReportData[$key] = $value;
797 * Save space for for serialization by removing useless values
799 function __sleep() {
800 return array_diff(
801 array_keys( get_object_vars( $this ) ),
802 array( 'mSecondaryDataUpdates', 'mParseStartTime' )