ApiBase.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Api;
 
use InvalidArgumentException;
use LogicException;
use MediaWiki\Api\Validator\SubmoduleDef;
use MediaWiki\Block\Block;
use MediaWiki\Context\ContextSource;
use MediaWiki\Context\IContextSource;
use MediaWiki\Exception\MWException;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\Language\RawMessage;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\Message\Message;
use MediaWiki\Page\PageIdentity;
use MediaWiki\Page\WikiPage;
use MediaWiki\ParamValidator\TypeDef\NamespaceDef;
use MediaWiki\Permissions\PermissionManager;
use MediaWiki\Permissions\PermissionStatus;
use MediaWiki\Registration\ExtensionRegistry;
use MediaWiki\Specials\SpecialVersion;
use MediaWiki\Status\Status;
use MediaWiki\Title\Title;
use MediaWiki\User\User;
use MediaWiki\User\UserRigorOptions;
use ReflectionClass;
use StatusValue;
use stdClass;
use Throwable;
use Wikimedia\Message\MessageSpecifier;
use Wikimedia\ParamValidator\ParamValidator;
use Wikimedia\ParamValidator\TypeDef\EnumDef;
use Wikimedia\ParamValidator\TypeDef\IntegerDef;
use Wikimedia\ParamValidator\TypeDef\StringDef;
use Wikimedia\Rdbms\IReadableDatabase;
use Wikimedia\Timestamp\TimestampException;
 
abstract class ApiBase extends ContextSource {
 
    private $hookContainer;
 
    private $hookRunner;
 
    public const PARAM_DFLT = ParamValidator::PARAM_DEFAULT;
    public const PARAM_ISMULTI = ParamValidator::PARAM_ISMULTI;
    public const PARAM_TYPE = ParamValidator::PARAM_TYPE;
    public const PARAM_MAX = IntegerDef::PARAM_MAX;
    public const PARAM_MAX2 = IntegerDef::PARAM_MAX2;
    public const PARAM_MIN = IntegerDef::PARAM_MIN;
    public const PARAM_ALLOW_DUPLICATES = ParamValidator::PARAM_ALLOW_DUPLICATES;
    public const PARAM_DEPRECATED = ParamValidator::PARAM_DEPRECATED;
    public const PARAM_REQUIRED = ParamValidator::PARAM_REQUIRED;
    public const PARAM_SUBMODULE_MAP = SubmoduleDef::PARAM_SUBMODULE_MAP;
    public const PARAM_SUBMODULE_PARAM_PREFIX = SubmoduleDef::PARAM_SUBMODULE_PARAM_PREFIX;
    public const PARAM_ALL = ParamValidator::PARAM_ALL;
    public const PARAM_EXTRA_NAMESPACES = NamespaceDef::PARAM_EXTRA_NAMESPACES;
    public const PARAM_SENSITIVE = ParamValidator::PARAM_SENSITIVE;
    public const PARAM_DEPRECATED_VALUES = EnumDef::PARAM_DEPRECATED_VALUES;
    public const PARAM_ISMULTI_LIMIT1 = ParamValidator::PARAM_ISMULTI_LIMIT1;
    public const PARAM_ISMULTI_LIMIT2 = ParamValidator::PARAM_ISMULTI_LIMIT2;
    public const PARAM_MAX_BYTES = StringDef::PARAM_MAX_BYTES;
    public const PARAM_MAX_CHARS = StringDef::PARAM_MAX_CHARS;
    public const PARAM_RANGE_ENFORCE = 'api-param-range-enforce';
 
    // region   API-specific constants for ::getAllowedParams() arrays
    public const PARAM_HELP_MSG = 'api-param-help-msg';
 
    public const PARAM_HELP_MSG_APPEND = 'api-param-help-msg-append';
 
    public const PARAM_HELP_MSG_INFO = 'api-param-help-msg-info';
 
    public const PARAM_VALUE_LINKS = 'api-param-value-links';
 
    public const PARAM_HELP_MSG_PER_VALUE = 'api-param-help-msg-per-value';
 
    public const PARAM_TEMPLATE_VARS = 'param-template-vars';
 
    // endregion -- end of API-specific constants for ::getAllowedParams() arrays
 
    public const ALL_DEFAULT_STRING = '*';
 
    public const LIMIT_BIG1 = 500;
    public const LIMIT_BIG2 = 5000;
    public const LIMIT_SML1 = 50;
    public const LIMIT_SML2 = 500;
 
    public const GET_VALUES_FOR_HELP = 1;
 
    private static $extensionInfo = null;
 
    private static $filterIDsCache = [];
 
    private const MESSAGE_CODE_MAP = [
        'actionthrottled' => [ 'apierror-ratelimited', 'ratelimited' ],
        'actionthrottledtext' => [ 'apierror-ratelimited', 'ratelimited' ],
    ];
 
    private $mMainModule;
 
    // Adding inline type hints for these two fields is non-trivial because
    // of tests that create mocks for ApiBase subclasses and use
    // disableOriginalConstructor(): in those cases the constructor here is never
    // hit and thus these will be empty and any uses will raise a "Typed property
    // must not be accessed before initialization" error.
    private $mModuleName;
    private $mModulePrefix;
 
    private $mReplicaDB = null;
    private $mParamCache = [];
    private $mModuleSource = false;
 
    public function __construct( ApiMain $mainModule, string $moduleName, string $modulePrefix = '' ) {
        $this->mMainModule = $mainModule;
        $this->mModuleName = $moduleName;
        $this->mModulePrefix = $modulePrefix;
 
        if ( !$this->isMain() ) {
            $this->setContext( $mainModule->getContext() );
        }
    }
 
    /***************************************************************************/
    // region   Methods to implement
    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 */ ) {
        // $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;
    }
 
    // endregion -- end of methods to implement
 
    /***************************************************************************/
    // region   Data access methods
    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();
    }
 
    private function dieIfMain( string $methodName ) {
        if ( $this->isMain() ) {
            self::dieDebug( $methodName, 'base method was called on main module.' );
        }
    }
 
    public function lacksSameOriginSecurity() {
        // The Main module has this method overridden, avoid infinite loops
        $this->dieIfMain( __METHOD__ );
 
        return $this->getMain()->lacksSameOriginSecurity();
    }
 
    public function getModulePath() {
        if ( $this->isMain() ) {
            return 'main';
        }
 
        if ( $this->getParent()->isMain() ) {
            return $this->getModuleName();
        }
 
        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 );
        }
 
        foreach ( $parts as $i => $v ) {
            $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( $v );
 
            if ( $module === null ) {
                $errorPath = $i
                    ? implode( '+', array_slice( $parts, 0, $i ) )
                    : $parent->getModuleName();
                $this->dieWithError(
                    [ 'apierror-badmodule-badsubmodule', $errorPath, wfEscapeWikiText( $v ) ],
                    'badmodule'
                );
            }
        }
 
        return $module;
    }
 
    public function getResult() {
        // The Main module has this method overridden, avoid infinite loops
        $this->dieIfMain( __METHOD__ );
 
        return $this->getMain()->getResult();
    }
 
    public function getErrorFormatter() {
        // The Main module has this method overridden, avoid infinite loops
        $this->dieIfMain( __METHOD__ );
 
        return $this->getMain()->getErrorFormatter();
    }
 
    protected function getDB() {
        if ( !$this->mReplicaDB ) {
            $this->mReplicaDB = MediaWikiServices::getInstance()
                ->getConnectionProvider()
                ->getReplicaDatabase();
        }
 
        return $this->mReplicaDB;
    }
 
    public function getContinuationManager() {
        // The Main module has this method overridden, avoid infinite loops
        $this->dieIfMain( __METHOD__ );
 
        return $this->getMain()->getContinuationManager();
    }
 
    public function setContinuationManager( ?ApiContinuationManager $manager = null ) {
        // The Main module has this method overridden, avoid infinite loops
        $this->dieIfMain( __METHOD__ );
 
        $this->getMain()->setContinuationManager( $manager );
    }
 
    protected function getPermissionManager(): PermissionManager {
        return MediaWikiServices::getInstance()->getPermissionManager();
    }
 
    protected function getHookContainer() {
        if ( !$this->hookContainer ) {
            $this->hookContainer = MediaWikiServices::getInstance()->getHookContainer();
        }
        return $this->hookContainer;
    }
 
    protected function getHookRunner() {
        if ( !$this->hookRunner ) {
            $this->hookRunner = new ApiHookRunner( $this->getHookContainer() );
        }
        return $this->hookRunner;
    }
 
    // endregion -- end of data access methods
 
    /***************************************************************************/
    // region   Parameter handling
    public function dynamicParameterDocumentation() {
        return null;
    }
 
    public function encodeParamName( $paramName ) {
        if ( is_array( $paramName ) ) {
            return array_map( function ( $name ) {
                return $this->mModulePrefix . $name;
            }, $paramName );
        }
 
        return $this->mModulePrefix . $paramName;
    }
 
    public function extractRequestParams( $options = [] ) {
        if ( is_bool( $options ) ) {
            $options = [ 'parseLimit' => $options ];
        }
        $options += [
            'parseLimit' => true,
            'safeMode' => false,
        ];
 
        $parseLimit = (bool)$options['parseLimit'];
        $cacheKey = (int)$parseLimit;
 
        // Cache parameters, for performance and to avoid T26564.
        if ( !isset( $this->mParamCache[$cacheKey] ) ) {
            $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 ) {
                [ $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[$cacheKey] = $results;
        }
 
        $ret = $this->mParamCache[$cacheKey];
        if ( !$options['safeMode'] ) {
            foreach ( $ret as $v ) {
                if ( $v instanceof ApiUsageException ) {
                    throw $v;
                }
            }
        }
 
        return $this->mParamCache[$cacheKey];
    }
 
    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 ) {
        $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>';
                    },
                    $required
                ) ),
                count( $required ),
            ], 'missingparam' );
        }
    }
 
    public function requireMaxOneParameter( $params, ...$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 ) {
        $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>';
                    },
                    $required
                ) ),
                count( $required ),
            ], 'missingparam' );
        }
    }
 
    public function requireNoConflictingParameters( $params, $trigger, $conflicts ) {
        $triggerValue = $params[$trigger] ?? null;
        if ( $triggerValue === null || $triggerValue === false ) {
            return;
        }
        $intersection = array_intersect(
            array_keys( array_filter( $params, $this->parameterNotEmpty( ... ) ) ),
            (array)$conflicts
        );
        if ( count( $intersection ) ) {
            $this->dieWithError( [
                'apierror-invalidparammix-cannotusewith',
                Message::listParam( array_map(
                    function ( $p ) {
                        return '<var>' . $this->encodeParamName( $p ) . '</var>';
                    },
                    array_values( $intersection )
                ) ),
                $trigger,
            ] );
        }
    }
 
    public function requirePostedParameters( $params, $prefix = 'prefix' ) {
        if ( !$this->mustBePosted() ) {
            // In order to allow client code to choose the correct method (GET or POST) depending *only*
            // on mustBePosted(), make sure that the module requires posting if any of its potential
            // parameters require posting.
 
            // TODO: Uncomment this
            // throw new LogicException( 'mustBePosted() must be true when using requirePostedParameters()' );
 
            // This seems to already be the case in all modules in practice, but deprecate it first just
            // in case.
            wfDeprecatedMsg( 'mustBePosted() must be true when using requirePostedParameters()',
                '1.42' );
        }
 
        // Skip if $wgDebugAPI is set, or if we're in internal mode
        if ( $this->getConfig()->get( MainConfigNames::DebugAPI ) ||
        $this->getMain()->isInternalMode() ) {
            return;
        }
 
        $queryValues = $this->getRequest()->getQueryValuesOnly();
        $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 $x !== null && $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' );
            }
            // @phan-suppress-next-line PhanTypeMismatchArgumentNullable T240141
            $pageObj = MediaWikiServices::getInstance()->getWikiPageFactory()->newFromTitle( $titleObj );
            if ( $load !== false ) {
                $pageObj->loadPageData( $load );
            }
        } elseif ( isset( $params['pageid'] ) ) {
            if ( $load === false ) {
                $load = 'fromdb';
            }
            $pageObj = MediaWikiServices::getInstance()->getWikiPageFactory()->newFromID( $params['pageid'], $load );
            if ( !$pageObj ) {
                $this->dieWithError( [ 'apierror-nosuchpageid', $params['pageid'] ] );
            }
        }
 
        // @phan-suppress-next-line PhanTypeMismatchReturnNullable requireOnlyOneParameter guard it is always set
        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'] ) ] );
            }
            // @phan-suppress-next-line PhanTypeMismatchReturnNullable T240141
            return $titleObj;
        }
 
        if ( isset( $params['pageid'] ) ) {
            $titleObj = Title::newFromID( $params['pageid'] );
            if ( !$titleObj ) {
                $this->dieWithError( [ 'apierror-nosuchpageid', $params['pageid'] ] );
            }
        }
 
        // @phan-suppress-next-line PhanTypeMismatchReturnNullable requireOnlyOneParameter guard it is always set
        return $titleObj;
    }
 
    protected function getParameterFromSettings( $name, $settings, $parseLimit ) {
        $validator = $this->getMain()->getParamValidator();
        $value = $validator->getValue( $this, $name, $settings, [
            'parse-limit' => $parseLimit,
            'raw' => ( $settings[ParamValidator::PARAM_TYPE] ?? '' ) === 'raw',
        ] );
 
        // @todo Deprecate and remove this, if possible.
        if ( $parseLimit && isset( $settings[ParamValidator::PARAM_TYPE] ) &&
            $settings[ParamValidator::PARAM_TYPE] === 'limit' &&
            $this->getMain()->getVal( $this->encodeParamName( $name ) ) === 'max'
        ) {
            $this->getResult()->addParsedLimit( $this->getModuleName(), $value );
        }
 
        return $value;
    }
 
    public function handleParamNormalization( $paramName, $value, $rawValue ) {
        $this->addWarning( [ 'apiwarn-badutf8', $paramName ] );
    }
 
    final public function validateToken( $token, array $params ) {
        $tokenType = $this->needsToken();
        $salts = ApiQueryTokens::getTokenTypeSalts();
        if ( !isset( $salts[$tokenType] ) ) {
            throw new LogicException(
                "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 );
 
        return $webUiSalt !== null && $this->getUser()->matchEditToken(
            $token, $webUiSalt, $this->getRequest()
        );
    }
 
    // endregion -- end of parameter handling
 
    /***************************************************************************/
    // region   Utility methods
    public function getWatchlistUser( $params ) {
        if ( $params['owner'] !== null && $params['token'] !== null ) {
            $services = MediaWikiServices::getInstance();
            $user = $services->getUserFactory()->newFromName( $params['owner'], UserRigorOptions::RIGOR_NONE );
            if ( !$user || !$user->isRegistered() ) {
                $this->dieWithError(
                    [ 'nosuchusershort', wfEscapeWikiText( $params['owner'] ) ], 'bad_wlowner'
                );
            }
            // @phan-suppress-next-line PhanTypeMismatchArgumentNullable T240141
            $token = $services->getUserOptionsLookup()->getOption( $user, 'watchlisttoken' );
            if ( $token == '' || !hash_equals( $token, $params['token'] ) ) {
                $this->dieWithError( 'apierror-bad-watchlist-token', 'bad_wltoken' );
            }
        } else {
            $user = $this->getUser();
            if ( !$user->isRegistered() ) {
                $this->dieWithError( 'watchlistanontext', 'notloggedin' );
            }
            $this->checkUserRightsAny( 'viewmywatchlist' );
        }
 
        // @phan-suppress-next-line PhanTypeMismatchReturnNullable T240141
        return $user;
    }
 
    public static function makeMessage( $msg, IContextSource $context, ?array $params = null ) {
        wfDeprecated( __METHOD__, '1.43' );
        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;
    }
 
    protected function useTransactionalTimeLimit() {
        if ( $this->getRequest()->wasPosted() ) {
            wfTransactionalTimeLimit();
        }
    }
 
    public static function clearCacheForTest(): void {
        if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
            throw new LogicException( 'Not allowed outside tests' );
        }
        self::$filterIDsCache = [];
    }
 
    protected function filterIDs( $fields, array $ids ) {
        $min = INF;
        $max = 0;
        foreach ( $fields as [ $table, $field ] ) {
            if ( isset( self::$filterIDsCache[$table][$field] ) ) {
                $row = self::$filterIDsCache[$table][$field];
            } else {
                $row = $this->getDB()->newSelectQueryBuilder()
                    ->select( [ 'min_id' => "MIN($field)", 'max_id' => "MAX($field)" ] )
                    ->from( $table )
                    ->caller( __METHOD__ )->fetchRow();
                self::$filterIDsCache[$table][$field] = $row;
            }
            $min = min( $min, $row->min_id );
            $max = max( $max, $row->max_id );
        }
        return array_filter( $ids, static function ( $id ) use ( $min, $max ) {
            return ( ( is_int( $id ) && $id >= 0 ) || ctype_digit( (string)$id ) )
                && $id >= $min && $id <= $max;
        } );
    }
 
    // endregion -- end of utility methods
 
    /***************************************************************************/
    // region   Warning and error reporting
    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' ) ];
        $this->getHookRunner()->onApiDeprecationHelp( $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 = 0 ): never {
        throw ApiUsageException::newWithMessage( $this, $msg, $code, $data, $httpCode );
    }
 
    public function dieWithException( Throwable $exception, array $options = [] ): never {
        $this->dieWithError(
            $this->getErrorFormatter()->getMessageFromException( $exception, $options )
        );
    }
 
    public function dieBlocked( Block $block ): never {
        $blockErrorFormatter = MediaWikiServices::getInstance()->getFormatterFactory()
            ->getBlockErrorFormatter( $this->getContext() );
 
        $msg = $blockErrorFormatter->getMessage(
            $block,
            $this->getUser(),
            null,
            $this->getRequest()->getIP()
        );
 
        $this->dieWithError( $msg );
    }
 
    public function dieStatus( StatusValue $status ): never {
        if ( $status->isGood() ) {
            throw new InvalidArgumentException( 'Successful status passed to ApiBase::dieStatus' );
        }
 
        foreach ( self::MESSAGE_CODE_MAP as $msg => [ $apiMsg, $code ] ) {
            if ( $status->hasMessage( $msg ) ) {
                $status->replaceMessage( $msg, ApiMessage::create( $apiMsg, $code ) );
            }
        }
 
        if (
            $status instanceof PermissionStatus
            && $status->isRateLimitExceeded()
            && !$status->hasMessage( 'apierror-ratelimited' )
        ) {
            $status->fatal( ApiMessage::create( 'apierror-ratelimited', 'ratelimited' ) );
        }
 
        // ApiUsageException needs a fatal status, but this method has
        // historically accepted any non-good status. Convert it if necessary.
        $status->setOK( false );
        if ( !$status->getMessages( 'error' ) ) {
            $newStatus = Status::newGood();
            foreach ( $status->getMessages( 'warning' ) as $err ) {
                $newStatus->fatal( $err );
            }
            if ( !$newStatus->getMessages( 'error' ) ) {
                $newStatus->fatal( 'unknownerror-nocode' );
            }
            $status = $newStatus;
        }
 
        throw new ApiUsageException( $this, $status );
    }
 
    public function dieReadOnly(): never {
        $this->dieWithError(
            'apierror-readonly',
            'readonly',
            [ 'readonlyreason' => MediaWikiServices::getInstance()->getReadOnlyMode()->getReason() ]
        );
    }
 
    public function checkUserRightsAny( $rights ) {
        $rights = (array)$rights;
        if ( !$this->getAuthority()->isAllowedAny( ...$rights ) ) {
            $this->dieWithError( [ 'apierror-permissiondenied', $this->msg( "action-{$rights[0]}" ) ] );
        }
    }
 
    public function checkTitleUserPermissions(
        PageIdentity $pageIdentity,
        $actions,
        array $options = []
    ) {
        $authority = $options['user'] ?? $this->getAuthority();
        $status = new PermissionStatus();
        foreach ( (array)$actions as $action ) {
            if ( $this->isWriteMode() ) {
                $authority->authorizeWrite( $action, $pageIdentity, $status );
            } else {
                $authority->authorizeRead( $action, $pageIdentity, $status );
            }
        }
        if ( !$status->isGood() ) {
            if ( !empty( $options['autoblock'] ) ) {
                $this->getUser()->spreadAnyEditBlock();
            }
            $this->dieStatus( $status );
        }
    }
 
    public function dieWithErrorOrDebug( $msg, $code = null, $data = null, $httpCode = null ) {
        if ( $this->getConfig()->get( MainConfigNames::DebugAPI ) !== true ) {
            $this->dieWithError( $msg, $code, $data, $httpCode ?? 0 );
        } else {
            $this->addWarning( $msg, $code, $data );
        }
    }
 
    protected function parseContinueParamOrDie( string $continue, array $types ): array {
        $cont = explode( '|', $continue );
        $this->dieContinueUsageIf( count( $cont ) != count( $types ) );
 
        foreach ( $cont as $i => &$value ) {
            switch ( $types[$i] ) {
                case 'string':
                    // Do nothing
                    break;
                case 'int':
                    $this->dieContinueUsageIf( $value !== (string)(int)$value );
                    $value = (int)$value;
                    break;
                case 'timestamp':
                    try {
                        $dbTs = $this->getDB()->timestamp( $value );
                    } catch ( TimestampException ) {
                        $dbTs = false;
                    }
                    $this->dieContinueUsageIf( $value !== $dbTs );
                    break;
                default:
                    throw new InvalidArgumentException( "Unknown type '{$types[$i]}'" );
            }
        }
 
        return $cont;
    }
 
    protected function dieContinueUsageIf( $condition ) {
        if ( $condition ) {
            $this->dieWithError( 'apierror-badcontinue' );
        }
    }
 
    protected static function dieDebug( $method, $message ): never {
        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,
            // Replace spaces with underscores in 'username' for historical reasons.
            'username' => str_replace( ' ', '_', $this->getUser()->getName() ),
            'clientip' => $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['clientip'] . '"' .
            ' "' . addslashes( $ctx['referer'] ) . '"' .
            ' "' . addslashes( $ctx['agent'] ) . '"';
 
        wfDebugLog( 'api-feature-usage', $s, 'private', $ctx );
 
        $this->getHookRunner()->onApiLogFeatureUsage(
            $feature,
            [
                'userName' => $this->getUser()->getName(),
                'userAgent' => $this->getMain()->getUserAgent(),
                'ipAddress' => $request->getIP()
            ]
        );
    }
 
    // endregion -- end of warning and error reporting
 
    /***************************************************************************/
    // region   Help message generation
    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() {
        return $this->msg(
            Message::newFromSpecifier( $this->getSummaryMessage() ),
            $this->getModulePrefix(),
            $this->getModuleName(),
            $this->getModulePath(),
        );
    }
 
    public function getFinalDescription() {
        $summary = $this->msg(
            Message::newFromSpecifier( $this->getSummaryMessage() ),
            $this->getModulePrefix(),
            $this->getModuleName(),
            $this->getModulePath(),
        );
        $extendedDesc = $this->getExtendedDescription();
        if ( is_array( $extendedDesc ) && is_array( $extendedDesc[0] ) ) {
            // The definition in getExtendedDescription() may also specify fallback keys. This is weird,
            // and it was never needed for other API doc messages, so it's only supported here.
            $extendedDesc = Message::newFallbackSequence( $extendedDesc[0] )
                ->params( array_slice( $extendedDesc, 1 ) );
        }
        $extendedDesc = $this->msg(
            Message::newFromSpecifier( $extendedDesc ),
            $this->getModulePrefix(),
            $this->getModuleName(),
            $this->getModulePath(),
        );
 
        $msgs = [ $summary, $extendedDesc ];
 
        $this->getHookRunner()->onAPIGetDescriptionMessages( $this, $msgs );
 
        return $msgs;
    }
 
    public function getFinalParams( $flags = 0 ) {
        // @phan-suppress-next-line PhanParamTooMany
        $params = $this->getAllowedParams( $flags );
        if ( !$params ) {
            $params = [];
        }
 
        if ( $this->needsToken() ) {
            $params['token'] = [
                ParamValidator::PARAM_TYPE => 'string',
                ParamValidator::PARAM_REQUIRED => true,
                ParamValidator::PARAM_SENSITIVE => true,
                self::PARAM_HELP_MSG => [
                    'api-help-param-token',
                    $this->needsToken(),
                ],
            ] + ( $params['token'] ?? [] );
        }
 
        $this->getHookRunner()->onAPIGetAllowedParams( $this, $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 = [];
            }
 
            $msg = isset( $settings[self::PARAM_HELP_MSG] )
                ? Message::newFromSpecifier( $settings[self::PARAM_HELP_MSG] )
                : Message::newFallbackSequence( [ "apihelp-$path-param-$param", 'api-help-param-no-description' ] );
            $msg = $this->msg( $msg, $prefix, $param, $name, $path );
            $msgs[$param] = [ $msg ];
 
            if ( isset( $settings[ParamValidator::PARAM_TYPE] ) &&
                $settings[ParamValidator::PARAM_TYPE] === 'submodule'
            ) {
                if ( isset( $settings[SubmoduleDef::PARAM_SUBMODULE_MAP] ) ) {
                    $map = $settings[SubmoduleDef::PARAM_SUBMODULE_MAP];
                } else {
                    $prefix = $this->isMain() ? '' : ( $this->getModulePath() . '+' );
                    $map = [];
                    foreach ( $this->getModuleManager()->getNames( $param ) as $submoduleName ) {
                        $map[$submoduleName] = $prefix . $submoduleName;
                    }
                }
 
                $submodules = [];
                $submoduleFlags = []; // for sorting: higher flags are sorted later
                $submoduleNames = []; // for sorting: lexicographical, ascending
                foreach ( $map as $v => $m ) {
                    $isDeprecated = false;
                    $isInternal = false;
                    $summary = null;
                    try {
                        $submod = $this->getModuleFromPath( $m );
                        if ( $submod ) {
                            $summary = $submod->getFinalSummary();
                            $isDeprecated = $submod->isDeprecated();
                            $isInternal = $submod->isInternal();
                        }
                    } catch ( ApiUsageException ) {
                        // 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,
                        $isInternal
                    );
                    $submodules[] = $m->setContext( $this->getContext() );
                    $submoduleFlags[] = ( $isDeprecated ? 1 : 0 ) | ( $isInternal ? 2 : 0 );
                    $submoduleNames[] = $v;
                }
                // sort $submodules by $submoduleFlags and $submoduleNames
                array_multisort( $submoduleFlags, $submoduleNames, $submodules );
                $msgs[$param] = array_merge( $msgs[$param], $submodules );
            } elseif ( isset( $settings[self::PARAM_HELP_MSG_PER_VALUE] ) ) {
                // ! keep these checks in sync with \MediaWiki\Api\Validator\ApiParamValidator::checkSettings
                if ( !is_array( $settings[self::PARAM_HELP_MSG_PER_VALUE] ) ) {
                    self::dieDebug( __METHOD__,
                        'ApiBase::PARAM_HELP_MSG_PER_VALUE is not valid' );
                }
                $isArrayOfStrings = is_array( $settings[ParamValidator::PARAM_TYPE] )
                    || (
                        $settings[ParamValidator::PARAM_TYPE] === 'string'
                        && ( $settings[ParamValidator::PARAM_ISMULTI] ?? false )
                    );
                if ( !$isArrayOfStrings ) {
                    self::dieDebug( __METHOD__,
                        'ApiBase::PARAM_HELP_MSG_PER_VALUE may only be used when ' .
                        'ParamValidator::PARAM_TYPE is an array or it is \'string\' and ' .
                        'ParamValidator::PARAM_ISMULTI is true' );
                }
 
                $values = is_array( $settings[ParamValidator::PARAM_TYPE] ) ?
                    $settings[ParamValidator::PARAM_TYPE] :
                    array_keys( $settings[self::PARAM_HELP_MSG_PER_VALUE] );
                $valueMsgs = $settings[self::PARAM_HELP_MSG_PER_VALUE];
                $deprecatedValues = $settings[EnumDef::PARAM_DEPRECATED_VALUES] ?? [];
 
                foreach ( $values as $value ) {
                    $msg = Message::newFromSpecifier( $valueMsgs[$value] ?? "apihelp-$path-paramvalue-$param-$value" );
                    $m = $this->msg( $msg, [ $prefix, $param, $name, $path, $value ] );
                    $m = new ApiHelpParamValueMessage(
                        $value,
                        // @phan-suppress-next-line PhanTypeMismatchArgumentProbablyReal
                        [ $m->getKey(), 'api-help-param-no-description' ],
                        $m->getParams(),
                        isset( $deprecatedValues[$value] )
                    );
                    $msgs[$param][] = $m->setContext( $this->getContext() );
                }
            }
 
            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 = $this->msg( Message::newFromSpecifier( $m ), [ $prefix, $param, $name, $path ] );
                    $msgs[$param][] = $m;
                }
            }
        }
 
        $this->getHookRunner()->onAPIGetParamDescriptionMessages( $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() {
        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 a map of extension directories to extension info
        if ( self::$extensionInfo === null ) {
            $extDir = $this->getConfig()->get( MainConfigNames::ExtensionDirectory );
            $baseDir = MW_INSTALL_PATH;
            self::$extensionInfo = [
                realpath( __DIR__ ) ?: __DIR__ => [
                    'path' => $baseDir,
                    'name' => 'MediaWiki',
                    'license-name' => 'GPL-2.0-or-later',
                ],
                realpath( "$baseDir/extensions" ) ?: "$baseDir/extensions" => null,
                realpath( $extDir ) ?: $extDir => null,
            ];
            $keep = [
                'path' => null,
                'name' => null,
                'namemsg' => null,
                'license-name' => null,
            ];
            $credits = SpecialVersion::getCredits( ExtensionRegistry::getInstance(), $this->getConfig() );
            foreach ( $credits 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 );
                }
            }
        }
 
        // 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 ) {
    }
 
    // endregion -- end of help message generation
 
    /***************************************************************************/
    // region   Data Unified metrics
    protected function recordUnifiedMetrics( $latency = 0, $detailLabels = [] ) {
        // The concept of "module" is different in Action API and REST API
        // in REST API, it represents the "collection" of endpoints
        // in Action API, it represents the "module" of the API (or an endpoint)
        // In order to make the metrics consistent, we want the module to also reflect
        // the "collection" of endpoints. The closest we can get is to use the namespace
        // of the API module, and get the area of the code or extension it belongs to.
        // If module exists, we'll take the namespace for it, otherwise fall back on
        // the current namespace. In both cases we'll remove the class name to only keep
        // the namespace.
        // Since this method can also be called from module classes (ApiQuery, etc)
        // we need to allow for accepting the submodule's class name, too, if it's given.
        $fullClass = get_class( $this );
        $moduleNamespace = substr( $fullClass, 0, strrpos( $fullClass, '\\' ) );
 
        // Get the endpoint representation, which for the moment is the module name.
        $endpoint = $this->getModuleName();
 
        // The "path" should give us useful and consistent information about the endpoint.
        // The ->getModulePath() method should give us a string wih the module parent and
        // its own name, which should be enough to identify the endpoint and work with
        // RegEx patterns to extract information from the path.
        $path = $this->getModulePath();
 
        // Unified metrics
        $metricsLabels = array_merge( [
            // This should represent the "collection" of endpoints
            'api_module' => $moduleNamespace,
            // This is the endpoint that is being executed
            'api_endpoint' => $endpoint,
            'path' => $path,
            'method' => $this->getRequest()->getMethod(),
            'status' => "200", // Success
        ], $detailLabels );
 
        $approvedLabels = [
            'api_module',
            'api_endpoint',
            'path',
            'method',
            'status',
        ];
 
        // Hit metrics
        $metricHitStats = $this->getMain()->getStatsFactory()->getCounter( 'action_api_modules_hit_total' )
            ->setLabel( 'api_type', 'ACTION_API' );
        foreach ( $approvedLabels as $label ) {
            // Set a fallback value for empty strings
            $value = (
                array_key_exists( $label, $metricsLabels ) &&
                is_string( $metricsLabels[$label] ) &&
                trim( $metricsLabels[$label] ) !== ''
            ) ? $metricsLabels[$label] : 'EMPTY_VALUE';
            $metricHitStats->setLabel( $label, $value );
        }
        $metricHitStats->increment();
 
        // Latency metrics
        $metricLatencyStats = $this->getMain()->getStatsFactory()->getTiming( 'action_api_modules_latency' )
            ->setLabel( 'api_type', 'ACTION_API' );
        // Iterate over the approved labels and set the labels for the metric
        foreach ( $approvedLabels as $label ) {
            // Set a fallback value for empty strings
            $value = (
                array_key_exists( $label, $metricsLabels ) &&
                is_string( $metricsLabels[$label] ) &&
                trim( $metricsLabels[$label] ) !== ''
            ) ? $metricsLabels[$label] : 'EMPTY_VALUE';
 
            $metricLatencyStats->setLabel( $label, $value );
        }
        $metricLatencyStats->observeNanoseconds( $latency );
    }
 
    // endregion -- end of Unified metrics methods
}
 
/*
 * This file uses VisualStudio style region/endregion fold markers which are
 * recognised by PHPStorm. If modelines are enabled, the following editor
 * configuration will also enable folding in vim, if it is in the last 5 lines
 * of the file. We also use "@name" which creates sections in Doxygen.
 *
 * vim: foldmarker=//\ region,//\ endregion foldmethod=marker
 */
 
class_alias( ApiBase::class, 'ApiBase' );