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 return $this->wrapOutputClass
;
499 public function setInterwikiMagic( $x ) {
500 return wfSetVar( $this->mInterwikiMagic
, $x );
503 public function setAllowExternalImages( $x ) {
504 return wfSetVar( $this->mAllowExternalImages
, $x );
507 public function setAllowExternalImagesFrom( $x ) {
508 return wfSetVar( $this->mAllowExternalImagesFrom
, $x );
511 public function setEnableImageWhitelist( $x ) {
512 return wfSetVar( $this->mEnableImageWhitelist
, $x );
515 public function setDateFormat( $x ) {
516 return wfSetVar( $this->mDateFormat
, $x );
519 public function setEditSection( $x ) {
520 return wfSetVar( $this->mEditSection
, $x );
523 public function setNumberHeadings( $x ) {
524 return wfSetVar( $this->mNumberHeadings
, $x );
527 public function setAllowSpecialInclusion( $x ) {
528 return wfSetVar( $this->mAllowSpecialInclusion
, $x );
531 public function setTidy( $x ) {
532 return wfSetVar( $this->mTidy
, $x );
535 public function setInterfaceMessage( $x ) {
536 return wfSetVar( $this->mInterfaceMessage
, $x );
539 public function setTargetLanguage( $x ) {
540 return wfSetVar( $this->mTargetLanguage
, $x, true );
543 public function setMaxIncludeSize( $x ) {
544 return wfSetVar( $this->mMaxIncludeSize
, $x );
547 public function setMaxPPNodeCount( $x ) {
548 return wfSetVar( $this->mMaxPPNodeCount
, $x );
551 public function setMaxGeneratedPPNodeCount( $x ) {
552 return wfSetVar( $this->mMaxGeneratedPPNodeCount
, $x );
555 public function setMaxTemplateDepth( $x ) {
556 return wfSetVar( $this->mMaxTemplateDepth
, $x );
560 public function setExpensiveParserFunctionLimit( $x ) {
561 return wfSetVar( $this->mExpensiveParserFunctionLimit
, $x );
564 public function setRemoveComments( $x ) {
565 return wfSetVar( $this->mRemoveComments
, $x );
569 public function setCurrentRevisionCallback( $x ) {
570 return wfSetVar( $this->mCurrentRevisionCallback
, $x );
574 public function setSpeculativeRevIdCallback( $x ) {
575 return wfSetVar( $this->mSpeculativeRevIdCallback
, $x );
578 public function setTemplateCallback( $x ) {
579 return wfSetVar( $this->mTemplateCallback
, $x );
582 public function enableLimitReport( $x = true ) {
583 return wfSetVar( $this->mEnableLimitReport
, $x );
586 public function setTimestamp( $x ) {
587 return wfSetVar( $this->mTimestamp
, $x );
590 public function setCleanSignatures( $x ) {
591 return wfSetVar( $this->mCleanSignatures
, $x );
594 public function setExternalLinkTarget( $x ) {
595 return wfSetVar( $this->mExternalLinkTarget
, $x );
598 public function disableContentConversion( $x = true ) {
599 return wfSetVar( $this->mDisableContentConversion
, $x );
602 public function disableTitleConversion( $x = true ) {
603 return wfSetVar( $this->mDisableTitleConversion
, $x );
606 public function setUserLang( $x ) {
607 if ( is_string( $x ) ) {
608 $x = Language
::factory( $x );
611 return wfSetVar( $this->mUserLang
, $x );
614 public function setThumbSize( $x ) {
615 return wfSetVar( $this->mThumbSize
, $x );
618 public function setStubThreshold( $x ) {
619 return wfSetVar( $this->mStubThreshold
, $x );
622 public function setPreSaveTransform( $x ) {
623 return wfSetVar( $this->mPreSaveTransform
, $x );
626 public function setIsPreview( $x ) {
627 return wfSetVar( $this->mIsPreview
, $x );
630 public function setIsSectionPreview( $x ) {
631 return wfSetVar( $this->mIsSectionPreview
, $x );
634 public function setIsPrintable( $x ) {
635 return wfSetVar( $this->mIsPrintable
, $x );
639 * @param bool|null Value to set or null to get current value
640 * @return bool Current value for allowUnsafeRawHtml
643 public function setAllowUnsafeRawHtml( $x ) {
644 return wfSetVar( $this->allowUnsafeRawHtml
, $x );
648 * CSS class to use to wrap output from Parser::parse()
650 * @param string|bool $className Set false to disable wrapping.
651 * @return string|bool Current value
653 public function setWrapOutputClass( $className ) {
654 if ( $className === true ) { // DWIM, they probably want the default class name
655 $className = 'mw-parser-output';
657 return wfSetVar( $this->wrapOutputClass
, $className );
661 * Set the redirect target.
663 * Note that setting or changing this does not *make* the page a redirect
664 * or change its target, it merely records the information for reference
668 * @param Title|null $title
670 function setRedirectTarget( $title ) {
671 $this->redirectTarget
= $title;
675 * Get the previously-set redirect target.
680 function getRedirectTarget() {
681 return $this->redirectTarget
;
685 * Extra key that should be present in the parser cache key.
688 public function addExtraKey( $key ) {
689 $this->mExtraKey
.= '!' . $key;
695 * @param Language $lang
697 public function __construct( $user = null, $lang = null ) {
698 if ( $user === null ) {
700 if ( $wgUser === null ) {
706 if ( $lang === null ) {
708 if ( !StubObject
::isRealObject( $wgLang ) ) {
713 $this->initialiseFromUser( $user, $lang );
717 * Get a ParserOptions object for an anonymous user
719 * @return ParserOptions
721 public static function newFromAnon() {
723 return new ParserOptions( new User
, $wgContLang );
727 * Get a ParserOptions object from a given user.
728 * Language will be taken from $wgLang.
731 * @return ParserOptions
733 public static function newFromUser( $user ) {
734 return new ParserOptions( $user );
738 * Get a ParserOptions object from a given user and language
741 * @param Language $lang
742 * @return ParserOptions
744 public static function newFromUserAndLang( User
$user, Language
$lang ) {
745 return new ParserOptions( $user, $lang );
749 * Get a ParserOptions object from a IContextSource object
751 * @param IContextSource $context
752 * @return ParserOptions
754 public static function newFromContext( IContextSource
$context ) {
755 return new ParserOptions( $context->getUser(), $context->getLanguage() );
762 * @param Language $lang
764 private function initialiseFromUser( $user, $lang ) {
765 global $wgInterwikiMagic, $wgAllowExternalImages,
766 $wgAllowExternalImagesFrom, $wgEnableImageWhitelist, $wgAllowSpecialInclusion,
767 $wgMaxArticleSize, $wgMaxPPNodeCount, $wgMaxTemplateDepth, $wgMaxPPExpandDepth,
768 $wgCleanSignatures, $wgExternalLinkTarget, $wgExpensiveParserFunctionLimit,
769 $wgMaxGeneratedPPNodeCount, $wgDisableLangConversion, $wgDisableTitleConversion,
772 // *UPDATE* ParserOptions::matches() if any of this changes as needed
773 $this->mInterwikiMagic
= $wgInterwikiMagic;
774 $this->mAllowExternalImages
= $wgAllowExternalImages;
775 $this->mAllowExternalImagesFrom
= $wgAllowExternalImagesFrom;
776 $this->mEnableImageWhitelist
= $wgEnableImageWhitelist;
777 $this->mAllowSpecialInclusion
= $wgAllowSpecialInclusion;
778 $this->mMaxIncludeSize
= $wgMaxArticleSize * 1024;
779 $this->mMaxPPNodeCount
= $wgMaxPPNodeCount;
780 $this->mMaxGeneratedPPNodeCount
= $wgMaxGeneratedPPNodeCount;
781 $this->mMaxPPExpandDepth
= $wgMaxPPExpandDepth;
782 $this->mMaxTemplateDepth
= $wgMaxTemplateDepth;
783 $this->mExpensiveParserFunctionLimit
= $wgExpensiveParserFunctionLimit;
784 $this->mCleanSignatures
= $wgCleanSignatures;
785 $this->mExternalLinkTarget
= $wgExternalLinkTarget;
786 $this->mDisableContentConversion
= $wgDisableLangConversion;
787 $this->mDisableTitleConversion
= $wgDisableLangConversion ||
$wgDisableTitleConversion;
788 $this->mMagicISBNLinks
= $wgEnableMagicLinks['ISBN'];
789 $this->mMagicPMIDLinks
= $wgEnableMagicLinks['PMID'];
790 $this->mMagicRFCLinks
= $wgEnableMagicLinks['RFC'];
792 $this->mUser
= $user;
793 $this->mNumberHeadings
= $user->getOption( 'numberheadings' );
794 $this->mThumbSize
= $user->getOption( 'thumbsize' );
795 $this->mStubThreshold
= $user->getStubThreshold();
796 $this->mUserLang
= $lang;
800 * Check if these options match that of another options set
802 * This ignores report limit settings that only affect HTML comments
804 * @param ParserOptions $other
808 public function matches( ParserOptions
$other ) {
809 $fields = array_keys( get_class_vars( __CLASS__
) );
810 $fields = array_diff( $fields, [
811 'mEnableLimitReport', // only effects HTML comments
812 'onAccessCallback', // only used for ParserOutput option tracking
814 foreach ( $fields as $field ) {
815 if ( !is_object( $this->$field ) && $this->$field !== $other->$field ) {
819 // Check the object and lazy-loaded options
821 $this->mUserLang
->equals( $other->mUserLang
) &&
822 $this->getDateFormat() === $other->getDateFormat()
827 * Registers a callback for tracking which ParserOptions which are used.
828 * This is a private API with the parser.
829 * @param callable $callback
831 public function registerWatcher( $callback ) {
832 $this->onAccessCallback
= $callback;
836 * Called when an option is accessed.
837 * Calls the watcher that was set using registerWatcher().
838 * Typically, the watcher callback is ParserOutput::registerOption().
839 * The information registered that way will be used by ParserCache::save().
841 * @param string $optionName Name of the option
843 public function optionUsed( $optionName ) {
844 if ( $this->onAccessCallback
) {
845 call_user_func( $this->onAccessCallback
, $optionName );
850 * Returns the full array of options that would have been used by
852 * Used to get the old parser cache entries when available.
855 public static function legacyOptions() {
867 * Generate a hash string with the values set on these ParserOptions
868 * for the keys given in the array.
869 * This will be used as part of the hash key for the parser cache,
870 * so users sharing the options with vary for the same page share
871 * the same cached data safely.
873 * Extensions which require it should install 'PageRenderingHash' hook,
874 * which will give them a chance to modify this key based on their own
878 * @param array $forOptions
879 * @param Title $title Used to get the content language of the page (since r97636)
880 * @return string Page rendering hash
882 public function optionsHash( $forOptions, $title = null ) {
883 global $wgRenderHashAppend;
885 // FIXME: Once the cache key is reorganized this argument
886 // can be dropped. It was used when the math extension was
890 // Space assigned for the stubthreshold but unused
891 // since it disables the parser cache, its value will always
892 // be 0 when this function is called by parsercache.
893 if ( in_array( 'stubthreshold', $forOptions ) ) {
894 $confstr .= '!' . $this->mStubThreshold
;
899 if ( in_array( 'dateformat', $forOptions ) ) {
900 $confstr .= '!' . $this->getDateFormat();
903 if ( in_array( 'numberheadings', $forOptions ) ) {
904 $confstr .= '!' . ( $this->mNumberHeadings ?
'1' : '' );
909 if ( in_array( 'userlang', $forOptions ) ) {
910 $confstr .= '!' . $this->mUserLang
->getCode();
915 if ( in_array( 'thumbsize', $forOptions ) ) {
916 $confstr .= '!' . $this->mThumbSize
;
921 // add in language specific options, if any
922 // @todo FIXME: This is just a way of retrieving the url/user preferred variant
923 if ( !is_null( $title ) ) {
924 $confstr .= $title->getPageLanguage()->getExtraHashOptions();
927 $confstr .= $wgContLang->getExtraHashOptions();
930 $confstr .= $wgRenderHashAppend;
932 // @note: as of Feb 2015, core never sets the editsection flag, since it uses
933 // <mw:editsection> tags to inject editsections on the fly. However, extensions
934 // may be using it by calling ParserOption::optionUsed resp. ParserOutput::registerOption
935 // directly. At least Wikibase does at this point in time.
936 if ( !in_array( 'editsection', $forOptions ) ) {
938 } elseif ( !$this->mEditSection
) {
939 $confstr .= '!edit=0';
942 if ( $this->mIsPrintable
&& in_array( 'printable', $forOptions ) ) {
943 $confstr .= '!printable=1';
946 if ( $this->mExtraKey
!= '' ) {
947 $confstr .= $this->mExtraKey
;
950 // Give a chance for extensions to modify the hash, if they have
951 // extra options or other effects on the parser cache.
952 Hooks
::run( 'PageRenderingHash', [ &$confstr, $this->getUser(), &$forOptions ] );
954 // Make it a valid memcached key fragment
955 $confstr = str_replace( ' ', '_', $confstr );
961 * Sets a hook to force that a page exists, and sets a current revision callback to return
962 * a revision with custom content when the current revision of the page is requested.
965 * @param Title $title
966 * @param Content $content
967 * @param User $user The user that the fake revision is attributed to
968 * @return ScopedCallback to unset the hook
970 public function setupFakeRevision( $title, $content, $user ) {
971 $oldCallback = $this->setCurrentRevisionCallback(
973 $titleToCheck, $parser = false ) use ( $title, $content, $user, &$oldCallback
975 if ( $titleToCheck->equals( $title ) ) {
976 return new Revision( [
977 'page' => $title->getArticleID(),
978 'user_text' => $user->getName(),
979 'user' => $user->getId(),
980 'parent_id' => $title->getLatestRevID(),
982 'content' => $content
985 return call_user_func( $oldCallback, $titleToCheck, $parser );
991 $wgHooks['TitleExists'][] =
992 function ( $titleToCheck, &$exists ) use ( $title ) {
993 if ( $titleToCheck->equals( $title ) ) {
997 end( $wgHooks['TitleExists'] );
998 $key = key( $wgHooks['TitleExists'] );
999 LinkCache
::singleton()->clearBadLink( $title->getPrefixedDBkey() );
1000 return new ScopedCallback( function () use ( $title, $key ) {
1002 unset( $wgHooks['TitleExists'][$key] );
1003 LinkCache
::singleton()->clearLink( $title );