ApiBase.php

Go to the documentation of this file.

<?php
use Wikimedia\Rdbms\IDatabase;
 
abstract class ApiBase extends ContextSource {
 
    const PARAM_DFLT = 0;
 
    const PARAM_ISMULTI = 1;
 
    const PARAM_TYPE = 2;
 
    const PARAM_MAX = 3;
 
    const PARAM_MAX2 = 4;
 
    const PARAM_MIN = 5;
 
    const PARAM_ALLOW_DUPLICATES = 6;
 
    const PARAM_DEPRECATED = 7;
 
    const PARAM_REQUIRED = 8;
 
    const PARAM_RANGE_ENFORCE = 9;
 
    const PARAM_HELP_MSG = 10;
 
    const PARAM_HELP_MSG_APPEND = 11;
 
    const PARAM_HELP_MSG_INFO = 12;
 
    const PARAM_VALUE_LINKS = 13;
 
    const PARAM_HELP_MSG_PER_VALUE = 14;
 
    const PARAM_SUBMODULE_MAP = 15;
 
    const PARAM_SUBMODULE_PARAM_PREFIX = 16;
 
    const PARAM_ALL = 17;
 
    const PARAM_EXTRA_NAMESPACES = 18;
 
    const PARAM_SENSITIVE = 19;
 
    const PARAM_DEPRECATED_VALUES = 20;
 
    const PARAM_ISMULTI_LIMIT1 = 21;
 
    const PARAM_ISMULTI_LIMIT2 = 22;
 
    const PARAM_MAX_BYTES = 23;
 
    const PARAM_MAX_CHARS = 24;
 
    const PARAM_TEMPLATE_VARS = 25;
 
    const ALL_DEFAULT_STRING = '*';
 
    const LIMIT_BIG1 = 500;
    const LIMIT_BIG2 = 5000;
    const LIMIT_SML1 = 50;
    const LIMIT_SML2 = 500;
 
    const GET_VALUES_FOR_HELP = 1;
 
    private static $extensionInfo = null;
 
    private static $filterIDsCache = [];
 
    private static $blockMsgMap = [
        'blockedtext' => [ 'apierror-blocked', 'blocked' ],
        'blockedtext-partial' => [ 'apierror-blocked', 'blocked' ],
        'autoblockedtext' => [ 'apierror-autoblocked', 'autoblocked' ],
        'systemblockedtext' => [ 'apierror-systemblocked', 'blocked' ],
    ];
 
    private $mMainModule;
    private $mModuleName, $mModulePrefix;
    private $mReplicaDB = null;
    private $mParamCache = [];
    private $mModuleSource = false;
 
    public function __construct( ApiMain $mainModule, $moduleName, $modulePrefix = '' ) {
        $this->mMainModule = $mainModule;
        $this->mModuleName = $moduleName;
        $this->mModulePrefix = $modulePrefix;
 
        if ( !$this->isMain() ) {
            $this->setContext( $mainModule->getContext() );
        }
    }
 
    /************************************************************************/
    abstract public function execute();
 
    public function getModuleManager() {
        return null;
    }
 
    public function getCustomPrinter() {
        return null;
    }
 
    protected function getExamplesMessages() {
        return [];
    }
 
    public function getHelpUrls() {
        return [];
    }
 
    protected function getAllowedParams( /* $flags = 0 */ ) {
        // int $flags is not declared because it causes "Strict standards"
        // warning. Most derived classes do not implement it.
        return [];
    }
 
    public function shouldCheckMaxlag() {
        return true;
    }
 
    public function isReadMode() {
        return true;
    }
 
    public function isWriteMode() {
        return false;
    }
 
    public function mustBePosted() {
        return $this->needsToken() !== false;
    }
 
    public function isDeprecated() {
        return false;
    }
 
    public function isInternal() {
        return false;
    }
 
    public function needsToken() {
        return false;
    }
 
    protected function getWebUITokenSalt( array $params ) {
        return null;
    }
 
    public function getConditionalRequestData( $condition ) {
        return null;
    }
 
    /************************************************************************/
    public function getModuleName() {
        return $this->mModuleName;
    }
 
    public function getModulePrefix() {
        return $this->mModulePrefix;
    }
 
    public function getMain() {
        return $this->mMainModule;
    }
 
    public function isMain() {
        return $this === $this->mMainModule;
    }
 
    public function getParent() {
        return $this->isMain() ? null : $this->getMain();
    }
 
    public function lacksSameOriginSecurity() {
        // Main module has this method overridden
        // Safety - avoid infinite loop:
        if ( $this->isMain() ) {
            self::dieDebug( __METHOD__, 'base method was called on main module.' );
        }
 
        return $this->getMain()->lacksSameOriginSecurity();
    }
 
    public function getModulePath() {
        if ( $this->isMain() ) {
            return 'main';
        } elseif ( $this->getParent()->isMain() ) {
            return $this->getModuleName();
        } else {
            return $this->getParent()->getModulePath() . '+' . $this->getModuleName();
        }
    }
 
    public function getModuleFromPath( $path ) {
        $module = $this->getMain();
        if ( $path === 'main' ) {
            return $module;
        }
 
        $parts = explode( '+', $path );
        if ( count( $parts ) === 1 ) {
            // In case the '+' was typed into URL, it resolves as a space
            $parts = explode( ' ', $path );
        }
 
        $count = count( $parts );
        for ( $i = 0; $i < $count; $i++ ) {
            $parent = $module;
            $manager = $parent->getModuleManager();
            if ( $manager === null ) {
                $errorPath = implode( '+', array_slice( $parts, 0, $i ) );
                $this->dieWithError( [ 'apierror-badmodule-nosubmodules', $errorPath ], 'badmodule' );
            }
            $module = $manager->getModule( $parts[$i] );
 
            if ( $module === null ) {
                $errorPath = $i ? implode( '+', array_slice( $parts, 0, $i ) ) : $parent->getModuleName();
                $this->dieWithError(
                    [ 'apierror-badmodule-badsubmodule', $errorPath, wfEscapeWikiText( $parts[$i] ) ],
                    'badmodule'
                );
            }
        }
 
        return $module;
    }
 
    public function getResult() {
        // Main module has getResult() method overridden
        // Safety - avoid infinite loop:
        if ( $this->isMain() ) {
            self::dieDebug( __METHOD__, 'base method was called on main module. ' );
        }
 
        return $this->getMain()->getResult();
    }
 
    public function getErrorFormatter() {
        // Main module has getErrorFormatter() method overridden
        // Safety - avoid infinite loop:
        if ( $this->isMain() ) {
            self::dieDebug( __METHOD__, 'base method was called on main module. ' );
        }
 
        return $this->getMain()->getErrorFormatter();
    }
 
    protected function getDB() {
        if ( !isset( $this->mReplicaDB ) ) {
            $this->mReplicaDB = wfGetDB( DB_REPLICA, 'api' );
        }
 
        return $this->mReplicaDB;
    }
 
    public function getContinuationManager() {
        // Main module has getContinuationManager() method overridden
        // Safety - avoid infinite loop:
        if ( $this->isMain() ) {
            self::dieDebug( __METHOD__, 'base method was called on main module. ' );
        }
 
        return $this->getMain()->getContinuationManager();
    }
 
    public function setContinuationManager( ApiContinuationManager $manager = null ) {
        // Main module has setContinuationManager() method overridden
        // Safety - avoid infinite loop:
        if ( $this->isMain() ) {
            self::dieDebug( __METHOD__, 'base method was called on main module. ' );
        }
 
        $this->getMain()->setContinuationManager( $manager );
    }
 
    /************************************************************************/
    public function dynamicParameterDocumentation() {
        return null;
    }
 
    public function encodeParamName( $paramName ) {
        if ( is_array( $paramName ) ) {
            return array_map( function ( $name ) {
                return $this->mModulePrefix . $name;
            }, $paramName );
        } else {
            return $this->mModulePrefix . $paramName;
        }
    }
 
    public function extractRequestParams( $options = [] ) {
        if ( is_bool( $options ) ) {
            $options = [ 'parseLimit' => $options ];
        }
        $options += [
            'parseLimit' => true,
            'safeMode' => false,
        ];
 
        $parseLimit = (bool)$options['parseLimit'];
 
        // Cache parameters, for performance and to avoid T26564.
        if ( !isset( $this->mParamCache[$parseLimit] ) ) {
            $params = $this->getFinalParams() ?: [];
            $results = [];
            $warned = [];
 
            // Process all non-templates and save templates for secondary
            // processing.
            $toProcess = [];
            foreach ( $params as $paramName => $paramSettings ) {
                if ( isset( $paramSettings[self::PARAM_TEMPLATE_VARS] ) ) {
                    $toProcess[] = [ $paramName, $paramSettings[self::PARAM_TEMPLATE_VARS], $paramSettings ];
                } else {
                    try {
                        $results[$paramName] = $this->getParameterFromSettings(
                            $paramName, $paramSettings, $parseLimit
                        );
                    } catch ( ApiUsageException $ex ) {
                        $results[$paramName] = $ex;
                    }
                }
            }
 
            // Now process all the templates by successively replacing the
            // placeholders with all client-supplied values.
            // This bit duplicates JavaScript logic in
            // ApiSandbox.PageLayout.prototype.updateTemplatedParams().
            // If you update this, see if that needs updating too.
            while ( $toProcess ) {
                list( $name, $targets, $settings ) = array_shift( $toProcess );
 
                foreach ( $targets as $placeholder => $target ) {
                    if ( !array_key_exists( $target, $results ) ) {
                        // The target wasn't processed yet, try the next one.
                        // If all hit this case, the parameter has no expansions.
                        continue;
                    }
                    if ( !is_array( $results[$target] ) || !$results[$target] ) {
                        // The target was processed but has no (valid) values.
                        // That means it has no expansions.
                        break;
                    }
 
                    // Expand this target in the name and all other targets,
                    // then requeue if there are more targets left or put in
                    // $results if all are done.
                    unset( $targets[$placeholder] );
                    $placeholder = '{' . $placeholder . '}';
                    // @phan-suppress-next-line PhanTypeNoAccessiblePropertiesForeach
                    foreach ( $results[$target] as $value ) {
                        if ( !preg_match( '/^[^{}]*$/', $value ) ) {
                            // Skip values that make invalid parameter names.
                            $encTargetName = $this->encodeParamName( $target );
                            if ( !isset( $warned[$encTargetName][$value] ) ) {
                                $warned[$encTargetName][$value] = true;
                                $this->addWarning( [
                                    'apiwarn-ignoring-invalid-templated-value',
                                    wfEscapeWikiText( $encTargetName ),
                                    wfEscapeWikiText( $value ),
                                ] );
                            }
                            continue;
                        }
 
                        $newName = str_replace( $placeholder, $value, $name );
                        if ( !$targets ) {
                            try {
                                $results[$newName] = $this->getParameterFromSettings( $newName, $settings, $parseLimit );
                            } catch ( ApiUsageException $ex ) {
                                $results[$newName] = $ex;
                            }
                        } else {
                            $newTargets = [];
                            foreach ( $targets as $k => $v ) {
                                $newTargets[$k] = str_replace( $placeholder, $value, $v );
                            }
                            $toProcess[] = [ $newName, $newTargets, $settings ];
                        }
                    }
                    break;
                }
            }
 
            $this->mParamCache[$parseLimit] = $results;
        }
 
        $ret = $this->mParamCache[$parseLimit];
        if ( !$options['safeMode'] ) {
            foreach ( $ret as $v ) {
                if ( $v instanceof ApiUsageException ) {
                    throw $v;
                }
            }
        }
 
        return $this->mParamCache[$parseLimit];
    }
 
    protected function getParameter( $paramName, $parseLimit = true ) {
        $ret = $this->extractRequestParams( [
            'parseLimit' => $parseLimit,
            'safeMode' => true,
        ] )[$paramName];
        if ( $ret instanceof ApiUsageException ) {
            throw $ret;
        }
        return $ret;
    }
 
    public function requireOnlyOneParameter( $params, $required /*...*/ ) {
        $required = func_get_args();
        array_shift( $required );
 
        $intersection = array_intersect( array_keys( array_filter( $params,
            [ $this, 'parameterNotEmpty' ] ) ), $required );
 
        if ( count( $intersection ) > 1 ) {
            $this->dieWithError( [
                'apierror-invalidparammix',
                Message::listParam( array_map(
                    function ( $p ) {
                        return '<var>' . $this->encodeParamName( $p ) . '</var>';
                    },
                    array_values( $intersection )
                ) ),
                count( $intersection ),
            ] );
        } elseif ( count( $intersection ) == 0 ) {
            $this->dieWithError( [
                'apierror-missingparam-one-of',
                Message::listParam( array_map(
                    function ( $p ) {
                        return '<var>' . $this->encodeParamName( $p ) . '</var>';
                    },
                    array_values( $required )
                ) ),
                count( $required ),
            ], 'missingparam' );
        }
    }
 
    public function requireMaxOneParameter( $params, $required /*...*/ ) {
        $required = func_get_args();
        array_shift( $required );
 
        $intersection = array_intersect( array_keys( array_filter( $params,
            [ $this, 'parameterNotEmpty' ] ) ), $required );
 
        if ( count( $intersection ) > 1 ) {
            $this->dieWithError( [
                'apierror-invalidparammix',
                Message::listParam( array_map(
                    function ( $p ) {
                        return '<var>' . $this->encodeParamName( $p ) . '</var>';
                    },
                    array_values( $intersection )
                ) ),
                count( $intersection ),
            ] );
        }
    }
 
    public function requireAtLeastOneParameter( $params, $required /*...*/ ) {
        $required = func_get_args();
        array_shift( $required );
 
        $intersection = array_intersect(
            array_keys( array_filter( $params, [ $this, 'parameterNotEmpty' ] ) ),
            $required
        );
 
        if ( count( $intersection ) == 0 ) {
            $this->dieWithError( [
                'apierror-missingparam-at-least-one-of',
                Message::listParam( array_map(
                    function ( $p ) {
                        return '<var>' . $this->encodeParamName( $p ) . '</var>';
                    },
                    array_values( $required )
                ) ),
                count( $required ),
            ], 'missingparam' );
        }
    }
 
    public function requirePostedParameters( $params, $prefix = 'prefix' ) {
        // Skip if $wgDebugAPI is set or we're in internal mode
        if ( $this->getConfig()->get( 'DebugAPI' ) || $this->getMain()->isInternalMode() ) {
            return;
        }
 
        $queryValues = $this->getRequest()->getQueryValues();
        $badParams = [];
        foreach ( $params as $param ) {
            if ( $prefix !== 'noprefix' ) {
                $param = $this->encodeParamName( $param );
            }
            if ( array_key_exists( $param, $queryValues ) ) {
                $badParams[] = $param;
            }
        }
 
        if ( $badParams ) {
            $this->dieWithError(
                [ 'apierror-mustpostparams', implode( ', ', $badParams ), count( $badParams ) ]
            );
        }
    }
 
    private function parameterNotEmpty( $x ) {
        return !is_null( $x ) && $x !== false;
    }
 
    public function getTitleOrPageId( $params, $load = false ) {
        $this->requireOnlyOneParameter( $params, 'title', 'pageid' );
 
        $pageObj = null;
        if ( isset( $params['title'] ) ) {
            $titleObj = Title::newFromText( $params['title'] );
            if ( !$titleObj || $titleObj->isExternal() ) {
                $this->dieWithError( [ 'apierror-invalidtitle', wfEscapeWikiText( $params['title'] ) ] );
            }
            if ( !$titleObj->canExist() ) {
                $this->dieWithError( 'apierror-pagecannotexist' );
            }
            $pageObj = WikiPage::factory( $titleObj );
            if ( $load !== false ) {
                $pageObj->loadPageData( $load );
            }
        } elseif ( isset( $params['pageid'] ) ) {
            if ( $load === false ) {
                $load = 'fromdb';
            }
            $pageObj = WikiPage::newFromID( $params['pageid'], $load );
            if ( !$pageObj ) {
                $this->dieWithError( [ 'apierror-nosuchpageid', $params['pageid'] ] );
            }
        }
 
        return $pageObj;
    }
 
    public function getTitleFromTitleOrPageId( $params ) {
        $this->requireOnlyOneParameter( $params, 'title', 'pageid' );
 
        $titleObj = null;
        if ( isset( $params['title'] ) ) {
            $titleObj = Title::newFromText( $params['title'] );
            if ( !$titleObj || $titleObj->isExternal() ) {
                $this->dieWithError( [ 'apierror-invalidtitle', wfEscapeWikiText( $params['title'] ) ] );
            }
            return $titleObj;
        } elseif ( isset( $params['pageid'] ) ) {
            $titleObj = Title::newFromID( $params['pageid'] );
            if ( !$titleObj ) {
                $this->dieWithError( [ 'apierror-nosuchpageid', $params['pageid'] ] );
            }
        }
 
        return $titleObj;
    }
 
    protected function getWatchlistValue( $watchlist, $titleObj, $userOption = null ) {
        $userWatching = $this->getUser()->isWatched( $titleObj, User::IGNORE_USER_RIGHTS );
 
        switch ( $watchlist ) {
            case 'watch':
                return true;
 
            case 'unwatch':
                return false;
 
            case 'preferences':
                # If the user is already watching, don't bother checking
                if ( $userWatching ) {
                    return true;
                }
                # If no user option was passed, use watchdefault and watchcreations
                if ( is_null( $userOption ) ) {
                    return $this->getUser()->getBoolOption( 'watchdefault' ) ||
                        $this->getUser()->getBoolOption( 'watchcreations' ) && !$titleObj->exists();
                }
 
                # Watch the article based on the user preference
                return $this->getUser()->getBoolOption( $userOption );
 
            case 'nochange':
                return $userWatching;
 
            default:
                return $userWatching;
        }
    }
 
    protected function getParameterFromSettings( $paramName, $paramSettings, $parseLimit ) {
        // Some classes may decide to change parameter names
        $encParamName = $this->encodeParamName( $paramName );
 
        // Shorthand
        if ( !is_array( $paramSettings ) ) {
            $paramSettings = [
                self::PARAM_DFLT => $paramSettings,
            ];
        }
 
        $default = $paramSettings[self::PARAM_DFLT] ?? null;
        $multi = $paramSettings[self::PARAM_ISMULTI] ?? false;
        $multiLimit1 = $paramSettings[self::PARAM_ISMULTI_LIMIT1] ?? null;
        $multiLimit2 = $paramSettings[self::PARAM_ISMULTI_LIMIT2] ?? null;
        $type = $paramSettings[self::PARAM_TYPE] ?? null;
        $dupes = $paramSettings[self::PARAM_ALLOW_DUPLICATES] ?? false;
        $deprecated = $paramSettings[self::PARAM_DEPRECATED] ?? false;
        $deprecatedValues = $paramSettings[self::PARAM_DEPRECATED_VALUES] ?? [];
        $required = $paramSettings[self::PARAM_REQUIRED] ?? false;
        $allowAll = $paramSettings[self::PARAM_ALL] ?? false;
 
        // When type is not given, and no choices, the type is the same as $default
        if ( !isset( $type ) ) {
            if ( isset( $default ) ) {
                $type = gettype( $default );
            } else {
                $type = 'NULL'; // allow everything
            }
        }
 
        if ( $type == 'password' || !empty( $paramSettings[self::PARAM_SENSITIVE] ) ) {
            $this->getMain()->markParamsSensitive( $encParamName );
        }
 
        if ( $type == 'boolean' ) {
            if ( isset( $default ) && $default !== false ) {
                // Having a default value of anything other than 'false' is not allowed
                self::dieDebug(
                    __METHOD__,
                    "Boolean param $encParamName's default is set to '$default'. " .
                        'Boolean parameters must default to false.'
                );
            }
 
            $value = $this->getMain()->getCheck( $encParamName );
            $provided = $value;
        } elseif ( $type == 'upload' ) {
            if ( isset( $default ) ) {
                // Having a default value is not allowed
                self::dieDebug(
                    __METHOD__,
                    "File upload param $encParamName's default is set to " .
                        "'$default'. File upload parameters may not have a default." );
            }
            if ( $multi ) {
                self::dieDebug( __METHOD__, "Multi-values not supported for $encParamName" );
            }
            $value = $this->getMain()->getUpload( $encParamName );
            $provided = $value->exists();
            if ( !$value->exists() ) {
                // This will get the value without trying to normalize it
                // (because trying to normalize a large binary file
                // accidentally uploaded as a field fails spectacularly)
                $value = $this->getMain()->getRequest()->unsetVal( $encParamName );
                if ( $value !== null ) {
                    $this->dieWithError(
                        [ 'apierror-badupload', $encParamName ],
                        "badupload_{$encParamName}"
                    );
                }
            }
        } else {
            $value = $this->getMain()->getVal( $encParamName, $default );
            $provided = $this->getMain()->getCheck( $encParamName );
 
            if ( isset( $value ) && $type == 'namespace' ) {
                $type = MWNamespace::getValidNamespaces();
                if ( isset( $paramSettings[self::PARAM_EXTRA_NAMESPACES] ) &&
                    is_array( $paramSettings[self::PARAM_EXTRA_NAMESPACES] )
                ) {
                    $type = array_merge( $type, $paramSettings[self::PARAM_EXTRA_NAMESPACES] );
                }
                // Namespace parameters allow ALL_DEFAULT_STRING to be used to
                // specify all namespaces irrespective of PARAM_ALL.
                $allowAll = true;
            }
            if ( isset( $value ) && $type == 'submodule' ) {
                if ( isset( $paramSettings[self::PARAM_SUBMODULE_MAP] ) ) {
                    $type = array_keys( $paramSettings[self::PARAM_SUBMODULE_MAP] );
                } else {
                    $type = $this->getModuleManager()->getNames( $paramName );
                }
            }
 
            $request = $this->getMain()->getRequest();
            $rawValue = $request->getRawVal( $encParamName );
            if ( $rawValue === null ) {
                $rawValue = $default;
            }
 
            // Preserve U+001F for self::parseMultiValue(), or error out if that won't be called
            if ( isset( $value ) && substr( $rawValue, 0, 1 ) === "\x1f" ) {
                if ( $multi ) {
                    // This loses the potential checkTitleEncoding() transformation done by
                    // WebRequest for $_GET. Let's call that a feature.
                    $value = implode( "\x1f", $request->normalizeUnicode( explode( "\x1f", $rawValue ) ) );
                } else {
                    $this->dieWithError( 'apierror-badvalue-notmultivalue', 'badvalue_notmultivalue' );
                }
            }
 
            // Check for NFC normalization, and warn
            if ( $rawValue !== $value ) {
                $this->handleParamNormalization( $paramName, $value, $rawValue );
            }
        }
 
        $allSpecifier = ( is_string( $allowAll ) ? $allowAll : self::ALL_DEFAULT_STRING );
        if ( $allowAll && $multi && is_array( $type ) && in_array( $allSpecifier, $type, true ) ) {
            self::dieDebug(
                __METHOD__,
                "For param $encParamName, PARAM_ALL collides with a possible value" );
        }
        if ( isset( $value ) && ( $multi || is_array( $type ) ) ) {
            $value = $this->parseMultiValue(
                $encParamName,
                $value,
                $multi,
                is_array( $type ) ? $type : null,
                $allowAll ? $allSpecifier : null,
                $multiLimit1,
                $multiLimit2
            );
        }
 
        if ( isset( $value ) ) {
            // More validation only when choices were not given
            // choices were validated in parseMultiValue()
            if ( !is_array( $type ) ) {
                switch ( $type ) {
                    case 'NULL': // nothing to do
                        break;
                    case 'string':
                    case 'text':
                    case 'password':
                        if ( $required && $value === '' ) {
                            $this->dieWithError( [ 'apierror-missingparam', $encParamName ] );
                        }
                        break;
                    case 'integer': // Force everything using intval() and optionally validate limits
                        $min = $paramSettings[self::PARAM_MIN] ?? null;
                        $max = $paramSettings[self::PARAM_MAX] ?? null;
                        $enforceLimits = $paramSettings[self::PARAM_RANGE_ENFORCE] ?? false;
 
                        if ( is_array( $value ) ) {
                            $value = array_map( 'intval', $value );
                            if ( !is_null( $min ) || !is_null( $max ) ) {
                                foreach ( $value as &$v ) {
                                    $this->validateLimit( $paramName, $v, $min, $max, null, $enforceLimits );
                                }
                            }
                        } else {
                            $value = (int)$value;
                            if ( !is_null( $min ) || !is_null( $max ) ) {
                                $this->validateLimit( $paramName, $value, $min, $max, null, $enforceLimits );
                            }
                        }
                        break;
                    case 'limit':
                        if ( !$parseLimit ) {
                            // Don't do any validation whatsoever
                            break;
                        }
                        if ( !isset( $paramSettings[self::PARAM_MAX] )
                            || !isset( $paramSettings[self::PARAM_MAX2] )
                        ) {
                            self::dieDebug(
                                __METHOD__,
                                "MAX1 or MAX2 are not defined for the limit $encParamName"
                            );
                        }
                        if ( $multi ) {
                            self::dieDebug( __METHOD__, "Multi-values not supported for $encParamName" );
                        }
                        $min = $paramSettings[self::PARAM_MIN] ?? 0;
                        if ( $value == 'max' ) {
                            $value = $this->getMain()->canApiHighLimits()
                                ? $paramSettings[self::PARAM_MAX2]
                                : $paramSettings[self::PARAM_MAX];
                            $this->getResult()->addParsedLimit( $this->getModuleName(), $value );
                        } else {
                            $value = (int)$value;
                            $this->validateLimit(
                                $paramName,
                                $value,
                                $min,
                                $paramSettings[self::PARAM_MAX],
                                $paramSettings[self::PARAM_MAX2]
                            );
                        }
                        break;
                    case 'boolean':
                        if ( $multi ) {
                            self::dieDebug( __METHOD__, "Multi-values not supported for $encParamName" );
                        }
                        break;
                    case 'timestamp':
                        if ( is_array( $value ) ) {
                            foreach ( $value as $key => $val ) {
                                $value[$key] = $this->validateTimestamp( $val, $encParamName );
                            }
                        } else {
                            $value = $this->validateTimestamp( $value, $encParamName );
                        }
                        break;
                    case 'user':
                        if ( is_array( $value ) ) {
                            foreach ( $value as $key => $val ) {
                                $value[$key] = $this->validateUser( $val, $encParamName );
                            }
                        } else {
                            $value = $this->validateUser( $value, $encParamName );
                        }
                        break;
                    case 'upload': // nothing to do
                        break;
                    case 'tags':
                        // If change tagging was requested, check that the tags are valid.
                        if ( !is_array( $value ) && !$multi ) {
                            $value = [ $value ];
                        }
                        $tagsStatus = ChangeTags::canAddTagsAccompanyingChange( $value );
                        if ( !$tagsStatus->isGood() ) {
                            $this->dieStatus( $tagsStatus );
                        }
                        break;
                    default:
                        self::dieDebug( __METHOD__, "Param $encParamName's type is unknown - $type" );
                }
            }
 
            // Throw out duplicates if requested
            if ( !$dupes && is_array( $value ) ) {
                $value = array_unique( $value );
            }
 
            if ( in_array( $type, [ 'NULL', 'string', 'text', 'password' ], true ) ) {
                foreach ( (array)$value as $val ) {
                    if ( isset( $paramSettings[self::PARAM_MAX_BYTES] )
                        && strlen( $val ) > $paramSettings[self::PARAM_MAX_BYTES]
                    ) {
                        $this->dieWithError( [ 'apierror-maxbytes', $encParamName,
                            $paramSettings[self::PARAM_MAX_BYTES] ] );
                    }
                    if ( isset( $paramSettings[self::PARAM_MAX_CHARS] )
                        && mb_strlen( $val, 'UTF-8' ) > $paramSettings[self::PARAM_MAX_CHARS]
                    ) {
                        $this->dieWithError( [ 'apierror-maxchars', $encParamName,
                            $paramSettings[self::PARAM_MAX_CHARS] ] );
                    }
                }
            }
 
            // Set a warning if a deprecated parameter has been passed
            if ( $deprecated && $provided ) {
                $feature = $encParamName;
                $m = $this;
                while ( !$m->isMain() ) {
                    $p = $m->getParent();
                    $name = $m->getModuleName();
                    $param = $p->encodeParamName( $p->getModuleManager()->getModuleGroup( $name ) );
                    $feature = "{$param}={$name}&{$feature}";
                    $m = $p;
                }
                $this->addDeprecation( [ 'apiwarn-deprecation-parameter', $encParamName ], $feature );
            }
 
            // Set a warning if a deprecated parameter value has been passed
            $usedDeprecatedValues = $deprecatedValues && $provided
                ? array_intersect( array_keys( $deprecatedValues ), (array)$value )
                : [];
            if ( $usedDeprecatedValues ) {
                $feature = "$encParamName=";
                $m = $this;
                while ( !$m->isMain() ) {
                    $p = $m->getParent();
                    $name = $m->getModuleName();
                    $param = $p->encodeParamName( $p->getModuleManager()->getModuleGroup( $name ) );
                    $feature = "{$param}={$name}&{$feature}";
                    $m = $p;
                }
                foreach ( $usedDeprecatedValues as $v ) {
                    $msg = $deprecatedValues[$v];
                    if ( $msg === true ) {
                        $msg = [ 'apiwarn-deprecation-parameter', "$encParamName=$v" ];
                    }
                    $this->addDeprecation( $msg, "$feature$v" );
                }
            }
        } elseif ( $required ) {
            $this->dieWithError( [ 'apierror-missingparam', $encParamName ] );
        }
 
        return $value;
    }
 
    protected function handleParamNormalization( $paramName, $value, $rawValue ) {
        $encParamName = $this->encodeParamName( $paramName );
        $this->addWarning( [ 'apiwarn-badutf8', $encParamName ] );
    }
 
    protected function explodeMultiValue( $value, $limit ) {
        if ( substr( $value, 0, 1 ) === "\x1f" ) {
            $sep = "\x1f";
            $value = substr( $value, 1 );
        } else {
            $sep = '|';
        }
 
        return explode( $sep, $value, $limit );
    }
 
    protected function parseMultiValue( $valueName, $value, $allowMultiple, $allowedValues,
        $allSpecifier = null, $limit1 = null, $limit2 = null
    ) {
        if ( ( $value === '' || $value === "\x1f" ) && $allowMultiple ) {
            return [];
        }
        $limit1 = $limit1 ?: self::LIMIT_SML1;
        $limit2 = $limit2 ?: self::LIMIT_SML2;
 
        // This is a bit awkward, but we want to avoid calling canApiHighLimits()
        // because it unstubs $wgUser
        $valuesList = $this->explodeMultiValue( $value, $limit2 + 1 );
        $sizeLimit = count( $valuesList ) > $limit1 && $this->mMainModule->canApiHighLimits()
            ? $limit2
            : $limit1;
 
        if ( $allowMultiple && is_array( $allowedValues ) && $allSpecifier &&
            count( $valuesList ) === 1 && $valuesList[0] === $allSpecifier
        ) {
            return $allowedValues;
        }
 
        if ( count( $valuesList ) > $sizeLimit ) {
            $this->dieWithError(
                [ 'apierror-toomanyvalues', $valueName, $sizeLimit ],
                "too-many-$valueName"
            );
        }
 
        if ( !$allowMultiple && count( $valuesList ) != 1 ) {
            // T35482 - Allow entries with | in them for non-multiple values
            if ( in_array( $value, $allowedValues, true ) ) {
                return $value;
            }
 
            $values = array_map( function ( $v ) {
                return '<kbd>' . wfEscapeWikiText( $v ) . '</kbd>';
            }, $allowedValues );
            $this->dieWithError( [
                'apierror-multival-only-one-of',
                $valueName,
                Message::listParam( $values ),
                count( $values ),
            ], "multival_$valueName" );
        }
 
        if ( is_array( $allowedValues ) ) {
            // Check for unknown values
            $unknown = array_map( 'wfEscapeWikiText', array_diff( $valuesList, $allowedValues ) );
            if ( count( $unknown ) ) {
                if ( $allowMultiple ) {
                    $this->addWarning( [
                        'apiwarn-unrecognizedvalues',
                        $valueName,
                        Message::listParam( $unknown, 'comma' ),
                        count( $unknown ),
                    ] );
                } else {
                    $this->dieWithError(
                        [ 'apierror-unrecognizedvalue', $valueName, wfEscapeWikiText( $valuesList[0] ) ],
                        "unknown_$valueName"
                    );
                }
            }
            // Now throw them out
            $valuesList = array_intersect( $valuesList, $allowedValues );
        }
 
        return $allowMultiple ? $valuesList : $valuesList[0];
    }
 
    protected function validateLimit( $paramName, &$value, $min, $max, $botMax = null,
        $enforceLimits = false
    ) {
        if ( !is_null( $min ) && $value < $min ) {
            $msg = ApiMessage::create(
                [ 'apierror-integeroutofrange-belowminimum',
                    $this->encodeParamName( $paramName ), $min, $value ],
                'integeroutofrange',
                [ 'min' => $min, 'max' => $max, 'botMax' => $botMax ?: $max ]
            );
            $this->warnOrDie( $msg, $enforceLimits );
            $value = $min;
        }
 
        // Minimum is always validated, whereas maximum is checked only if not
        // running in internal call mode
        if ( $this->getMain()->isInternalMode() ) {
            return;
        }
 
        // Optimization: do not check user's bot status unless really needed -- skips db query
        // assumes $botMax >= $max
        if ( !is_null( $max ) && $value > $max ) {
            if ( !is_null( $botMax ) && $this->getMain()->canApiHighLimits() ) {
                if ( $value > $botMax ) {
                    $msg = ApiMessage::create(
                        [ 'apierror-integeroutofrange-abovebotmax',
                            $this->encodeParamName( $paramName ), $botMax, $value ],
                        'integeroutofrange',
                        [ 'min' => $min, 'max' => $max, 'botMax' => $botMax ?: $max ]
                    );
                    $this->warnOrDie( $msg, $enforceLimits );
                    $value = $botMax;
                }
            } else {
                $msg = ApiMessage::create(
                    [ 'apierror-integeroutofrange-abovemax',
                        $this->encodeParamName( $paramName ), $max, $value ],
                    'integeroutofrange',
                    [ 'min' => $min, 'max' => $max, 'botMax' => $botMax ?: $max ]
                );
                $this->warnOrDie( $msg, $enforceLimits );
                $value = $max;
            }
        }
    }
 
    protected function validateTimestamp( $value, $encParamName ) {
        // Confusing synonyms for the current time accepted by wfTimestamp()
        // (wfTimestamp() also accepts various non-strings and the string of 14
        // ASCII NUL bytes, but those can't get here)
        if ( !$value ) {
            $this->addDeprecation(
                [ 'apiwarn-unclearnowtimestamp', $encParamName, wfEscapeWikiText( $value ) ],
                'unclear-"now"-timestamp'
            );
            return wfTimestamp( TS_MW );
        }
 
        // Explicit synonym for the current time
        if ( $value === 'now' ) {
            return wfTimestamp( TS_MW );
        }
 
        $timestamp = wfTimestamp( TS_MW, $value );
        if ( $timestamp === false ) {
            $this->dieWithError(
                [ 'apierror-badtimestamp', $encParamName, wfEscapeWikiText( $value ) ],
                "badtimestamp_{$encParamName}"
            );
        }
 
        return $timestamp;
    }
 
    final public function validateToken( $token, array $params ) {
        $tokenType = $this->needsToken();
        $salts = ApiQueryTokens::getTokenTypeSalts();
        if ( !isset( $salts[$tokenType] ) ) {
            throw new MWException(
                "Module '{$this->getModuleName()}' tried to use token type '$tokenType' " .
                    'without registering it'
            );
        }
 
        $tokenObj = ApiQueryTokens::getToken(
            $this->getUser(), $this->getRequest()->getSession(), $salts[$tokenType]
        );
        if ( $tokenObj->match( $token ) ) {
            return true;
        }
 
        $webUiSalt = $this->getWebUITokenSalt( $params );
        if ( $webUiSalt !== null && $this->getUser()->matchEditToken(
            $token,
            $webUiSalt,
            $this->getRequest()
        ) ) {
            return true;
        }
 
        return false;
    }
 
    private function validateUser( $value, $encParamName ) {
        if ( ExternalUserNames::isExternal( $value ) && User::newFromName( $value, false ) ) {
            return $value;
        }
 
        $name = User::getCanonicalName( $value, 'valid' );
        if ( $name !== false ) {
            return $name;
        }
 
        if (
            // We allow ranges as well, for blocks.
            IP::isIPAddress( $value ) ||
            // See comment for User::isIP.  We don't just call that function
            // here because it also returns true for things like
            // 300.300.300.300 that are neither valid usernames nor valid IP
            // addresses.
            preg_match(
                '/^' . RE_IP_BYTE . '\.' . RE_IP_BYTE . '\.' . RE_IP_BYTE . '\.xxx$/',
                $value
            )
        ) {
            return IP::sanitizeIP( $value );
        }
 
        $this->dieWithError(
            [ 'apierror-baduser', $encParamName, wfEscapeWikiText( $value ) ],
            "baduser_{$encParamName}"
        );
    }
 
    /************************************************************************/
    protected function setWatch( $watch, $titleObj, $userOption = null ) {
        $value = $this->getWatchlistValue( $watch, $titleObj, $userOption );
        if ( $value === null ) {
            return;
        }
 
        WatchAction::doWatchOrUnwatch( $value, $titleObj, $this->getUser() );
    }
 
    public function getWatchlistUser( $params ) {
        if ( !is_null( $params['owner'] ) && !is_null( $params['token'] ) ) {
            $user = User::newFromName( $params['owner'], false );
            if ( !( $user && $user->getId() ) ) {
                $this->dieWithError(
                    [ 'nosuchusershort', wfEscapeWikiText( $params['owner'] ) ], 'bad_wlowner'
                );
            }
            $token = $user->getOption( 'watchlisttoken' );
            if ( $token == '' || !hash_equals( $token, $params['token'] ) ) {
                $this->dieWithError( 'apierror-bad-watchlist-token', 'bad_wltoken' );
            }
        } else {
            if ( !$this->getUser()->isLoggedIn() ) {
                $this->dieWithError( 'watchlistanontext', 'notloggedin' );
            }
            $this->checkUserRightsAny( 'viewmywatchlist' );
            $user = $this->getUser();
        }
 
        return $user;
    }
 
    public static function makeMessage( $msg, IContextSource $context, array $params = null ) {
        if ( is_string( $msg ) ) {
            $msg = wfMessage( $msg );
        } elseif ( is_array( $msg ) ) {
            $msg = wfMessage( ...$msg );
        }
        if ( !$msg instanceof Message ) {
            return null;
        }
 
        $msg->setContext( $context );
        if ( $params ) {
            $msg->params( $params );
        }
 
        return $msg;
    }
 
    public function errorArrayToStatus( array $errors, User $user = null ) {
        if ( $user === null ) {
            $user = $this->getUser();
        }
 
        $status = Status::newGood();
        foreach ( $errors as $error ) {
            if ( !is_array( $error ) ) {
                $error = [ $error ];
            }
            if ( is_string( $error[0] ) && isset( self::$blockMsgMap[$error[0]] ) && $user->getBlock() ) {
                list( $msg, $code ) = self::$blockMsgMap[$error[0]];
                $status->fatal( ApiMessage::create( $msg, $code,
                    [ 'blockinfo' => ApiQueryUserInfo::getBlockInfo( $user->getBlock() ) ]
                ) );
            } else {
                $status->fatal( ...$error );
            }
        }
        return $status;
    }
 
    public function addBlockInfoToStatus( StatusValue $status, User $user = null ) {
        if ( $user === null ) {
            $user = $this->getUser();
        }
 
        foreach ( self::$blockMsgMap as $msg => list( $apiMsg, $code ) ) {
            if ( $status->hasMessage( $msg ) && $user->getBlock() ) {
                $status->replaceMessage( $msg, ApiMessage::create( $apiMsg, $code,
                    [ 'blockinfo' => ApiQueryUserInfo::getBlockInfo( $user->getBlock() ) ]
                ) );
            }
        }
    }
 
    protected function useTransactionalTimeLimit() {
        if ( $this->getRequest()->wasPosted() ) {
            wfTransactionalTimeLimit();
        }
    }
 
    protected function filterIDs( $fields, array $ids ) {
        $min = INF;
        $max = 0;
        foreach ( $fields as list( $table, $field ) ) {
            if ( isset( self::$filterIDsCache[$table][$field] ) ) {
                $row = self::$filterIDsCache[$table][$field];
            } else {
                $row = $this->getDB()->selectRow(
                    $table,
                    [
                        'min_id' => "MIN($field)",
                        'max_id' => "MAX($field)",
                    ],
                    '',
                    __METHOD__
                );
                self::$filterIDsCache[$table][$field] = $row;
            }
            $min = min( $min, $row->min_id );
            $max = max( $max, $row->max_id );
        }
        return array_filter( $ids, function ( $id ) use ( $min, $max ) {
            return ( is_int( $id ) && $id >= 0 || ctype_digit( $id ) )
                && $id >= $min && $id <= $max;
        } );
    }
 
    /************************************************************************/
    public function addWarning( $msg, $code = null, $data = null ) {
        $this->getErrorFormatter()->addWarning( $this->getModulePath(), $msg, $code, $data );
    }
 
    public function addDeprecation( $msg, $feature, $data = [] ) {
        $data = (array)$data;
        if ( $feature !== null ) {
            $data['feature'] = $feature;
            $this->logFeatureUsage( $feature );
        }
        $this->addWarning( $msg, 'deprecation', $data );
 
        // No real need to deduplicate here, ApiErrorFormatter does that for
        // us (assuming the hook is deterministic).
        $msgs = [ $this->msg( 'api-usage-mailinglist-ref' ) ];
        Hooks::run( 'ApiDeprecationHelp', [ &$msgs ] );
        if ( count( $msgs ) > 1 ) {
            $key = '$' . implode( ' $', range( 1, count( $msgs ) ) );
            $msg = ( new RawMessage( $key ) )->params( $msgs );
        } else {
            $msg = reset( $msgs );
        }
        $this->getMain()->addWarning( $msg, 'deprecation-help' );
    }
 
    public function addError( $msg, $code = null, $data = null ) {
        $this->getErrorFormatter()->addError( $this->getModulePath(), $msg, $code, $data );
    }
 
    public function addMessagesFromStatus(
        StatusValue $status, $types = [ 'warning', 'error' ], array $filter = []
    ) {
        $this->getErrorFormatter()->addMessagesFromStatus(
            $this->getModulePath(), $status, $types, $filter
        );
    }
 
    public function dieWithError( $msg, $code = null, $data = null, $httpCode = null ) {
        throw ApiUsageException::newWithMessage( $this, $msg, $code, $data, $httpCode );
    }
 
    public function dieWithException( $exception, array $options = [] ) {
        $this->dieWithError(
            $this->getErrorFormatter()->getMessageFromException( $exception, $options )
        );
    }
 
    private function warnOrDie( ApiMessage $msg, $enforceLimits = false ) {
        if ( $enforceLimits ) {
            $this->dieWithError( $msg );
        } else {
            $this->addWarning( $msg );
        }
    }
 
    public function dieBlocked( Block $block ) {
        // Die using the appropriate message depending on block type
        if ( $block->getType() == Block::TYPE_AUTO ) {
            $this->dieWithError(
                'apierror-autoblocked',
                'autoblocked',
                [ 'blockinfo' => ApiQueryUserInfo::getBlockInfo( $block ) ]
            );
        } elseif ( !$block->isSitewide() ) {
            $this->dieWithError(
                'apierror-blocked-partial',
                'blocked',
                [ 'blockinfo' => ApiQueryUserInfo::getBlockInfo( $block ) ]
            );
        } else {
            $this->dieWithError(
                'apierror-blocked',
                'blocked',
                [ 'blockinfo' => ApiQueryUserInfo::getBlockInfo( $block ) ]
            );
        }
    }
 
    public function dieStatus( StatusValue $status ) {
        if ( $status->isGood() ) {
            throw new MWException( 'Successful status passed to ApiBase::dieStatus' );
        }
 
        // ApiUsageException needs a fatal status, but this method has
        // historically accepted any non-good status. Convert it if necessary.
        $status->setOK( false );
        if ( !$status->getErrorsByType( 'error' ) ) {
            $newStatus = Status::newGood();
            foreach ( $status->getErrorsByType( 'warning' ) as $err ) {
                $newStatus->fatal( $err['message'], ...$err['params'] );
            }
            if ( !$newStatus->getErrorsByType( 'error' ) ) {
                $newStatus->fatal( 'unknownerror-nocode' );
            }
            $status = $newStatus;
        }
 
        $this->addBlockInfoToStatus( $status );
        throw new ApiUsageException( $this, $status );
    }
 
    public function dieReadOnly() {
        $this->dieWithError(
            'apierror-readonly',
            'readonly',
            [ 'readonlyreason' => wfReadOnlyReason() ]
        );
    }
 
    public function checkUserRightsAny( $rights, $user = null ) {
        if ( !$user ) {
            $user = $this->getUser();
        }
        $rights = (array)$rights;
        if ( !$user->isAllowedAny( ...$rights ) ) {
            $this->dieWithError( [ 'apierror-permissiondenied', $this->msg( "action-{$rights[0]}" ) ] );
        }
    }
 
    public function checkTitleUserPermissions( Title $title, $actions, $options = [] ) {
        if ( !is_array( $options ) ) {
            wfDeprecated( '$user as the third parameter to ' . __METHOD__, '1.33' );
            $options = [ 'user' => $options ];
        }
        $user = $options['user'] ?? $this->getUser();
 
        $errors = [];
        foreach ( (array)$actions as $action ) {
            $errors = array_merge( $errors, $title->getUserPermissionsErrors( $action, $user ) );
        }
 
        if ( $errors ) {
            if ( !empty( $options['autoblock'] ) ) {
                $user->spreadAnyEditBlock();
            }
 
            $this->dieStatus( $this->errorArrayToStatus( $errors, $user ) );
        }
    }
 
    public function dieWithErrorOrDebug( $msg, $code = null, $data = null, $httpCode = null ) {
        if ( $this->getConfig()->get( 'DebugAPI' ) !== true ) {
            $this->dieWithError( $msg, $code, $data, $httpCode );
        } else {
            $this->addWarning( $msg, $code, $data );
        }
    }
 
    protected function dieContinueUsageIf( $condition ) {
        if ( $condition ) {
            $this->dieWithError( 'apierror-badcontinue' );
        }
    }
 
    protected static function dieDebug( $method, $message ) {
        throw new MWException( "Internal error in $method: $message" );
    }
 
    public function logFeatureUsage( $feature ) {
        static $loggedFeatures = [];
 
        // Only log each feature once per request. We can get multiple calls from calls to
        // extractRequestParams() with different values for 'parseLimit', for example.
        if ( isset( $loggedFeatures[$feature] ) ) {
            return;
        }
        $loggedFeatures[$feature] = true;
 
        $request = $this->getRequest();
        $ctx = [
            'feature' => $feature,
            // Spaces to underscores in 'username' for historical reasons.
            'username' => str_replace( ' ', '_', $this->getUser()->getName() ),
            'ip' => $request->getIP(),
            'referer' => (string)$request->getHeader( 'Referer' ),
            'agent' => $this->getMain()->getUserAgent(),
        ];
 
        // Text string is deprecated. Remove (or replace with just $feature) in MW 1.34.
        $s = '"' . addslashes( $ctx['feature'] ) . '"' .
            ' "' . wfUrlencode( $ctx['username'] ) . '"' .
            ' "' . $ctx['ip'] . '"' .
            ' "' . addslashes( $ctx['referer'] ) . '"' .
            ' "' . addslashes( $ctx['agent'] ) . '"';
 
        wfDebugLog( 'api-feature-usage', $s, 'private', $ctx );
    }
 
    /************************************************************************/
    protected function getSummaryMessage() {
        return "apihelp-{$this->getModulePath()}-summary";
    }
 
    protected function getExtendedDescription() {
        return [ [
            "apihelp-{$this->getModulePath()}-extended-description",
            'api-help-no-extended-description',
        ] ];
    }
 
    public function getFinalSummary() {
        $msg = self::makeMessage( $this->getSummaryMessage(), $this->getContext(), [
            $this->getModulePrefix(),
            $this->getModuleName(),
            $this->getModulePath(),
        ] );
        return $msg;
    }
 
    public function getFinalDescription() {
        $summary = self::makeMessage( $this->getSummaryMessage(), $this->getContext(), [
            $this->getModulePrefix(),
            $this->getModuleName(),
            $this->getModulePath(),
        ] );
        $extendedDescription = self::makeMessage(
            $this->getExtendedDescription(), $this->getContext(), [
                $this->getModulePrefix(),
                $this->getModuleName(),
                $this->getModulePath(),
            ]
        );
 
        $msgs = [ $summary, $extendedDescription ];
 
        Hooks::run( 'APIGetDescriptionMessages', [ $this, &$msgs ] );
 
        return $msgs;
    }
 
    public function getFinalParams( $flags = 0 ) {
        $params = $this->getAllowedParams( $flags );
        if ( !$params ) {
            $params = [];
        }
 
        if ( $this->needsToken() ) {
            $params['token'] = [
                self::PARAM_TYPE => 'string',
                self::PARAM_REQUIRED => true,
                self::PARAM_SENSITIVE => true,
                self::PARAM_HELP_MSG => [
                    'api-help-param-token',
                    $this->needsToken(),
                ],
            ] + ( $params['token'] ?? [] );
        }
 
        // Avoid PHP 7.1 warning of passing $this by reference
        $apiModule = $this;
        Hooks::run( 'APIGetAllowedParams', [ &$apiModule, &$params, $flags ] );
 
        return $params;
    }
 
    public function getFinalParamDescription() {
        $prefix = $this->getModulePrefix();
        $name = $this->getModuleName();
        $path = $this->getModulePath();
 
        $params = $this->getFinalParams( self::GET_VALUES_FOR_HELP );
        $msgs = [];
        foreach ( $params as $param => $settings ) {
            if ( !is_array( $settings ) ) {
                $settings = [];
            }
 
            if ( isset( $settings[self::PARAM_HELP_MSG] ) ) {
                $msg = $settings[self::PARAM_HELP_MSG];
            } else {
                $msg = $this->msg( "apihelp-{$path}-param-{$param}" );
            }
            $msg = self::makeMessage( $msg, $this->getContext(),
                [ $prefix, $param, $name, $path ] );
            if ( !$msg ) {
                self::dieDebug( __METHOD__,
                    'Value in ApiBase::PARAM_HELP_MSG is not valid' );
            }
            $msgs[$param] = [ $msg ];
 
            if ( isset( $settings[self::PARAM_TYPE] ) &&
                $settings[self::PARAM_TYPE] === 'submodule'
            ) {
                if ( isset( $settings[self::PARAM_SUBMODULE_MAP] ) ) {
                    $map = $settings[self::PARAM_SUBMODULE_MAP];
                } else {
                    $prefix = $this->isMain() ? '' : ( $this->getModulePath() . '+' );
                    $map = [];
                    foreach ( $this->getModuleManager()->getNames( $param ) as $submoduleName ) {
                        $map[$submoduleName] = $prefix . $submoduleName;
                    }
                }
                ksort( $map );
                $submodules = [];
                $deprecatedSubmodules = [];
                foreach ( $map as $v => $m ) {
                    $arr = &$submodules;
                    $isDeprecated = false;
                    $summary = null;
                    try {
                        $submod = $this->getModuleFromPath( $m );
                        if ( $submod ) {
                            $summary = $submod->getFinalSummary();
                            $isDeprecated = $submod->isDeprecated();
                            if ( $isDeprecated ) {
                                $arr = &$deprecatedSubmodules;
                            }
                        }
                    } catch ( ApiUsageException $ex ) {
                        // Ignore
                    }
                    if ( $summary ) {
                        $key = $summary->getKey();
                        $params = $summary->getParams();
                    } else {
                        $key = 'api-help-undocumented-module';
                        $params = [ $m ];
                    }
                    $m = new ApiHelpParamValueMessage( "[[Special:ApiHelp/$m|$v]]", $key, $params, $isDeprecated );
                    $arr[] = $m->setContext( $this->getContext() );
                }
                $msgs[$param] = array_merge( $msgs[$param], $submodules, $deprecatedSubmodules );
            } elseif ( isset( $settings[self::PARAM_HELP_MSG_PER_VALUE] ) ) {
                if ( !is_array( $settings[self::PARAM_HELP_MSG_PER_VALUE] ) ) {
                    self::dieDebug( __METHOD__,
                        'ApiBase::PARAM_HELP_MSG_PER_VALUE is not valid' );
                }
                if ( !is_array( $settings[self::PARAM_TYPE] ) ) {
                    self::dieDebug( __METHOD__,
                        'ApiBase::PARAM_HELP_MSG_PER_VALUE may only be used when ' .
                        'ApiBase::PARAM_TYPE is an array' );
                }
 
                $valueMsgs = $settings[self::PARAM_HELP_MSG_PER_VALUE];
                $deprecatedValues = $settings[self::PARAM_DEPRECATED_VALUES] ?? [];
 
                foreach ( $settings[self::PARAM_TYPE] as $value ) {
                    if ( isset( $valueMsgs[$value] ) ) {
                        $msg = $valueMsgs[$value];
                    } else {
                        $msg = "apihelp-{$path}-paramvalue-{$param}-{$value}";
                    }
                    $m = self::makeMessage( $msg, $this->getContext(),
                        [ $prefix, $param, $name, $path, $value ] );
                    if ( $m ) {
                        $m = new ApiHelpParamValueMessage(
                            $value,
                            [ $m->getKey(), 'api-help-param-no-description' ],
                            $m->getParams(),
                            isset( $deprecatedValues[$value] )
                        );
                        $msgs[$param][] = $m->setContext( $this->getContext() );
                    } else {
                        self::dieDebug( __METHOD__,
                            "Value in ApiBase::PARAM_HELP_MSG_PER_VALUE for $value is not valid" );
                    }
                }
            }
 
            if ( isset( $settings[self::PARAM_HELP_MSG_APPEND] ) ) {
                if ( !is_array( $settings[self::PARAM_HELP_MSG_APPEND] ) ) {
                    self::dieDebug( __METHOD__,
                        'Value for ApiBase::PARAM_HELP_MSG_APPEND is not an array' );
                }
                foreach ( $settings[self::PARAM_HELP_MSG_APPEND] as $m ) {
                    $m = self::makeMessage( $m, $this->getContext(),
                        [ $prefix, $param, $name, $path ] );
                    if ( $m ) {
                        $msgs[$param][] = $m;
                    } else {
                        self::dieDebug( __METHOD__,
                            'Value in ApiBase::PARAM_HELP_MSG_APPEND is not valid' );
                    }
                }
            }
        }
 
        Hooks::run( 'APIGetParamDescriptionMessages', [ $this, &$msgs ] );
 
        return $msgs;
    }
 
    protected function getHelpFlags() {
        $flags = [];
 
        if ( $this->isDeprecated() ) {
            $flags[] = 'deprecated';
        }
        if ( $this->isInternal() ) {
            $flags[] = 'internal';
        }
        if ( $this->isReadMode() ) {
            $flags[] = 'readrights';
        }
        if ( $this->isWriteMode() ) {
            $flags[] = 'writerights';
        }
        if ( $this->mustBePosted() ) {
            $flags[] = 'mustbeposted';
        }
 
        return $flags;
    }
 
    protected function getModuleSourceInfo() {
        global $IP;
 
        if ( $this->mModuleSource !== false ) {
            return $this->mModuleSource;
        }
 
        // First, try to find where the module comes from...
        $rClass = new ReflectionClass( $this );
        $path = $rClass->getFileName();
        if ( !$path ) {
            // No path known?
            $this->mModuleSource = null;
            return null;
        }
        $path = realpath( $path ) ?: $path;
 
        // Build map of extension directories to extension info
        if ( self::$extensionInfo === null ) {
            $extDir = $this->getConfig()->get( 'ExtensionDirectory' );
            self::$extensionInfo = [
                realpath( __DIR__ ) ?: __DIR__ => [
                    'path' => $IP,
                    'name' => 'MediaWiki',
                    'license-name' => 'GPL-2.0-or-later',
                ],
                realpath( "$IP/extensions" ) ?: "$IP/extensions" => null,
                realpath( $extDir ) ?: $extDir => null,
            ];
            $keep = [
                'path' => null,
                'name' => null,
                'namemsg' => null,
                'license-name' => null,
            ];
            foreach ( $this->getConfig()->get( 'ExtensionCredits' ) as $group ) {
                foreach ( $group as $ext ) {
                    if ( !isset( $ext['path'] ) || !isset( $ext['name'] ) ) {
                        // This shouldn't happen, but does anyway.
                        continue;
                    }
 
                    $extpath = $ext['path'];
                    if ( !is_dir( $extpath ) ) {
                        $extpath = dirname( $extpath );
                    }
                    self::$extensionInfo[realpath( $extpath ) ?: $extpath] =
                        array_intersect_key( $ext, $keep );
                }
            }
            foreach ( ExtensionRegistry::getInstance()->getAllThings() as $ext ) {
                $extpath = $ext['path'];
                if ( !is_dir( $extpath ) ) {
                    $extpath = dirname( $extpath );
                }
                self::$extensionInfo[realpath( $extpath ) ?: $extpath] =
                    array_intersect_key( $ext, $keep );
            }
        }
 
        // Now traverse parent directories until we find a match or run out of
        // parents.
        do {
            if ( array_key_exists( $path, self::$extensionInfo ) ) {
                // Found it!
                $this->mModuleSource = self::$extensionInfo[$path];
                return $this->mModuleSource;
            }
 
            $oldpath = $path;
            $path = dirname( $path );
        } while ( $path !== $oldpath );
 
        // No idea what extension this might be.
        $this->mModuleSource = null;
        return null;
    }
 
    public function modifyHelp( array &$help, array $options, array &$tocData ) {
    }
 
    /************************************************************************/
    protected function getDescription() {
        wfDeprecated( __METHOD__, '1.25' );
        return false;
    }
 
    protected function getParamDescription() {
        wfDeprecated( __METHOD__, '1.25' );
        return [];
    }
 
    protected function getExamples() {
        wfDeprecated( __METHOD__, '1.25' );
        return false;
    }
 
    protected function getDescriptionMessage() {
        wfDeprecated( __METHOD__, '1.30' );
        return [ [
            "apihelp-{$this->getModulePath()}-description",
            "apihelp-{$this->getModulePath()}-summary",
        ] ];
    }
 
    public static function truncateArray( &$arr, $limit ) {
        wfDeprecated( __METHOD__, '1.32' );
        $modified = false;
        while ( count( $arr ) > $limit ) {
            array_pop( $arr );
            $modified = true;
        }
 
        return $modified;
    }
 
}