3 * Options for the PHP parser
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
23 use Wikimedia\ScopedCallback
;
26 * @brief Set options of the Parser
28 * All member variables are supposed to be private in theory, although in
29 * practice this is not the case.
36 * Interlanguage links are removed and returned in an array
38 private $mInterwikiMagic;
41 * Allow external images inline?
43 private $mAllowExternalImages;
46 * If not, any exception?
48 private $mAllowExternalImagesFrom;
51 * If not or it doesn't match, should we check an on-wiki whitelist?
53 private $mEnableImageWhitelist;
58 private $mDateFormat = null;
61 * Create "edit section" links?
63 private $mEditSection = true;
66 * Allow inclusion of special pages?
68 private $mAllowSpecialInclusion;
71 * Use tidy to cleanup output HTML?
73 private $mTidy = false;
76 * Which lang to call for PLURAL and GRAMMAR
78 private $mInterfaceMessage = false;
81 * Overrides $mInterfaceMessage with arbitrary language
83 private $mTargetLanguage = null;
86 * Maximum size of template expansions, in bytes
88 private $mMaxIncludeSize;
91 * Maximum number of nodes touched by PPFrame::expand()
93 private $mMaxPPNodeCount;
96 * Maximum number of nodes generated by Preprocessor::preprocessToObj()
98 private $mMaxGeneratedPPNodeCount;
101 * Maximum recursion depth in PPFrame::expand()
103 private $mMaxPPExpandDepth;
106 * Maximum recursion depth for templates within templates
108 private $mMaxTemplateDepth;
111 * Maximum number of calls per parse to expensive parser functions
113 private $mExpensiveParserFunctionLimit;
116 * Remove HTML comments. ONLY APPLIES TO PREPROCESS OPERATIONS
118 private $mRemoveComments = true;
121 * @var callable Callback for current revision fetching; first argument to call_user_func().
123 private $mCurrentRevisionCallback =
124 [ 'Parser', 'statelessFetchRevision' ];
127 * @var callable Callback for template fetching; first argument to call_user_func().
129 private $mTemplateCallback =
130 [ 'Parser', 'statelessFetchTemplate' ];
133 * @var callable|null Callback to generate a guess for {{REVISIONID}}
135 private $mSpeculativeRevIdCallback;
138 * Enable limit report in an HTML comment on output
140 private $mEnableLimitReport = false;
143 * Timestamp used for {{CURRENTDAY}} etc.
148 * Target attribute for external links
150 private $mExternalLinkTarget;
153 * Clean up signature texts?
154 * @see Parser::cleanSig
156 private $mCleanSignatures;
159 * Transform wiki markup when saving the page?
161 private $mPreSaveTransform = true;
164 * Whether content conversion should be disabled
166 private $mDisableContentConversion;
169 * Whether title conversion should be disabled
171 private $mDisableTitleConversion;
174 * Automatically number headings?
176 private $mNumberHeadings;
179 * Thumb size preferred by the user.
184 * Maximum article size of an article to be marked as "stub"
186 private $mStubThreshold;
189 * Language object of the User language.
200 * Parsing the page for a "preview" operation?
202 private $mIsPreview = false;
205 * Parsing the page for a "preview" operation on a single section?
207 private $mIsSectionPreview = false;
210 * Parsing the printable version of the page?
212 private $mIsPrintable = false;
215 * Extra key that should be present in the caching key.
217 private $mExtraKey = '';
220 * Are magic ISBN links enabled?
222 private $mMagicISBNLinks = true;
225 * Are magic PMID links enabled?
227 private $mMagicPMIDLinks = true;
230 * Are magic RFC links enabled?
232 private $mMagicRFCLinks = true;
235 * Function to be called when an option is accessed.
237 private $onAccessCallback = null;
240 * If the page being parsed is a redirect, this should hold the redirect
244 private $redirectTarget = null;
247 * If the wiki is configured to allow raw html ($wgRawHtml = true)
248 * is it allowed in the specific case of parsing this page.
250 * This is meant to disable unsafe parser tags in cases where
251 * a malicious user may control the input to the parser.
253 * @note This is expected to be true for normal pages even if the
254 * wiki has $wgRawHtml disabled in general. The setting only
255 * signifies that raw html would be unsafe in the current context
256 * provided that raw html is allowed at all.
259 private $allowUnsafeRawHtml = true;
262 * CSS class to use to wrap output from Parser::parse().
265 private $wrapOutputClass = 'mw-parser-output';
267 public function getInterwikiMagic() {
268 return $this->mInterwikiMagic
;
271 public function getAllowExternalImages() {
272 return $this->mAllowExternalImages
;
275 public function getAllowExternalImagesFrom() {
276 return $this->mAllowExternalImagesFrom
;
279 public function getEnableImageWhitelist() {
280 return $this->mEnableImageWhitelist
;
283 public function getEditSection() {
284 return $this->mEditSection
;
287 public function getNumberHeadings() {
288 $this->optionUsed( 'numberheadings' );
290 return $this->mNumberHeadings
;
293 public function getAllowSpecialInclusion() {
294 return $this->mAllowSpecialInclusion
;
297 public function getTidy() {
301 public function getInterfaceMessage() {
302 return $this->mInterfaceMessage
;
305 public function getTargetLanguage() {
306 return $this->mTargetLanguage
;
309 public function getMaxIncludeSize() {
310 return $this->mMaxIncludeSize
;
313 public function getMaxPPNodeCount() {
314 return $this->mMaxPPNodeCount
;
317 public function getMaxGeneratedPPNodeCount() {
318 return $this->mMaxGeneratedPPNodeCount
;
321 public function getMaxPPExpandDepth() {
322 return $this->mMaxPPExpandDepth
;
325 public function getMaxTemplateDepth() {
326 return $this->mMaxTemplateDepth
;
330 public function getExpensiveParserFunctionLimit() {
331 return $this->mExpensiveParserFunctionLimit
;
334 public function getRemoveComments() {
335 return $this->mRemoveComments
;
339 public function getCurrentRevisionCallback() {
340 return $this->mCurrentRevisionCallback
;
343 public function getTemplateCallback() {
344 return $this->mTemplateCallback
;
348 public function getSpeculativeRevIdCallback() {
349 return $this->mSpeculativeRevIdCallback
;
352 public function getEnableLimitReport() {
353 return $this->mEnableLimitReport
;
356 public function getCleanSignatures() {
357 return $this->mCleanSignatures
;
360 public function getExternalLinkTarget() {
361 return $this->mExternalLinkTarget
;
364 public function getDisableContentConversion() {
365 return $this->mDisableContentConversion
;
368 public function getDisableTitleConversion() {
369 return $this->mDisableTitleConversion
;
372 public function getThumbSize() {
373 $this->optionUsed( 'thumbsize' );
375 return $this->mThumbSize
;
378 public function getStubThreshold() {
379 $this->optionUsed( 'stubthreshold' );
381 return $this->mStubThreshold
;
384 public function getIsPreview() {
385 return $this->mIsPreview
;
388 public function getIsSectionPreview() {
389 return $this->mIsSectionPreview
;
392 public function getIsPrintable() {
393 $this->optionUsed( 'printable' );
395 return $this->mIsPrintable
;
398 public function getUser() {
402 public function getPreSaveTransform() {
403 return $this->mPreSaveTransform
;
406 public function getDateFormat() {
407 $this->optionUsed( 'dateformat' );
408 if ( !isset( $this->mDateFormat
) ) {
409 $this->mDateFormat
= $this->mUser
->getDatePreference();
411 return $this->mDateFormat
;
414 public function getTimestamp() {
415 if ( !isset( $this->mTimestamp
) ) {
416 $this->mTimestamp
= wfTimestampNow();
418 return $this->mTimestamp
;
422 * Get the user language used by the parser for this page and split the parser cache.
424 * @warning: Calling this causes the parser cache to be fragmented by user language!
425 * To avoid cache fragmentation, output should not depend on the user language.
426 * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
428 * @note This function will trigger a cache fragmentation by recording the
429 * 'userlang' option, see optionUsed(). This is done to avoid cache pollution
430 * when the page is rendered based on the language of the user.
432 * @note When saving, this will return the default language instead of the user's.
433 * {{int: }} uses this which used to produce inconsistent link tables (T16404).
438 public function getUserLangObj() {
439 $this->optionUsed( 'userlang' );
440 return $this->mUserLang
;
444 * Same as getUserLangObj() but returns a string instead.
446 * @warning: Calling this causes the parser cache to be fragmented by user language!
447 * To avoid cache fragmentation, output should not depend on the user language.
448 * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
450 * @see getUserLangObj()
452 * @return string Language code
455 public function getUserLang() {
456 return $this->getUserLangObj()->getCode();
463 public function getMagicISBNLinks() {
464 return $this->mMagicISBNLinks
;
471 public function getMagicPMIDLinks() {
472 return $this->mMagicPMIDLinks
;
478 public function getMagicRFCLinks() {
479 return $this->mMagicRFCLinks
;
486 public function getAllowUnsafeRawHtml() {
487 return $this->allowUnsafeRawHtml
;
491 * Class to use to wrap output from Parser::parse()
493 * @return string|bool
495 public function getWrapOutputClass() {
496 $this->optionUsed( 'wrapclass' );
497 return $this->wrapOutputClass
;
500 public function setInterwikiMagic( $x ) {
501 return wfSetVar( $this->mInterwikiMagic
, $x );
504 public function setAllowExternalImages( $x ) {
505 return wfSetVar( $this->mAllowExternalImages
, $x );
508 public function setAllowExternalImagesFrom( $x ) {
509 return wfSetVar( $this->mAllowExternalImagesFrom
, $x );
512 public function setEnableImageWhitelist( $x ) {
513 return wfSetVar( $this->mEnableImageWhitelist
, $x );
516 public function setDateFormat( $x ) {
517 return wfSetVar( $this->mDateFormat
, $x );
520 public function setEditSection( $x ) {
521 return wfSetVar( $this->mEditSection
, $x );
524 public function setNumberHeadings( $x ) {
525 return wfSetVar( $this->mNumberHeadings
, $x );
528 public function setAllowSpecialInclusion( $x ) {
529 return wfSetVar( $this->mAllowSpecialInclusion
, $x );
532 public function setTidy( $x ) {
533 return wfSetVar( $this->mTidy
, $x );
536 public function setInterfaceMessage( $x ) {
537 return wfSetVar( $this->mInterfaceMessage
, $x );
540 public function setTargetLanguage( $x ) {
541 return wfSetVar( $this->mTargetLanguage
, $x, true );
544 public function setMaxIncludeSize( $x ) {
545 return wfSetVar( $this->mMaxIncludeSize
, $x );
548 public function setMaxPPNodeCount( $x ) {
549 return wfSetVar( $this->mMaxPPNodeCount
, $x );
552 public function setMaxGeneratedPPNodeCount( $x ) {
553 return wfSetVar( $this->mMaxGeneratedPPNodeCount
, $x );
556 public function setMaxTemplateDepth( $x ) {
557 return wfSetVar( $this->mMaxTemplateDepth
, $x );
561 public function setExpensiveParserFunctionLimit( $x ) {
562 return wfSetVar( $this->mExpensiveParserFunctionLimit
, $x );
565 public function setRemoveComments( $x ) {
566 return wfSetVar( $this->mRemoveComments
, $x );
570 public function setCurrentRevisionCallback( $x ) {
571 return wfSetVar( $this->mCurrentRevisionCallback
, $x );
575 public function setSpeculativeRevIdCallback( $x ) {
576 return wfSetVar( $this->mSpeculativeRevIdCallback
, $x );
579 public function setTemplateCallback( $x ) {
580 return wfSetVar( $this->mTemplateCallback
, $x );
583 public function enableLimitReport( $x = true ) {
584 return wfSetVar( $this->mEnableLimitReport
, $x );
587 public function setTimestamp( $x ) {
588 return wfSetVar( $this->mTimestamp
, $x );
591 public function setCleanSignatures( $x ) {
592 return wfSetVar( $this->mCleanSignatures
, $x );
595 public function setExternalLinkTarget( $x ) {
596 return wfSetVar( $this->mExternalLinkTarget
, $x );
599 public function disableContentConversion( $x = true ) {
600 return wfSetVar( $this->mDisableContentConversion
, $x );
603 public function disableTitleConversion( $x = true ) {
604 return wfSetVar( $this->mDisableTitleConversion
, $x );
607 public function setUserLang( $x ) {
608 if ( is_string( $x ) ) {
609 $x = Language
::factory( $x );
612 return wfSetVar( $this->mUserLang
, $x );
615 public function setThumbSize( $x ) {
616 return wfSetVar( $this->mThumbSize
, $x );
619 public function setStubThreshold( $x ) {
620 return wfSetVar( $this->mStubThreshold
, $x );
623 public function setPreSaveTransform( $x ) {
624 return wfSetVar( $this->mPreSaveTransform
, $x );
627 public function setIsPreview( $x ) {
628 return wfSetVar( $this->mIsPreview
, $x );
631 public function setIsSectionPreview( $x ) {
632 return wfSetVar( $this->mIsSectionPreview
, $x );
635 public function setIsPrintable( $x ) {
636 return wfSetVar( $this->mIsPrintable
, $x );
640 * @param bool|null Value to set or null to get current value
641 * @return bool Current value for allowUnsafeRawHtml
644 public function setAllowUnsafeRawHtml( $x ) {
645 return wfSetVar( $this->allowUnsafeRawHtml
, $x );
649 * CSS class to use to wrap output from Parser::parse()
651 * @param string|bool $className Set false to disable wrapping.
652 * @return string|bool Current value
654 public function setWrapOutputClass( $className ) {
655 if ( $className === true ) { // DWIM, they probably want the default class name
656 $className = 'mw-parser-output';
658 return wfSetVar( $this->wrapOutputClass
, $className );
662 * Set the redirect target.
664 * Note that setting or changing this does not *make* the page a redirect
665 * or change its target, it merely records the information for reference
669 * @param Title|null $title
671 function setRedirectTarget( $title ) {
672 $this->redirectTarget
= $title;
676 * Get the previously-set redirect target.
681 function getRedirectTarget() {
682 return $this->redirectTarget
;
686 * Extra key that should be present in the parser cache key.
689 public function addExtraKey( $key ) {
690 $this->mExtraKey
.= '!' . $key;
696 * @param Language $lang
698 public function __construct( $user = null, $lang = null ) {
699 if ( $user === null ) {
701 if ( $wgUser === null ) {
707 if ( $lang === null ) {
709 if ( !StubObject
::isRealObject( $wgLang ) ) {
714 $this->initialiseFromUser( $user, $lang );
718 * Get a ParserOptions object for an anonymous user
720 * @return ParserOptions
722 public static function newFromAnon() {
724 return new ParserOptions( new User
, $wgContLang );
728 * Get a ParserOptions object from a given user.
729 * Language will be taken from $wgLang.
732 * @return ParserOptions
734 public static function newFromUser( $user ) {
735 return new ParserOptions( $user );
739 * Get a ParserOptions object from a given user and language
742 * @param Language $lang
743 * @return ParserOptions
745 public static function newFromUserAndLang( User
$user, Language
$lang ) {
746 return new ParserOptions( $user, $lang );
750 * Get a ParserOptions object from a IContextSource object
752 * @param IContextSource $context
753 * @return ParserOptions
755 public static function newFromContext( IContextSource
$context ) {
756 return new ParserOptions( $context->getUser(), $context->getLanguage() );
763 * @param Language $lang
765 private function initialiseFromUser( $user, $lang ) {
766 global $wgInterwikiMagic, $wgAllowExternalImages,
767 $wgAllowExternalImagesFrom, $wgEnableImageWhitelist, $wgAllowSpecialInclusion,
768 $wgMaxArticleSize, $wgMaxPPNodeCount, $wgMaxTemplateDepth, $wgMaxPPExpandDepth,
769 $wgCleanSignatures, $wgExternalLinkTarget, $wgExpensiveParserFunctionLimit,
770 $wgMaxGeneratedPPNodeCount, $wgDisableLangConversion, $wgDisableTitleConversion,
773 // *UPDATE* ParserOptions::matches() if any of this changes as needed
774 $this->mInterwikiMagic
= $wgInterwikiMagic;
775 $this->mAllowExternalImages
= $wgAllowExternalImages;
776 $this->mAllowExternalImagesFrom
= $wgAllowExternalImagesFrom;
777 $this->mEnableImageWhitelist
= $wgEnableImageWhitelist;
778 $this->mAllowSpecialInclusion
= $wgAllowSpecialInclusion;
779 $this->mMaxIncludeSize
= $wgMaxArticleSize * 1024;
780 $this->mMaxPPNodeCount
= $wgMaxPPNodeCount;
781 $this->mMaxGeneratedPPNodeCount
= $wgMaxGeneratedPPNodeCount;
782 $this->mMaxPPExpandDepth
= $wgMaxPPExpandDepth;
783 $this->mMaxTemplateDepth
= $wgMaxTemplateDepth;
784 $this->mExpensiveParserFunctionLimit
= $wgExpensiveParserFunctionLimit;
785 $this->mCleanSignatures
= $wgCleanSignatures;
786 $this->mExternalLinkTarget
= $wgExternalLinkTarget;
787 $this->mDisableContentConversion
= $wgDisableLangConversion;
788 $this->mDisableTitleConversion
= $wgDisableLangConversion ||
$wgDisableTitleConversion;
789 $this->mMagicISBNLinks
= $wgEnableMagicLinks['ISBN'];
790 $this->mMagicPMIDLinks
= $wgEnableMagicLinks['PMID'];
791 $this->mMagicRFCLinks
= $wgEnableMagicLinks['RFC'];
793 $this->mUser
= $user;
794 $this->mNumberHeadings
= $user->getOption( 'numberheadings' );
795 $this->mThumbSize
= $user->getOption( 'thumbsize' );
796 $this->mStubThreshold
= $user->getStubThreshold();
797 $this->mUserLang
= $lang;
801 * Check if these options match that of another options set
803 * This ignores report limit settings that only affect HTML comments
805 * @param ParserOptions $other
809 public function matches( ParserOptions
$other ) {
810 $fields = array_keys( get_class_vars( __CLASS__
) );
811 $fields = array_diff( $fields, [
812 'mEnableLimitReport', // only effects HTML comments
813 'onAccessCallback', // only used for ParserOutput option tracking
815 foreach ( $fields as $field ) {
816 if ( !is_object( $this->$field ) && $this->$field !== $other->$field ) {
820 // Check the object and lazy-loaded options
822 $this->mUserLang
->equals( $other->mUserLang
) &&
823 $this->getDateFormat() === $other->getDateFormat()
828 * Registers a callback for tracking which ParserOptions which are used.
829 * This is a private API with the parser.
830 * @param callable $callback
832 public function registerWatcher( $callback ) {
833 $this->onAccessCallback
= $callback;
837 * Called when an option is accessed.
838 * Calls the watcher that was set using registerWatcher().
839 * Typically, the watcher callback is ParserOutput::registerOption().
840 * The information registered that way will be used by ParserCache::save().
842 * @param string $optionName Name of the option
844 public function optionUsed( $optionName ) {
845 if ( $this->onAccessCallback
) {
846 call_user_func( $this->onAccessCallback
, $optionName );
851 * Returns the full array of options that would have been used by
853 * Used to get the old parser cache entries when available.
856 public static function legacyOptions() {
868 * Generate a hash string with the values set on these ParserOptions
869 * for the keys given in the array.
870 * This will be used as part of the hash key for the parser cache,
871 * so users sharing the options with vary for the same page share
872 * the same cached data safely.
874 * Extensions which require it should install 'PageRenderingHash' hook,
875 * which will give them a chance to modify this key based on their own
879 * @param array $forOptions
880 * @param Title $title Used to get the content language of the page (since r97636)
881 * @return string Page rendering hash
883 public function optionsHash( $forOptions, $title = null ) {
884 global $wgRenderHashAppend;
886 // FIXME: Once the cache key is reorganized this argument
887 // can be dropped. It was used when the math extension was
891 // Space assigned for the stubthreshold but unused
892 // since it disables the parser cache, its value will always
893 // be 0 when this function is called by parsercache.
894 if ( in_array( 'stubthreshold', $forOptions ) ) {
895 $confstr .= '!' . $this->mStubThreshold
;
900 if ( in_array( 'dateformat', $forOptions ) ) {
901 $confstr .= '!' . $this->getDateFormat();
904 if ( in_array( 'numberheadings', $forOptions ) ) {
905 $confstr .= '!' . ( $this->mNumberHeadings ?
'1' : '' );
910 if ( in_array( 'userlang', $forOptions ) ) {
911 $confstr .= '!' . $this->mUserLang
->getCode();
916 if ( in_array( 'thumbsize', $forOptions ) ) {
917 $confstr .= '!' . $this->mThumbSize
;
922 // add in language specific options, if any
923 // @todo FIXME: This is just a way of retrieving the url/user preferred variant
924 if ( !is_null( $title ) ) {
925 $confstr .= $title->getPageLanguage()->getExtraHashOptions();
928 $confstr .= $wgContLang->getExtraHashOptions();
931 $confstr .= $wgRenderHashAppend;
933 // @note: as of Feb 2015, core never sets the editsection flag, since it uses
934 // <mw:editsection> tags to inject editsections on the fly. However, extensions
935 // may be using it by calling ParserOption::optionUsed resp. ParserOutput::registerOption
936 // directly. At least Wikibase does at this point in time.
937 if ( !in_array( 'editsection', $forOptions ) ) {
939 } elseif ( !$this->mEditSection
) {
940 $confstr .= '!edit=0';
943 if ( $this->mIsPrintable
&& in_array( 'printable', $forOptions ) ) {
944 $confstr .= '!printable=1';
947 if ( $this->wrapOutputClass
!== 'mw-parser-output' && in_array( 'wrapclass', $forOptions ) ) {
948 $confstr .= '!wrapclass=' . $this->wrapOutputClass
;
951 if ( $this->mExtraKey
!= '' ) {
952 $confstr .= $this->mExtraKey
;
955 // Give a chance for extensions to modify the hash, if they have
956 // extra options or other effects on the parser cache.
957 Hooks
::run( 'PageRenderingHash', [ &$confstr, $this->getUser(), &$forOptions ] );
959 // Make it a valid memcached key fragment
960 $confstr = str_replace( ' ', '_', $confstr );
966 * Sets a hook to force that a page exists, and sets a current revision callback to return
967 * a revision with custom content when the current revision of the page is requested.
970 * @param Title $title
971 * @param Content $content
972 * @param User $user The user that the fake revision is attributed to
973 * @return ScopedCallback to unset the hook
975 public function setupFakeRevision( $title, $content, $user ) {
976 $oldCallback = $this->setCurrentRevisionCallback(
978 $titleToCheck, $parser = false ) use ( $title, $content, $user, &$oldCallback
980 if ( $titleToCheck->equals( $title ) ) {
981 return new Revision( [
982 'page' => $title->getArticleID(),
983 'user_text' => $user->getName(),
984 'user' => $user->getId(),
985 'parent_id' => $title->getLatestRevID(),
987 'content' => $content
990 return call_user_func( $oldCallback, $titleToCheck, $parser );
996 $wgHooks['TitleExists'][] =
997 function ( $titleToCheck, &$exists ) use ( $title ) {
998 if ( $titleToCheck->equals( $title ) ) {
1002 end( $wgHooks['TitleExists'] );
1003 $key = key( $wgHooks['TitleExists'] );
1004 LinkCache
::singleton()->clearBadLink( $title->getPrefixedDBkey() );
1005 return new ScopedCallback( function () use ( $title, $key ) {
1007 unset( $wgHooks['TitleExists'][$key] );
1008 LinkCache
::singleton()->clearLink( $title );