}
}
- /*****************************************************************************
- * ABSTRACT METHODS *
- *****************************************************************************/
+
+ /************************************************************************//**
+ * @name Methods to implement
+ * @{
+ */
/**
* Evaluates the parameters, performs the requested query, and sets up
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' );
+ public function getModuleManager() {
+ return null;
+ }
- return '';
+ /**
+ * 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 getCustomPrinter() {
+ return null;
}
/**
- * Get the name of the module being executed by this instance
- * @return string
+ * Returns the description string for this module
+ * @return string|array
*/
- public function getModuleName() {
- return $this->mModuleName;
+ protected function getDescription() {
+ return false;
}
/**
- * Get the module manager, or null if this module has no sub-modules
- * @since 1.21
- * @return ApiModuleManager
+ * Returns usage examples for this module. Return false if no examples are available.
+ * @return bool|string|array
*/
- public function getModuleManager() {
- return null;
+ protected function getExamples() {
+ return false;
}
/**
- * Get parameter prefix (usually two letters or an empty string).
- * @return string
+ * @return bool|string|array Returns a false if the module has no help URL,
+ * else returns a (array of) string
*/
- public function getModulePrefix() {
- return $this->mModulePrefix;
+ public function getHelpUrls() {
+ return false;
}
/**
- * Get the name of the module as shown in the profiler log
+ * 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 DatabaseBase|bool $db
+ * 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';
- }
-
- 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
+ * 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;
}
/**
- * 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
+ * Indicates whether this module must be called with a POST request
+ * @return bool
*/
- 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 );
+ public function mustBePosted() {
+ return $this->needsToken() !== 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
+ * 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 getCustomPrinter() {
- return null;
+ public function needsToken() {
+ return false;
}
/**
- * Generates help message for this module, or false if there is no description
- * @return string|bool
+ * 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 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";
- }
+ protected function getWebUITokenSalt( array $params ) {
+ return null;
+ }
- // 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 string $item
+ * 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 string|array $input
+ * 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|bool
+ * 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 ( $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;
- }
+ public function getMain() {
+ return $this->mMainModule;
+ }
- 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 string|array
+ * 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;
}
/**
*/
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;
*/
public function getFinalParamDescription() {
$desc = $this->getParamDescription();
- wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) );
- return $desc;
- }
+ $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"
+ );
+ }
- /**
- * 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;
- }
+ wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) );
- /**
- * @see self::getResultProperties()
- * @deprecated since 1.24
- * @return array|bool
- */
- public function getFinalResultProperties() {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
+ return $desc;
}
- /**
- * @see self::getResultProperties()
- * @deprecated since 1.24
- */
- protected static function addTokenProperties( &$props, $tokenFunctions ) {
- wfDeprecated( __METHOD__, '1.24' );
- }
+ /**@}*/
- /**
- * Get final module description, after hooks have had a chance to tweak it as
- * needed.
- *
- * @return array|bool False on no parameters
+ /************************************************************************//**
+ * @name Parameter handling
+ * @{
*/
- public function getFinalDescription() {
- $desc = $this->getDescription();
- wfRunHooks( 'APIGetDescription', array( &$this, &$desc ) );
-
- return $desc;
- }
/**
* This method mangles parameter name based on the prefix supplied to the constructor.
}
}
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getRequireOnlyOneParameterErrorMessages( $params ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
/**
* Die if more than one of a certain set of parameters is set and not false.
*
}
}
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getRequireMaxOneParameterErrorMessages( $params ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
/**
* Die if none of a certain set of parameters is set and not false.
*
}
/**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
+ * Callback function used in requireOnlyOneParameter to check whether required parameters are set
+ *
+ * @param object $x Parameter to check is not null/false
+ * @return bool
*/
- public function getRequireAtLeastOneParameterErrorMessages( $params ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
+ private function parameterNotEmpty( $x ) {
+ return !is_null( $x ) && $x !== false;
}
/**
return $pageObj;
}
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getTitleOrPageIdErrorMessage() {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
- /**
- * 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;
- }
-
/**
* 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'
}
}
- /**
- * 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
- */
- 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 int $botMax Maximum value for sysops/bots
* @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)";
* @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(
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
return $title->getText();
}
+ /**@}*/
+
+ /************************************************************************//**
+ * @name Utility methods
+ * @{
+ */
+
+ /**
+ * 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
+ */
+ protected function setWatch( $watch, $titleObj, $userOption = null ) {
+ $value = $this->getWatchlistValue( $watch, $titleObj, $userOption );
+ if ( $value === null ) {
+ return;
+ }
+
+ WatchAction::doWatchOrUnwatch( $value, $titleObj, $this->getUser() );
+ }
+
+ /**
+ * Truncate an array to a certain length.
+ * @param array $arr Array to truncate
+ * @param int $limit Maximum length
+ * @return bool True if the array was truncated, false otherwise
+ */
+ public static function truncateArray( &$arr, $limit ) {
+ $modified = false;
+ while ( count( $arr ) > $limit ) {
+ 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
*
$this->setWarning( $msg );
}
- /**
- * Truncate an array to a certain length.
- * @param array $arr Array to truncate
- * @param int $limit Maximum length
- * @return bool True if the array was truncated, false otherwise
- */
- public static function truncateArray( &$arr, $limit ) {
- $modified = false;
- while ( count( $arr ) > $limit ) {
- array_pop( $arr );
- $modified = true;
- }
-
- return $modified;
- }
-
/**
* Throw a UsageException, which will (if uncaught) call the main module's
* error handler and die with an error message.
'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(
throw new MWException( "Internal error in $method: $message" );
}
+ /**@}*/
+
+ /************************************************************************//**
+ * @name Help message generation
+ * @{
+ */
+
/**
- * Indicates if this module needs maxlag to be checked
- * @return bool
+ * Generates help message for this module, or false if there is no description
+ * @return string|bool
*/
- public function shouldCheckMaxlag() {
- return true;
+ 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;
}
/**
- * Indicates whether this module requires read rights
- * @return bool
+ * @param string $item
+ * @return string
*/
- public function isReadMode() {
- return true;
+ private function indentExampleText( $item ) {
+ return " " . $item;
}
/**
- * Indicates whether this module requires write mode
- * @return bool
+ * @param string $prefix Text to split output items
+ * @param string $title What is being output
+ * @param string|array $input
+ * @return string
*/
- public function isWriteMode() {
- return false;
+ 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 '';
}
/**
- * Indicates whether this module must be called with a POST request
- * @return bool
+ * Generates the parameter descriptions for this module, to be displayed in the
+ * module's help.
+ * @return string|bool
*/
- public function mustBePosted() {
- return false;
- }
+ 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 ( $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;
+ }
+ }
- /**
- * 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;
- }
+ if ( $multi ) {
+ if ( $hintPipeSeparated ) {
+ $desc .= $paramPrefix . "Separate values with '|'";
+ }
- /**
- * 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;
- }
+ $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)";
+ }
+ }
+ }
- /**
- * 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' );
+ $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 );
}
- $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
- */
- public function getHelpUrls() {
return false;
}
- /**
- * 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
+ /************************************************************************//**
+ * @name Profiling
+ * @{
*/
- public function getFinalPossibleErrors() {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
/**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
+ * Profiling: total module execution time
*/
- public function parseErrors( $errors ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
+ private $mTimeIn = 0, $mModuleTime = 0;
/**
- * Profiling: total module execution time
+ * Get the name of the module as shown in the profiler log
+ *
+ * @param DatabaseBase|bool $db
+ *
+ * @return string
*/
- private $mTimeIn = 0, $mModuleTime = 0;
+ public function getModuleProfileName( $db = false ) {
+ if ( $db ) {
+ return 'API:' . $this->mModuleName . '-DB';
+ }
+
+ return 'API:' . $this->mModuleName;
+ }
/**
* Start module profiling
return $this->mDBTime;
}
- /**
- * Gets a default slave database connection object
- * @return DatabaseBase
- */
- protected function getDB() {
- if ( !isset( $this->mSlaveDB ) ) {
- $this->profileDBIn();
- $this->mSlaveDB = wfGetDB( DB_SLAVE, 'api' );
- $this->profileDBOut();
- }
-
- return $this->mSlaveDB;
- }
-
- /**
- * Debugging function that prints a value and an optional backtrace
- * @param mixed $value Value to print
- * @param string $name Description of the printed value
- * @param bool $backtrace If true, print a backtrace
- */
- 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";
- }
-
/**
* Write logging information for API features to a debug log, for usage
* analysis.
' "' . addslashes( $request->getHeader( 'User-agent' ) ) . '"';
wfDebugLog( 'api-feature-usage', $s, 'private' );
}
+
+ /**@}*/
+
+ /************************************************************************//**
+ * @name Deprecated
+ * @{
+ */
+
+ /**
+ * 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 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
+ */
dépôts / lhc / web / wiklou.git / blobdiff