ParserOptions.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
use Wikimedia\ScopedCallback;
 
class ParserOptions {
 
    const HAS_NEWCANONICAL_FROM_CONTEXT = 1;
 
    private static $defaults = null;
 
    private static $lazyOptions = [
        'dateformat' => [ __CLASS__, 'initDateFormat' ],
        'speculativeRevId' => [ __CLASS__, 'initSpeculativeRevId' ],
        'speculativePageId' => [ __CLASS__, 'initSpeculativePageId' ],
    ];
 
    private static $inCacheKey = [
        'dateformat' => true,
        'numberheadings' => true,
        'thumbsize' => true,
        'stubthreshold' => true,
        'printable' => true,
        'userlang' => true,
    ];
 
    private $options;
 
    private $mTimestamp;
 
    private $mUser;
 
    private $onAccessCallback = null;
 
    private $redirectTarget = null;
 
    private $mExtraKey = '';
 
    public function getOption( $name ) {
        if ( !array_key_exists( $name, $this->options ) ) {
            throw new InvalidArgumentException( "Unknown parser option $name" );
        }
 
        $this->lazyLoadOption( $name );
        if ( !empty( self::$inCacheKey[$name] ) ) {
            $this->optionUsed( $name );
        }
        return $this->options[$name];
    }
 
    private function lazyLoadOption( $name ) {
        if ( isset( self::$lazyOptions[$name] ) && $this->options[$name] === null ) {
            $this->options[$name] = call_user_func( self::$lazyOptions[$name], $this, $name );
        }
    }
 
    public function setOption( $name, $value ) {
        if ( !array_key_exists( $name, $this->options ) ) {
            throw new InvalidArgumentException( "Unknown parser option $name" );
        }
        $old = $this->options[$name];
        $this->options[$name] = $value;
        return $old;
    }
 
    protected function setOptionLegacy( $name, $value ) {
        if ( !array_key_exists( $name, $this->options ) ) {
            throw new InvalidArgumentException( "Unknown parser option $name" );
        }
        return wfSetVar( $this->options[$name], $value );
    }
 
    public function getInterwikiMagic() {
        return $this->getOption( 'interwikiMagic' );
    }
 
    public function setInterwikiMagic( $x ) {
        return $this->setOptionLegacy( 'interwikiMagic', $x );
    }
 
    public function getAllowExternalImages() {
        return $this->getOption( 'allowExternalImages' );
    }
 
    public function setAllowExternalImages( $x ) {
        return $this->setOptionLegacy( 'allowExternalImages', $x );
    }
 
    public function getAllowExternalImagesFrom() {
        return $this->getOption( 'allowExternalImagesFrom' );
    }
 
    public function setAllowExternalImagesFrom( $x ) {
        return $this->setOptionLegacy( 'allowExternalImagesFrom', $x );
    }
 
    public function getEnableImageWhitelist() {
        return $this->getOption( 'enableImageWhitelist' );
    }
 
    public function setEnableImageWhitelist( $x ) {
        return $this->setOptionLegacy( 'enableImageWhitelist', $x );
    }
 
    public function getNumberHeadings() {
        return $this->getOption( 'numberheadings' );
    }
 
    public function setNumberHeadings( $x ) {
        return $this->setOptionLegacy( 'numberheadings', $x );
    }
 
    public function getAllowSpecialInclusion() {
        return $this->getOption( 'allowSpecialInclusion' );
    }
 
    public function setAllowSpecialInclusion( $x ) {
        return $this->setOptionLegacy( 'allowSpecialInclusion', $x );
    }
 
    public function getTidy() {
        return $this->getOption( 'tidy' );
    }
 
    public function setTidy( $x ) {
        return $this->setOptionLegacy( 'tidy', $x );
    }
 
    public function getInterfaceMessage() {
        return $this->getOption( 'interfaceMessage' );
    }
 
    public function setInterfaceMessage( $x ) {
        return $this->setOptionLegacy( 'interfaceMessage', $x );
    }
 
    public function getTargetLanguage() {
        return $this->getOption( 'targetLanguage' );
    }
 
    public function setTargetLanguage( $x ) {
        return $this->setOption( 'targetLanguage', $x );
    }
 
    public function getMaxIncludeSize() {
        return $this->getOption( 'maxIncludeSize' );
    }
 
    public function setMaxIncludeSize( $x ) {
        return $this->setOptionLegacy( 'maxIncludeSize', $x );
    }
 
    public function getMaxPPNodeCount() {
        return $this->getOption( 'maxPPNodeCount' );
    }
 
    public function setMaxPPNodeCount( $x ) {
        return $this->setOptionLegacy( 'maxPPNodeCount', $x );
    }
 
    public function getMaxGeneratedPPNodeCount() {
        return $this->getOption( 'maxGeneratedPPNodeCount' );
    }
 
    public function setMaxGeneratedPPNodeCount( $x ) {
        return $this->setOptionLegacy( 'maxGeneratedPPNodeCount', $x );
    }
 
    public function getMaxPPExpandDepth() {
        return $this->getOption( 'maxPPExpandDepth' );
    }
 
    public function getMaxTemplateDepth() {
        return $this->getOption( 'maxTemplateDepth' );
    }
 
    public function setMaxTemplateDepth( $x ) {
        return $this->setOptionLegacy( 'maxTemplateDepth', $x );
    }
 
    public function getExpensiveParserFunctionLimit() {
        return $this->getOption( 'expensiveParserFunctionLimit' );
    }
 
    public function setExpensiveParserFunctionLimit( $x ) {
        return $this->setOptionLegacy( 'expensiveParserFunctionLimit', $x );
    }
 
    public function getRemoveComments() {
        return $this->getOption( 'removeComments' );
    }
 
    public function setRemoveComments( $x ) {
        return $this->setOptionLegacy( 'removeComments', $x );
    }
 
    public function getEnableLimitReport() {
        return $this->getOption( 'enableLimitReport' );
    }
 
    public function enableLimitReport( $x = true ) {
        return $this->setOptionLegacy( 'enableLimitReport', $x );
    }
 
    public function getCleanSignatures() {
        return $this->getOption( 'cleanSignatures' );
    }
 
    public function setCleanSignatures( $x ) {
        return $this->setOptionLegacy( 'cleanSignatures', $x );
    }
 
    public function getExternalLinkTarget() {
        return $this->getOption( 'externalLinkTarget' );
    }
 
    public function setExternalLinkTarget( $x ) {
        return $this->setOptionLegacy( 'externalLinkTarget', $x );
    }
 
    public function getDisableContentConversion() {
        return $this->getOption( 'disableContentConversion' );
    }
 
    public function disableContentConversion( $x = true ) {
        return $this->setOptionLegacy( 'disableContentConversion', $x );
    }
 
    public function getDisableTitleConversion() {
        return $this->getOption( 'disableTitleConversion' );
    }
 
    public function disableTitleConversion( $x = true ) {
        return $this->setOptionLegacy( 'disableTitleConversion', $x );
    }
 
    public function getThumbSize() {
        return $this->getOption( 'thumbsize' );
    }
 
    public function setThumbSize( $x ) {
        return $this->setOptionLegacy( 'thumbsize', $x );
    }
 
    public function getStubThreshold() {
        return $this->getOption( 'stubthreshold' );
    }
 
    public function setStubThreshold( $x ) {
        return $this->setOptionLegacy( 'stubthreshold', $x );
    }
 
    public function getIsPreview() {
        return $this->getOption( 'isPreview' );
    }
 
    public function setIsPreview( $x ) {
        return $this->setOptionLegacy( 'isPreview', $x );
    }
 
    public function getIsSectionPreview() {
        return $this->getOption( 'isSectionPreview' );
    }
 
    public function setIsSectionPreview( $x ) {
        return $this->setOptionLegacy( 'isSectionPreview', $x );
    }
 
    public function getIsPrintable() {
        return $this->getOption( 'printable' );
    }
 
    public function setIsPrintable( $x ) {
        return $this->setOptionLegacy( 'printable', $x );
    }
 
    public function getPreSaveTransform() {
        return $this->getOption( 'preSaveTransform' );
    }
 
    public function setPreSaveTransform( $x ) {
        return $this->setOptionLegacy( 'preSaveTransform', $x );
    }
 
    public function getDateFormat() {
        return $this->getOption( 'dateformat' );
    }
 
    private static function initDateFormat( ParserOptions $popt ) {
        return $popt->mUser->getDatePreference();
    }
 
    public function setDateFormat( $x ) {
        return $this->setOptionLegacy( 'dateformat', $x );
    }
 
    public function getUserLangObj() {
        return $this->getOption( 'userlang' );
    }
 
    public function getUserLang() {
        return $this->getUserLangObj()->getCode();
    }
 
    public function setUserLang( $x ) {
        if ( is_string( $x ) ) {
            $x = Language::factory( $x );
        }
 
        return $this->setOptionLegacy( 'userlang', $x );
    }
 
    public function getMagicISBNLinks() {
        return $this->getOption( 'magicISBNLinks' );
    }
 
    public function getMagicPMIDLinks() {
        return $this->getOption( 'magicPMIDLinks' );
    }
 
    public function getMagicRFCLinks() {
        return $this->getOption( 'magicRFCLinks' );
    }
 
    public function getAllowUnsafeRawHtml() {
        return $this->getOption( 'allowUnsafeRawHtml' );
    }
 
    public function setAllowUnsafeRawHtml( $x ) {
        return $this->setOptionLegacy( 'allowUnsafeRawHtml', $x );
    }
 
    public function getWrapOutputClass() {
        return $this->getOption( 'wrapclass' );
    }
 
    public function setWrapOutputClass( $className ) {
        if ( $className === true ) { // DWIM, they probably want the default class name
            $className = 'mw-parser-output';
        }
        if ( $className === false ) {
            wfDeprecated( __METHOD__ . '( false )', '1.31' );
        }
        return $this->setOption( 'wrapclass', $className );
    }
 
    public function getCurrentRevisionCallback() {
        return $this->getOption( 'currentRevisionCallback' );
    }
 
    public function setCurrentRevisionCallback( $x ) {
        return $this->setOptionLegacy( 'currentRevisionCallback', $x );
    }
 
    public function getTemplateCallback() {
        return $this->getOption( 'templateCallback' );
    }
 
    public function setTemplateCallback( $x ) {
        return $this->setOptionLegacy( 'templateCallback', $x );
    }
 
    public function getSpeculativeRevId() {
        return $this->getOption( 'speculativeRevId' );
    }
 
    public function getSpeculativePageId() {
        return $this->getOption( 'speculativePageId' );
    }
 
    private static function initSpeculativeRevId( ParserOptions $popt ) {
        $cb = $popt->getOption( 'speculativeRevIdCallback' );
        $id = $cb ? $cb() : null;
 
        // returning null would result in this being re-called every access
        return $id ?? false;
    }
 
    private static function initSpeculativePageId( ParserOptions $popt ) {
        $cb = $popt->getOption( 'speculativePageIdCallback' );
        $id = $cb ? $cb() : null;
 
        // returning null would result in this being re-called every access
        return $id ?? false;
    }
 
    public function setSpeculativeRevIdCallback( $x ) {
        $this->setOption( 'speculativeRevId', null ); // reset
        return $this->setOption( 'speculativeRevIdCallback', $x );
    }
 
    public function setSpeculativePageIdCallback( $x ) {
        $this->setOption( 'speculativePageId', null ); // reset
        return $this->setOption( 'speculativePageIdCallback', $x );
    }
 
    public function getTimestamp() {
        if ( !isset( $this->mTimestamp ) ) {
            $this->mTimestamp = wfTimestampNow();
        }
        return $this->mTimestamp;
    }
 
    public function setTimestamp( $x ) {
        return wfSetVar( $this->mTimestamp, $x );
    }
 
    function setRedirectTarget( $title ) {
        $this->redirectTarget = $title;
    }
 
    function getRedirectTarget() {
        return $this->redirectTarget;
    }
 
    public function addExtraKey( $key ) {
        $this->mExtraKey .= '!' . $key;
    }
 
    public function getUser() {
        return $this->mUser;
    }
 
    public function __construct( $user = null, $lang = null ) {
        if ( $user === null ) {
            global $wgUser;
            if ( $wgUser === null ) {
                $user = new User;
            } else {
                $user = $wgUser;
            }
        }
        if ( $lang === null ) {
            global $wgLang;
            if ( !StubObject::isRealObject( $wgLang ) ) {
                $wgLang->_unstub();
            }
            $lang = $wgLang;
        }
        $this->initialiseFromUser( $user, $lang );
    }
 
    public static function newFromAnon() {
        return new ParserOptions( new User,
            MediaWikiServices::getInstance()->getContentLanguage() );
    }
 
    public static function newFromUser( $user ) {
        return new ParserOptions( $user );
    }
 
    public static function newFromUserAndLang( User $user, Language $lang ) {
        return new ParserOptions( $user, $lang );
    }
 
    public static function newFromContext( IContextSource $context ) {
        return new ParserOptions( $context->getUser(), $context->getLanguage() );
    }
 
    public static function newCanonical( $context = null, $userLang = null ) {
        if ( $context instanceof IContextSource ) {
            $ret = self::newFromContext( $context );
        } elseif ( $context === 'canonical' ) {
            $ret = self::newFromAnon();
        } elseif ( $context instanceof User || $context === null ) {
            $ret = new self( $context, $userLang );
        } else {
            throw new InvalidArgumentException(
                '$context must be an IContextSource, the string "canonical", a User, or null'
            );
        }
 
        foreach ( self::getCanonicalOverrides() as $k => $v ) {
            $ret->setOption( $k, $v );
        }
        return $ret;
    }
 
    private static function getDefaults() {
        global $wgInterwikiMagic, $wgAllowExternalImages,
            $wgAllowExternalImagesFrom, $wgEnableImageWhitelist, $wgAllowSpecialInclusion,
            $wgMaxArticleSize, $wgMaxPPNodeCount, $wgMaxTemplateDepth, $wgMaxPPExpandDepth,
            $wgCleanSignatures, $wgExternalLinkTarget, $wgExpensiveParserFunctionLimit,
            $wgMaxGeneratedPPNodeCount, $wgDisableLangConversion, $wgDisableTitleConversion,
            $wgEnableMagicLinks;
 
        if ( self::$defaults === null ) {
            // *UPDATE* ParserOptions::matches() if any of this changes as needed
            self::$defaults = [
                'dateformat' => null,
                'tidy' => true,
                'interfaceMessage' => false,
                'targetLanguage' => null,
                'removeComments' => true,
                'enableLimitReport' => false,
                'preSaveTransform' => true,
                'isPreview' => false,
                'isSectionPreview' => false,
                'printable' => false,
                'allowUnsafeRawHtml' => true,
                'wrapclass' => 'mw-parser-output',
                'currentRevisionCallback' => [ Parser::class, 'statelessFetchRevision' ],
                'templateCallback' => [ Parser::class, 'statelessFetchTemplate' ],
                'speculativeRevIdCallback' => null,
                'speculativeRevId' => null,
                'speculativePageIdCallback' => null,
                'speculativePageId' => null,
            ];
 
            Hooks::run( 'ParserOptionsRegister', [
                &self::$defaults,
                &self::$inCacheKey,
                &self::$lazyOptions,
            ] );
 
            ksort( self::$inCacheKey );
        }
 
        // Unit tests depend on being able to modify the globals at will
        return self::$defaults + [
            'interwikiMagic' => $wgInterwikiMagic,
            'allowExternalImages' => $wgAllowExternalImages,
            'allowExternalImagesFrom' => $wgAllowExternalImagesFrom,
            'enableImageWhitelist' => $wgEnableImageWhitelist,
            'allowSpecialInclusion' => $wgAllowSpecialInclusion,
            'maxIncludeSize' => $wgMaxArticleSize * 1024,
            'maxPPNodeCount' => $wgMaxPPNodeCount,
            'maxGeneratedPPNodeCount' => $wgMaxGeneratedPPNodeCount,
            'maxPPExpandDepth' => $wgMaxPPExpandDepth,
            'maxTemplateDepth' => $wgMaxTemplateDepth,
            'expensiveParserFunctionLimit' => $wgExpensiveParserFunctionLimit,
            'externalLinkTarget' => $wgExternalLinkTarget,
            'cleanSignatures' => $wgCleanSignatures,
            'disableContentConversion' => $wgDisableLangConversion,
            'disableTitleConversion' => $wgDisableLangConversion || $wgDisableTitleConversion,
            'magicISBNLinks' => $wgEnableMagicLinks['ISBN'],
            'magicPMIDLinks' => $wgEnableMagicLinks['PMID'],
            'magicRFCLinks' => $wgEnableMagicLinks['RFC'],
            'numberheadings' => User::getDefaultOption( 'numberheadings' ),
            'thumbsize' => User::getDefaultOption( 'thumbsize' ),
            'stubthreshold' => 0,
            'userlang' => MediaWikiServices::getInstance()->getContentLanguage(),
        ];
    }
 
    private static function getCanonicalOverrides() {
        global $wgEnableParserLimitReporting;
 
        return [
            'enableLimitReport' => $wgEnableParserLimitReporting,
        ];
    }
 
    private function initialiseFromUser( $user, $lang ) {
        $this->options = self::getDefaults();
 
        $this->mUser = $user;
        $this->options['numberheadings'] = $user->getOption( 'numberheadings' );
        $this->options['thumbsize'] = $user->getOption( 'thumbsize' );
        $this->options['stubthreshold'] = $user->getStubThreshold();
        $this->options['userlang'] = $lang;
    }
 
    public function matches( ParserOptions $other ) {
        // Compare most options
        $options = array_keys( $this->options );
        $options = array_diff( $options, [
            'enableLimitReport', // only affects HTML comments
        ] );
        foreach ( $options as $option ) {
            // Resolve any lazy options
            $this->lazyLoadOption( $option );
            $other->lazyLoadOption( $option );
 
            $o1 = $this->optionToString( $this->options[$option] );
            $o2 = $this->optionToString( $other->options[$option] );
            if ( $o1 !== $o2 ) {
                return false;
            }
        }
 
        // Compare most other fields
        $fields = array_keys( get_class_vars( __CLASS__ ) );
        $fields = array_diff( $fields, [
            'defaults', // static
            'lazyOptions', // static
            'inCacheKey', // static
            'options', // Already checked above
            'onAccessCallback', // only used for ParserOutput option tracking
        ] );
        foreach ( $fields as $field ) {
            if ( !is_object( $this->$field ) && $this->$field !== $other->$field ) {
                return false;
            }
        }
 
        return true;
    }
 
    public function matchesForCacheKey( ParserOptions $other ) {
        foreach ( self::allCacheVaryingOptions() as $option ) {
            // Populate any lazy options
            $this->lazyLoadOption( $option );
            $other->lazyLoadOption( $option );
 
            $o1 = $this->optionToString( $this->options[$option] );
            $o2 = $this->optionToString( $other->options[$option] );
            if ( $o1 !== $o2 ) {
                return false;
            }
        }
 
        return true;
    }
 
    public function registerWatcher( $callback ) {
        $this->onAccessCallback = $callback;
    }
 
    public function optionUsed( $optionName ) {
        if ( $this->onAccessCallback ) {
            call_user_func( $this->onAccessCallback, $optionName );
        }
    }
 
    public static function allCacheVaryingOptions() {
        // Trigger a call to the 'ParserOptionsRegister' hook if it hasn't
        // already been called.
        if ( self::$defaults === null ) {
            self::getDefaults();
        }
        return array_keys( array_filter( self::$inCacheKey ) );
    }
 
    private function optionToString( $value ) {
        if ( $value === true ) {
            return '1';
        } elseif ( $value === false ) {
            return '0';
        } elseif ( $value === null ) {
            return '';
        } elseif ( $value instanceof Language ) {
            return $value->getCode();
        } elseif ( is_array( $value ) ) {
            return '[' . implode( ',', array_map( [ $this, 'optionToString' ], $value ) ) . ']';
        } else {
            return (string)$value;
        }
    }
 
    public function optionsHash( $forOptions, $title = null ) {
        global $wgRenderHashAppend;
 
        $inCacheKey = self::allCacheVaryingOptions();
 
        // Resolve any lazy options
        $lazyOpts = array_intersect( $forOptions, $inCacheKey, array_keys( self::$lazyOptions ) );
        foreach ( $lazyOpts as $k ) {
            $this->lazyLoadOption( $k );
        }
 
        $options = $this->options;
        $defaults = self::getCanonicalOverrides() + self::getDefaults();
 
        // We only include used options with non-canonical values in the key
        // so adding a new option doesn't invalidate the entire parser cache.
        // The drawback to this is that changing the default value of an option
        // requires manual invalidation of existing cache entries, as mentioned
        // in the docs on the relevant methods and hooks.
        $values = [];
        foreach ( array_intersect( $inCacheKey, $forOptions ) as $option ) {
            $v = $this->optionToString( $options[$option] );
            $d = $this->optionToString( $defaults[$option] );
            if ( $v !== $d ) {
                $values[] = "$option=$v";
            }
        }
 
        $confstr = $values ? implode( '!', $values ) : 'canonical';
 
        // add in language specific options, if any
        // @todo FIXME: This is just a way of retrieving the url/user preferred variant
        if ( !is_null( $title ) ) {
            $confstr .= $title->getPageLanguage()->getExtraHashOptions();
        } else {
            $confstr .=
                MediaWikiServices::getInstance()->getContentLanguage()->getExtraHashOptions();
        }
 
        $confstr .= $wgRenderHashAppend;
 
        if ( $this->mExtraKey != '' ) {
            $confstr .= $this->mExtraKey;
        }
 
        // Give a chance for extensions to modify the hash, if they have
        // extra options or other effects on the parser cache.
        Hooks::run( 'PageRenderingHash', [ &$confstr, $this->getUser(), &$forOptions ] );
 
        // Make it a valid memcached key fragment
        $confstr = str_replace( ' ', '_', $confstr );
 
        return $confstr;
    }
 
    public function isSafeToCache() {
        $defaults = self::getCanonicalOverrides() + self::getDefaults();
        foreach ( $this->options as $option => $value ) {
            if ( empty( self::$inCacheKey[$option] ) ) {
                $v = $this->optionToString( $value );
                $d = $this->optionToString( $defaults[$option] );
                if ( $v !== $d ) {
                    return false;
                }
            }
        }
        return true;
    }
 
    public function setupFakeRevision( $title, $content, $user ) {
        $oldCallback = $this->setCurrentRevisionCallback(
            function (
                $titleToCheck, $parser = false ) use ( $title, $content, $user, &$oldCallback
            ) {
                if ( $titleToCheck->equals( $title ) ) {
                    return new Revision( [
                        'page' => $title->getArticleID(),
                        'user_text' => $user->getName(),
                        'user' => $user->getId(),
                        'parent_id' => $title->getLatestRevID(),
                        'title' => $title,
                        'content' => $content
                    ] );
                } else {
                    return call_user_func( $oldCallback, $titleToCheck, $parser );
                }
            }
        );
 
        global $wgHooks;
        $wgHooks['TitleExists'][] =
            function ( $titleToCheck, &$exists ) use ( $title ) {
                if ( $titleToCheck->equals( $title ) ) {
                    $exists = true;
                }
            };
        end( $wgHooks['TitleExists'] );
        $key = key( $wgHooks['TitleExists'] );
        $linkCache = MediaWikiServices::getInstance()->getLinkCache();
        $linkCache->clearBadLink( $title->getPrefixedDBkey() );
        return new ScopedCallback( function () use ( $title, $key, $linkCache ) {
            global $wgHooks;
            unset( $wgHooks['TitleExists'][$key] );
            $linkCache->clearLink( $title );
        } );
    }
}