diff options
Diffstat (limited to 'includes/api/ApiBase.php')
| -rw-r--r-- | includes/api/ApiBase.php | 2267 |
1 files changed, 1416 insertions, 851 deletions
diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index c1454e76..944e4895 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -30,36 +30,40 @@ * The class functions are divided into several areas of functionality: * * Module parameters: Derived classes can define getAllowedParams() to specify - * which parameters to expect, how to parse and validate them. + * which parameters to expect, how to parse and validate them. * * Profiling: various methods to allow keeping tabs on various tasks and their - * time costs + * time costs * * Self-documentation: code to allow the API to document its own state * * @ingroup API */ abstract class ApiBase extends ContextSource { - // These constants allow modules to specify exactly how to treat incoming parameters. - const PARAM_DFLT = 0; // Default value of the parameter - const PARAM_ISMULTI = 1; // Boolean, do we accept more than one item for this parameter (e.g.: titles)? - const PARAM_TYPE = 2; // Can be either a string type (e.g.: 'integer') or an array of allowed values - const PARAM_MAX = 3; // Max value allowed for a parameter. Only applies if TYPE='integer' - const PARAM_MAX2 = 4; // Max value allowed for a parameter for bots and sysops. Only applies if TYPE='integer' - const PARAM_MIN = 5; // Lowest value allowed for a parameter. Only applies if TYPE='integer' - const PARAM_ALLOW_DUPLICATES = 6; // Boolean, do we allow the same value to be set more than once when ISMULTI=true - const PARAM_DEPRECATED = 7; // Boolean, is the parameter deprecated (will show a warning) + // Default value of the parameter + const PARAM_DFLT = 0; + // Boolean, do we accept more than one item for this parameter (e.g.: titles)? + const PARAM_ISMULTI = 1; + // Can be either a string type (e.g.: 'integer') or an array of allowed values + const PARAM_TYPE = 2; + // Max value allowed for a parameter. Only applies if TYPE='integer' + const PARAM_MAX = 3; + // Max value allowed for a parameter for bots and sysops. Only applies if TYPE='integer' + const PARAM_MAX2 = 4; + // Lowest value allowed for a parameter. Only applies if TYPE='integer' + const PARAM_MIN = 5; + // Boolean, do we allow the same value to be set more than once when ISMULTI=true + const PARAM_ALLOW_DUPLICATES = 6; + // Boolean, is the parameter deprecated (will show a warning) + const PARAM_DEPRECATED = 7; /// @since 1.17 const PARAM_REQUIRED = 8; // Boolean, is the parameter required? /// @since 1.17 - const PARAM_RANGE_ENFORCE = 9; // Boolean, if MIN/MAX are set, enforce (die) these? Only applies if TYPE='integer' Use with extreme caution - - const PROP_ROOT = 'ROOT'; // Name of property group that is on the root element of the result, i.e. not part of a list - const PROP_LIST = 'LIST'; // Boolean, is the result multiple items? Defaults to true for query modules, to false for other modules - const PROP_TYPE = 0; // Type of the property, uses same format as PARAM_TYPE - const PROP_NULLABLE = 1; // Boolean, can the property be not included in the result? Defaults to false + // Boolean, if MIN/MAX are set, enforce (die) these? + // Only applies if TYPE='integer' Use with extreme caution + const PARAM_RANGE_ENFORCE = 9; const LIMIT_BIG1 = 500; // Fast query, std user limit const LIMIT_BIG2 = 5000; // Fast query, bot/sysop limit @@ -73,17 +77,19 @@ abstract class ApiBase extends ContextSource { */ const GET_VALUES_FOR_HELP = 1; - private $mMainModule, $mModuleName, $mModulePrefix; + /** @var ApiMain */ + private $mMainModule; + /** @var string */ + private $mModuleName, $mModulePrefix; private $mSlaveDB = null; private $mParamCache = array(); /** - * Constructor - * @param $mainModule ApiMain object + * @param ApiMain $mainModule * @param string $moduleName Name of this module * @param string $modulePrefix Prefix to use for parameter names */ - public function __construct( $mainModule, $moduleName, $modulePrefix = '' ) { + public function __construct( ApiMain $mainModule, $moduleName, $modulePrefix = '' ) { $this->mMainModule = $mainModule; $this->mModuleName = $moduleName; $this->mModulePrefix = $modulePrefix; @@ -93,9 +99,11 @@ abstract class ApiBase extends ContextSource { } } - /***************************************************************************** - * ABSTRACT METHODS * - *****************************************************************************/ + + /************************************************************************//** + * @name Methods to implement + * @{ + */ /** * Evaluates the parameters, performs the requested query, and sets up @@ -116,432 +124,232 @@ abstract class ApiBase extends ContextSource { abstract public function execute(); /** - * Returns a string that identifies the version of the extending class. - * Typically includes the class name, the svn revision, timestamp, and - * last author. Usually done with SVN's Id keyword - * @return string - * @deprecated since 1.21, version string is no longer supported + * Get the module manager, or null if this module has no sub-modules + * @since 1.21 + * @return ApiModuleManager */ - public function getVersion() { - wfDeprecated( __METHOD__, '1.21' ); - return ''; + public function getModuleManager() { + return null; } /** - * Get the name of the module being executed by this instance - * @return string + * If the module may only be used with a certain format module, + * it should override this method to return an instance of that formatter. + * A value of null means the default format will be used. + * @return mixed Instance of a derived class of ApiFormatBase, or null */ - public function getModuleName() { - return $this->mModuleName; + public function getCustomPrinter() { + return null; } /** - * Get the module manager, or null if this module has no sub-modules - * @since 1.21 - * @return ApiModuleManager + * Returns the description string for this module + * @return string|array */ - public function getModuleManager() { - return null; + protected function getDescription() { + return false; } /** - * Get parameter prefix (usually two letters or an empty string). - * @return string + * Returns usage examples for this module. Return false if no examples are available. + * @return bool|string|array */ - public function getModulePrefix() { - return $this->mModulePrefix; + protected function getExamples() { + return false; } /** - * Get the name of the module as shown in the profiler log + * @return bool|string|array Returns a false if the module has no help URL, + * else returns a (array of) string + */ + public function getHelpUrls() { + return false; + } + + /** + * Returns an array of allowed parameters (parameter name) => (default + * value) or (parameter name) => (array with PARAM_* constants as keys) + * Don't call this function directly: use getFinalParams() to allow + * hooks to modify parameters as needed. * - * @param $db DatabaseBase|bool + * Some derived classes may choose to handle an integer $flags parameter + * in the overriding methods. Callers of this method can pass zero or + * more OR-ed flags like GET_VALUES_FOR_HELP. * - * @return string + * @return array|bool */ - public function getModuleProfileName( $db = false ) { - if ( $db ) { - return 'API:' . $this->mModuleName . '-DB'; - } else { - return 'API:' . $this->mModuleName; - } + protected function getAllowedParams( /* $flags = 0 */ ) { + // int $flags is not declared because it causes "Strict standards" + // warning. Most derived classes do not implement it. + return false; } /** - * Get the main module - * @return ApiMain object + * Returns an array of parameter descriptions. + * Don't call this function directly: use getFinalParamDescription() to + * allow hooks to modify descriptions as needed. + * @return array|bool False on no parameter descriptions */ - public function getMain() { - return $this->mMainModule; + protected function getParamDescription() { + return false; } /** - * Returns true if this module is the main module ($this === $this->mMainModule), - * false otherwise. + * Indicates if this module needs maxlag to be checked * @return bool */ - public function isMain() { - return $this === $this->mMainModule; + public function shouldCheckMaxlag() { + return true; } /** - * Get the result object - * @return ApiResult + * Indicates whether this module requires read rights + * @return bool */ - public function getResult() { - // Main module has getResult() method overridden - // Safety - avoid infinite loop: - if ( $this->isMain() ) { - ApiBase::dieDebug( __METHOD__, 'base method was called on main module. ' ); - } - return $this->getMain()->getResult(); + public function isReadMode() { + return true; } /** - * Get the result data array (read-only) - * @return array + * Indicates whether this module requires write mode + * @return bool */ - public function getResultData() { - return $this->getResult()->getData(); + public function isWriteMode() { + return false; } /** - * Create a new RequestContext object to use e.g. for calls to other parts - * the software. - * The object will have the WebRequest and the User object set to the ones - * used in this instance. - * - * @deprecated since 1.19 use getContext to get the current context - * @return DerivativeContext + * Indicates whether this module must be called with a POST request + * @return bool */ - public function createContext() { - wfDeprecated( __METHOD__, '1.19' ); - return new DerivativeContext( $this->getContext() ); + public function mustBePosted() { + return $this->needsToken() !== false; } /** - * Set warning section for this module. Users should monitor this - * section to notice any changes in API. Multiple calls to this - * function will result in the warning messages being separated by - * newlines - * @param string $warning Warning message + * Returns the token type this module requires in order to execute. + * + * Modules are strongly encouraged to use the core 'csrf' type unless they + * have specialized security needs. If the token type is not one of the + * core types, you must use the ApiQueryTokensRegisterTypes hook to + * register it. + * + * Returning a non-falsey value here will cause self::getFinalParams() to + * return a required string 'token' parameter and + * self::getFinalParamDescription() to ensure there is standardized + * documentation for it. Also, self::mustBePosted() must return true when + * tokens are used. + * + * In previous versions of MediaWiki, true was a valid return value. + * Returning true will generate errors indicating that the API module needs + * updating. + * + * @return string|false */ - public function setWarning( $warning ) { - $result = $this->getResult(); - $data = $result->getData(); - $moduleName = $this->getModuleName(); - if ( isset( $data['warnings'][$moduleName] ) ) { - // Don't add duplicate warnings - $oldWarning = $data['warnings'][$moduleName]['*']; - $warnPos = strpos( $oldWarning, $warning ); - // If $warning was found in $oldWarning, check if it starts at 0 or after "\n" - if ( $warnPos !== false && ( $warnPos === 0 || $oldWarning[$warnPos - 1] === "\n" ) ) { - // Check if $warning is followed by "\n" or the end of the $oldWarning - $warnPos += strlen( $warning ); - if ( strlen( $oldWarning ) <= $warnPos || $oldWarning[$warnPos] === "\n" ) { - return; - } - } - // If there is a warning already, append it to the existing one - $warning = "$oldWarning\n$warning"; - } - $msg = array(); - ApiResult::setContent( $msg, $warning ); - $result->disableSizeCheck(); - $result->addValue( 'warnings', $moduleName, - $msg, ApiResult::OVERRIDE | ApiResult::ADD_ON_TOP ); - $result->enableSizeCheck(); + public function needsToken() { + return false; } /** - * If the module may only be used with a certain format module, - * it should override this method to return an instance of that formatter. - * A value of null means the default format will be used. - * @return mixed instance of a derived class of ApiFormatBase, or null + * Fetch the salt used in the Web UI corresponding to this module. + * + * Only override this if the Web UI uses a token with a non-constant salt. + * + * @since 1.24 + * @param array $params All supplied parameters for the module + * @return string|array|null */ - public function getCustomPrinter() { + protected function getWebUITokenSalt( array $params ) { return null; } - /** - * Generates help message for this module, or false if there is no description - * @return mixed string or false - */ - public function makeHelpMsg() { - static $lnPrfx = "\n "; - - $msg = $this->getFinalDescription(); - - if ( $msg !== false ) { - - if ( !is_array( $msg ) ) { - $msg = array( - $msg - ); - } - $msg = $lnPrfx . implode( $lnPrfx, $msg ) . "\n"; + /**@}*/ - $msg .= $this->makeHelpArrayToString( $lnPrfx, false, $this->getHelpUrls() ); - - if ( $this->isReadMode() ) { - $msg .= "\nThis module requires read rights"; - } - if ( $this->isWriteMode() ) { - $msg .= "\nThis module requires write rights"; - } - if ( $this->mustBePosted() ) { - $msg .= "\nThis module only accepts POST requests"; - } - if ( $this->isReadMode() || $this->isWriteMode() || - $this->mustBePosted() ) { - $msg .= "\n"; - } - - // Parameters - $paramsMsg = $this->makeHelpMsgParameters(); - if ( $paramsMsg !== false ) { - $msg .= "Parameters:\n$paramsMsg"; - } - - $examples = $this->getExamples(); - if ( $examples ) { - if ( !is_array( $examples ) ) { - $examples = array( - $examples - ); - } - $msg .= "Example" . ( count( $examples ) > 1 ? 's' : '' ) . ":\n"; - foreach ( $examples as $k => $v ) { - if ( is_numeric( $k ) ) { - $msg .= " $v\n"; - } else { - if ( is_array( $v ) ) { - $msgExample = implode( "\n", array_map( array( $this, 'indentExampleText' ), $v ) ); - } else { - $msgExample = " $v"; - } - $msgExample .= ":"; - $msg .= wordwrap( $msgExample, 100, "\n" ) . "\n $k\n"; - } - } - } - } - - return $msg; - } + /************************************************************************//** + * @name Data access methods + * @{ + */ /** - * @param $item string + * Get the name of the module being executed by this instance * @return string */ - private function indentExampleText( $item ) { - return " " . $item; + public function getModuleName() { + return $this->mModuleName; } /** - * @param string $prefix Text to split output items - * @param string $title What is being output - * @param $input string|array + * Get parameter prefix (usually two letters or an empty string). * @return string */ - protected function makeHelpArrayToString( $prefix, $title, $input ) { - if ( $input === false ) { - return ''; - } - if ( !is_array( $input ) ) { - $input = array( $input ); - } - - if ( count( $input ) > 0 ) { - if ( $title ) { - $msg = $title . ( count( $input ) > 1 ? 's' : '' ) . ":\n "; - } else { - $msg = ' '; - } - $msg .= implode( $prefix, $input ) . "\n"; - return $msg; - } - return ''; + public function getModulePrefix() { + return $this->mModulePrefix; } /** - * Generates the parameter descriptions for this module, to be displayed in the - * module's help. - * @return string or false + * Get the main module + * @return ApiMain */ - public function makeHelpMsgParameters() { - $params = $this->getFinalParams( ApiBase::GET_VALUES_FOR_HELP ); - if ( $params ) { - - $paramsDescription = $this->getFinalParamDescription(); - $msg = ''; - $paramPrefix = "\n" . str_repeat( ' ', 24 ); - $descWordwrap = "\n" . str_repeat( ' ', 28 ); - foreach ( $params as $paramName => $paramSettings ) { - $desc = isset( $paramsDescription[$paramName] ) ? $paramsDescription[$paramName] : ''; - if ( is_array( $desc ) ) { - $desc = implode( $paramPrefix, $desc ); - } - - //handle shorthand - if ( !is_array( $paramSettings ) ) { - $paramSettings = array( - self::PARAM_DFLT => $paramSettings, - ); - } - - //handle missing type - if ( !isset( $paramSettings[ApiBase::PARAM_TYPE] ) ) { - $dflt = isset( $paramSettings[ApiBase::PARAM_DFLT] ) ? $paramSettings[ApiBase::PARAM_DFLT] : null; - if ( is_bool( $dflt ) ) { - $paramSettings[ApiBase::PARAM_TYPE] = 'boolean'; - } elseif ( is_string( $dflt ) || is_null( $dflt ) ) { - $paramSettings[ApiBase::PARAM_TYPE] = 'string'; - } elseif ( is_int( $dflt ) ) { - $paramSettings[ApiBase::PARAM_TYPE] = 'integer'; - } - } - - if ( isset( $paramSettings[self::PARAM_DEPRECATED] ) && $paramSettings[self::PARAM_DEPRECATED] ) { - $desc = "DEPRECATED! $desc"; - } - - if ( isset( $paramSettings[self::PARAM_REQUIRED] ) && $paramSettings[self::PARAM_REQUIRED] ) { - $desc .= $paramPrefix . "This parameter is required"; - } - - $type = isset( $paramSettings[self::PARAM_TYPE] ) ? $paramSettings[self::PARAM_TYPE] : null; - if ( isset( $type ) ) { - $hintPipeSeparated = true; - $multi = isset( $paramSettings[self::PARAM_ISMULTI] ) ? $paramSettings[self::PARAM_ISMULTI] : false; - if ( $multi ) { - $prompt = 'Values (separate with \'|\'): '; - } else { - $prompt = 'One value: '; - } - - if ( is_array( $type ) ) { - $choices = array(); - $nothingPrompt = ''; - foreach ( $type as $t ) { - if ( $t === '' ) { - $nothingPrompt = 'Can be empty, or '; - } else { - $choices[] = $t; - } - } - $desc .= $paramPrefix . $nothingPrompt . $prompt; - $choicesstring = implode( ', ', $choices ); - $desc .= wordwrap( $choicesstring, 100, $descWordwrap ); - $hintPipeSeparated = false; - } else { - switch ( $type ) { - case 'namespace': - // Special handling because namespaces are type-limited, yet they are not given - $desc .= $paramPrefix . $prompt; - $desc .= wordwrap( implode( ', ', MWNamespace::getValidNamespaces() ), - 100, $descWordwrap ); - $hintPipeSeparated = false; - break; - case 'limit': - $desc .= $paramPrefix . "No more than {$paramSettings[self::PARAM_MAX]}"; - if ( isset( $paramSettings[self::PARAM_MAX2] ) ) { - $desc .= " ({$paramSettings[self::PARAM_MAX2]} for bots)"; - } - $desc .= ' allowed'; - break; - case 'integer': - $s = $multi ? 's' : ''; - $hasMin = isset( $paramSettings[self::PARAM_MIN] ); - $hasMax = isset( $paramSettings[self::PARAM_MAX] ); - if ( $hasMin || $hasMax ) { - if ( !$hasMax ) { - $intRangeStr = "The value$s must be no less than {$paramSettings[self::PARAM_MIN]}"; - } elseif ( !$hasMin ) { - $intRangeStr = "The value$s must be no more than {$paramSettings[self::PARAM_MAX]}"; - } else { - $intRangeStr = "The value$s must be between {$paramSettings[self::PARAM_MIN]} and {$paramSettings[self::PARAM_MAX]}"; - } - - $desc .= $paramPrefix . $intRangeStr; - } - break; - case 'upload': - $desc .= $paramPrefix . "Must be posted as a file upload using multipart/form-data"; - break; - } - } - - if ( $multi ) { - if ( $hintPipeSeparated ) { - $desc .= $paramPrefix . "Separate values with '|'"; - } - - $isArray = is_array( $type ); - if ( !$isArray - || $isArray && count( $type ) > self::LIMIT_SML1 ) { - $desc .= $paramPrefix . "Maximum number of values " . - self::LIMIT_SML1 . " (" . self::LIMIT_SML2 . " for bots)"; - } - } - } - - $default = isset( $paramSettings[self::PARAM_DFLT] ) ? $paramSettings[self::PARAM_DFLT] : null; - if ( !is_null( $default ) && $default !== false ) { - $desc .= $paramPrefix . "Default: $default"; - } - - $msg .= sprintf( " %-19s - %s\n", $this->encodeParamName( $paramName ), $desc ); - } - return $msg; + public function getMain() { + return $this->mMainModule; + } - } else { - return false; - } + /** + * Returns true if this module is the main module ($this === $this->mMainModule), + * false otherwise. + * @return bool + */ + public function isMain() { + return $this === $this->mMainModule; } /** - * Returns the description string for this module - * @return mixed string or array of strings + * Get the result object + * @return ApiResult */ - protected function getDescription() { - return false; + public function getResult() { + // Main module has getResult() method overridden + // Safety - avoid infinite loop: + if ( $this->isMain() ) { + ApiBase::dieDebug( __METHOD__, 'base method was called on main module. ' ); + } + + return $this->getMain()->getResult(); } /** - * Returns usage examples for this module. Return false if no examples are available. - * @return bool|string|array + * Get the result data array (read-only) + * @return array */ - protected function getExamples() { - return false; + public function getResultData() { + return $this->getResult()->getData(); } /** - * Returns an array of allowed parameters (parameter name) => (default - * value) or (parameter name) => (array with PARAM_* constants as keys) - * Don't call this function directly: use getFinalParams() to allow - * hooks to modify parameters as needed. - * - * Some derived classes may choose to handle an integer $flags parameter - * in the overriding methods. Callers of this method can pass zero or - * more OR-ed flags like GET_VALUES_FOR_HELP. - * - * @return array|bool + * Gets a default slave database connection object + * @return DatabaseBase */ - protected function getAllowedParams( /* $flags = 0 */ ) { - // int $flags is not declared because it causes "Strict standards" - // warning. Most derived classes do not implement it. - return false; + protected function getDB() { + if ( !isset( $this->mSlaveDB ) ) { + $this->profileDBIn(); + $this->mSlaveDB = wfGetDB( DB_SLAVE, 'api' ); + $this->profileDBOut(); + } + + return $this->mSlaveDB; } /** - * Returns an array of parameter descriptions. - * Don't call this function directly: use getFinalParamDescription() to - * allow hooks to modify descriptions as needed. - * @return array|bool False on no parameter descriptions + * Get final module description, after hooks have had a chance to tweak it as + * needed. + * + * @return array|bool False on no parameters */ - protected function getParamDescription() { - return false; + public function getFinalDescription() { + $desc = $this->getDescription(); + wfRunHooks( 'APIGetDescription', array( &$this, &$desc ) ); + + return $desc; } /** @@ -549,12 +357,21 @@ abstract class ApiBase extends ContextSource { * tweak it as needed. * * @param int $flags Zero or more flags like GET_VALUES_FOR_HELP - * @return array|Bool False on no parameters + * @return array|bool False on no parameters * @since 1.21 $flags param added */ public function getFinalParams( $flags = 0 ) { $params = $this->getAllowedParams( $flags ); + + if ( $this->needsToken() ) { + $params['token'] = array( + ApiBase::PARAM_TYPE => 'string', + ApiBase::PARAM_REQUIRED => true, + ); + } + wfRunHooks( 'APIGetAllowedParams', array( &$this, &$params, $flags ) ); + return $params; } @@ -566,67 +383,33 @@ abstract class ApiBase extends ContextSource { */ public function getFinalParamDescription() { $desc = $this->getParamDescription(); - wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) ); - return $desc; - } - /** - * Returns possible properties in the result, grouped by the value of the prop parameter - * that shows them. - * - * Properties that are shown always are in a group with empty string as a key. - * Properties that can be shown by several values of prop are included multiple times. - * If some properties are part of a list and some are on the root object (see ApiQueryQueryPage), - * those on the root object are under the key PROP_ROOT. - * The array can also contain a boolean under the key PROP_LIST, - * indicating whether the result is a list. - * - * Don't call this function directly: use getFinalResultProperties() to - * allow hooks to modify descriptions as needed. - * - * @return array|bool False on no properties - */ - protected function getResultProperties() { - return false; - } - - /** - * Get final possible result properties, after hooks have had a chance to tweak it as - * needed. - * - * @return array - */ - public function getFinalResultProperties() { - $properties = $this->getResultProperties(); - wfRunHooks( 'APIGetResultProperties', array( $this, &$properties ) ); - return $properties; - } - - /** - * Add token properties to the array used by getResultProperties, - * based on a token functions mapping. - */ - protected static function addTokenProperties( &$props, $tokenFunctions ) { - foreach ( array_keys( $tokenFunctions ) as $token ) { - $props[''][$token . 'token'] = array( - ApiBase::PROP_TYPE => 'string', - ApiBase::PROP_NULLABLE => true + $tokenType = $this->needsToken(); + if ( $tokenType ) { + if ( !isset( $desc['token'] ) ) { + $desc['token'] = array(); + } elseif ( !is_array( $desc['token'] ) ) { + // We ignore a plain-string token, because it's probably an + // extension that is supplying the string for BC. + $desc['token'] = array(); + } + array_unshift( $desc['token'], + "A '$tokenType' token retrieved from action=query&meta=tokens" ); } - } - /** - * Get final module description, after hooks have had a chance to tweak it as - * needed. - * - * @return array|bool False on no parameters - */ - public function getFinalDescription() { - $desc = $this->getDescription(); - wfRunHooks( 'APIGetDescription', array( &$this, &$desc ) ); + wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) ); + return $desc; } + /**@}*/ + + /************************************************************************//** + * @name Parameter handling + * @{ + */ + /** * This method mangles parameter name based on the prefix supplied to the constructor. * Override this method to change parameter name during runtime @@ -643,7 +426,7 @@ abstract class ApiBase extends ContextSource { * value - validated value from user or default. limits will not be * parsed if $parseLimit is set to false; use this when the max * limit is not definitive yet, e.g. when getting revisions. - * @param $parseLimit Boolean: true by default + * @param bool $parseLimit True by default * @return array */ public function extractRequestParams( $parseLimit = true ) { @@ -660,26 +443,30 @@ abstract class ApiBase extends ContextSource { } $this->mParamCache[$parseLimit] = $results; } + return $this->mParamCache[$parseLimit]; } /** * Get a value for the given parameter * @param string $paramName Parameter name - * @param bool $parseLimit see extractRequestParams() + * @param bool $parseLimit See extractRequestParams() * @return mixed Parameter value */ protected function getParameter( $paramName, $parseLimit = true ) { $params = $this->getFinalParams(); $paramSettings = $params[$paramName]; + return $this->getParameterFromSettings( $paramName, $paramSettings, $parseLimit ); } /** * Die if none or more than one of a certain set of parameters is set and not false. - * @param array $params of parameter names + * + * @param array $params User provided set of parameters, as from $this->extractRequestParams() + * @param string $required,... Names of parameters of which exactly one must be set */ - public function requireOnlyOneParameter( $params ) { + public function requireOnlyOneParameter( $params, $required /*...*/ ) { $required = func_get_args(); array_shift( $required ); $p = $this->getModulePrefix(); @@ -688,34 +475,24 @@ abstract class ApiBase extends ContextSource { array( $this, "parameterNotEmpty" ) ) ), $required ); if ( count( $intersection ) > 1 ) { - $this->dieUsage( "The parameters {$p}" . implode( ", {$p}", $intersection ) . ' can not be used together', 'invalidparammix' ); + $this->dieUsage( + "The parameters {$p}" . implode( ", {$p}", $intersection ) . ' can not be used together', + 'invalidparammix' ); } elseif ( count( $intersection ) == 0 ) { - $this->dieUsage( "One of the parameters {$p}" . implode( ", {$p}", $required ) . ' is required', 'missingparam' ); + $this->dieUsage( + "One of the parameters {$p}" . implode( ", {$p}", $required ) . ' is required', + 'missingparam' + ); } } /** - * Generates the possible errors requireOnlyOneParameter() can die with - * - * @param $params array - * @return array - */ - public function getRequireOnlyOneParameterErrorMessages( $params ) { - $p = $this->getModulePrefix(); - $params = implode( ", {$p}", $params ); - - return array( - array( 'code' => "{$p}missingparam", 'info' => "One of the parameters {$p}{$params} is required" ), - array( 'code' => "{$p}invalidparammix", 'info' => "The parameters {$p}{$params} can not be used together" ) - ); - } - - /** * Die if more than one of a certain set of parameters is set and not false. * - * @param $params array + * @param array $params User provided set of parameters, as from $this->extractRequestParams() + * @param string $required,... Names of parameters of which at most one must be set */ - public function requireMaxOneParameter( $params ) { + public function requireMaxOneParameter( $params, $required /*...*/ ) { $required = func_get_args(); array_shift( $required ); $p = $this->getModulePrefix(); @@ -724,27 +501,51 @@ abstract class ApiBase extends ContextSource { array( $this, "parameterNotEmpty" ) ) ), $required ); if ( count( $intersection ) > 1 ) { - $this->dieUsage( "The parameters {$p}" . implode( ", {$p}", $intersection ) . ' can not be used together', 'invalidparammix' ); + $this->dieUsage( + "The parameters {$p}" . implode( ", {$p}", $intersection ) . ' can not be used together', + 'invalidparammix' + ); } } /** - * Generates the possible error requireMaxOneParameter() can die with + * Die if none of a certain set of parameters is set and not false. * - * @param $params array - * @return array + * @since 1.23 + * @param array $params User provided set of parameters, as from $this->extractRequestParams() + * @param string $required,... Names of parameters of which at least one must be set */ - public function getRequireMaxOneParameterErrorMessages( $params ) { + public function requireAtLeastOneParameter( $params, $required /*...*/ ) { + $required = func_get_args(); + array_shift( $required ); $p = $this->getModulePrefix(); - $params = implode( ", {$p}", $params ); - return array( - array( 'code' => "{$p}invalidparammix", 'info' => "The parameters {$p}{$params} can not be used together" ) + $intersection = array_intersect( + array_keys( array_filter( $params, array( $this, "parameterNotEmpty" ) ) ), + $required ); + + if ( count( $intersection ) == 0 ) { + $this->dieUsage( "At least one of the parameters {$p}" . + implode( ", {$p}", $required ) . ' is required', "{$p}missingparam" ); + } + } + + /** + * Callback function used in requireOnlyOneParameter to check whether required parameters are set + * + * @param object $x Parameter to check is not null/false + * @return bool + */ + private function parameterNotEmpty( $x ) { + return !is_null( $x ) && $x !== false; } /** - * @param $params array + * Get a WikiPage object from a title or pageid param, if possible. + * Can die, if no param is set or if the title or page id is not valid. + * + * @param array $params * @param bool|string $load Whether load the object's state from the database: * - false: don't load (if the pageid is given, it will still be loaded) * - 'fromdb': load from a slave database @@ -781,44 +582,11 @@ abstract class ApiBase extends ContextSource { } /** - * @return array - */ - public function getTitleOrPageIdErrorMessage() { - return array_merge( - $this->getRequireOnlyOneParameterErrorMessages( array( 'title', 'pageid' ) ), - array( - array( 'invalidtitle', 'title' ), - array( 'nosuchpageid', 'pageid' ), - ) - ); - } - - /** - * Callback function used in requireOnlyOneParameter to check whether required parameters are set - * - * @param $x object Parameter to check is not null/false - * @return bool - */ - private function parameterNotEmpty( $x ) { - return !is_null( $x ) && $x !== false; - } - - /** - * @deprecated since 1.17 use MWNamespace::getValidNamespaces() - * - * @return array - */ - public static function getValidNamespaces() { - wfDeprecated( __METHOD__, '1.17' ); - return MWNamespace::getValidNamespaces(); - } - - /** * Return true if we're to watch the page, false if not, null if no change. * @param string $watchlist Valid values: 'watch', 'unwatch', 'preferences', 'nochange' - * @param $titleObj Title the page under consideration + * @param Title $titleObj The page under consideration * @param string $userOption The user option to consider when $watchlist=preferences. - * If not set will magically default to either watchdefault or watchcreations + * If not set will use watchdefault always and watchcreations if $titleObj doesn't exist. * @return bool */ protected function getWatchlistValue( $watchlist, $titleObj, $userOption = null ) { @@ -837,11 +605,12 @@ abstract class ApiBase extends ContextSource { if ( $userWatching ) { return true; } - # If no user option was passed, use watchdefault or watchcreations + # If no user option was passed, use watchdefault and watchcreations if ( is_null( $userOption ) ) { - $userOption = $titleObj->exists() - ? 'watchdefault' : 'watchcreations'; + return $this->getUser()->getBoolOption( 'watchdefault' ) || + $this->getUser()->getBoolOption( 'watchcreations' ) && !$titleObj->exists(); } + # Watch the article based on the user preference return $this->getUser()->getBoolOption( $userOption ); @@ -854,27 +623,12 @@ abstract class ApiBase extends ContextSource { } /** - * Set a watch (or unwatch) based the based on a watchlist parameter. - * @param string $watch Valid values: 'watch', 'unwatch', 'preferences', 'nochange' - * @param $titleObj Title the article's title to change - * @param string $userOption The user option to consider when $watch=preferences - */ - protected function setWatch( $watch, $titleObj, $userOption = null ) { - $value = $this->getWatchlistValue( $watch, $titleObj, $userOption ); - if ( $value === null ) { - return; - } - - WatchAction::doWatchOrUnwatch( $value, $titleObj, $this->getUser() ); - } - - /** * Using the settings determine the value for the given parameter * - * @param string $paramName parameter name - * @param array|mixed $paramSettings default value or an array of settings + * @param string $paramName Parameter name + * @param array|mixed $paramSettings Default value or an array of settings * using PARAM_* constants. - * @param $parseLimit Boolean: parse limit? + * @param bool $parseLimit Parse limit? * @return mixed Parameter value */ protected function getParameterFromSettings( $paramName, $paramSettings, $parseLimit ) { @@ -889,12 +643,24 @@ abstract class ApiBase extends ContextSource { $deprecated = false; $required = false; } else { - $default = isset( $paramSettings[self::PARAM_DFLT] ) ? $paramSettings[self::PARAM_DFLT] : null; - $multi = isset( $paramSettings[self::PARAM_ISMULTI] ) ? $paramSettings[self::PARAM_ISMULTI] : false; - $type = isset( $paramSettings[self::PARAM_TYPE] ) ? $paramSettings[self::PARAM_TYPE] : null; - $dupes = isset( $paramSettings[self::PARAM_ALLOW_DUPLICATES] ) ? $paramSettings[self::PARAM_ALLOW_DUPLICATES] : false; - $deprecated = isset( $paramSettings[self::PARAM_DEPRECATED] ) ? $paramSettings[self::PARAM_DEPRECATED] : false; - $required = isset( $paramSettings[self::PARAM_REQUIRED] ) ? $paramSettings[self::PARAM_REQUIRED] : false; + $default = isset( $paramSettings[self::PARAM_DFLT] ) + ? $paramSettings[self::PARAM_DFLT] + : null; + $multi = isset( $paramSettings[self::PARAM_ISMULTI] ) + ? $paramSettings[self::PARAM_ISMULTI] + : false; + $type = isset( $paramSettings[self::PARAM_TYPE] ) + ? $paramSettings[self::PARAM_TYPE] + : null; + $dupes = isset( $paramSettings[self::PARAM_ALLOW_DUPLICATES] ) + ? $paramSettings[self::PARAM_ALLOW_DUPLICATES] + : false; + $deprecated = isset( $paramSettings[self::PARAM_DEPRECATED] ) + ? $paramSettings[self::PARAM_DEPRECATED] + : false; + $required = isset( $paramSettings[self::PARAM_REQUIRED] ) + ? $paramSettings[self::PARAM_REQUIRED] + : false; // When type is not given, and no choices, the type is the same as $default if ( !isset( $type ) ) { @@ -909,14 +675,21 @@ abstract class ApiBase extends ContextSource { if ( $type == 'boolean' ) { if ( isset( $default ) && $default !== false ) { // Having a default value of anything other than 'false' is not allowed - ApiBase::dieDebug( __METHOD__, "Boolean param $encParamName's default is set to '$default'. Boolean parameters must default to false." ); + ApiBase::dieDebug( + __METHOD__, + "Boolean param $encParamName's default is set to '$default'. " . + "Boolean parameters must default to false." + ); } $value = $this->getMain()->getCheck( $encParamName ); } elseif ( $type == 'upload' ) { if ( isset( $default ) ) { // Having a default value is not allowed - ApiBase::dieDebug( __METHOD__, "File upload param $encParamName's default is set to '$default'. File upload parameters may not have a default." ); + ApiBase::dieDebug( + __METHOD__, + "File upload param $encParamName's default is set to " . + "'$default'. File upload parameters may not have a default." ); } if ( $multi ) { ApiBase::dieDebug( __METHOD__, "Multi-values not supported for $encParamName" ); @@ -930,8 +703,8 @@ abstract class ApiBase extends ContextSource { if ( $value !== null ) { $this->dieUsage( "File upload param $encParamName is not a file upload; " . - "be sure to use multipart/form-data for your POST and include " . - "a filename in the Content-Disposition header.", + "be sure to use multipart/form-data for your POST and include " . + "a filename in the Content-Disposition header.", "badupload_{$encParamName}" ); } @@ -942,10 +715,18 @@ abstract class ApiBase extends ContextSource { if ( isset( $value ) && $type == 'namespace' ) { $type = MWNamespace::getValidNamespaces(); } + if ( isset( $value ) && $type == 'submodule' ) { + $type = $this->getModuleManager()->getNames( $paramName ); + } } if ( isset( $value ) && ( $multi || is_array( $type ) ) ) { - $value = $this->parseMultiValue( $encParamName, $value, $multi, is_array( $type ) ? $type : null ); + $value = $this->parseMultiValue( + $encParamName, + $value, + $multi, + is_array( $type ) ? $type : null + ); } // More validation only when choices were not given @@ -964,7 +745,7 @@ abstract class ApiBase extends ContextSource { $min = isset( $paramSettings[self::PARAM_MIN] ) ? $paramSettings[self::PARAM_MIN] : null; $max = isset( $paramSettings[self::PARAM_MAX] ) ? $paramSettings[self::PARAM_MAX] : null; $enforceLimits = isset( $paramSettings[self::PARAM_RANGE_ENFORCE] ) - ? $paramSettings[self::PARAM_RANGE_ENFORCE] : false; + ? $paramSettings[self::PARAM_RANGE_ENFORCE] : false; if ( is_array( $value ) ) { $value = array_map( 'intval', $value ); @@ -985,19 +766,32 @@ abstract class ApiBase extends ContextSource { // Don't do any validation whatsoever break; } - if ( !isset( $paramSettings[self::PARAM_MAX] ) || !isset( $paramSettings[self::PARAM_MAX2] ) ) { - ApiBase::dieDebug( __METHOD__, "MAX1 or MAX2 are not defined for the limit $encParamName" ); + if ( !isset( $paramSettings[self::PARAM_MAX] ) + || !isset( $paramSettings[self::PARAM_MAX2] ) + ) { + ApiBase::dieDebug( + __METHOD__, + "MAX1 or MAX2 are not defined for the limit $encParamName" + ); } if ( $multi ) { ApiBase::dieDebug( __METHOD__, "Multi-values not supported for $encParamName" ); } $min = isset( $paramSettings[self::PARAM_MIN] ) ? $paramSettings[self::PARAM_MIN] : 0; if ( $value == 'max' ) { - $value = $this->getMain()->canApiHighLimits() ? $paramSettings[self::PARAM_MAX2] : $paramSettings[self::PARAM_MAX]; + $value = $this->getMain()->canApiHighLimits() + ? $paramSettings[self::PARAM_MAX2] + : $paramSettings[self::PARAM_MAX]; $this->getResult()->setParsedLimit( $this->getModuleName(), $value ); } else { $value = intval( $value ); - $this->validateLimit( $paramName, $value, $min, $paramSettings[self::PARAM_MAX], $paramSettings[self::PARAM_MAX2] ); + $this->validateLimit( + $paramName, + $value, + $min, + $paramSettings[self::PARAM_MAX], + $paramSettings[self::PARAM_MAX2] + ); } break; case 'boolean': @@ -1052,25 +846,28 @@ abstract class ApiBase extends ContextSource { * * @param string $valueName The name of the parameter (for error * reporting) - * @param $value mixed The value being parsed + * @param mixed $value The value being parsed * @param bool $allowMultiple Can $value contain more than one value * separated by '|'? - * @param $allowedValues mixed An array of values to check against. If + * @param string[]|null $allowedValues An array of values to check against. If * null, all values are accepted. - * @return mixed (allowMultiple ? an_array_of_values : a_single_value) + * @return string|string[] (allowMultiple ? an_array_of_values : a_single_value) */ protected function parseMultiValue( $valueName, $value, $allowMultiple, $allowedValues ) { if ( trim( $value ) === '' && $allowMultiple ) { return array(); } - // This is a bit awkward, but we want to avoid calling canApiHighLimits() because it unstubs $wgUser + // This is a bit awkward, but we want to avoid calling canApiHighLimits() + // because it unstubs $wgUser $valuesList = explode( '|', $value, self::LIMIT_SML2 + 1 ); - $sizeLimit = count( $valuesList ) > self::LIMIT_SML1 && $this->mMainModule->canApiHighLimits() ? - self::LIMIT_SML2 : self::LIMIT_SML1; + $sizeLimit = count( $valuesList ) > self::LIMIT_SML1 && $this->mMainModule->canApiHighLimits() + ? self::LIMIT_SML2 + : self::LIMIT_SML1; if ( self::truncateArray( $valuesList, $sizeLimit ) ) { - $this->setWarning( "Too many values supplied for parameter '$valueName': the limit is $sizeLimit" ); + $this->setWarning( "Too many values supplied for parameter '$valueName': " . + "the limit is $sizeLimit" ); } if ( !$allowMultiple && count( $valuesList ) != 1 ) { @@ -1079,8 +876,13 @@ abstract class ApiBase extends ContextSource { return $value; } - $possibleValues = is_array( $allowedValues ) ? "of '" . implode( "', '", $allowedValues ) . "'" : ''; - $this->dieUsage( "Only one $possibleValues is allowed for parameter '$valueName'", "multival_$valueName" ); + $possibleValues = is_array( $allowedValues ) + ? "of '" . implode( "', '", $allowedValues ) . "'" + : ''; + $this->dieUsage( + "Only one $possibleValues is allowed for parameter '$valueName'", + "multival_$valueName" + ); } if ( is_array( $allowedValues ) ) { @@ -1092,7 +894,10 @@ abstract class ApiBase extends ContextSource { $vals = implode( ", ", $unknown ); $this->setWarning( "Unrecognized value$s for parameter '$valueName': $vals" ); } else { - $this->dieUsage( "Unrecognized value for parameter '$valueName': {$valuesList[0]}", "unknown_$valueName" ); + $this->dieUsage( + "Unrecognized value for parameter '$valueName': {$valuesList[0]}", + "unknown_$valueName" + ); } } // Now throw them out @@ -1110,9 +915,9 @@ abstract class ApiBase extends ContextSource { * @param int|null $min Minimum value * @param int|null $max Maximum value for users * @param int $botMax Maximum value for sysops/bots - * @param $enforceLimits Boolean Whether to enforce (die) if value is outside limits + * @param bool $enforceLimits Whether to enforce (die) if value is outside limits */ - function validateLimit( $paramName, &$value, $min, $max, $botMax = null, $enforceLimits = false ) { + protected function validateLimit( $paramName, &$value, $min, $max, $botMax = null, $enforceLimits = false ) { if ( !is_null( $min ) && $value < $min ) { $msg = $this->encodeParamName( $paramName ) . " may not be less than $min (set to $value)"; @@ -1120,7 +925,8 @@ abstract class ApiBase extends ContextSource { $value = $min; } - // Minimum is always validated, whereas maximum is checked only if not running in internal call mode + // Minimum is always validated, whereas maximum is checked only if not + // running in internal call mode if ( $this->getMain()->isInternalMode() ) { return; } @@ -1130,7 +936,8 @@ abstract class ApiBase extends ContextSource { if ( !is_null( $max ) && $value > $max ) { if ( !is_null( $botMax ) && $this->getMain()->canApiHighLimits() ) { if ( $value > $botMax ) { - $msg = $this->encodeParamName( $paramName ) . " may not be over $botMax (set to $value) for bots or sysops"; + $msg = $this->encodeParamName( $paramName ) . + " may not be over $botMax (set to $value) for bots or sysops"; $this->warnOrDie( $msg, $enforceLimits ); $value = $botMax; } @@ -1148,15 +955,57 @@ abstract class ApiBase extends ContextSource { * @param string $encParamName Parameter name * @return string Validated and normalized parameter */ - function validateTimestamp( $value, $encParamName ) { + protected function validateTimestamp( $value, $encParamName ) { $unixTimestamp = wfTimestamp( TS_UNIX, $value ); if ( $unixTimestamp === false ) { - $this->dieUsage( "Invalid value '$value' for timestamp parameter $encParamName", "badtimestamp_{$encParamName}" ); + $this->dieUsage( + "Invalid value '$value' for timestamp parameter $encParamName", + "badtimestamp_{$encParamName}" + ); } + return wfTimestamp( TS_MW, $unixTimestamp ); } /** + * Validate the supplied token. + * + * @since 1.24 + * @param string $token Supplied token + * @param array $params All supplied parameters for the module + * @return bool + */ + public final 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' + ); + } + + if ( $this->getUser()->matchEditToken( + $token, + $salts[$tokenType], + $this->getRequest() + ) ) { + return true; + } + + $webUiSalt = $this->getWebUITokenSalt( $params ); + if ( $webUiSalt !== null && $this->getUser()->matchEditToken( + $token, + $webUiSalt, + $this->getRequest() + ) ) { + return true; + } + + return false; + } + + /** * Validate and normalize of parameters of type 'user' * @param string $value Parameter value * @param string $encParamName Parameter name @@ -1165,23 +1014,35 @@ abstract class ApiBase extends ContextSource { private function validateUser( $value, $encParamName ) { $title = Title::makeTitleSafe( NS_USER, $value ); if ( $title === null ) { - $this->dieUsage( "Invalid value '$value' for user parameter $encParamName", "baduser_{$encParamName}" ); + $this->dieUsage( + "Invalid value '$value' for user parameter $encParamName", + "baduser_{$encParamName}" + ); } + return $title->getText(); } + /**@}*/ + + /************************************************************************//** + * @name Utility methods + * @{ + */ + /** - * Adds a warning to the output, else dies - * - * @param $msg String Message to show as a warning, or error message if dying - * @param $enforceLimits Boolean Whether this is an enforce (die) + * Set a watch (or unwatch) based the based on a watchlist parameter. + * @param string $watch Valid values: 'watch', 'unwatch', 'preferences', 'nochange' + * @param Title $titleObj The article's title to change + * @param string $userOption The user option to consider when $watch=preferences */ - private function warnOrDie( $msg, $enforceLimits = false ) { - if ( $enforceLimits ) { - $this->dieUsage( $msg, 'integeroutofrange' ); - } else { - $this->setWarning( $msg ); + protected function setWatch( $watch, $titleObj, $userOption = null ) { + $value = $this->getWatchlistValue( $watch, $titleObj, $userOption ); + if ( $value === null ) { + return; } + + WatchAction::doWatchOrUnwatch( $value, $titleObj, $this->getUser() ); } /** @@ -1196,10 +1057,96 @@ abstract class ApiBase extends ContextSource { array_pop( $arr ); $modified = true; } + return $modified; } /** + * Gets the user for whom to get the watchlist + * + * @param array $params + * @return User + */ + public function getWatchlistUser( $params ) { + if ( !is_null( $params['owner'] ) && !is_null( $params['token'] ) ) { + $user = User::newFromName( $params['owner'], false ); + if ( !( $user && $user->getId() ) ) { + $this->dieUsage( 'Specified user does not exist', 'bad_wlowner' ); + } + $token = $user->getOption( 'watchlisttoken' ); + if ( $token == '' || $token != $params['token'] ) { + $this->dieUsage( + 'Incorrect watchlist token provided -- please set a correct token in Special:Preferences', + 'bad_wltoken' + ); + } + } else { + if ( !$this->getUser()->isLoggedIn() ) { + $this->dieUsage( 'You must be logged-in to have a watchlist', 'notloggedin' ); + } + if ( !$this->getUser()->isAllowed( 'viewmywatchlist' ) ) { + $this->dieUsage( 'You don\'t have permission to view your watchlist', 'permissiondenied' ); + } + $user = $this->getUser(); + } + + return $user; + } + + /**@}*/ + + /************************************************************************//** + * @name Warning and error reporting + * @{ + */ + + /** + * Set warning section for this module. Users should monitor this + * section to notice any changes in API. Multiple calls to this + * function will result in the warning messages being separated by + * newlines + * @param string $warning Warning message + */ + public function setWarning( $warning ) { + $result = $this->getResult(); + $data = $result->getData(); + $moduleName = $this->getModuleName(); + if ( isset( $data['warnings'][$moduleName] ) ) { + // Don't add duplicate warnings + $oldWarning = $data['warnings'][$moduleName]['*']; + $warnPos = strpos( $oldWarning, $warning ); + // If $warning was found in $oldWarning, check if it starts at 0 or after "\n" + if ( $warnPos !== false && ( $warnPos === 0 || $oldWarning[$warnPos - 1] === "\n" ) ) { + // Check if $warning is followed by "\n" or the end of the $oldWarning + $warnPos += strlen( $warning ); + if ( strlen( $oldWarning ) <= $warnPos || $oldWarning[$warnPos] === "\n" ) { + return; + } + } + // If there is a warning already, append it to the existing one + $warning = "$oldWarning\n$warning"; + } + $msg = array(); + ApiResult::setContent( $msg, $warning ); + $result->addValue( 'warnings', $moduleName, + $msg, ApiResult::OVERRIDE | ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK ); + } + + /** + * Adds a warning to the output, else dies + * + * @param string $msg Message to show as a warning, or error message if dying + * @param bool $enforceLimits Whether this is an enforce (die) + */ + private function warnOrDie( $msg, $enforceLimits = false ) { + if ( $enforceLimits ) { + $this->dieUsage( $msg, 'integeroutofrange' ); + } + + $this->setWarning( $msg ); + } + + /** * Throw a UsageException, which will (if uncaught) call the main module's * error handler and die with an error message. * @@ -1213,17 +1160,22 @@ abstract class ApiBase extends ContextSource { */ public function dieUsage( $description, $errorCode, $httpRespCode = 0, $extradata = null ) { Profiler::instance()->close(); - throw new UsageException( $description, $this->encodeParamName( $errorCode ), $httpRespCode, $extradata ); + throw new UsageException( + $description, + $this->encodeParamName( $errorCode ), + $httpRespCode, + $extradata + ); } /** - * Throw a UsageException based on the errors in the Status object. + * Get error (as code, string) from a Status object. * - * @since 1.22 - * @param Status $status Status object - * @throws UsageException + * @since 1.23 + * @param Status $status + * @return array Array of code and error string */ - public function dieStatus( $status ) { + public function getErrorFromStatus( $status ) { if ( $status->isGood() ) { throw new MWException( 'Successful status passed to ApiBase::dieStatus' ); } @@ -1248,13 +1200,28 @@ abstract class ApiBase extends ContextSource { $msg = wfMessage( $code, $errors[0] ); } if ( isset( ApiBase::$messageMap[$code] ) ) { - // Translate message to code, for backwards compatability + // Translate message to code, for backwards compatibility $code = ApiBase::$messageMap[$code]['code']; } - $this->dieUsage( $msg->inLanguage( 'en' )->useDatabase( false )->plain(), $code ); + + return array( $code, $msg->inLanguage( 'en' )->useDatabase( false )->plain() ); } /** + * Throw a UsageException based on the errors in the Status object. + * + * @since 1.22 + * @param Status $status + * @throws MWException + */ + public function dieStatus( $status ) { + + list( $code, $msg ) = $this->getErrorFromStatus( $status ); + $this->dieUsage( $msg, $code ); + } + + // @codingStandardsIgnoreStart Allow long lines. Cannot split these. + /** * Array that maps message keys to error messages. $1 and friends are replaced. */ public static $messageMap = array( @@ -1263,74 +1230,243 @@ abstract class ApiBase extends ContextSource { 'unknownerror-nocode' => array( 'code' => 'unknownerror', 'info' => 'Unknown error' ), // Messages from Title::getUserPermissionsErrors() - 'ns-specialprotected' => array( 'code' => 'unsupportednamespace', 'info' => "Pages in the Special namespace can't be edited" ), - 'protectedinterface' => array( 'code' => 'protectednamespace-interface', 'info' => "You're not allowed to edit interface messages" ), - 'namespaceprotected' => array( 'code' => 'protectednamespace', 'info' => "You're not allowed to edit pages in the \"\$1\" namespace" ), - 'customcssprotected' => array( 'code' => 'customcssprotected', 'info' => "You're not allowed to edit custom CSS pages" ), - 'customjsprotected' => array( 'code' => 'customjsprotected', 'info' => "You're not allowed to edit custom JavaScript pages" ), - 'cascadeprotected' => array( 'code' => 'cascadeprotected', 'info' => "The page you're trying to edit is protected because it's included in a cascade-protected page" ), - 'protectedpagetext' => array( 'code' => 'protectedpage', 'info' => "The \"\$1\" right is required to edit this page" ), - 'protect-cantedit' => array( 'code' => 'cantedit', 'info' => "You can't protect this page because you can't edit it" ), - 'badaccess-group0' => array( 'code' => 'permissiondenied', 'info' => "Permission denied" ), // Generic permission denied message - 'badaccess-groups' => array( 'code' => 'permissiondenied', 'info' => "Permission denied" ), - 'titleprotected' => array( 'code' => 'protectedtitle', 'info' => "This title has been protected from creation" ), - 'nocreate-loggedin' => array( 'code' => 'cantcreate', 'info' => "You don't have permission to create new pages" ), - 'nocreatetext' => array( 'code' => 'cantcreate-anon', 'info' => "Anonymous users can't create new pages" ), - 'movenologintext' => array( 'code' => 'cantmove-anon', 'info' => "Anonymous users can't move pages" ), - 'movenotallowed' => array( 'code' => 'cantmove', 'info' => "You don't have permission to move pages" ), - 'confirmedittext' => array( 'code' => 'confirmemail', 'info' => "You must confirm your email address before you can edit" ), - 'blockedtext' => array( 'code' => 'blocked', 'info' => "You have been blocked from editing" ), - 'autoblockedtext' => array( 'code' => 'autoblocked', 'info' => "Your IP address has been blocked automatically, because it was used by a blocked user" ), + 'ns-specialprotected' => array( + 'code' => 'unsupportednamespace', + 'info' => "Pages in the Special namespace can't be edited" + ), + 'protectedinterface' => array( + 'code' => 'protectednamespace-interface', + 'info' => "You're not allowed to edit interface messages" + ), + 'namespaceprotected' => array( + 'code' => 'protectednamespace', + 'info' => "You're not allowed to edit pages in the \"\$1\" namespace" + ), + 'customcssprotected' => array( + 'code' => 'customcssprotected', + 'info' => "You're not allowed to edit custom CSS pages" + ), + 'customjsprotected' => array( + 'code' => 'customjsprotected', + 'info' => "You're not allowed to edit custom JavaScript pages" + ), + 'cascadeprotected' => array( + 'code' => 'cascadeprotected', + 'info' => "The page you're trying to edit is protected because it's included in a cascade-protected page" + ), + 'protectedpagetext' => array( + 'code' => 'protectedpage', + 'info' => "The \"\$1\" right is required to edit this page" + ), + 'protect-cantedit' => array( + 'code' => 'cantedit', + 'info' => "You can't protect this page because you can't edit it" + ), + 'deleteprotected' => array( + 'code' => 'cantedit', + 'info' => "You can't delete this page because it has been protected" + ), + 'badaccess-group0' => array( + 'code' => 'permissiondenied', + 'info' => "Permission denied" + ), // Generic permission denied message + 'badaccess-groups' => array( + 'code' => 'permissiondenied', + 'info' => "Permission denied" + ), + 'titleprotected' => array( + 'code' => 'protectedtitle', + 'info' => "This title has been protected from creation" + ), + 'nocreate-loggedin' => array( + 'code' => 'cantcreate', + 'info' => "You don't have permission to create new pages" + ), + 'nocreatetext' => array( + 'code' => 'cantcreate-anon', + 'info' => "Anonymous users can't create new pages" + ), + 'movenologintext' => array( + 'code' => 'cantmove-anon', + 'info' => "Anonymous users can't move pages" + ), + 'movenotallowed' => array( + 'code' => 'cantmove', + 'info' => "You don't have permission to move pages" + ), + 'confirmedittext' => array( + 'code' => 'confirmemail', + 'info' => "You must confirm your email address before you can edit" + ), + 'blockedtext' => array( + 'code' => 'blocked', + 'info' => "You have been blocked from editing" + ), + 'autoblockedtext' => array( + 'code' => 'autoblocked', + 'info' => "Your IP address has been blocked automatically, because it was used by a blocked user" + ), // Miscellaneous interface messages - 'actionthrottledtext' => array( 'code' => 'ratelimited', 'info' => "You've exceeded your rate limit. Please wait some time and try again" ), - 'alreadyrolled' => array( 'code' => 'alreadyrolled', 'info' => "The page you tried to rollback was already rolled back" ), - 'cantrollback' => array( 'code' => 'onlyauthor', 'info' => "The page you tried to rollback only has one author" ), - 'readonlytext' => array( 'code' => 'readonly', 'info' => "The wiki is currently in read-only mode" ), - 'sessionfailure' => array( 'code' => 'badtoken', 'info' => "Invalid token" ), - 'cannotdelete' => array( 'code' => 'cantdelete', 'info' => "Couldn't delete \"\$1\". Maybe it was deleted already by someone else" ), - 'notanarticle' => array( 'code' => 'missingtitle', 'info' => "The page you requested doesn't exist" ), - 'selfmove' => array( 'code' => 'selfmove', 'info' => "Can't move a page to itself" ), - 'immobile_namespace' => array( 'code' => 'immobilenamespace', 'info' => "You tried to move pages from or to a namespace that is protected from moving" ), - 'articleexists' => array( 'code' => 'articleexists', 'info' => "The destination article already exists and is not a redirect to the source article" ), - 'protectedpage' => array( 'code' => 'protectedpage', 'info' => "You don't have permission to perform this move" ), - 'hookaborted' => array( 'code' => 'hookaborted', 'info' => "The modification you tried to make was aborted by an extension hook" ), - 'cantmove-titleprotected' => array( 'code' => 'protectedtitle', 'info' => "The destination article has been protected from creation" ), - 'imagenocrossnamespace' => array( 'code' => 'nonfilenamespace', 'info' => "Can't move a file to a non-file namespace" ), - 'imagetypemismatch' => array( 'code' => 'filetypemismatch', 'info' => "The new file extension doesn't match its type" ), + 'actionthrottledtext' => array( + 'code' => 'ratelimited', + 'info' => "You've exceeded your rate limit. Please wait some time and try again" + ), + 'alreadyrolled' => array( + 'code' => 'alreadyrolled', + 'info' => "The page you tried to rollback was already rolled back" + ), + 'cantrollback' => array( + 'code' => 'onlyauthor', + 'info' => "The page you tried to rollback only has one author" + ), + 'readonlytext' => array( + 'code' => 'readonly', + 'info' => "The wiki is currently in read-only mode" + ), + 'sessionfailure' => array( + 'code' => 'badtoken', + 'info' => "Invalid token" ), + 'cannotdelete' => array( + 'code' => 'cantdelete', + 'info' => "Couldn't delete \"\$1\". Maybe it was deleted already by someone else" + ), + 'notanarticle' => array( + 'code' => 'missingtitle', + 'info' => "The page you requested doesn't exist" + ), + 'selfmove' => array( 'code' => 'selfmove', 'info' => "Can't move a page to itself" + ), + 'immobile_namespace' => array( + 'code' => 'immobilenamespace', + 'info' => "You tried to move pages from or to a namespace that is protected from moving" + ), + 'articleexists' => array( + 'code' => 'articleexists', + 'info' => "The destination article already exists and is not a redirect to the source article" + ), + 'protectedpage' => array( + 'code' => 'protectedpage', + 'info' => "You don't have permission to perform this move" + ), + 'hookaborted' => array( + 'code' => 'hookaborted', + 'info' => "The modification you tried to make was aborted by an extension hook" + ), + 'cantmove-titleprotected' => array( + 'code' => 'protectedtitle', + 'info' => "The destination article has been protected from creation" + ), + 'imagenocrossnamespace' => array( + 'code' => 'nonfilenamespace', + 'info' => "Can't move a file to a non-file namespace" + ), + 'imagetypemismatch' => array( + 'code' => 'filetypemismatch', + 'info' => "The new file extension doesn't match its type" + ), // 'badarticleerror' => shouldn't happen // 'badtitletext' => shouldn't happen 'ip_range_invalid' => array( 'code' => 'invalidrange', 'info' => "Invalid IP range" ), - 'range_block_disabled' => array( 'code' => 'rangedisabled', 'info' => "Blocking IP ranges has been disabled" ), - 'nosuchusershort' => array( 'code' => 'nosuchuser', 'info' => "The user you specified doesn't exist" ), + 'range_block_disabled' => array( + 'code' => 'rangedisabled', + 'info' => "Blocking IP ranges has been disabled" + ), + 'nosuchusershort' => array( + 'code' => 'nosuchuser', + 'info' => "The user you specified doesn't exist" + ), 'badipaddress' => array( 'code' => 'invalidip', 'info' => "Invalid IP address specified" ), 'ipb_expiry_invalid' => array( 'code' => 'invalidexpiry', 'info' => "Invalid expiry time" ), - 'ipb_already_blocked' => array( 'code' => 'alreadyblocked', 'info' => "The user you tried to block was already blocked" ), - 'ipb_blocked_as_range' => array( 'code' => 'blockedasrange', 'info' => "IP address \"\$1\" was blocked as part of range \"\$2\". You can't unblock the IP individually, but you can unblock the range as a whole." ), - 'ipb_cant_unblock' => array( 'code' => 'cantunblock', 'info' => "The block you specified was not found. It may have been unblocked already" ), - 'mailnologin' => array( 'code' => 'cantsend', 'info' => "You are not logged in, you do not have a confirmed email address, or you are not allowed to send email to other users, so you cannot send email" ), - 'ipbblocked' => array( 'code' => 'ipbblocked', 'info' => 'You cannot block or unblock users while you are yourself blocked' ), - 'ipbnounblockself' => array( 'code' => 'ipbnounblockself', 'info' => 'You are not allowed to unblock yourself' ), - 'usermaildisabled' => array( 'code' => 'usermaildisabled', 'info' => "User email has been disabled" ), - 'blockedemailuser' => array( 'code' => 'blockedfrommail', 'info' => "You have been blocked from sending email" ), - 'notarget' => array( 'code' => 'notarget', 'info' => "You have not specified a valid target for this action" ), - 'noemail' => array( 'code' => 'noemail', 'info' => "The user has not specified a valid email address, or has chosen not to receive email from other users" ), - 'rcpatroldisabled' => array( 'code' => 'patroldisabled', 'info' => "Patrolling is disabled on this wiki" ), - 'markedaspatrollederror-noautopatrol' => array( 'code' => 'noautopatrol', 'info' => "You don't have permission to patrol your own changes" ), - 'delete-toobig' => array( 'code' => 'bigdelete', 'info' => "You can't delete this page because it has more than \$1 revisions" ), - 'movenotallowedfile' => array( 'code' => 'cantmovefile', 'info' => "You don't have permission to move files" ), - 'userrights-no-interwiki' => array( 'code' => 'nointerwikiuserrights', 'info' => "You don't have permission to change user rights on other wikis" ), - 'userrights-nodatabase' => array( 'code' => 'nosuchdatabase', 'info' => "Database \"\$1\" does not exist or is not local" ), + 'ipb_already_blocked' => array( + 'code' => 'alreadyblocked', + 'info' => "The user you tried to block was already blocked" + ), + 'ipb_blocked_as_range' => array( + 'code' => 'blockedasrange', + 'info' => "IP address \"\$1\" was blocked as part of range \"\$2\". You can't unblock the IP individually, but you can unblock the range as a whole." + ), + 'ipb_cant_unblock' => array( + 'code' => 'cantunblock', + 'info' => "The block you specified was not found. It may have been unblocked already" + ), + 'mailnologin' => array( + 'code' => 'cantsend', + 'info' => "You are not logged in, you do not have a confirmed email address, or you are not allowed to send email to other users, so you cannot send email" + ), + 'ipbblocked' => array( + 'code' => 'ipbblocked', + 'info' => 'You cannot block or unblock users while you are yourself blocked' + ), + 'ipbnounblockself' => array( + 'code' => 'ipbnounblockself', + 'info' => 'You are not allowed to unblock yourself' + ), + 'usermaildisabled' => array( + 'code' => 'usermaildisabled', + 'info' => "User email has been disabled" + ), + 'blockedemailuser' => array( + 'code' => 'blockedfrommail', + 'info' => "You have been blocked from sending email" + ), + 'notarget' => array( + 'code' => 'notarget', + 'info' => "You have not specified a valid target for this action" + ), + 'noemail' => array( + 'code' => 'noemail', + 'info' => "The user has not specified a valid email address, or has chosen not to receive email from other users" + ), + 'rcpatroldisabled' => array( + 'code' => 'patroldisabled', + 'info' => "Patrolling is disabled on this wiki" + ), + 'markedaspatrollederror-noautopatrol' => array( + 'code' => 'noautopatrol', + 'info' => "You don't have permission to patrol your own changes" + ), + 'delete-toobig' => array( + 'code' => 'bigdelete', + 'info' => "You can't delete this page because it has more than \$1 revisions" + ), + 'movenotallowedfile' => array( + 'code' => 'cantmovefile', + 'info' => "You don't have permission to move files" + ), + 'userrights-no-interwiki' => array( + 'code' => 'nointerwikiuserrights', + 'info' => "You don't have permission to change user rights on other wikis" + ), + 'userrights-nodatabase' => array( + 'code' => 'nosuchdatabase', + 'info' => "Database \"\$1\" does not exist or is not local" + ), 'nouserspecified' => array( 'code' => 'invaliduser', 'info' => "Invalid username \"\$1\"" ), 'noname' => array( 'code' => 'invaliduser', 'info' => "Invalid username \"\$1\"" ), 'summaryrequired' => array( 'code' => 'summaryrequired', 'info' => 'Summary required' ), - 'import-rootpage-invalid' => array( 'code' => 'import-rootpage-invalid', 'info' => 'Root page is an invalid title' ), - 'import-rootpage-nosubpage' => array( 'code' => 'import-rootpage-nosubpage', 'info' => 'Namespace "$1" of the root page does not allow subpages' ), + 'import-rootpage-invalid' => array( + 'code' => 'import-rootpage-invalid', + 'info' => 'Root page is an invalid title' + ), + 'import-rootpage-nosubpage' => array( + 'code' => 'import-rootpage-nosubpage', + 'info' => 'Namespace "$1" of the root page does not allow subpages' + ), // API-specific messages - 'readrequired' => array( 'code' => 'readapidenied', 'info' => "You need read permission to use this module" ), - 'writedisabled' => array( 'code' => 'noapiwrite', 'info' => "Editing of this wiki through the API is disabled. Make sure the \$wgEnableWriteAPI=true; statement is included in the wiki's LocalSettings.php file" ), - 'writerequired' => array( 'code' => 'writeapidenied', 'info' => "You're not allowed to edit this wiki through the API" ), + 'readrequired' => array( + 'code' => 'readapidenied', + 'info' => "You need read permission to use this module" + ), + 'writedisabled' => array( + 'code' => 'noapiwrite', + 'info' => "Editing of this wiki through the API is disabled. Make sure the \$wgEnableWriteAPI=true; statement is included in the wiki's LocalSettings.php file" + ), + 'writerequired' => array( + 'code' => 'writeapidenied', + 'info' => "You're not allowed to edit this wiki through the API" + ), 'missingparam' => array( 'code' => 'no$1', 'info' => "The \$1 parameter must be set" ), 'invalidtitle' => array( 'code' => 'invalidtitle', 'info' => "Bad title \"\$1\"" ), 'nosuchpageid' => array( 'code' => 'nosuchpageid', 'info' => "There is no page with ID \$1" ), @@ -1339,81 +1475,253 @@ abstract class ApiBase extends ContextSource { 'invaliduser' => array( 'code' => 'invaliduser', 'info' => "Invalid username \"\$1\"" ), 'invalidexpiry' => array( 'code' => 'invalidexpiry', 'info' => "Invalid expiry time \"\$1\"" ), 'pastexpiry' => array( 'code' => 'pastexpiry', 'info' => "Expiry time \"\$1\" is in the past" ), - 'create-titleexists' => array( 'code' => 'create-titleexists', 'info' => "Existing titles can't be protected with 'create'" ), - 'missingtitle-createonly' => array( 'code' => 'missingtitle-createonly', 'info' => "Missing titles can only be protected with 'create'" ), - 'cantblock' => array( 'code' => 'cantblock', 'info' => "You don't have permission to block users" ), - 'canthide' => array( 'code' => 'canthide', 'info' => "You don't have permission to hide user names from the block log" ), - 'cantblock-email' => array( 'code' => 'cantblock-email', 'info' => "You don't have permission to block users from sending email through the wiki" ), - 'unblock-notarget' => array( 'code' => 'notarget', 'info' => "Either the id or the user parameter must be set" ), - 'unblock-idanduser' => array( 'code' => 'idanduser', 'info' => "The id and user parameters can't be used together" ), - 'cantunblock' => array( 'code' => 'permissiondenied', 'info' => "You don't have permission to unblock users" ), - 'cannotundelete' => array( 'code' => 'cantundelete', 'info' => "Couldn't undelete: the requested revisions may not exist, or may have been undeleted already" ), - 'permdenied-undelete' => array( 'code' => 'permissiondenied', 'info' => "You don't have permission to restore deleted revisions" ), - 'createonly-exists' => array( 'code' => 'articleexists', 'info' => "The article you tried to create has been created already" ), - 'nocreate-missing' => array( 'code' => 'missingtitle', 'info' => "The article you tried to edit doesn't exist" ), - 'cantchangecontentmodel' => array( 'code' => 'cantchangecontentmodel', 'info' => "You don't have permission to change the content model of a page" ), - 'nosuchrcid' => array( 'code' => 'nosuchrcid', 'info' => "There is no change with rcid \"\$1\"" ), - 'protect-invalidaction' => array( 'code' => 'protect-invalidaction', 'info' => "Invalid protection type \"\$1\"" ), - 'protect-invalidlevel' => array( 'code' => 'protect-invalidlevel', 'info' => "Invalid protection level \"\$1\"" ), - 'toofewexpiries' => array( 'code' => 'toofewexpiries', 'info' => "\$1 expiry timestamps were provided where \$2 were needed" ), - 'cantimport' => array( 'code' => 'cantimport', 'info' => "You don't have permission to import pages" ), - 'cantimport-upload' => array( 'code' => 'cantimport-upload', 'info' => "You don't have permission to import uploaded pages" ), + 'create-titleexists' => array( + 'code' => 'create-titleexists', + 'info' => "Existing titles can't be protected with 'create'" + ), + 'missingtitle-createonly' => array( + 'code' => 'missingtitle-createonly', + 'info' => "Missing titles can only be protected with 'create'" + ), + 'cantblock' => array( 'code' => 'cantblock', + 'info' => "You don't have permission to block users" + ), + 'canthide' => array( + 'code' => 'canthide', + 'info' => "You don't have permission to hide user names from the block log" + ), + 'cantblock-email' => array( + 'code' => 'cantblock-email', + 'info' => "You don't have permission to block users from sending email through the wiki" + ), + 'unblock-notarget' => array( + 'code' => 'notarget', + 'info' => "Either the id or the user parameter must be set" + ), + 'unblock-idanduser' => array( + 'code' => 'idanduser', + 'info' => "The id and user parameters can't be used together" + ), + 'cantunblock' => array( + 'code' => 'permissiondenied', + 'info' => "You don't have permission to unblock users" + ), + 'cannotundelete' => array( + 'code' => 'cantundelete', + 'info' => "Couldn't undelete: the requested revisions may not exist, or may have been undeleted already" + ), + 'permdenied-undelete' => array( + 'code' => 'permissiondenied', + 'info' => "You don't have permission to restore deleted revisions" + ), + 'createonly-exists' => array( + 'code' => 'articleexists', + 'info' => "The article you tried to create has been created already" + ), + 'nocreate-missing' => array( + 'code' => 'missingtitle', + 'info' => "The article you tried to edit doesn't exist" + ), + 'cantchangecontentmodel' => array( + 'code' => 'cantchangecontentmodel', + 'info' => "You don't have permission to change the content model of a page" + ), + 'nosuchrcid' => array( + 'code' => 'nosuchrcid', + 'info' => "There is no change with rcid \"\$1\"" + ), + 'protect-invalidaction' => array( + 'code' => 'protect-invalidaction', + 'info' => "Invalid protection type \"\$1\"" + ), + 'protect-invalidlevel' => array( + 'code' => 'protect-invalidlevel', + 'info' => "Invalid protection level \"\$1\"" + ), + 'toofewexpiries' => array( + 'code' => 'toofewexpiries', + 'info' => "\$1 expiry timestamps were provided where \$2 were needed" + ), + 'cantimport' => array( + 'code' => 'cantimport', + 'info' => "You don't have permission to import pages" + ), + 'cantimport-upload' => array( + 'code' => 'cantimport-upload', + 'info' => "You don't have permission to import uploaded pages" + ), 'importnofile' => array( 'code' => 'nofile', 'info' => "You didn't upload a file" ), - 'importuploaderrorsize' => array( 'code' => 'filetoobig', 'info' => 'The file you uploaded is bigger than the maximum upload size' ), - 'importuploaderrorpartial' => array( 'code' => 'partialupload', 'info' => 'The file was only partially uploaded' ), - 'importuploaderrortemp' => array( 'code' => 'notempdir', 'info' => 'The temporary upload directory is missing' ), - 'importcantopen' => array( 'code' => 'cantopenfile', 'info' => "Couldn't open the uploaded file" ), - 'import-noarticle' => array( 'code' => 'badinterwiki', 'info' => 'Invalid interwiki title specified' ), - 'importbadinterwiki' => array( 'code' => 'badinterwiki', 'info' => 'Invalid interwiki title specified' ), - 'import-unknownerror' => array( 'code' => 'import-unknownerror', 'info' => "Unknown error on import: \"\$1\"" ), - 'cantoverwrite-sharedfile' => array( 'code' => 'cantoverwrite-sharedfile', 'info' => 'The target file exists on a shared repository and you do not have permission to override it' ), - 'sharedfile-exists' => array( 'code' => 'fileexists-sharedrepo-perm', 'info' => 'The target file exists on a shared repository. Use the ignorewarnings parameter to override it.' ), - 'mustbeposted' => array( 'code' => 'mustbeposted', 'info' => "The \$1 module requires a POST request" ), - 'show' => array( 'code' => 'show', 'info' => 'Incorrect parameter - mutually exclusive values may not be supplied' ), - 'specialpage-cantexecute' => array( 'code' => 'specialpage-cantexecute', 'info' => "You don't have permission to view the results of this special page" ), - 'invalidoldimage' => array( 'code' => 'invalidoldimage', 'info' => 'The oldimage parameter has invalid format' ), - 'nodeleteablefile' => array( 'code' => 'nodeleteablefile', 'info' => 'No such old version of the file' ), - 'fileexists-forbidden' => array( 'code' => 'fileexists-forbidden', 'info' => 'A file with name "$1" already exists, and cannot be overwritten.' ), - 'fileexists-shared-forbidden' => array( 'code' => 'fileexists-shared-forbidden', 'info' => 'A file with name "$1" already exists in the shared file repository, and cannot be overwritten.' ), - 'filerevert-badversion' => array( 'code' => 'filerevert-badversion', 'info' => 'There is no previous local version of this file with the provided timestamp.' ), + 'importuploaderrorsize' => array( + 'code' => 'filetoobig', + 'info' => 'The file you uploaded is bigger than the maximum upload size' + ), + 'importuploaderrorpartial' => array( + 'code' => 'partialupload', + 'info' => 'The file was only partially uploaded' + ), + 'importuploaderrortemp' => array( + 'code' => 'notempdir', + 'info' => 'The temporary upload directory is missing' + ), + 'importcantopen' => array( + 'code' => 'cantopenfile', + 'info' => "Couldn't open the uploaded file" + ), + 'import-noarticle' => array( + 'code' => 'badinterwiki', + 'info' => 'Invalid interwiki title specified' + ), + 'importbadinterwiki' => array( + 'code' => 'badinterwiki', + 'info' => 'Invalid interwiki title specified' + ), + 'import-unknownerror' => array( + 'code' => 'import-unknownerror', + 'info' => "Unknown error on import: \"\$1\"" + ), + 'cantoverwrite-sharedfile' => array( + 'code' => 'cantoverwrite-sharedfile', + 'info' => 'The target file exists on a shared repository and you do not have permission to override it' + ), + 'sharedfile-exists' => array( + 'code' => 'fileexists-sharedrepo-perm', + 'info' => 'The target file exists on a shared repository. Use the ignorewarnings parameter to override it.' + ), + 'mustbeposted' => array( + 'code' => 'mustbeposted', + 'info' => "The \$1 module requires a POST request" + ), + 'show' => array( + 'code' => 'show', + 'info' => 'Incorrect parameter - mutually exclusive values may not be supplied' + ), + 'specialpage-cantexecute' => array( + 'code' => 'specialpage-cantexecute', + 'info' => "You don't have permission to view the results of this special page" + ), + 'invalidoldimage' => array( + 'code' => 'invalidoldimage', + 'info' => 'The oldimage parameter has invalid format' + ), + 'nodeleteablefile' => array( + 'code' => 'nodeleteablefile', + 'info' => 'No such old version of the file' + ), + 'fileexists-forbidden' => array( + 'code' => 'fileexists-forbidden', + 'info' => 'A file with name "$1" already exists, and cannot be overwritten.' + ), + 'fileexists-shared-forbidden' => array( + 'code' => 'fileexists-shared-forbidden', + 'info' => 'A file with name "$1" already exists in the shared file repository, and cannot be overwritten.' + ), + 'filerevert-badversion' => array( + 'code' => 'filerevert-badversion', + 'info' => 'There is no previous local version of this file with the provided timestamp.' + ), // ApiEditPage messages - 'noimageredirect-anon' => array( 'code' => 'noimageredirect-anon', 'info' => "Anonymous users can't create image redirects" ), - 'noimageredirect-logged' => array( 'code' => 'noimageredirect', 'info' => "You don't have permission to create image redirects" ), - 'spamdetected' => array( 'code' => 'spamdetected', 'info' => "Your edit was refused because it contained a spam fragment: \"\$1\"" ), - 'contenttoobig' => array( 'code' => 'contenttoobig', 'info' => "The content you supplied exceeds the article size limit of \$1 kilobytes" ), + 'noimageredirect-anon' => array( + 'code' => 'noimageredirect-anon', + 'info' => "Anonymous users can't create image redirects" + ), + 'noimageredirect-logged' => array( + 'code' => 'noimageredirect', + 'info' => "You don't have permission to create image redirects" + ), + 'spamdetected' => array( + 'code' => 'spamdetected', + 'info' => "Your edit was refused because it contained a spam fragment: \"\$1\"" + ), + 'contenttoobig' => array( + 'code' => 'contenttoobig', + 'info' => "The content you supplied exceeds the article size limit of \$1 kilobytes" + ), 'noedit-anon' => array( 'code' => 'noedit-anon', 'info' => "Anonymous users can't edit pages" ), 'noedit' => array( 'code' => 'noedit', 'info' => "You don't have permission to edit pages" ), - 'wasdeleted' => array( 'code' => 'pagedeleted', 'info' => "The page has been deleted since you fetched its timestamp" ), - 'blankpage' => array( 'code' => 'emptypage', 'info' => "Creating new, empty pages is not allowed" ), + 'wasdeleted' => array( + 'code' => 'pagedeleted', + 'info' => "The page has been deleted since you fetched its timestamp" + ), + 'blankpage' => array( + 'code' => 'emptypage', + 'info' => "Creating new, empty pages is not allowed" + ), 'editconflict' => array( 'code' => 'editconflict', 'info' => "Edit conflict detected" ), 'hashcheckfailed' => array( 'code' => 'badmd5', 'info' => "The supplied MD5 hash was incorrect" ), - 'missingtext' => array( 'code' => 'notext', 'info' => "One of the text, appendtext, prependtext and undo parameters must be set" ), - 'emptynewsection' => array( 'code' => 'emptynewsection', 'info' => 'Creating empty new sections is not possible.' ), - 'revwrongpage' => array( 'code' => 'revwrongpage', 'info' => "r\$1 is not a revision of \"\$2\"" ), - 'undo-failure' => array( 'code' => 'undofailure', 'info' => 'Undo failed due to conflicting intermediate edits' ), + 'missingtext' => array( + 'code' => 'notext', + 'info' => "One of the text, appendtext, prependtext and undo parameters must be set" + ), + 'emptynewsection' => array( + 'code' => 'emptynewsection', + 'info' => 'Creating empty new sections is not possible.' + ), + 'revwrongpage' => array( + 'code' => 'revwrongpage', + 'info' => "r\$1 is not a revision of \"\$2\"" + ), + 'undo-failure' => array( + 'code' => 'undofailure', + 'info' => 'Undo failed due to conflicting intermediate edits' + ), + 'content-not-allowed-here' => array( + 'code' => 'contentnotallowedhere', + 'info' => 'Content model "$1" is not allowed at title "$2"' + ), // Messages from WikiPage::doEit() - 'edit-hook-aborted' => array( 'code' => 'edit-hook-aborted', 'info' => "Your edit was aborted by an ArticleSave hook" ), - 'edit-gone-missing' => array( 'code' => 'edit-gone-missing', 'info' => "The page you tried to edit doesn't seem to exist anymore" ), + 'edit-hook-aborted' => array( + 'code' => 'edit-hook-aborted', + 'info' => "Your edit was aborted by an ArticleSave hook" + ), + 'edit-gone-missing' => array( + 'code' => 'edit-gone-missing', + 'info' => "The page you tried to edit doesn't seem to exist anymore" + ), 'edit-conflict' => array( 'code' => 'editconflict', 'info' => "Edit conflict detected" ), - 'edit-already-exists' => array( 'code' => 'edit-already-exists', 'info' => "It seems the page you tried to create already exist" ), + 'edit-already-exists' => array( + 'code' => 'edit-already-exists', + 'info' => 'It seems the page you tried to create already exist' + ), // uploadMsgs 'invalid-file-key' => array( 'code' => 'invalid-file-key', 'info' => 'Not a valid file key' ), 'nouploadmodule' => array( 'code' => 'nouploadmodule', 'info' => 'No upload module set' ), - 'uploaddisabled' => array( 'code' => 'uploaddisabled', 'info' => 'Uploads are not enabled. Make sure $wgEnableUploads is set to true in LocalSettings.php and the PHP ini setting file_uploads is true' ), - 'copyuploaddisabled' => array( 'code' => 'copyuploaddisabled', 'info' => 'Uploads by URL is not enabled. Make sure $wgAllowCopyUploads is set to true in LocalSettings.php.' ), - 'copyuploadbaddomain' => array( 'code' => 'copyuploadbaddomain', 'info' => 'Uploads by URL are not allowed from this domain.' ), - 'copyuploadbadurl' => array( 'code' => 'copyuploadbadurl', 'info' => 'Upload not allowed from this URL.' ), - - 'filename-tooshort' => array( 'code' => 'filename-tooshort', 'info' => 'The filename is too short' ), + 'uploaddisabled' => array( + 'code' => 'uploaddisabled', + 'info' => 'Uploads are not enabled. Make sure $wgEnableUploads is set to true in LocalSettings.php and the PHP ini setting file_uploads is true' + ), + 'copyuploaddisabled' => array( + 'code' => 'copyuploaddisabled', + 'info' => 'Uploads by URL is not enabled. Make sure $wgAllowCopyUploads is set to true in LocalSettings.php.' + ), + 'copyuploadbaddomain' => array( + 'code' => 'copyuploadbaddomain', + 'info' => 'Uploads by URL are not allowed from this domain.' + ), + 'copyuploadbadurl' => array( + 'code' => 'copyuploadbadurl', + 'info' => 'Upload not allowed from this URL.' + ), + + 'filename-tooshort' => array( + 'code' => 'filename-tooshort', + 'info' => 'The filename is too short' + ), 'filename-toolong' => array( 'code' => 'filename-toolong', 'info' => 'The filename is too long' ), - 'illegal-filename' => array( 'code' => 'illegal-filename', 'info' => 'The filename is not allowed' ), - 'filetype-missing' => array( 'code' => 'filetype-missing', 'info' => 'The file is missing an extension' ), + 'illegal-filename' => array( + 'code' => 'illegal-filename', + 'info' => 'The filename is not allowed' + ), + 'filetype-missing' => array( + 'code' => 'filetype-missing', + 'info' => 'The file is missing an extension' + ), 'mustbeloggedin' => array( 'code' => 'mustbeloggedin', 'info' => 'You must be logged in to $1.' ) ); + // @codingStandardsIgnoreEnd /** * Helper function for readonly errors @@ -1426,7 +1734,7 @@ abstract class ApiBase extends ContextSource { /** * Output the error message related to a certain array - * @param $error (array|string) Element of a getUserPermissionsErrors()-style array + * @param array|string $error Element of a getUserPermissionsErrors()-style array */ public function dieUsageMsg( $error ) { # most of the time we send a 1 element, so we might as well send it as @@ -1441,26 +1749,25 @@ abstract class ApiBase extends ContextSource { /** * Will only set a warning instead of failing if the global $wgDebugAPI * is set to true. Otherwise behaves exactly as dieUsageMsg(). - * @param $error (array|string) Element of a getUserPermissionsErrors()-style array + * @param array|string $error Element of a getUserPermissionsErrors()-style array * @since 1.21 */ public function dieUsageMsgOrDebug( $error ) { - global $wgDebugAPI; - if ( $wgDebugAPI !== true ) { + if ( $this->getConfig()->get( 'DebugAPI' ) !== true ) { $this->dieUsageMsg( $error ); - } else { - if ( is_string( $error ) ) { - $error = array( $error ); - } - $parsed = $this->parseMsg( $error ); - $this->setWarning( '$wgDebugAPI: ' . $parsed['code'] - . ' - ' . $parsed['info'] ); } + + if ( is_string( $error ) ) { + $error = array( $error ); + } + $parsed = $this->parseMsg( $error ); + $this->setWarning( '$wgDebugAPI: ' . $parsed['code'] . ' - ' . $parsed['info'] ); } /** - * Die with the $prefix.'badcontinue' error. This call is common enough to make it into the base method. - * @param $condition boolean will only die if this value is true + * Die with the $prefix.'badcontinue' error. This call is common enough to + * make it into the base method. + * @param bool $condition Will only die if this value is true * @since 1.21 */ protected function dieContinueUsageIf( $condition ) { @@ -1502,193 +1809,311 @@ abstract class ApiBase extends ContextSource { * Internal code errors should be reported with this method * @param string $method Method or function name * @param string $message Error message + * @throws MWException */ protected static function dieDebug( $method, $message ) { throw new MWException( "Internal error in $method: $message" ); } - /** - * Indicates if this module needs maxlag to be checked - * @return bool - */ - public function shouldCheckMaxlag() { - return true; - } + /**@}*/ - /** - * Indicates whether this module requires read rights - * @return bool + /************************************************************************//** + * @name Help message generation + * @{ */ - public function isReadMode() { - return true; - } - /** - * Indicates whether this module requires write mode - * @return bool - */ - public function isWriteMode() { - return false; - } /** - * Indicates whether this module must be called with a POST request - * @return bool + * Generates help message for this module, or false if there is no description + * @return string|bool */ - public function mustBePosted() { - return false; - } + public function makeHelpMsg() { + static $lnPrfx = "\n "; - /** - * Returns whether this module requires a token to execute - * It is used to show possible errors in action=paraminfo - * see bug 25248 - * @return bool - */ - public function needsToken() { - return false; - } + $msg = $this->getFinalDescription(); - /** - * Returns the token salt if there is one, - * '' if the module doesn't require a salt, - * else false if the module doesn't need a token - * You have also to override needsToken() - * Value is passed to User::getEditToken - * @return bool|string|array - */ - public function getTokenSalt() { - return false; - } + if ( $msg !== false ) { - /** - * Gets the user for whom to get the watchlist - * - * @param $params array - * @return User - */ - public function getWatchlistUser( $params ) { - if ( !is_null( $params['owner'] ) && !is_null( $params['token'] ) ) { - $user = User::newFromName( $params['owner'], false ); - if ( !( $user && $user->getId() ) ) { - $this->dieUsage( 'Specified user does not exist', 'bad_wlowner' ); + if ( !is_array( $msg ) ) { + $msg = array( + $msg + ); } - $token = $user->getOption( 'watchlisttoken' ); - if ( $token == '' || $token != $params['token'] ) { - $this->dieUsage( 'Incorrect watchlist token provided -- please set a correct token in Special:Preferences', 'bad_wltoken' ); + $msg = $lnPrfx . implode( $lnPrfx, $msg ) . "\n"; + + $msg .= $this->makeHelpArrayToString( $lnPrfx, false, $this->getHelpUrls() ); + + if ( $this->isReadMode() ) { + $msg .= "\nThis module requires read rights"; } - } else { - if ( !$this->getUser()->isLoggedIn() ) { - $this->dieUsage( 'You must be logged-in to have a watchlist', 'notloggedin' ); + if ( $this->isWriteMode() ) { + $msg .= "\nThis module requires write rights"; } - if ( !$this->getUser()->isAllowed( 'viewmywatchlist' ) ) { - $this->dieUsage( 'You don\'t have permission to view your watchlist', 'permissiondenied' ); + if ( $this->mustBePosted() ) { + $msg .= "\nThis module only accepts POST requests"; + } + if ( $this->isReadMode() || $this->isWriteMode() || + $this->mustBePosted() + ) { + $msg .= "\n"; + } + + // Parameters + $paramsMsg = $this->makeHelpMsgParameters(); + if ( $paramsMsg !== false ) { + $msg .= "Parameters:\n$paramsMsg"; + } + + $examples = $this->getExamples(); + if ( $examples ) { + if ( !is_array( $examples ) ) { + $examples = array( + $examples + ); + } + $msg .= "Example" . ( count( $examples ) > 1 ? 's' : '' ) . ":\n"; + foreach ( $examples as $k => $v ) { + if ( is_numeric( $k ) ) { + $msg .= " $v\n"; + } else { + if ( is_array( $v ) ) { + $msgExample = implode( "\n", array_map( array( $this, 'indentExampleText' ), $v ) ); + } else { + $msgExample = " $v"; + } + $msgExample .= ":"; + $msg .= wordwrap( $msgExample, 100, "\n" ) . "\n $k\n"; + } + } } - $user = $this->getUser(); } - return $user; + + return $msg; } /** - * @return bool|string|array Returns a false if the module has no help url, else returns a (array of) string + * @param string $item + * @return string */ - public function getHelpUrls() { - return false; + private function indentExampleText( $item ) { + return " " . $item; } /** - * Returns a list of all possible errors returned by the module - * - * Don't call this function directly: use getFinalPossibleErrors() to allow - * hooks to modify parameters as needed. - * - * @return array in the format of array( key, param1, param2, ... ) or array( 'code' => ..., 'info' => ... ) + * @param string $prefix Text to split output items + * @param string $title What is being output + * @param string|array $input + * @return string */ - public function getPossibleErrors() { - $ret = array(); - - $params = $this->getFinalParams(); - if ( $params ) { - foreach ( $params as $paramName => $paramSettings ) { - if ( isset( $paramSettings[ApiBase::PARAM_REQUIRED] ) && $paramSettings[ApiBase::PARAM_REQUIRED] ) { - $ret[] = array( 'missingparam', $paramName ); - } - } - if ( array_key_exists( 'continue', $params ) ) { - $ret[] = array( - 'code' => 'badcontinue', - 'info' => 'Invalid continue param. You should pass the original value returned by the previous query' - ); - } - } - - if ( $this->mustBePosted() ) { - $ret[] = array( 'mustbeposted', $this->getModuleName() ); - } - - if ( $this->isReadMode() ) { - $ret[] = array( 'readrequired' ); + protected function makeHelpArrayToString( $prefix, $title, $input ) { + if ( $input === false ) { + return ''; } - - if ( $this->isWriteMode() ) { - $ret[] = array( 'writerequired' ); - $ret[] = array( 'writedisabled' ); + if ( !is_array( $input ) ) { + $input = array( $input ); } - if ( $this->needsToken() ) { - if ( !isset( $params['token'][ApiBase::PARAM_REQUIRED] ) - || !$params['token'][ApiBase::PARAM_REQUIRED] - ) { - // Add token as possible missing parameter, if not already done - $ret[] = array( 'missingparam', 'token' ); + if ( count( $input ) > 0 ) { + if ( $title ) { + $msg = $title . ( count( $input ) > 1 ? 's' : '' ) . ":\n "; + } else { + $msg = ' '; } - $ret[] = array( 'sessionfailure' ); + $msg .= implode( $prefix, $input ) . "\n"; + + return $msg; } - return $ret; + return ''; } /** - * Get final list of possible errors, after hooks have had a chance to - * tweak it as needed. - * - * @return array - * @since 1.22 + * Generates the parameter descriptions for this module, to be displayed in the + * module's help. + * @return string|bool */ - public function getFinalPossibleErrors() { - $possibleErrors = $this->getPossibleErrors(); - wfRunHooks( 'APIGetPossibleErrors', array( $this, &$possibleErrors ) ); - return $possibleErrors; - } + public function makeHelpMsgParameters() { + $params = $this->getFinalParams( ApiBase::GET_VALUES_FOR_HELP ); + if ( $params ) { - /** - * Parses a list of errors into a standardised format - * @param array $errors List of errors. Items can be in the for array( key, param1, param2, ... ) or array( 'code' => ..., 'info' => ... ) - * @return array Parsed list of errors with items in the form array( 'code' => ..., 'info' => ... ) - */ - public function parseErrors( $errors ) { - $ret = array(); + $paramsDescription = $this->getFinalParamDescription(); + $msg = ''; + $paramPrefix = "\n" . str_repeat( ' ', 24 ); + $descWordwrap = "\n" . str_repeat( ' ', 28 ); + foreach ( $params as $paramName => $paramSettings ) { + $desc = isset( $paramsDescription[$paramName] ) ? $paramsDescription[$paramName] : ''; + if ( is_array( $desc ) ) { + $desc = implode( $paramPrefix, $desc ); + } - foreach ( $errors as $row ) { - if ( isset( $row['code'] ) && isset( $row['info'] ) ) { - $ret[] = $row; - } else { - $ret[] = $this->parseMsg( $row ); + //handle shorthand + if ( !is_array( $paramSettings ) ) { + $paramSettings = array( + self::PARAM_DFLT => $paramSettings, + ); + } + + //handle missing type + if ( !isset( $paramSettings[ApiBase::PARAM_TYPE] ) ) { + $dflt = isset( $paramSettings[ApiBase::PARAM_DFLT] ) + ? $paramSettings[ApiBase::PARAM_DFLT] + : null; + if ( is_bool( $dflt ) ) { + $paramSettings[ApiBase::PARAM_TYPE] = 'boolean'; + } elseif ( is_string( $dflt ) || is_null( $dflt ) ) { + $paramSettings[ApiBase::PARAM_TYPE] = 'string'; + } elseif ( is_int( $dflt ) ) { + $paramSettings[ApiBase::PARAM_TYPE] = 'integer'; + } + } + + if ( isset( $paramSettings[self::PARAM_DEPRECATED] ) + && $paramSettings[self::PARAM_DEPRECATED] + ) { + $desc = "DEPRECATED! $desc"; + } + + if ( isset( $paramSettings[self::PARAM_REQUIRED] ) + && $paramSettings[self::PARAM_REQUIRED] + ) { + $desc .= $paramPrefix . "This parameter is required"; + } + + $type = isset( $paramSettings[self::PARAM_TYPE] ) + ? $paramSettings[self::PARAM_TYPE] + : null; + if ( isset( $type ) ) { + $hintPipeSeparated = true; + $multi = isset( $paramSettings[self::PARAM_ISMULTI] ) + ? $paramSettings[self::PARAM_ISMULTI] + : false; + if ( $multi ) { + $prompt = 'Values (separate with \'|\'): '; + } else { + $prompt = 'One value: '; + } + + if ( $type === 'submodule' ) { + $type = $this->getModuleManager()->getNames( $paramName ); + sort( $type ); + } + if ( is_array( $type ) ) { + $choices = array(); + $nothingPrompt = ''; + foreach ( $type as $t ) { + if ( $t === '' ) { + $nothingPrompt = 'Can be empty, or '; + } else { + $choices[] = $t; + } + } + $desc .= $paramPrefix . $nothingPrompt . $prompt; + $choicesstring = implode( ', ', $choices ); + $desc .= wordwrap( $choicesstring, 100, $descWordwrap ); + $hintPipeSeparated = false; + } else { + switch ( $type ) { + case 'namespace': + // Special handling because namespaces are + // type-limited, yet they are not given + $desc .= $paramPrefix . $prompt; + $desc .= wordwrap( implode( ', ', MWNamespace::getValidNamespaces() ), + 100, $descWordwrap ); + $hintPipeSeparated = false; + break; + case 'limit': + $desc .= $paramPrefix . "No more than {$paramSettings[self::PARAM_MAX]}"; + if ( isset( $paramSettings[self::PARAM_MAX2] ) ) { + $desc .= " ({$paramSettings[self::PARAM_MAX2]} for bots)"; + } + $desc .= ' allowed'; + break; + case 'integer': + $s = $multi ? 's' : ''; + $hasMin = isset( $paramSettings[self::PARAM_MIN] ); + $hasMax = isset( $paramSettings[self::PARAM_MAX] ); + if ( $hasMin || $hasMax ) { + if ( !$hasMax ) { + $intRangeStr = "The value$s must be no less than " . + "{$paramSettings[self::PARAM_MIN]}"; + } elseif ( !$hasMin ) { + $intRangeStr = "The value$s must be no more than " . + "{$paramSettings[self::PARAM_MAX]}"; + } else { + $intRangeStr = "The value$s must be between " . + "{$paramSettings[self::PARAM_MIN]} and {$paramSettings[self::PARAM_MAX]}"; + } + + $desc .= $paramPrefix . $intRangeStr; + } + break; + case 'upload': + $desc .= $paramPrefix . "Must be posted as a file upload using multipart/form-data"; + break; + } + } + + if ( $multi ) { + if ( $hintPipeSeparated ) { + $desc .= $paramPrefix . "Separate values with '|'"; + } + + $isArray = is_array( $type ); + if ( !$isArray + || $isArray && count( $type ) > self::LIMIT_SML1 + ) { + $desc .= $paramPrefix . "Maximum number of values " . + self::LIMIT_SML1 . " (" . self::LIMIT_SML2 . " for bots)"; + } + } + } + + $default = isset( $paramSettings[self::PARAM_DFLT] ) ? $paramSettings[self::PARAM_DFLT] : null; + if ( !is_null( $default ) && $default !== false ) { + $desc .= $paramPrefix . "Default: $default"; + } + + $msg .= sprintf( " %-19s - %s\n", $this->encodeParamName( $paramName ), $desc ); } + + return $msg; } - return $ret; + + return false; } + /**@}*/ + + /************************************************************************//** + * @name Profiling + * @{ + */ + /** * Profiling: total module execution time */ private $mTimeIn = 0, $mModuleTime = 0; /** + * Get the name of the module as shown in the profiler log + * + * @param DatabaseBase|bool $db + * + * @return string + */ + public function getModuleProfileName( $db = false ) { + if ( $db ) { + return 'API:' . $this->mModuleName . '-DB'; + } + + return 'API:' . $this->mModuleName; + } + + /** * Start module profiling */ public function profileIn() { if ( $this->mTimeIn !== 0 ) { - ApiBase::dieDebug( __METHOD__, 'called twice without calling profileOut()' ); + ApiBase::dieDebug( __METHOD__, 'Called twice without calling profileOut()' ); } $this->mTimeIn = microtime( true ); wfProfileIn( $this->getModuleProfileName() ); @@ -1699,10 +2124,13 @@ abstract class ApiBase extends ContextSource { */ public function profileOut() { if ( $this->mTimeIn === 0 ) { - ApiBase::dieDebug( __METHOD__, 'called without calling profileIn() first' ); + ApiBase::dieDebug( __METHOD__, 'Called without calling profileIn() first' ); } if ( $this->mDBTimeIn !== 0 ) { - ApiBase::dieDebug( __METHOD__, 'must be called after database profiling is done with profileDBOut()' ); + ApiBase::dieDebug( + __METHOD__, + 'Must be called after database profiling is done with profileDBOut()' + ); } $this->mModuleTime += microtime( true ) - $this->mTimeIn; @@ -1729,8 +2157,9 @@ abstract class ApiBase extends ContextSource { */ public function getProfileTime() { if ( $this->mTimeIn !== 0 ) { - ApiBase::dieDebug( __METHOD__, 'called without calling profileOut() first' ); + ApiBase::dieDebug( __METHOD__, 'Called without calling profileOut() first' ); } + return $this->mModuleTime; } @@ -1744,10 +2173,13 @@ abstract class ApiBase extends ContextSource { */ public function profileDBIn() { if ( $this->mTimeIn === 0 ) { - ApiBase::dieDebug( __METHOD__, 'must be called while profiling the entire module with profileIn()' ); + ApiBase::dieDebug( + __METHOD__, + 'Must be called while profiling the entire module with profileIn()' + ); } if ( $this->mDBTimeIn !== 0 ) { - ApiBase::dieDebug( __METHOD__, 'called twice without calling profileDBOut()' ); + ApiBase::dieDebug( __METHOD__, 'Called twice without calling profileDBOut()' ); } $this->mDBTimeIn = microtime( true ); wfProfileIn( $this->getModuleProfileName( true ) ); @@ -1758,10 +2190,11 @@ abstract class ApiBase extends ContextSource { */ public function profileDBOut() { if ( $this->mTimeIn === 0 ) { - ApiBase::dieDebug( __METHOD__, 'must be called while profiling the entire module with profileIn()' ); + ApiBase::dieDebug( __METHOD__, 'Must be called while profiling ' . + 'the entire module with profileIn()' ); } if ( $this->mDBTimeIn === 0 ) { - ApiBase::dieDebug( __METHOD__, 'called without calling profileDBIn() first' ); + ApiBase::dieDebug( __METHOD__, 'Called without calling profileDBIn() first' ); } $time = microtime( true ) - $this->mDBTimeIn; @@ -1778,36 +2211,168 @@ abstract class ApiBase extends ContextSource { */ public function getProfileDBTime() { if ( $this->mDBTimeIn !== 0 ) { - ApiBase::dieDebug( __METHOD__, 'called without calling profileDBOut() first' ); + ApiBase::dieDebug( __METHOD__, 'Called without calling profileDBOut() first' ); } + return $this->mDBTime; } /** - * Gets a default slave database connection object - * @return DatabaseBase + * Write logging information for API features to a debug log, for usage + * analysis. + * @param string $feature Feature being used. */ - protected function getDB() { - if ( !isset( $this->mSlaveDB ) ) { - $this->profileDBIn(); - $this->mSlaveDB = wfGetDB( DB_SLAVE, 'api' ); - $this->profileDBOut(); - } - return $this->mSlaveDB; + protected function logFeatureUsage( $feature ) { + $request = $this->getRequest(); + $s = '"' . addslashes( $feature ) . '"' . + ' "' . wfUrlencode( str_replace( ' ', '_', $this->getUser()->getName() ) ) . '"' . + ' "' . $request->getIP() . '"' . + ' "' . addslashes( $request->getHeader( 'Referer' ) ) . '"' . + ' "' . addslashes( $request->getHeader( 'User-agent' ) ) . '"'; + wfDebugLog( 'api-feature-usage', $s, 'private' ); } + /**@}*/ + + /************************************************************************//** + * @name Deprecated + * @{ + */ + + /// @deprecated since 1.24 + const PROP_ROOT = 'ROOT'; + /// @deprecated since 1.24 + const PROP_LIST = 'LIST'; + /// @deprecated since 1.24 + const PROP_TYPE = 0; + /// @deprecated since 1.24 + const PROP_NULLABLE = 1; + /** - * Debugging function that prints a value and an optional backtrace - * @param $value mixed Value to print - * @param string $name Description of the printed value - * @param bool $backtrace If true, print a backtrace + * Formerly returned a string that identifies the version of the extending + * class. Typically included the class name, the svn revision, timestamp, + * and last author. Usually done with SVN's Id keyword + * + * @deprecated since 1.21, version string is no longer supported + * @return string */ - public static function debugPrint( $value, $name = 'unknown', $backtrace = false ) { - print "\n\n<pre><b>Debugging value '$name':</b>\n\n"; - var_export( $value ); - if ( $backtrace ) { - print "\n" . wfBacktrace(); - } - print "\n</pre>\n"; + public function getVersion() { + wfDeprecated( __METHOD__, '1.21' ); + return ''; + } + + /** + * Formerly used to fetch a list of possible properites in the result, + * somehow organized with respect to the prop parameter that causes them to + * be returned. The specific semantics of the return value was never + * specified. Since this was never possible to be accurately updated, it + * has been removed. + * + * @deprecated since 1.24 + * @return array|bool + */ + protected function getResultProperties() { + wfDeprecated( __METHOD__, '1.24' ); + return false; + } + + /** + * @see self::getResultProperties() + * @deprecated since 1.24 + * @return array|bool + */ + public function getFinalResultProperties() { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /** + * @see self::getResultProperties() + * @deprecated since 1.24 + */ + protected static function addTokenProperties( &$props, $tokenFunctions ) { + wfDeprecated( __METHOD__, '1.24' ); + } + + /** + * @see self::getPossibleErrors() + * @deprecated since 1.24 + * @return array + */ + public function getRequireOnlyOneParameterErrorMessages( $params ) { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /** + * @see self::getPossibleErrors() + * @deprecated since 1.24 + * @return array + */ + public function getRequireMaxOneParameterErrorMessages( $params ) { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /** + * @see self::getPossibleErrors() + * @deprecated since 1.24 + * @return array + */ + public function getRequireAtLeastOneParameterErrorMessages( $params ) { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /** + * @see self::getPossibleErrors() + * @deprecated since 1.24 + * @return array + */ + public function getTitleOrPageIdErrorMessage() { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /** + * This formerly attempted to return a list of all possible errors returned + * by the module. However, this was impossible to maintain in many cases + * since errors could come from other areas of MediaWiki and in some cases + * from arbitrary extension hooks. Since a partial list claiming to be + * comprehensive is unlikely to be useful, it was removed. + * + * @deprecated since 1.24 + * @return array + */ + public function getPossibleErrors() { + wfDeprecated( __METHOD__, '1.24' ); + return array(); } + + /** + * @see self::getPossibleErrors() + * @deprecated since 1.24 + * @return array + */ + public function getFinalPossibleErrors() { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /** + * @see self::getPossibleErrors() + * @deprecated since 1.24 + * @return array + */ + public function parseErrors( $errors ) { + wfDeprecated( __METHOD__, '1.24' ); + return array(); + } + + /**@}*/ } + +/** + * For really cool vim folding this needs to be at the end: + * vim: foldmarker=@{,@} foldmethod=marker + */ |