=== Action API changes in 1.25 ===
* (bug 65403) XML tag highlighting is now only performed for formats
"xmlfm" and "wddxfm".
+* action=paraminfo supports generalized submodules (modules=query+value),
+ querymodules and formatmodules are deprecated
+* action=paraminfo no longer outputs descriptions and other help text by
+ default. If needed, it may be requested using the new 'helpformat' parameter.
+* action=help has been completely rewritten, and outputs help in HTML
+ rather than plain text.
+* Hitting api.php without specifying an action now displays only the help for
+ the main module, with links to submodule help.
+* API help is no longer displayed on errors.
+* Internationalized messages returned by the API will be in the wiki's content
+ language by default. 'uselang' is now a recognized API parameter;
+ "uselang=user" may be used to select the language from the current user's
+ preferences.
=== Action API internal changes in 1.25 ===
+* ApiHelp has been rewritten to support i18n and paginated HTML output.
+ Most existing modules should continue working without changes, but should do
+ the following:
+ * Add an i18n message "apihelp-{$moduleName}-description" to replace getDescription().
+ * Add i18n messages "apihelp-{$moduleName}-param-{$param}" for each parameter
+ to replace getParamDescription(). If necessary, the settings array returned
+ by getParams() can use the new ApiBase::PARAM_HELP_MSG key to override the
+ message.
+ * Implement getExamplesMessages() to replace getExamples().
+* Modules with submodules (like action=query) must have their submodules
+ override ApiBase::getParent() to return the correct parent object.
+* The 'APIGetDescription' and 'APIGetParamDescription' hooks are deprecated,
+ and will have no effect for modules using i18n messages. Use
+ 'APIGetDescriptionMessages' and 'APIGetParamDescriptionMessages' instead.
+* Api formatters will no longer be asked to display the help screen on errors.
+* ApiMain::getCredits() was removed. The credits are available in the
+ 'api-credits' i18n message.
+* The following methods have been deprecated and may be removed in a future
+ release:
+ * ApiBase::getDescription
+ * ApiBase::getParamDescription
+ * ApiBase::getExamples
+ * ApiBase::makeHelpMsg
+ * ApiBase::makeHelpArrayToString
+ * ApiBase::makeHelpMsgParameters
+ * ApiFormatBase::setUnescapeAmps
+ * ApiFormatBase::getWantsHelp
+ * ApiFormatBase::setHelp
+ * ApiMain::setHelp
+ * ApiMain::reallyMakeHelpMsg
+ * ApiMain::makeHelpMsgHeader
=== Languages updated in 1.25 ===
&$params: Array of parameters
$flags: int zero or OR-ed flags like ApiBase::GET_VALUES_FOR_HELP
-'APIGetDescription': Use this hook to modify a module's description.
+'APIGetDescription': DEPRECATED! Use APIGetDescriptionMessages instead.
+Use this hook to modify a module's description.
&$module: ApiBase Module object
-&$desc: Array of descriptions
+&$desc: String description, or array of description strings
-'APIGetParamDescription': Use this hook to modify a module's parameter
-descriptions.
+'APIGetDescriptionMessages': Use this hook to modify a module's help message.
+$module: ApiBase Module object
+&$msg: Array of Message objects
+
+'APIGetParamDescription': DEPRECATED! Use APIGetParamDescriptionMessages instead.
+Use this hook to modify a module's parameter descriptions.
&$module: ApiBase Module object
&$desc: Array of parameter descriptions
+'APIGetParamDescriptionMessages': Use this hook to modify a module's parameter descriptions.
+$module: ApiBase Module object
+&$msg: Array of arrays of Message objects
+
+'APIHelpModifyOutput': Use this hook to modify an API module's help output.
+$module: ApiBase Module object
+&$help: Array of HTML strings to be joined for the output.
+$options: Array Options passed to ApiHelp::getHelp
+
'APIQueryAfterExecute': After calling the execute() method of an
action=query submodule. Use this to extend core API modules.
&$module: Module object
'SpecialAllMessages' => 'includes/specials/SpecialAllMessages.php',
'SpecialAllMyUploads' => 'includes/specials/SpecialMyRedirectPages.php',
'SpecialAllPages' => 'includes/specials/SpecialAllPages.php',
+ 'SpecialApiHelp' => 'includes/specials/SpecialApiHelp.php',
'SpecialBlankpage' => 'includes/specials/SpecialBlankpage.php',
'SpecialBlock' => 'includes/specials/SpecialBlock.php',
'SpecialBlockList' => 'includes/specials/SpecialBlockList.php',
*/
$wgMessagesDirs = array(
'core' => "$IP/languages/i18n",
+ 'api' => "$IP/includes/api/i18n",
'oojs-ui' => "$IP/resources/lib/oojs-ui/i18n",
);
// Boolean, if MIN/MAX are set, enforce (die) these?
// Only applies if TYPE='integer' Use with extreme caution
const PARAM_RANGE_ENFORCE = 9;
+ /// @since 1.25
+ // Specify an alternative i18n message for this help parameter.
+ // Value can be a string key, an array giving key and parameters, or a
+ // Message object.
+ const PARAM_HELP_MSG = 10;
+ /// @since 1.25
+ // Specify additional i18n messages to append to the normal message. Value
+ // is an array of any of strings giving the message key, arrays giving key and
+ // parameters, or Message objects.
+ const PARAM_HELP_MSG_APPEND = 11;
const LIMIT_BIG1 = 500; // Fast query, std user limit
const LIMIT_BIG2 = 5000; // Fast query, bot/sysop limit
}
/**
- * Returns the description string for this module
- * @return string|array
+ * Returns usage examples for this module.
+ *
+ * Return value has query strings as keys, with values being either strings
+ * (message key), arrays (message key + parameter), or Message objects.
+ *
+ * Do not call this base class implementation when overriding this method.
+ *
+ * @since 1.25
+ * @return array
*/
- protected function getDescription() {
- return false;
- }
+ protected function getExamplesMessages() {
+ // Fall back to old non-localised method
+ $ret = array();
+
+ $examples = $this->getExamples();
+ if ( $examples ) {
+ if ( !is_array( $examples ) ) {
+ $examples = array( $examples );
+ } elseif ( $examples && ( count( $examples ) & 1 ) == 0 &&
+ array_keys( $examples ) === range( 0, count( $examples ) - 1 ) &&
+ !preg_match( '/^\s*api\.php\?/', $examples[0] )
+ ) {
+ // Fix up the ugly "even numbered elements are description, odd
+ // numbered elemts are the link" format (see doc for self::getExamples)
+ $tmp = array();
+ for ( $i = 0; $i < count( $examples ); $i += 2 ) {
+ $tmp[$examples[$i + 1]] = $examples[$i];
+ }
+ $examples = $tmp;
+ }
- /**
- * Returns usage examples for this module. Return false if no examples are available.
- * @return bool|string|array
- */
- protected function getExamples() {
- return false;
+ foreach ( $examples as $k => $v ) {
+ if ( is_numeric( $k ) ) {
+ $qs = $v;
+ $msg = '';
+ } else {
+ $qs = $k;
+ $msg = self::escapeWikiText( $v );
+ if ( is_array( $msg ) ) {
+ $msg = join( " ", $msg );
+ }
+ }
+
+ $qs = preg_replace( '/^\s*api\.php\?/', '', $qs );
+ $ret[$qs] = $this->msg( 'api-help-fallback-example', array( $msg ) );
+ }
+ }
+
+ return $ret;
}
/**
- * @return bool|string|array Returns a false if the module has no help URL,
- * else returns a (array of) string
+ * Return links to more detailed help pages about the module.
+ * @since 1.25, returning boolean false is deprecated
+ * @return string|array
*/
public function getHelpUrls() {
- return false;
+ return array();
}
/**
* in the overriding methods. Callers of this method can pass zero or
* more OR-ed flags like GET_VALUES_FOR_HELP.
*
- * @return array|bool
+ * @return array
*/
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;
- }
-
- /**
- * 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
- */
- protected function getParamDescription() {
- return false;
+ return array();
}
/**
return $this->needsToken() !== false;
}
+ /**
+ * Indicates whether this module is deprecated
+ * @since 1.25
+ * @return bool
+ */
+ public function isDeprecated() {
+ return false;
+ }
+
+ /**
+ * Indicates whether this module is "internal" or unstable
+ * @since 1.25
+ * @return bool
+ */
+ public function isInternal() {
+ return false;
+ }
+
/**
* Returns the token type this module requires in order to execute.
*
* 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.
+ * Returning a non-falsey value here will force the addition of an
+ * appropriate 'token' parameter in self::getFinalParams(). 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
return $this === $this->mMainModule;
}
+ /**
+ * Get the parent of this module
+ * @since 1.25
+ * @return ApiBase|null
+ */
+ public function getParent() {
+ return $this->isMain() ? null : $this->getMain();
+ }
+
+ /**
+ * Get the path to this module
+ *
+ * @since 1.25
+ * @return string
+ */
+ public function getModulePath() {
+ if ( $this->isMain() ) {
+ return 'main';
+ } elseif ( $this->getParent()->isMain() ) {
+ return $this->getModuleName();
+ } else {
+ return $this->getParent()->getModulePath() . '+' . $this->getModuleName();
+ }
+ }
+
+ /**
+ * Get a module from its module path
+ *
+ * @since 1.25
+ * @param string $path
+ * @return ApiBase|null
+ * @throws UsageException
+ */
+ public function getModuleFromPath( $path ) {
+ $module = $this->getMain();
+ if ( $path === 'main' ) {
+ return $module;
+ }
+
+ $parts = explode( '+', $path );
+ if ( count( $parts ) === 1 ) {
+ // In case the '+' was typed into URL, it resolves as a space
+ $parts = explode( ' ', $path );
+ }
+
+ $count = count( $parts );
+ for ( $i = 0; $i < $count; $i++ ) {
+ $parent = $module;
+ $manager = $parent->getModuleManager();
+ if ( $manager === null ) {
+ $errorPath = join( '+', array_slice( $parts, 0, $i ) );
+ $this->dieUsage( "The module \"$errorPath\" has no submodules", 'badmodule' );
+ }
+ $module = $manager->getModule( $parts[$i] );
+
+ if ( $module === null ) {
+ $errorPath = $i ? join( '+', array_slice( $parts, 0, $i ) ) : $parent->getModuleName();
+ $this->dieUsage(
+ "The module \"$errorPath\" does not have a submodule \"{$parts[$i]}\"",
+ 'badmodule'
+ );
+ }
+ }
+
+ return $module;
+ }
+
/**
* Get the result object
* @return ApiResult
return $this->mSlaveDB;
}
- /**
- * 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 ) );
-
- return $desc;
- }
-
- /**
- * Get final list of parameters, after hooks have had a chance to
- * tweak it as needed.
- *
- * @param int $flags Zero or more flags like GET_VALUES_FOR_HELP
- * @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;
- }
-
- /**
- * Get final parameter descriptions, after hooks have had a chance to tweak it as
- * needed.
- *
- * @return array|bool False on no parameter descriptions
- */
- public function getFinalParamDescription() {
- $desc = $this->getParamDescription();
-
- $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"
- );
- }
-
- wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) );
-
- return $desc;
- }
-
/**@}*/
/************************************************************************//**
return $user;
}
+ /**
+ * A subset of wfEscapeWikiText for BC texts
+ *
+ * @since 1.25
+ * @param string|array $v
+ * @return string|array
+ */
+ private static function escapeWikiText( $v ) {
+ if ( is_array( $v ) ) {
+ return array_map( 'self::escapeWikiText', $v );
+ } else {
+ return strtr( $v, array(
+ '__' => '__', '{' => '{', '}' => '}',
+ '[[Category:' => '[[:Category:',
+ '[[File:' => '[[:File:', '[[Image:' => '[[:Image:',
+ ) );
+ }
+ }
+
+ /**
+ * Create a Message from a string or array
+ *
+ * A string is used as a message key. An array has the message key as the
+ * first value and message parameters as subsequent values.
+ *
+ * @since 1.25
+ * @param string|array|Message $msg
+ * @param IContextSource $context
+ * @param array $params
+ * @return Message|null
+ */
+ public static function makeMessage( $msg, IContextSource $context, array $params = null ) {
+ if ( is_string( $msg ) ) {
+ $msg = wfMessage( $msg );
+ } elseif ( is_array( $msg ) ) {
+ $msg = call_user_func_array( 'wfMessage', $msg );
+ }
+ if ( !$msg instanceof Message ) {
+ return null;
+ }
+
+ $msg->setContext( $context );
+ if ( $params ) {
+ $msg->params( $params );
+ }
+
+ return $msg;
+ }
+
/**@}*/
/************************************************************************//**
*/
/**
- * Generates help message for this module, or false if there is no description
- * @return string|bool
+ * Get final module description, after hooks have had a chance to tweak it as
+ * needed.
+ *
+ * @since 1.25, returns Message[] rather than string[]
+ * @return Message[]
*/
- public function makeHelpMsg() {
- static $lnPrfx = "\n ";
+ public function getFinalDescription() {
+ $desc = $this->getDescription();
+ wfRunHooks( 'APIGetDescription', array( &$this, &$desc ) );
+ $desc = self::escapeWikiText( $desc );
+ if ( is_array( $desc ) ) {
+ $desc = join( "\n", $desc );
+ } else {
+ $desc = (string)$desc;
+ }
- $msg = $this->getFinalDescription();
+ $msg = $this->msg( "apihelp-{$this->getModulePath()}-description", array(
+ $this->getModulePrefix(),
+ $this->getModuleName(),
+ $this->getModulePath(),
+ ) );
+ if ( !$msg->exists() ) {
+ $msg = $this->msg( 'api-help-fallback-description', $desc );
+ }
+ $msgs = array( $msg );
- if ( $msg !== false ) {
+ wfRunHooks( 'APIGetDescriptionMessages', array( $this, &$msgs ) );
- if ( !is_array( $msg ) ) {
- $msg = array(
- $msg
- );
- }
- $msg = $lnPrfx . implode( $lnPrfx, $msg ) . "\n";
+ return $msgs;
+ }
- $msg .= $this->makeHelpArrayToString( $lnPrfx, false, $this->getHelpUrls() );
+ /**
+ * Get final list of parameters, after hooks have had a chance to
+ * tweak it as needed.
+ *
+ * @param int $flags Zero or more flags like GET_VALUES_FOR_HELP
+ * @return array|bool False on no parameters
+ * @since 1.21 $flags param added
+ */
+ public function getFinalParams( $flags = 0 ) {
+ $params = $this->getAllowedParams( $flags );
+ if ( !$params ) {
+ $params = array();
+ }
- 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->needsToken() ) {
+ $params['token'] = array(
+ ApiBase::PARAM_TYPE => 'string',
+ ApiBase::PARAM_REQUIRED => true,
+ ApiBase::PARAM_HELP_MSG => array(
+ 'api-help-param-token',
+ $this->needsToken(),
+ ),
+ ) + ( isset( $params['token'] ) ? $params['token'] : array() );
+ }
+
+ wfRunHooks( 'APIGetAllowedParams', array( &$this, &$params, $flags ) );
+
+ return $params;
+ }
+
+ /**
+ * Get final parameter descriptions, after hooks have had a chance to tweak it as
+ * needed.
+ *
+ * @since 1.25, returns array of Message[] rather than array of string[]
+ * @return array Keys are parameter names, values are arrays of Message objects
+ */
+ public function getFinalParamDescription() {
+ $desc = $this->getParamDescription();
+ wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) );
+
+ if ( !$desc ) {
+ $desc = array();
+ }
+ $desc = self::escapeWikiText( $desc );
+
+ $params = $this->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
+ $msgs = array();
+ foreach ( $params as $param => $settings ) {
+ if ( !is_array( $settings ) ) {
+ $settings = array();
}
- if ( $this->isReadMode() || $this->isWriteMode() ||
- $this->mustBePosted()
- ) {
- $msg .= "\n";
+
+ $d = isset( $desc[$param] ) ? $desc[$param] : '';
+ if ( is_array( $d ) ) {
+ // Special handling for prop parameters
+ $d = array_map( function ( $line ) {
+ if ( preg_match( '/^\s+(\S+)\s+-\s+(.+)$/', $line, $m ) ) {
+ $line = "\n;{$m[1]}:{$m[2]}";
+ }
+ return $line;
+ }, $d );
+ $d = join( ' ', $d );
}
- // Parameters
- $paramsMsg = $this->makeHelpMsgParameters();
- if ( $paramsMsg !== false ) {
- $msg .= "Parameters:\n$paramsMsg";
+ if ( isset( $settings[ApiBase::PARAM_HELP_MSG] ) ) {
+ $msg = $settings[ApiBase::PARAM_HELP_MSG];
+ } else {
+ $msg = $this->msg( "apihelp-{$this->getModulePath()}-param-{$param}" );
+ if ( !$msg->exists() ) {
+ $msg = $this->msg( 'api-help-fallback-parameter', $d );
+ }
+ }
+ $msg = ApiBase::makeMessage( $msg, $this->getContext(), array(
+ $this->getModulePrefix(),
+ $param,
+ $this->getModuleName(),
+ $this->getModulePath(),
+ ) );
+ if ( !$msg ) {
+ $this->dieDebug( __METHOD__,
+ 'Value in ApiBase::PARAM_HELP_MSG is not valid' );
}
+ $msgs[$param] = array( $msg );
- $examples = $this->getExamples();
- if ( $examples ) {
- if ( !is_array( $examples ) ) {
- $examples = array(
- $examples
- );
+ if ( isset( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
+ if ( !is_array( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
+ $this->dieDebug( __METHOD__,
+ 'Value for ApiBase::PARAM_HELP_MSG_APPEND is not an array' );
}
- $msg .= "Example" . ( count( $examples ) > 1 ? 's' : '' ) . ":\n";
- foreach ( $examples as $k => $v ) {
- if ( is_numeric( $k ) ) {
- $msg .= " $v\n";
+ foreach ( $settings[ApiBase::PARAM_HELP_MSG_APPEND] as $m ) {
+ $m = ApiBase::makeMessage( $m, $this->getContext(), array(
+ $this->getModulePrefix(),
+ $param,
+ $this->getModuleName(),
+ $this->getModulePath(),
+ ) );
+ if ( $m ) {
+ $msgs[$param][] = $m;
} 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";
+ $this->dieDebug( __METHOD__,
+ 'Value in ApiBase::PARAM_HELP_MSG_APPEND is not valid' );
}
}
}
}
- return $msg;
+ wfRunHooks( 'APIGetParamDescriptionMessages', array( $this, &$msgs ) );
+
+ return $msgs;
}
/**
- * @param string $item
- * @return string
- */
- private function indentExampleText( $item ) {
- return " " . $item;
- }
-
- /**
- * @param string $prefix Text to split output items
- * @param string $title What is being output
- * @param string|array $input
- * @return string
+ * Generates the list of flags for the help screen and for action=paraminfo
+ *
+ * Corresponding messages: api-help-flag-deprecated,
+ * api-help-flag-internal, api-help-flag-readrights,
+ * api-help-flag-writerights, api-help-flag-mustbeposted
+ *
+ * @return string[]
*/
- protected function makeHelpArrayToString( $prefix, $title, $input ) {
- if ( $input === false ) {
- return '';
+ protected function getHelpFlags() {
+ $flags = array();
+
+ if ( $this->isDeprecated() ) {
+ $flags[] = 'deprecated';
}
- if ( !is_array( $input ) ) {
- $input = array( $input );
+ if ( $this->isInternal() ) {
+ $flags[] = 'internal';
}
-
- if ( count( $input ) > 0 ) {
- if ( $title ) {
- $msg = $title . ( count( $input ) > 1 ? 's' : '' ) . ":\n ";
- } else {
- $msg = ' ';
- }
- $msg .= implode( $prefix, $input ) . "\n";
-
- return $msg;
+ if ( $this->isReadMode() ) {
+ $flags[] = 'readrights';
+ }
+ if ( $this->isWriteMode() ) {
+ $flags[] = 'writerights';
+ }
+ if ( $this->mustBePosted() ) {
+ $flags[] = 'mustbeposted';
}
- return '';
+ return $flags;
}
/**
- * Generates the parameter descriptions for this module, to be displayed in the
- * module's help.
- * @return string|bool
+ * Called from ApiHelp before the pieces are joined together and returned.
+ *
+ * This exists mainly for ApiMain to add the Permissions and Credits
+ * sections. Other modules probably don't need it.
+ *
+ * @param string[] &$help Array of help data
+ * @param array $options Options passed to ApiHelp::getHelp
*/
- 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;
- }
-
- return false;
+ public function modifyHelp( array &$help, array $options ) {
}
/**@}*/
return array();
}
+ /**
+ * Returns the description string for this module
+ *
+ * Ignored if an i18n message exists for
+ * "apihelp-{$this->getModulePathString()}-description".
+ *
+ * @deprecated since 1.25
+ * @return Message|string|array
+ */
+ protected function getDescription() {
+ return false;
+ }
+
+ /**
+ * Returns an array of parameter descriptions.
+ *
+ * For each parameter, ignored if an i18n message exists for the parameter.
+ * By default that message is
+ * "apihelp-{$this->getModulePathString()}-param-{$param}", but it may be
+ * overridden using ApiBase::PARAM_HELP_MSG in the data returned by
+ * self::getFinalParams().
+ *
+ * @deprecated since 1.25
+ * @return array|bool False on no parameter descriptions
+ */
+ protected function getParamDescription() {
+ return false;
+ }
+
+ /**
+ * Returns usage examples for this module.
+ *
+ * Return value as an array is either:
+ * - numeric keys with partial URLs ("api.php?" plus a query string) as
+ * values
+ * - sequential numeric keys with even-numbered keys being display-text
+ * and odd-numbered keys being partial urls
+ * - partial URLs as keys with display-text (string or array-to-be-joined)
+ * as values
+ * Return value as a string is the same as an array with a numeric key and
+ * that value, and boolean false means "no examples".
+ *
+ * @deprecated since 1.25, use getExamplesMessages() instead
+ * @return bool|string|array
+ */
+ protected function getExamples() {
+ return false;
+ }
+
+ /**
+ * Generates help message for this module, or false if there is no description
+ * @deprecated since 1.25
+ * @return string|bool
+ */
+ public function makeHelpMsg() {
+ wfDeprecated( __METHOD__, '1.25' );
+ 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;
+ }
+
+ /**
+ * @deprecated since 1.25
+ * @param string $item
+ * @return string
+ */
+ private function indentExampleText( $item ) {
+ return " " . $item;
+ }
+
+ /**
+ * @deprecated since 1.25
+ * @param string $prefix Text to split output items
+ * @param string $title What is being output
+ * @param string|array $input
+ * @return string
+ */
+ protected function makeHelpArrayToString( $prefix, $title, $input ) {
+ wfDeprecated( __METHOD__, '1.25' );
+ 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 '';
+ }
+
+ /**
+ * Generates the parameter descriptions for this module, to be displayed in the
+ * module's help.
+ * @deprecated since 1.25
+ * @return string|bool
+ */
+ public function makeHelpMsgParameters() {
+ wfDeprecated( __METHOD__, '1.25' );
+ $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;
+ }
+
+ return false;
+ }
+
/**@}*/
}
* special-case fix that should be removed once the help has been
* reworked to use a fully HTML interface.
*
+ * @deprecated since 1.25
* @param bool $b Whether or not ampersands should be escaped.
*/
public function setUnescapeAmps( $b ) {
+ wfDeprecated( __METHOD__, '1.25' );
$this->mUnescapeAmps = $b;
}
* Whether this formatter can format the help message in a nice way.
* By default, this returns the same as getIsHtml().
* When action=help is set explicitly, the help will always be shown
+ * @deprecated since 1.25
* @return bool
*/
public function getWantsHelp() {
+ wfDeprecated( __METHOD__, '1.25' );
return $this->getIsHtml();
}
* A human-targeted notice about available formats is printed for the HTML-based output,
* except for help screens (caused by either an error in the API parameters,
* the calling of action=help, or requesting the root script api.php).
- * @param bool $isHelpScreen Whether a help screen is going to be shown
+ * @param bool $unused Always false since 1.25
*/
- function initPrinter( $isHelpScreen ) {
+ function initPrinter( $unused ) {
if ( $this->mDisabled ) {
return;
}
?> <title>MediaWiki API Result</title>
<?php
}
+// @codingStandardsIgnoreStart Exclude long line from CodeSniffer checks
?>
</head>
<body>
-<?php
- if ( !$isHelpScreen ) {
-// @codingStandardsIgnoreStart Exclude long line from CodeSniffer checks
-?>
<br />
<small>
You are looking at the HTML representation of the <?php echo $this->mFormat; ?> format.<br />
<pre style='white-space: pre-wrap;'>
<?php
// @codingStandardsIgnoreEnd
- // don't wrap the contents of the <pre> for help screens
- // because these are actually formatted to rely on
- // the monospaced font for layout purposes
- } else {
-?>
-<pre>
-<?php
- }
}
}
/**
* Sets whether the pretty-printer should format *bold*
+ * @deprecated since 1.25
* @param bool $help
*/
public function setHelp( $help = true ) {
+ wfDeprecated( __METHOD__, '1.25' );
$this->mHelp = $help;
}
}
public function getDescription() {
- return 'DEPRECATED! Output data in PHP\'s var_export() format' . parent::getDescription();
+ return 'Output data in PHP\'s var_export() format' . parent::getDescription();
+ }
+
+ public function isDeprecated() {
+ return true;
}
}
}
public function getDescription() {
- return 'DEPRECATED! Output data in PHP\'s var_dump() format' . parent::getDescription();
+ return 'Output data in PHP\'s var_dump() format' . parent::getDescription();
+ }
+
+ public function isDeprecated() {
+ return true;
}
}
return $this->mIsRaw;
}
+ /**
+ * @deprecated since 1.25
+ */
public function getWantsHelp() {
+ wfDeprecated( __METHOD__, '1.25' );
// Help is always ugly in JSON
return false;
}
}
public function getDescription() {
- return 'DEPRECATED! Output data in PHP\'s print_r() format' . parent::getDescription();
+ return 'Output data in PHP\'s print_r() format' . parent::getDescription();
+ }
+
+ public function isDeprecated() {
+ return true;
}
}
}
public function getDescription() {
- return 'DEPRECATED! Output data in WDDX format' . parent::getDescription();
+ return 'Output data in WDDX format' . parent::getDescription();
+ }
+
+ public function isDeprecated() {
+ return true;
}
}
}
public function getDescription() {
- return 'DEPRECATED! Output data in YAML format' . ApiFormatBase::getDescription();
+ return 'Output data in YAML format' . ApiFormatBase::getDescription();
+ }
+
+ public function isDeprecated() {
+ return true;
}
}
/**
*
*
- * Created on Sep 6, 2006
+ * Created on Aug 29, 2014
*
- * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
+ * Copyright © 2014 Brad Jorsch <bjorsch@wikimedia.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
*/
/**
- * This is a simple class to handle action=help
+ * Class to output help for an API module
*
+ * @since 1.25 completely rewritten
* @ingroup API
*/
class ApiHelp extends ApiBase {
- /**
- * Module for displaying help
- */
public function execute() {
- // Get parameters
+ global $wgContLang;
+
$params = $this->extractRequestParams();
+ $modules = array();
- if ( !isset( $params['modules'] ) && !isset( $params['querymodules'] ) ) {
- $this->dieUsage( '', 'help' );
+ foreach ( $params['modules'] as $path ) {
+ $modules[] = $this->getModuleFromPath( $path );
}
- $this->getMain()->setHelp();
- $result = $this->getResult();
+ // Get the help
+ $context = new RequestContext;
+ $context->setUser( new User ); // anon to avoid caching issues
+ $context->setSkin( SkinFactory::getDefaultInstance()->makeSkin( 'apioutput' ) );
+ $context->setLanguage( $this->getMain()->getLanguage() );
- if ( is_array( $params['modules'] ) ) {
- $modules = $params['modules'];
+ self::getHelp( $context, $modules, $params );
+
+ // Grab the output from the skin
+ ob_start();
+ $context->getOutput()->output();
+ $html = ob_get_clean();
+
+ $result = $this->getResult();
+ if ( $params['wrap'] ) {
+ $data = array(
+ 'mime' => 'text/html',
+ 'help' => $help,
+ );
+ $result->setSubelements( $data, 'help' );
+ $result->addValue( null, $this->getModuleName(), $data );
} else {
- $modules = array();
+ $result->reset();
+ $result->addValue( null, 'text', $html, ApiResult::NO_SIZE_CHECK );
+ $result->addValue( null, 'mime', 'text/html', ApiResult::NO_SIZE_CHECK );
}
+ }
+
+ /**
+ * Generate help for the specified modules
+ *
+ * Help is placed into the OutputPage object returned by
+ * $context->getOutput().
+ *
+ * Recognized options include:
+ * - headerlevel: (int) Header tag level
+ * - nolead: (bool) Skip the inclusion of api-help-lead
+ * - noheader: (bool) Skip the inclusion of the top-level section headers
+ * - submodules: (bool) Include help for submodules of the current module
+ * - recursivesubmodules: (bool) Include help for submodules recursively
+ * - helptitle: (string) Title to link for additional modules' help. Should contain $1.
+ *
+ * @param IContextSource $context
+ * @param ApiBase[]|ApiBase $modules
+ * @param array $options Formatting options (described above)
+ * @return string
+ */
+ public static function getHelp( IContextSource $context, $modules, array $options ) {
+ global $wgMemc, $wgContLang;
+
+ if ( !is_array( $modules ) ) {
+ $modules = array( $modules );
+ }
+
+ $out = $context->getOutput();
+ $out->addModules( 'mediawiki.apihelp' );
+ $out->setPageTitle( $context->msg( 'api-help-title' ) );
- if ( is_array( $params['querymodules'] ) ) {
- $this->logFeatureUsage( 'action=help&querymodules' );
- $queryModules = $params['querymodules'];
- foreach ( $queryModules as $m ) {
- $modules[] = 'query+' . $m;
+ $cacheKey = null;
+ if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain &&
+ $options['recursivesubmodules'] && $context->getLanguage() === $wgContLang
+ ) {
+ $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
+ if ( $cacheHelpTimeout > 0 ) {
+ // Get help text from cache if present
+ $cacheKey = wfMemcKey( 'apihelp', $modules[0]->getModulePath(),
+ str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) ) );
+ $cached = $wgMemc->get( $cacheKey );
+ if ( $cached ) {
+ $out->addHTML( $cached );
+ return;
+ }
}
- } else {
- $queryModules = array();
}
+ if ( $out->getHTML() !== '' ) {
+ // Don't save to cache, there's someone else's content in the page
+ // already
+ $cacheKey = null;
+ }
+
+ $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
+ $options['submodules'] = $options['recursivesubmodules'] || !empty( $options['submodules'] );
- $r = array();
- foreach ( $modules as $m ) {
- // sub-modules could be given in the form of "name[+name[+name...]]"
- $subNames = explode( '+', $m );
- if ( count( $subNames ) === 1 ) {
- // In case the '+' was typed into URL, it resolves as a space
- $subNames = explode( ' ', $m );
+ // Prepend lead
+ if ( empty( $options['nolead'] ) ) {
+ $msg = $context->msg( 'api-help-lead' );
+ if ( !$msg->isDisabled() ) {
+ $out->addHTML( $msg->parseAsBlock() );
}
+ }
- $module = $this->getMain();
- $subNamesCount = count( $subNames );
- for ( $i = 0; $i < $subNamesCount; $i++ ) {
- $subs = $module->getModuleManager();
- if ( $subs === null ) {
- $module = null;
- } else {
- $module = $subs->getModule( $subNames[$i] );
- }
+ $haveModules = array();
+ $out->addHTML( self::getHelpInternal( $context, $modules, $options, $haveModules ) );
- if ( $module === null ) {
- if ( count( $subNames ) === 2
- && $i === 1
- && $subNames[0] === 'query'
- && in_array( $subNames[1], $queryModules )
- ) {
- // Legacy: This is one of the renamed 'querymodule=...' parameters,
- // do not use '+' notation in the output, use submodule's name instead.
- $name = $subNames[1];
- } else {
- $name = implode( '+', array_slice( $subNames, 0, $i + 1 ) );
- }
- $r[] = array( 'name' => $name, 'missing' => '' );
- break;
+ $helptitle = isset( $options['helptitle'] ) ? $options['helptitle'] : null;
+ $html = self::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
+ $out->clearHTML();
+ $out->addHTML( $html );
+
+ if ( $cacheKey !== null ) {
+ $wgMemc->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
+ }
+ }
+
+ /**
+ * Replace Special:ApiHelp links with links to api.php
+ *
+ * @param string $html
+ * @param string|null $helptitle Title to link to rather than api.php, must contain '$1'
+ * @param array $localModules Modules to link within the current page
+ * @return string
+ */
+ public static function fixHelpLinks( $html, $helptitle = null, $localModules = array() ) {
+ $formatter = new HtmlFormatter( $html );
+ $doc = $formatter->getDoc();
+ $xpath = new DOMXPath( $doc );
+ $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
+ foreach ( $nodes as $node ) {
+ $href = $node->getAttribute( 'href' );
+ do {
+ $old = $href;
+ $href = rawurldecode( $href );
+ } while ( $old !== $href );
+ if ( preg_match( '!Special:ApiHelp/([^&/|]+)!', $href, $m ) ) {
+ if ( isset( $localModules[$m[1]] ) ) {
+ $href = '#' . $m[1];
+ } elseif ( $helptitle !== null ) {
+ $href = Title::newFromText( str_replace( '$1', $m[1], $helptitle ) )
+ ->getFullUrl();
} else {
- $type = $subs->getModuleGroup( $subNames[$i] );
+ $href = wfAppendQuery( wfScript( 'api' ), array(
+ 'action' => 'help',
+ 'modules' => $m[1],
+ ) );
}
- }
-
- if ( $module !== null ) {
- $r[] = $this->buildModuleHelp( $module, $type );
+ $node->setAttribute( 'href', $href );
+ $node->removeAttribute( 'title' );
}
}
- $result->setIndexedTagName( $r, 'module' );
- $result->addValue( null, $this->getModuleName(), $r );
+ return $formatter->getText();
+ }
+
+ /**
+ * Wrap a message in HTML with a class.
+ *
+ * @param Message $msg
+ * @param string $class
+ * @param string $tag
+ * @return string
+ */
+ private static function wrap( Message $msg, $class, $tag = 'span' ) {
+ return Html::rawElement( $tag, array( 'class' => $class ),
+ $msg->parse()
+ );
}
/**
- * @param ApiBase $module
- * @param string $type What type of request is this? e.g. action, query, list, prop, meta, format
+ * Recursively-called function to actually construct the help
+ *
+ * @param IContextSource $context
+ * @param ApiBase[] $modules
+ * @param array $options
+ * @param array &$haveModules
* @return string
*/
- private function buildModuleHelp( $module, $type ) {
- $msg = ApiMain::makeHelpMsgHeader( $module, $type );
+ private static function getHelpInternal( IContextSource $context, array $modules,
+ array $options, &$haveModules
+ ) {
+ $out = '';
+
+ $level = min( 6, empty( $options['headerlevel'] ) ? 2 : $options['headerlevel'] );
+ $options['headerlevel'] = $level;
+
+ foreach ( $modules as $module ) {
+ $haveModules[$module->getModulePath()] = true;
+ $module->setContext( $context );
+ $help = array(
+ 'header' => '',
+ 'flags' => '',
+ 'description' => '',
+ 'help-urls' => '',
+ 'parameters' => '',
+ 'examples' => '',
+ 'submodules' => '',
+ );
+
+ if ( empty( $options['noheader'] ) ) {
+ $path = $module->getModulePath();
+ if ( $module->isMain() ) {
+ $header = $context->msg( 'api-help-main-header' )->parse();
+ } else {
+ $name = $module->getModuleName();
+ $header = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
+ "=$name";
+ if ( $module->getModulePrefix() !== '' ) {
+ $header .= ' ' .
+ $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
+ }
+ }
+ $help['header'] .= Html::element( "h$level",
+ array( 'id' => $path, 'class' => 'apihelp-header' ),
+ $header
+ );
+ }
+
+ $links = array();
+ $any = false;
+ for ( $m = $module; $m !== null; $m = $m->getParent() ) {
+ $name = $m->getModuleName();
+ if ( $name === 'main_int' ) {
+ $name = 'main';
+ }
+
+ if ( count( $modules ) === 1 && $m === $modules[0] &&
+ !( !empty( $options['submodules'] ) && $m->getModuleManager() )
+ ) {
+ $link = Html::element( 'b', null, $name );
+ } else {
+ $link = SpecialPage::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
+ $link = Html::element( 'a',
+ array( 'href' => $link, 'class' => 'apihelp-linktrail' ),
+ $name
+ );
+ $any = true;
+ }
+ array_unshift( $links, $link );
+ }
+ if ( $any ) {
+ $help['header'] .= self::wrap(
+ $context->msg( 'parentheses' )
+ ->rawParams( $context->getLanguage()->pipeList( $links ) ),
+ 'apihelp-linktrail', 'div'
+ );
+ }
+
+ $flags = $module->getHelpFlags();
+ if ( $flags ) {
+ $help['flags'] .= Html::openElement( 'div',
+ array( 'class' => 'apihelp-block apihelp-flags' ) );
+ $msg = $context->msg( 'api-help-flags' );
+ if ( !$msg->isDisabled() ) {
+ $help['flags'] .= self::wrap(
+ $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
+ );
+ }
+ $help['flags'] .= Html::openElement( 'ul' );
+ foreach ( $flags as $flag ) {
+ $help['flags'] .= Html::rawElement( 'li', null,
+ self::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
+ );
+ }
+ $help['flags'] .= Html::closeElement( 'ul' );
+ $help['flags'] .= Html::closeElement( 'div' );
+ }
+
+ foreach ( $module->getFinalDescription() as $msg ) {
+ $msg->setContext( $context );
+ $help['description'] .= $msg->parseAsBlock();
+ }
+
+ $urls = $module->getHelpUrls();
+ if ( $urls ) {
+ $help['help-urls'] .= Html::openElement( 'div',
+ array( 'class' => 'apihelp-block apihelp-help-urls' )
+ );
+ $msg = $context->msg( 'api-help-help-urls' );
+ if ( !$msg->isDisabled() ) {
+ $help['help-urls'] .= self::wrap(
+ $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
+ );
+ }
+ if ( !is_array( $urls ) ) {
+ $urls = array( $urls );
+ }
+ $help['help-urls'] .= Html::openElement( 'ul' );
+ foreach ( $urls as $url ) {
+ $help['help-urls'] .= Html::rawElement( 'li', null,
+ Html::element( 'a', array( 'href' => $url ), $url )
+ );
+ }
+ $help['help-urls'] .= Html::closeElement( 'ul' );
+ $help['help-urls'] .= Html::closeElement( 'div' );
+ }
+
+ $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
+ $groups = array();
+ if ( $params ) {
+ $help['parameters'] .= Html::openElement( 'div',
+ array( 'class' => 'apihelp-block apihelp-parameters' )
+ );
+ $msg = $context->msg( 'api-help-parameters' );
+ if ( !$msg->isDisabled() ) {
+ $help['parameters'] .= self::wrap(
+ $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
+ );
+ }
+ $help['parameters'] .= Html::openElement( 'dl' );
+
+ $descriptions = $module->getFinalParamDescription();
+
+ foreach ( $params as $name => $settings ) {
+ if ( !is_array( $settings ) ) {
+ $settings = array( ApiBase::PARAM_DFLT => $settings );
+ }
+
+ $help['parameters'] .= Html::element( 'dt', null,
+ $module->encodeParamName( $name ) );
+
+ // Add description
+ $description = array();
+ if ( isset( $descriptions[$name] ) ) {
+ foreach ( $descriptions[$name] as $msg ) {
+ $msg->setContext( $context );
+ $description[] = $msg->parseAsBlock();
+ }
+ }
+
+ // Add usage info
+ $info = array();
+
+ // Required?
+ if ( !empty( $settings[ApiBase::PARAM_REQUIRED] ) ) {
+ $info[] = $context->msg( 'api-help-param-required' )->parse();
+ }
+
+ // Type documentation
+ if ( !isset( $settings[ApiBase::PARAM_TYPE] ) ) {
+ $dflt = isset( $settings[ApiBase::PARAM_DFLT] )
+ ? $settings[ApiBase::PARAM_DFLT]
+ : null;
+ if ( is_bool( $dflt ) ) {
+ $settings[ApiBase::PARAM_TYPE] = 'boolean';
+ } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
+ $settings[ApiBase::PARAM_TYPE] = 'string';
+ } elseif ( is_int( $dflt ) ) {
+ $settings[ApiBase::PARAM_TYPE] = 'integer';
+ }
+ }
+ if ( isset( $settings[ApiBase::PARAM_TYPE] ) ) {
+ $type = $settings[ApiBase::PARAM_TYPE];
+ $multi = !empty( $settings[ApiBase::PARAM_ISMULTI] );
+ $hintPipeSeparated = true;
+ $count = ApiBase::LIMIT_SML2 + 1;
+
+ if ( is_array( $type ) ) {
+ $count = count( $type );
+ $type = array_map( 'wfEscapeWikiText', $type );
+ $i = array_search( '', $type, true );
+ if ( $i === false ) {
+ $type = $context->getLanguage()->commaList( $type );
+ } else {
+ unset( $type[$i] );
+ $type = $context->msg( 'api-help-param-list-can-be-empty' )
+ ->numParams( count( $type ) )
+ ->params( $context->getLanguage()->commaList( $type ) )
+ ->parse();
+ }
+ $info[] = $context->msg( 'api-help-param-list' )
+ ->params( $multi ? 2 : 1 )
+ ->params( $type )
+ ->parse();
+ $hintPipeSeparated = false;
+ } else {
+ switch ( $type ) {
+ case 'submodule':
+ $groups[] = $name;
+ $submodules = $module->getModuleManager()->getNames( $name );
+ $count = count( $submodules );
+ sort( $submodules );
+ $prefix = $module->isMain()
+ ? '' : ( $module->getModulePath() . '+' );
+ $submodules = array_map( function ( $name ) use ( $prefix ) {
+ return "[[Special:ApiHelp/{$prefix}{$name}|{$name}]]";
+ }, $submodules );
+ $info[] = $context->msg( 'api-help-param-list' )
+ ->params( $multi ? 2 : 1 )
+ ->params( $context->getLanguage()->commaList( $submodules ) )
+ ->parse();
+ $hintPipeSeparated = false;
+ break;
+
+ case 'namespace':
+ $namespaces = MWNamespace::getValidNamespaces();
+ $count = count( $namespaces );
+ $info[] = $context->msg( 'api-help-param-list' )
+ ->params( $multi ? 2 : 1 )
+ ->params( $context->getLanguage()->commaList( $namespaces ) )
+ ->parse();
+ $hintPipeSeparated = false;
+ break;
+
+ case 'limit':
+ if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
+ $info[] = $context->msg( 'api-help-param-limit2' )
+ ->numParams( $settings[ApiBase::PARAM_MAX] )
+ ->numParams( $settings[ApiBase::PARAM_MAX2] )
+ ->parse();
+ } else {
+ $info[] = $context->msg( 'api-help-param-limit' )
+ ->numParams( $settings[ApiBase::PARAM_MAX] )
+ ->parse();
+ }
+ break;
+
+ case 'integer':
+ // Possible messages:
+ // api-help-param-integer-min,
+ // api-help-param-integer-max,
+ // api-help-param-integer-minmax
+ $suffix = '';
+ $min = $max = 0;
+ if ( isset( $settings[ApiBase::PARAM_MIN] ) ) {
+ $suffix .= 'min';
+ $min = $settings[ApiBase::PARAM_MIN];
+ }
+ if ( isset( $settings[ApiBase::PARAM_MAX] ) ) {
+ $suffix .= 'max';
+ $max = $settings[ApiBase::PARAM_MAX];
+ }
+ if ( $suffix !== '' ) {
+ $info[] =
+ $context->msg( "api-help-param-integer-$suffix" )
+ ->params( $multi ? 2 : 1 )
+ ->numParams( $min, $max )
+ ->parse();
+ }
+ break;
+
+ case 'upload':
+ $info[] = $context->msg( 'api-help-param-upload' )
+ ->parse();
+ break;
+ }
+ }
+
+ if ( $multi ) {
+ $extra = array();
+ if ( $hintPipeSeparated ) {
+ $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
+ }
+ if ( $count > ApiBase::LIMIT_SML1 ) {
+ $extra[] = $context->msg( 'api-help-param-multi-max' )
+ ->numParams( ApiBase::LIMIT_SML1, ApiBase::LIMIT_SML2 )
+ ->parse();
+ }
+ if ( $extra ) {
+ $info[] = join( ' ', $extra );
+ }
+ }
+ }
+
+ // Add default
+ $default = isset( $settings[ApiBase::PARAM_DFLT] )
+ ? $settings[ApiBase::PARAM_DFLT]
+ : null;
+ if ( $default === '' ) {
+ $info[] = $context->msg( 'api-help-param-default-empty' )
+ ->parse();
+ } elseif ( $default !== null && $default !== false ) {
+ $info[] = $context->msg( 'api-help-param-default' )
+ ->params( wfEscapeWikiText( $default ) )
+ ->parse();
+ }
+
+ if ( !$description && !$info ) {
+ $description[] = self::wrap(
+ $context->msg( 'api-help-param-no-description' ),
+ 'apihelp-empty'
+ );
+ }
+
+ // Add "deprecated" flag
+ if ( !empty( $settings[ApiBase::PARAM_DEPRECATED] ) ) {
+ $help['parameters'] .= Html::openElement( 'dd',
+ array( 'class' => 'info' ) );
+ $help['parameters'] .= self::wrap(
+ $context->msg( 'api-help-param-deprecated' ),
+ 'apihelp-deprecated', 'strong'
+ );
+ $help['parameters'] .= Html::closeElement( 'dd' );
+ }
+
+ if ( $description ) {
+ $help['parameters'] .= Html::openElement( 'dd',
+ array( 'class' => 'description' ) );
+ $help['parameters'] .= join( '', $description );
+ $help['parameters'] .= Html::closeElement( 'dd' );
+ }
+
+ foreach ( $info as $i ) {
+ $help['parameters'] .= Html::rawElement( 'dd', array( 'class' => 'info' ), $i );
+ }
+ }
+
+ $help['parameters'] .= Html::closeElement( 'dl' );
+ $help['parameters'] .= Html::closeElement( 'div' );
+ }
+
+ $examples = $module->getExamplesMessages();
+ if ( $examples ) {
+ $help['examples'] .= Html::openElement( 'div',
+ array( 'class' => 'apihelp-block apihelp-examples' ) );
+ $msg = $context->msg( 'api-help-examples' );
+ if ( !$msg->isDisabled() ) {
+ $help['examples'] .= self::wrap(
+ $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
+ );
+ }
+
+ $help['examples'] .= Html::openElement( 'dl' );
+ foreach ( $examples as $qs => $msg ) {
+ $msg = ApiBase::makeMessage( $msg, $context, array(
+ $module->getModulePrefix(),
+ $module->getModuleName(),
+ $module->getModulePath()
+ ) );
+
+ $link = wfAppendQuery( wfScript( 'api' ), $qs );
+ $help['examples'] .= Html::rawElement( 'dt', null, $msg->parse() );
+ $help['examples'] .= Html::rawElement( 'dd', null,
+ Html::element( 'a', array( 'href' => $link ), "api.php?$qs" )
+ );
+ }
+ $help['examples'] .= Html::closeElement( 'dl' );
+ $help['examples'] .= Html::closeElement( 'div' );
+ }
+
+ if ( $options['submodules'] && $module->getModuleManager() ) {
+ $manager = $module->getModuleManager();
+ $submodules = array();
+ foreach ( $groups as $group ) {
+ $names = $manager->getNames( $group );
+ sort( $names );
+ foreach ( $names as $name ) {
+ $submodules[] = $manager->getModule( $name );
+ }
+ }
+ $help['submodules'] .= self::getHelpInternal( $context, $submodules, array(
+ 'submodules' => $options['recursivesubmodules'],
+ 'headerlevel' => $level + 1,
+ 'noheader' => false,
+ ) + $options, $haveModules );
+ }
+
+ $module->modifyHelp( $help, $options );
- $msg2 = $module->makeHelpMsg();
- if ( $msg2 !== false ) {
- $msg .= $msg2;
+ wfRunHooks( 'APIHelpModifyOutput', array( $module, &$help, $options ) );
+
+ $out .= join( "\n", $help );
}
- return $msg;
+ return $out;
}
public function shouldCheckMaxlag() {
return false;
}
+ public function getCustomPrinter() {
+ $params = $this->extractRequestParams();
+ if ( $params['wrap'] ) {
+ return null;
+ }
+
+ $main = $this->getMain();
+ $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
+ return new ApiFormatRaw( $main, $errorPrinter );
+ }
+
public function getAllowedParams() {
return array(
'modules' => array(
- ApiBase::PARAM_ISMULTI => true
- ),
- 'querymodules' => array(
+ ApiBase::PARAM_DFLT => 'main',
ApiBase::PARAM_ISMULTI => true,
- ApiBase::PARAM_DEPRECATED => true
),
+ 'submodules' => false,
+ 'recursivesubmodules' => false,
+ 'wrap' => false,
+ 'toc' => false,
);
}
- public function getParamDescription() {
- return array(
- 'modules' => 'List of module names (value of the action= parameter). ' .
- 'Can specify submodules with a \'+\'',
- 'querymodules' => 'Use modules=query+value instead. List of query ' .
- 'module names (value of prop=, meta= or list= parameter)',
- );
- }
-
- public function getDescription() {
- return 'Display this help screen. Or the help screen for the specified module.';
- }
-
- public function getExamples() {
+ public function getExamplesMessages() {
return array(
- 'api.php?action=help' => 'Whole help page',
- 'api.php?action=help&modules=protect' => 'Module (action) help page',
- 'api.php?action=help&modules=query+categorymembers'
- => 'Help for the query/categorymembers module',
- 'api.php?action=help&modules=login|query+info'
- => 'Help for the login and query/info modules',
+ 'action=help' => 'apihelp-help-example-main',
+ 'action=help&recursivesubmodules=1' => 'apihelp-help-example-recursive',
+ 'action=help&modules=help' => 'apihelp-help-example-help',
+ 'action=help&modules=query+info|query+categorymembers' => 'apihelp-help-example-query',
);
}
*/
private static $mRights = array(
'writeapi' => array(
- 'msg' => 'Use of the write API',
+ 'msg' => 'right-writeapi',
'params' => array()
),
'apihighlimits' => array(
- 'msg' => 'Use higher limits in API queries (Slow queries: $1 results; Fast queries: $2 results). The limits for slow queries also apply to multivalue parameters.',
+ 'msg' => 'api-help-right-apihighlimits',
'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
)
);
}
}
+ $uselang = $this->getParameter( 'uselang' );
+ if ( $uselang === 'user' ) {
+ $uselang = $this->getUser()->getOption( 'language' );
+ $uselang = RequestContext::sanitizeLangCode( $uselang );
+ wfRunHooks( 'UserGetLanguageObject', array( $this->getUser(), &$uselang, $this ) );
+ }
+ $code = RequestContext::sanitizeLangCode( $uselang );
+ $this->getContext()->setLanguage( $code );
+ if ( !$this->mInternalMode ) {
+ global $wgLang;
+ $wgLang = RequestContext::getMain()->getLanguage();
+ }
+
$config = $this->getConfig();
$this->mModuleMgr = new ApiModuleManager( $this );
$this->mModuleMgr->addModules( self::$Modules, 'action' );
}
}
+ if ( $mode === 'public' && $this->getParameter( 'uselang' ) === 'user' ) {
+ // User language is used for i18n, so we don't want to publicly
+ // cache. Anons are ok, because if they have non-default language
+ // then there's an appropriate Vary header set by whatever set
+ // their non-default language.
+ wfDebug( __METHOD__ . ": downgrading cache mode 'public' to " .
+ "'anon-public-user-private' due to uselang=user\n" );
+ $mode = 'anon-public-user-private';
+ }
+
wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
$this->mCacheMode = $mode;
}
$config = $this->getConfig();
if ( $e instanceof UsageException ) {
- // User entered incorrect parameters - print usage screen
+ // User entered incorrect parameters - generate error response
$errMessage = $e->getMessageArray();
-
- // Only print the help message when this is for the developer, not runtime
- if ( $this->mPrinter->getWantsHelp() || $this->mAction == 'help' ) {
- ApiResult::setContent( $errMessage, $this->makeHelpMsg() );
- }
+ $link = wfExpandUrl( wfScript( 'api' ) );
+ ApiResult::setContent( $errMessage, "See $link for API usage" );
} else {
// Something is seriously wrong
if ( ( $e instanceof DBQueryError ) && !$config->get( 'ShowSQLErrors' ) ) {
$printer = $this->mPrinter;
$printer->profileIn();
- /**
- * If the help message is requested in the default (xmlfm) format,
- * tell the printer not to escape ampersands so that our links do
- * not break.
- */
- $isHelp = $isError || $this->mAction == 'help';
- $printer->setUnescapeAmps( $isHelp && $printer->getFormat() == 'XML' && $printer->getIsHtml() );
-
- $printer->initPrinter( $isHelp );
+ $printer->initPrinter( false );
$printer->execute();
$printer->closePrinter();
* @return array
*/
public function getAllowedParams() {
+ global $wgContLang;
+
return array(
- 'format' => array(
- ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
- ApiBase::PARAM_TYPE => 'submodule',
- ),
'action' => array(
ApiBase::PARAM_DFLT => 'help',
ApiBase::PARAM_TYPE => 'submodule',
),
+ 'format' => array(
+ ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
+ ApiBase::PARAM_TYPE => 'submodule',
+ ),
'maxlag' => array(
ApiBase::PARAM_TYPE => 'integer'
),
'servedby' => false,
'curtimestamp' => false,
'origin' => null,
+ 'uselang' => array(
+ ApiBase::PARAM_DFLT => $wgContLang->getCode(),
+ ),
);
}
+ /** @see ApiBase::getExamplesMessages() */
+ public function getExamplesMessages() {
+ return array(
+ 'action=help' => 'apihelp-help-example-main',
+ 'action=help&recursivesubmodules=1' => 'apihelp-help-example-recursive',
+ );
+ }
+
+ public function modifyHelp( array &$help, array $options ) {
+ // Wish PHP had an "array_insert_before". Instead, we have to manually
+ // reindex the array to get 'permissions' in the right place.
+ $oldHelp = $help;
+ $help = array();
+ foreach ( $oldHelp as $k => $v ) {
+ if ( $k === 'submodules' ) {
+ $help['permissions'] = '';
+ }
+ $help[$k] = $v;
+ }
+ $help['credits'] = '';
+
+ // Fill 'permissions'
+ $help['permissions'] .= Html::openElement( 'div',
+ array( 'class' => 'apihelp-block apihelp-permissions' ) );
+ $m = $this->msg( 'api-help-permissions' );
+ if ( !$m->isDisabled() ) {
+ $help['permissions'] .= Html::rawElement( 'div', array( 'class' => 'apihelp-block-head' ),
+ $m->numParams( count( self::$mRights ) )->parse()
+ );
+ }
+ $help['permissions'] .= Html::openElement( 'dl' );
+ foreach ( self::$mRights as $right => $rightMsg ) {
+ $help['permissions'] .= Html::element( 'dt', null, $right );
+
+ $rightMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )->parse();
+ $help['permissions'] .= Html::rawElement( 'dd', null, $rightMsg );
+
+ $groups = array_map( function ( $group ) {
+ return $group == '*' ? 'all' : $group;
+ }, User::getGroupsWithPermission( $right ) );
+
+ $help['permissions'] .= Html::rawElement( 'dd', null,
+ $this->msg( 'api-help-permissions-granted-to' )
+ ->numParams( count( $groups ) )
+ ->params( $this->getLanguage()->commaList( $groups ) )
+ ->parse()
+ );
+ }
+ $help['permissions'] .= Html::closeElement( 'dl' );
+ $help['permissions'] .= Html::closeElement( 'div' );
+
+ // Fill 'credits', if applicable
+ if ( empty( $options['nolead'] ) ) {
+ $help['credits'] .= Html::element( 'h' . min( 6, $options['headerlevel'] + 1 ),
+ array( 'id' => '+credits', 'class' => 'apihelp-header' ),
+ $this->msg( 'api-credits-header' )->parse()
+ );
+ $help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();
+ }
+ }
+
+ private $mCanApiHighLimits = null;
+
/**
- * See ApiBase for description.
- *
+ * Check whether the current user is allowed to use high limits
+ * @return bool
+ */
+ public function canApiHighLimits() {
+ if ( !isset( $this->mCanApiHighLimits ) ) {
+ $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
+ }
+
+ return $this->mCanApiHighLimits;
+ }
+
+ /**
+ * Overrides to return this instance's module manager.
+ * @return ApiModuleManager
+ */
+ public function getModuleManager() {
+ return $this->mModuleMgr;
+ }
+
+ /************************************************************************//**
+ * @name Deprecated
+ * @{
+ */
+
+ /**
+ * @deprecated since 1.25
* @return array
*/
public function getParamDescription() {
}
/**
- * See ApiBase for description.
- *
+ * @deprecated since 1.25
* @return array
*/
public function getDescription() {
);
}
- /**
- * Returns an array of strings with credits for the API
- * @return array
- */
- protected function getCredits() {
- return array(
- 'API developers:',
- ' Roan Kattouw (lead developer Sep 2007-2009)',
- ' Victor Vasiliev',
- ' Bryan Tong Minh',
- ' Sam Reed',
- ' Yuri Astrakhan (creator, lead developer Sep 2006-Sep 2007, 2012-2013)',
- ' Brad Jorsch (lead developer 2013-now)',
- '',
- 'Please send your comments, suggestions and questions to mediawiki-api@lists.wikimedia.org',
- 'or file a bug report at https://bugzilla.wikimedia.org/'
- );
- }
-
/**
* Sets whether the pretty-printer should format *bold* and $italics$
*
+ * @deprecated since 1.25
* @param bool $help
*/
public function setHelp( $help = true ) {
+ wfDeprecated( __METHOD__, '1.25' );
$this->mPrinter->setHelp( $help );
}
/**
* Override the parent to generate help messages for all available modules.
*
+ * @deprecated since 1.25
* @return string
*/
public function makeHelpMsg() {
+ wfDeprecated( __METHOD__, '1.25' );
global $wgMemc;
$this->setHelp();
// Get help text from cache if present
}
/**
+ * @deprecated since 1.25
* @return mixed|string
*/
public function reallyMakeHelpMsg() {
+ wfDeprecated( __METHOD__, '1.25' );
$this->setHelp();
// Use parent to make default message for the main module
$msg .= "\n$astriks Permissions $astriks\n\n";
foreach ( self::$mRights as $right => $rightMsg ) {
+ $rightsMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )
+ ->useDatabase( false )
+ ->inLanguage( 'en' )
+ ->text();
$groups = User::getGroupsWithPermission( $right );
- $msg .= "* " . $right . " *\n " . wfMsgReplaceArgs( $rightMsg['msg'], $rightMsg['params'] ) .
+ $msg .= "* " . $right . " *\n $rightsMsg" .
"\nGranted to:\n " . str_replace( '*', 'all', implode( ', ', $groups ) ) . "\n\n";
}
$msg .= "\n";
}
- $msg .= "\n*** Credits: ***\n " . implode( "\n ", $this->getCredits() ) . "\n";
+ $credits = $this->msg( 'api-credits' )->useDatabase( 'false' )->inLanguage( 'en' )->text();
+ $credits = str_replace( "\n", "\n ", $credits );
+ $msg .= "\n*** Credits: ***\n $credits\n";
return $msg;
}
/**
+ * @deprecated since 1.25
* @param ApiBase $module
* @param string $paramName What type of request is this? e.g. action,
* query, list, prop, meta, format
* @return string
*/
public static function makeHelpMsgHeader( $module, $paramName ) {
+ wfDeprecated( __METHOD__, '1.25' );
$modulePrefix = $module->getModulePrefix();
if ( strval( $modulePrefix ) !== '' ) {
$modulePrefix = "($modulePrefix) ";
return "* $paramName={$module->getModuleName()} $modulePrefix*";
}
- private $mCanApiHighLimits = null;
-
- /**
- * Check whether the current user is allowed to use high limits
- * @return bool
- */
- public function canApiHighLimits() {
- if ( !isset( $this->mCanApiHighLimits ) ) {
- $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
- }
-
- return $this->mCanApiHighLimits;
- }
-
/**
* Check whether the user wants us to show version information in the API help
* @return bool
return false;
}
- /**
- * Overrides to return this instance's module manager.
- * @return ApiModuleManager
- */
- public function getModuleManager() {
- return $this->mModuleMgr;
- }
-
/**
* Add or overwrite a module in this ApiMain instance. Intended for use by extending
* classes who wish to add their own modules to their lexicon or override the
public function getFormats() {
return $this->getModuleManager()->getNamesWithClasses( 'format' );
}
+
+ /**@}*/
+
}
/**
* This exception will be thrown when dieUsage is called to stop module execution.
- * The exception handling code will print a help screen explaining how this API may be used.
*
* @ingroup API
*/
return "{$this->getCodeString()}: {$this->getMessage()}";
}
}
+
+/**
+ * For really cool vim folding this needs to be at the end:
+ * vim: foldmarker=@{,@} foldmethod=marker
+ */
*/
class ApiParamInfo extends ApiBase {
- /**
- * @var ApiQuery
- */
- protected $queryObj;
+ private $helpFormat;
+ private $context;
public function __construct( ApiMain $main, $action ) {
parent::__construct( $main, $action );
- $this->queryObj = new ApiQuery( $this->getMain(), 'query' );
}
public function execute() {
+ global $wgContLang;
+
// Get parameters
$params = $this->extractRequestParams();
- $resultObj = $this->getResult();
+
+ $this->helpFormat = $params['helpformat'];
+ $this->context = new RequestContext;
+ $this->context->setUser( new User ); // anon to avoid caching issues
+ $this->context->setLanguage( $this->getMain()->getLanguage() );
+
+ if ( is_array( $params['modules'] ) ) {
+ $modules = $params['modules'];
+ } else {
+ $modules = array();
+ }
+
+ if ( is_array( $params['querymodules'] ) ) {
+ $this->logFeatureUsage( 'action=paraminfo&querymodules' );
+ $queryModules = $params['querymodules'];
+ foreach ( $queryModules as $m ) {
+ $modules[] = 'query+' . $m;
+ }
+ } else {
+ $queryModules = array();
+ }
+
+ if ( is_array( $params['formatmodules'] ) ) {
+ $this->logFeatureUsage( 'action=paraminfo&formatmodules' );
+ $formatModules = $params['formatmodules'];
+ foreach ( $formatModules as $m ) {
+ $modules[] = $m;
+ }
+ } else {
+ $formatModules = array();
+ }
$res = array();
- $this->addModulesInfo( $params, 'modules', $res, $resultObj );
+ foreach ( $modules as $m ) {
+ try {
+ $module = $this->getModuleFromPath( $m );
+ } catch ( UsageException $ex ) {
+ $this->setWarning( $ex->getMessage() );
+ continue;
+ }
+ $key = 'modules';
+
+ // Back compat
+ $isBCQuery = false;
+ if ( $module->getParent() && $module->getParent()->getModuleName() == 'query' &&
+ in_array( $module->getModuleName(), $queryModules )
+ ) {
+ $isBCQuery = true;
+ $key = 'querymodules';
+ }
+ if ( in_array( $module->getModuleName(), $formatModules ) ) {
+ $key = 'formatmodules';
+ }
+
+ $item = $this->getModuleInfo( $module );
+ if ( $isBCQuery ) {
+ $item['querytype'] = $item['group'];
+ }
+ $res[$key][] = $item;
+ }
+
+ $result = $this->getResult();
+ $result->addValue( array( $this->getModuleName() ), 'helpformat', $this->helpFormat );
- $this->addModulesInfo( $params, 'querymodules', $res, $resultObj );
+ foreach ( $res as $key => $stuff ) {
+ $result->setIndexedTagName( $res[$key], 'module' );
+ }
if ( $params['mainmodule'] ) {
- $res['mainmodule'] = $this->getClassInfo( $this->getMain() );
+ $this->logFeatureUsage( 'action=paraminfo&mainmodule' );
+ $res['mainmodule'] = $this->getModuleInfo( $this->getMain() );
}
if ( $params['pagesetmodule'] ) {
- $pageSet = new ApiPageSet( $this->queryObj );
- $res['pagesetmodule'] = $this->getClassInfo( $pageSet );
+ $this->logFeatureUsage( 'action=paraminfo&pagesetmodule' );
+ $pageSet = new ApiPageSet( $this->getMain()->getModuleManager()->getModule( 'query' ) );
+ $res['pagesetmodule'] = $this->getModuleInfo( $pageSet );
+ unset( $res['pagesetmodule']['name'] );
+ unset( $res['pagesetmodule']['path'] );
+ unset( $res['pagesetmodule']['group'] );
}
- $this->addModulesInfo( $params, 'formatmodules', $res, $resultObj );
-
- $resultObj->addValue( null, $this->getModuleName(), $res );
+ $result->addValue( null, $this->getModuleName(), $res );
}
/**
- * If the type is requested in parameters, adds a section to res with module info.
- * @param array $params User parameters array
- * @param string $type Parameter name
- * @param array $res Store results in this array
- * @param ApiResult $resultObj Results object to set indexed tag.
+ * @param array $res Result array
+ * @param string $key Result key
+ * @param Message[] $msgs
*/
- private function addModulesInfo( $params, $type, &$res, $resultObj ) {
- if ( !is_array( $params[$type] ) ) {
- return;
- }
- $isQuery = ( $type === 'querymodules' );
- if ( $isQuery ) {
- $mgr = $this->queryObj->getModuleManager();
- } else {
- $mgr = $this->getMain()->getModuleManager();
- }
- $res[$type] = array();
- foreach ( $params[$type] as $mod ) {
- if ( !$mgr->isDefined( $mod ) ) {
- $res[$type][] = array( 'name' => $mod, 'missing' => '' );
- continue;
- }
- $obj = $mgr->getModule( $mod );
- $item = $this->getClassInfo( $obj );
- $item['name'] = $mod;
- if ( $isQuery ) {
- $item['querytype'] = $mgr->getModuleGroup( $mod );
- }
- $res[$type][] = $item;
+ protected function formatHelpMessages( array &$res, $key, array $msgs ) {
+ switch ( $this->helpFormat ) {
+ case 'none':
+ break;
+
+ case 'wikitext':
+ $ret = array();
+ foreach ( $msgs as $m ) {
+ $ret[] = $m->setContext( $this->context )->text();
+ }
+ $res[$key] = join( "\n\n", $ret );
+ break;
+
+ case 'html':
+ $ret = array();
+ foreach ( $msgs as $m ) {
+ $ret[] = $m->setContext( $this->context )->parseAsBlock();
+ }
+ $res[$key] = join( "\n", $ret );
+ break;
+
+ case 'raw':
+ $res[$key] = array();
+ foreach ( $msgs as $m ) {
+ $res[$key][] = array(
+ 'key' => $m->getKey(),
+ 'params' => $m->getParams(),
+ );
+ }
+ $this->getResult()->setIndexedTagName( $res[$key], 'msg' );
+ break;
}
- $resultObj->setIndexedTagName( $res[$type], 'module' );
}
/**
- * @param ApiBase $obj
+ * @param ApiBase $module
* @return ApiResult
*/
- private function getClassInfo( $obj ) {
+ private function getModuleInfo( $module ) {
$result = $this->getResult();
- $retval['classname'] = get_class( $obj );
- $retval['description'] = implode( "\n", (array)$obj->getFinalDescription() );
- $retval['examples'] = '';
-
- // version is deprecated since 1.21, but needs to be returned for v1
- $retval['version'] = '';
- $retval['prefix'] = $obj->getModulePrefix();
-
- if ( $obj->isReadMode() ) {
- $retval['readrights'] = '';
- }
- if ( $obj->isWriteMode() ) {
- $retval['writerights'] = '';
- }
- if ( $obj->mustBePosted() ) {
- $retval['mustbeposted'] = '';
- }
- if ( $obj instanceof ApiQueryGeneratorBase ) {
- $retval['generator'] = '';
+ $ret = array();
+
+ $ret['name'] = $module->getModuleName();
+ $ret['classname'] = get_class( $module );
+ $ret['path'] = $module->getModulePath();
+ if ( !$module->isMain() ) {
+ $ret['group'] = $module->getParent()->getModuleManager()->getModuleGroup(
+ $module->getModuleName()
+ );
}
+ $ret['prefix'] = $module->getModulePrefix();
- $allowedParams = $obj->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
- if ( !is_array( $allowedParams ) ) {
- return $retval;
- }
+ $this->formatHelpMessages( $ret, 'description', $module->getFinalDescription() );
- $retval['helpurls'] = (array)$obj->getHelpUrls();
- if ( isset( $retval['helpurls'][0] ) && $retval['helpurls'][0] === false ) {
- $retval['helpurls'] = array();
+ foreach ( $module->getHelpFlags() as $flag ) {
+ $ret[$flag] = '';
}
- $result->setIndexedTagName( $retval['helpurls'], 'helpurl' );
- $examples = $obj->getExamples();
- $retval['allexamples'] = array();
- if ( $examples !== false ) {
- if ( is_string( $examples ) ) {
- $examples = array( $examples );
- }
- foreach ( $examples as $k => $v ) {
- if ( strlen( $retval['examples'] ) ) {
- $retval['examples'] .= ' ';
- }
- $item = array();
- if ( is_numeric( $k ) ) {
- $retval['examples'] .= $v;
- ApiResult::setContent( $item, $v );
- } else {
- if ( !is_array( $v ) ) {
- $item['description'] = $v;
+ $ret['helpurls'] = (array)$module->getHelpUrls();
+ if ( isset( $ret['helpurls'][0] ) && $ret['helpurls'][0] === false ) {
+ $ret['helpurls'] = array();
+ }
+ $result->setIndexedTagName( $ret['helpurls'], 'helpurl' );
+
+ if ( $this->helpFormat !== 'none' ) {
+ $ret['examples'] = array();
+ $examples = $module->getExamplesMessages();
+ foreach ( $examples as $qs => $msg ) {
+ $item = array(
+ 'query' => $qs
+ );
+ $msg = ApiBase::makeMessage( $msg, $this->context, array(
+ $module->getModulePrefix(),
+ $module->getModuleName(),
+ $module->getModulePath()
+ ) );
+ $this->formatHelpMessages( $item, 'description', array( $msg ) );
+ if ( isset( $item['description'] ) ) {
+ if ( is_array( $item['description'] ) ) {
+ $item['description'] = $item['description'][0];
} else {
- $item['description'] = implode( $v, "\n" );
+ $result->setSubelements( $item, 'description' );
}
- $retval['examples'] .= $item['description'] . ' ' . $k;
- ApiResult::setContent( $item, $k );
}
- $retval['allexamples'][] = $item;
+ $ret['examples'][] = $item;
}
+ $result->setIndexedTagName( $ret['examples'], 'example' );
}
- $result->setIndexedTagName( $retval['allexamples'], 'example' );
-
- $retval['parameters'] = array();
- $paramDesc = $obj->getFinalParamDescription();
- foreach ( $allowedParams as $n => $p ) {
- $a = array( 'name' => $n );
- if ( isset( $paramDesc[$n] ) ) {
- $a['description'] = implode( "\n", (array)$paramDesc[$n] );
+
+ $ret['parameters'] = array();
+ $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
+ $paramDesc = $module->getFinalParamDescription();
+ foreach ( $params as $name => $settings ) {
+ if ( !is_array( $settings ) ) {
+ $settings = array( ApiBase::PARAM_DFLT => $settings );
}
- //handle shorthand
- if ( !is_array( $p ) ) {
- $p = array(
- ApiBase::PARAM_DFLT => $p,
- );
+ $item = array(
+ 'name' => $name
+ );
+ if ( isset( $paramDesc[$name] ) ) {
+ $this->formatHelpMessages( $item, 'description', $paramDesc[$name] );
}
- //handle missing type
- if ( !isset( $p[ApiBase::PARAM_TYPE] ) ) {
- $dflt = isset( $p[ApiBase::PARAM_DFLT] ) ? $p[ApiBase::PARAM_DFLT] : null;
- if ( is_bool( $dflt ) ) {
- $p[ApiBase::PARAM_TYPE] = 'boolean';
- } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
- $p[ApiBase::PARAM_TYPE] = 'string';
- } elseif ( is_int( $dflt ) ) {
- $p[ApiBase::PARAM_TYPE] = 'integer';
- }
+ if ( !empty( $settings[ApiBase::PARAM_REQUIRED] ) ) {
+ $item['required'] = '';
}
- if ( isset( $p[ApiBase::PARAM_DEPRECATED] ) && $p[ApiBase::PARAM_DEPRECATED] ) {
- $a['deprecated'] = '';
+ if ( !empty( $settings[ApiBase::PARAM_DEPRECATED] ) ) {
+ $item['deprecated'] = '';
}
- if ( isset( $p[ApiBase::PARAM_REQUIRED] ) && $p[ApiBase::PARAM_REQUIRED] ) {
- $a['required'] = '';
+
+ if ( $name === 'token' && $module->needsToken() ) {
+ $item['tokentype'] = $module->needsToken();
}
- if ( $n === 'token' && $obj->needsToken() ) {
- $a['tokentype'] = $obj->needsToken();
+ if ( !isset( $settings[ApiBase::PARAM_TYPE] ) ) {
+ $dflt = isset( $settings[ApiBase::PARAM_DFLT] )
+ ? $settings[ApiBase::PARAM_DFLT]
+ : null;
+ if ( is_bool( $dflt ) ) {
+ $settings[ApiBase::PARAM_TYPE] = 'boolean';
+ } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
+ $settings[ApiBase::PARAM_TYPE] = 'string';
+ } elseif ( is_int( $dflt ) ) {
+ $settings[ApiBase::PARAM_TYPE] = 'integer';
+ }
}
- if ( isset( $p[ApiBase::PARAM_DFLT] ) ) {
- $type = $p[ApiBase::PARAM_TYPE];
- if ( $type === 'boolean' ) {
- $a['default'] = ( $p[ApiBase::PARAM_DFLT] ? 'true' : 'false' );
- } elseif ( $type === 'string' ) {
- $a['default'] = strval( $p[ApiBase::PARAM_DFLT] );
- } elseif ( $type === 'integer' ) {
- $a['default'] = intval( $p[ApiBase::PARAM_DFLT] );
- } else {
- $a['default'] = $p[ApiBase::PARAM_DFLT];
+ if ( isset( $settings[ApiBase::PARAM_DFLT] ) ) {
+ switch ( $settings[ApiBase::PARAM_TYPE] ) {
+ case 'boolean':
+ $item['default'] = ( $settings[ApiBase::PARAM_DFLT] ? 'true' : 'false' );
+ break;
+ case 'string':
+ $item['default'] = strval( $settings[ApiBase::PARAM_DFLT] );
+ break;
+ case 'integer':
+ $item['default'] = intval( $settings[ApiBase::PARAM_DFLT] );
+ break;
+ default:
+ $item['default'] = $settings[ApiBase::PARAM_DFLT];
+ break;
}
}
- if ( isset( $p[ApiBase::PARAM_ISMULTI] ) && $p[ApiBase::PARAM_ISMULTI] ) {
- $a['multi'] = '';
- $a['limit'] = $this->getMain()->canApiHighLimits() ?
+
+ if ( !empty( $settings[ApiBase::PARAM_ISMULTI] ) ) {
+ $item['multi'] = '';
+ $item['limit'] = $this->getMain()->canApiHighLimits() ?
ApiBase::LIMIT_SML2 :
ApiBase::LIMIT_SML1;
- $a['lowlimit'] = ApiBase::LIMIT_SML1;
- $a['highlimit'] = ApiBase::LIMIT_SML2;
+ $item['lowlimit'] = ApiBase::LIMIT_SML1;
+ $item['highlimit'] = ApiBase::LIMIT_SML2;
}
- if ( isset( $p[ApiBase::PARAM_ALLOW_DUPLICATES] ) && $p[ApiBase::PARAM_ALLOW_DUPLICATES] ) {
- $a['allowsduplicates'] = '';
+ if ( !empty( $settings[ApiBase::PARAM_ALLOW_DUPLICATES] ) ) {
+ $item['allowsduplicates'] = '';
}
- if ( isset( $p[ApiBase::PARAM_TYPE] ) ) {
- if ( $p[ApiBase::PARAM_TYPE] === 'submodule' ) {
- $a['type'] = $obj->getModuleManager()->getNames( $n );
- sort( $a['type'] );
- $a['submodules'] = '';
+ if ( isset( $settings[ApiBase::PARAM_TYPE] ) ) {
+ if ( $settings[ApiBase::PARAM_TYPE] === 'submodule' ) {
+ $item['type'] = $module->getModuleManager()->getNames( $name );
+ sort( $item['type'] );
+ $item['submodules'] = '';
} else {
- $a['type'] = $p[ApiBase::PARAM_TYPE];
+ $item['type'] = $settings[ApiBase::PARAM_TYPE];
}
- if ( is_array( $a['type'] ) ) {
+ if ( is_array( $item['type'] ) ) {
// To prevent sparse arrays from being serialized to JSON as objects
- $a['type'] = array_values( $a['type'] );
- $result->setIndexedTagName( $a['type'], 't' );
+ $item['type'] = array_values( $item['type'] );
+ $result->setIndexedTagName( $item['type'], 't' );
}
}
- if ( isset( $p[ApiBase::PARAM_MAX] ) ) {
- $a['max'] = $p[ApiBase::PARAM_MAX];
+ if ( isset( $settings[ApiBase::PARAM_MAX] ) ) {
+ $item['max'] = $settings[ApiBase::PARAM_MAX];
}
- if ( isset( $p[ApiBase::PARAM_MAX2] ) ) {
- $a['highmax'] = $p[ApiBase::PARAM_MAX2];
+ if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
+ $item['highmax'] = $settings[ApiBase::PARAM_MAX2];
}
- if ( isset( $p[ApiBase::PARAM_MIN] ) ) {
- $a['min'] = $p[ApiBase::PARAM_MIN];
+ if ( isset( $settings[ApiBase::PARAM_MIN] ) ) {
+ $item['min'] = $settings[ApiBase::PARAM_MIN];
}
- $retval['parameters'][] = $a;
+ $ret['parameters'][] = $item;
}
- $result->setIndexedTagName( $retval['parameters'], 'param' );
+ $result->setIndexedTagName( $ret['parameters'], 'param' );
- return $retval;
+ return $ret;
}
public function isReadMode() {
}
public function getAllowedParams() {
- $modules = $this->getMain()->getModuleManager()->getNames( 'action' );
- sort( $modules );
- $querymodules = $this->queryObj->getModuleManager()->getNames();
+ // back compat
+ $querymodules = $this->getMain()->getModuleManager()
+ ->getModule( 'query' )->getModuleManager()->getNames();
sort( $querymodules );
$formatmodules = $this->getMain()->getModuleManager()->getNames( 'format' );
sort( $formatmodules );
return array(
'modules' => array(
ApiBase::PARAM_ISMULTI => true,
- ApiBase::PARAM_TYPE => $modules,
),
+ 'helpformat' => array(
+ ApiBase::PARAM_DFLT => 'none',
+ ApiBase::PARAM_TYPE => array( 'html', 'wikitext', 'raw', 'none' ),
+ ),
+
'querymodules' => array(
+ ApiBase::PARAM_DEPRECATED => true,
ApiBase::PARAM_ISMULTI => true,
ApiBase::PARAM_TYPE => $querymodules,
),
- 'mainmodule' => false,
- 'pagesetmodule' => false,
+ 'mainmodule' => array(
+ ApiBase::PARAM_DEPRECATED => true,
+ ),
+ 'pagesetmodule' => array(
+ ApiBase::PARAM_DEPRECATED => true,
+ ),
'formatmodules' => array(
+ ApiBase::PARAM_DEPRECATED => true,
ApiBase::PARAM_ISMULTI => true,
ApiBase::PARAM_TYPE => $formatmodules,
)
public function getParamDescription() {
return array(
- 'modules' => 'List of module names (value of the action= parameter)',
+ 'modules' => 'List of module names (values of the action= and format= parameters, or "main"). Can specify submodules with a \'+\'',
+ 'helpformat' => 'Format of help strings',
+
'querymodules' => 'List of query module names (value of prop=, meta= or list= parameter)',
'mainmodule' => 'Get information about the main (top-level) module as well',
'pagesetmodule' => 'Get information about the pageset module ' .
public function getExamples() {
return array(
- 'api.php?action=paraminfo&modules=parse&querymodules=allpages|siteinfo'
+ 'api.php?action=paraminfo&modules=parse|phpfm|query+allpages|query+siteinfo'
);
}
// TODO: Does this still need $wgTitle?
global $wgParser, $wgTitle;
- // Currently unnecessary, code to act as a safeguard against any change
- // in current behavior of uselang
- $oldLang = null;
- if ( isset( $params['uselang'] )
- && $params['uselang'] != $this->getContext()->getLanguage()->getCode()
- ) {
- $oldLang = $this->getContext()->getLanguage(); // Backup language
- $this->getContext()->setLanguage( Language::factory( $params['uselang'] ) );
- }
-
$redirValues = null;
// Return result
);
$this->setIndexedTagNames( $result_array, $result_mapping );
$result->addValue( null, $this->getModuleName(), $result_array );
-
- if ( !is_null( $oldLang ) ) {
- $this->getContext()->setLanguage( $oldLang ); // Reset language to $oldLang
- }
}
/**
$entry['lang'] = $bits[0];
if ( $title ) {
$entry['url'] = wfExpandUrl( $title->getFullURL(), PROTO_CURRENT );
- // localised language name in user language (maybe set by uselang=)
+ // localised language name in 'uselang' language
$entry['langname'] = Language::fetchLanguageName(
$title->getInterwiki(),
$this->getLanguage()->getCode()
'pst' => false,
'onlypst' => false,
'effectivelanglinks' => false,
- 'uselang' => null,
'section' => null,
'disablepp' => false,
'disableeditsection' => false,
'Returns the same wikitext, after a PST has been applied.',
"Only valid when used with {$p}text",
),
- 'uselang' => 'Which language to parse the request in',
'section' => 'Only retrieve the content of this section number',
'disablepp' => 'Disable the PP Report from the parser output',
'disableeditsection' => 'Disable edit section links from the parser output',
/**
* Override the parent to generate help messages for all available query modules.
+ * @deprecated since 1.25
* @return string
*/
public function makeHelpMsg() {
+ wfDeprecated( __METHOD__, '1.25' );
// Use parent to make default message for the query module
$msg = parent::makeHelpMsg();
/**
* For all modules of a given group, generate help messages and join them together
+ * @deprecated since 1.25
* @param string $group Module group
* @return string
*/
return $this->mQueryModule;
}
+ /**
+ * @see ApiBase::getParent()
+ */
+ public function getParent() {
+ return $this->getQuery();
+ }
+
/**
* Get the Query database connection (read-only)
* @return DatabaseBase
}
}
+ /**
+ * @see ApiBase::getHelpFlags()
+ *
+ * Corresponding messages: api-help-flag-generator
+ */
+ protected function getHelpFlags() {
+ $flags = parent::getHelpFlags();
+ $flags[] = 'generator';
+ return $flags;
+ }
+
/**
* Execute this module as a generator
* @param ApiPageSet $resultPageSet All output should be appended to this object
return $types;
}
+ public function isDeprecated() {
+ return true;
+ }
+
public function getAllowedParams() {
return array(
'type' => array(
$res = array( 'title' => $title->getPrefixedText() );
- // Currently unnecessary, code to act as a safeguard against any change
- // in current behavior of uselang.
- // Copy from ApiParse
- $oldLang = null;
- if ( isset( $params['uselang'] ) &&
- $params['uselang'] != $this->getContext()->getLanguage()->getCode()
- ) {
- $oldLang = $this->getContext()->getLanguage(); // Backup language
- $this->getContext()->setLanguage( Language::factory( $params['uselang'] ) );
- }
-
if ( $params['unwatch'] ) {
$status = UnwatchAction::doUnwatch( $title, $user );
if ( $status->isOK() ) {
}
}
- if ( !is_null( $oldLang ) ) {
- $this->getContext()->setLanguage( $oldLang ); // Reset language to $oldLang
- }
-
if ( !$status->isOK() ) {
if ( $compatibilityMode ) {
$this->dieStatus( $status );
ApiBase::PARAM_DEPRECATED => true
),
'unwatch' => false,
- 'uselang' => null,
'continue' => '',
);
if ( $flags ) {
return $psModule->getParamDescription() + array(
'title' => 'The page to (un)watch. use titles instead',
'unwatch' => 'If set the page will be unwatched rather than watched',
- 'uselang' => 'Language to show the message in',
'continue' => 'When more results are available, use this to continue',
);
}
--- /dev/null
+{
+ "@metadata": {
+ "authors": [
+ "Anomie"
+ ]
+ },
+
+ "apihelp-main-description": "<div class=\"hlist plainlinks api-main-links\">\n* [https://www.mediawiki.org/wiki/API:Main_page Documentation]\n* [https://www.mediawiki.org/wiki/API:FAQ FAQ]\n* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-api Mailing list]\n* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce API Announcements]\n* [https://bugzilla.wikimedia.org/buglist.cgi?component=API&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&order=bugs.delta_ts Bugs & requests]\n</div>\n<strong>Status:</strong> All features shown on this page should be working, but the API is still in active development, and may change at any time. Subscribe to [https://lists.wikimedia.org/pipermail/mediawiki-api-announce/ the mediawiki-api-announce mailing list] for notice of updates.\n\n<strong>Erroneous requests:</strong> When erroneous requests are sent to the API, a HTTP header will be sent with the key \"MediaWiki-API-Error\" and then both the value of the header and the error code sent back will be set to the same value. For more information see https://www.mediawiki.org/wiki/API:Errors_and_warnings.",
+ "apihelp-main-param-action": "Which action to perform.",
+ "apihelp-main-param-format": "The format of the output.",
+ "apihelp-main-param-maxlag": "Maximum lag can be used when MediaWiki is installed on a database replicated cluster. To save actions causing any more site replication lag, this parameter can make the client wait until the replication lag is less than the specified value. In case of excessive lag, error code \"maxlag\" is returned with a message like \"Waiting for $host: $lag seconds lagged\".<br />See https://www.mediawiki.org/wiki/Manual:Maxlag_parameter for more information.",
+ "apihelp-main-param-smaxage": "Set the s-maxage header to this many seconds. Errors are never cached.",
+ "apihelp-main-param-maxage": "Set the max-age header to this many seconds. Errors are never cached.",
+ "apihelp-main-param-assert": "Verify the user is logged in if set to \"user\", or has the bot userright if \"bot\".",
+ "apihelp-main-param-requestid": "Any value given here will be included in the response. May be used to distinguish requests.",
+ "apihelp-main-param-servedby": "Include the hostname that served the request in the results.",
+ "apihelp-main-param-curtimestamp": "Include the current timestamp in the result.",
+ "apihelp-main-param-origin": "When accessing the API using a cross-domain AJAX request (CORS), set this to the originating domain. This must be included in any pre-flight request, and therefore must be part of the request URI (not the POST body). This must match one of the origins in the Origin: header exactly, so it has to be set to something like http://en.wikipedia.org or https://meta.wikimedia.org. If this parameter does not match the Origin: header, a 403 response will be returned. If this parameter matches the Origin: header and the origin is whitelisted, an Access-Control-Allow-Origin header will be set.",
+ "apihelp-main-param-uselang": "Language to use for message translations. A list of codes may be fetched from [[Special:ApiHelp/query+siteinfo|action=query&meta=siteinfo&siprop=languages]], or specify \"user\" to use the current user's language preference.",
+
+ "apihelp-help-description": "Display help for the specified modules.",
+ "apihelp-help-param-modules": "Modules to display help for (values of the action= and format= parameters, or \"main\"). Can specify submodules with a \"+\".",
+ "apihelp-help-param-submodules": "Include help for submodules of the named module.",
+ "apihelp-help-param-recursivesubmodules": "Include help for submodules recursively.",
+ "apihelp-help-param-helpformat": "Format of the help output.",
+ "apihelp-help-param-wrap": "Wrap the output in a standard API response structure.",
+ "apihelp-help-param-toc": "Include a table of contents in the HTML output.",
+ "apihelp-help-example-main": "Help for the main module",
+ "apihelp-help-example-recursive": "All help in one page",
+ "apihelp-help-example-help": "Help for the help module itself",
+ "apihelp-help-example-query": "Help for two query submodules",
+
+ "api-help-title": "MediaWiki API help",
+ "api-help-lead": "This is an auto-generated MediaWiki API documentation page.\n\nDocumentation and examples: https://www.mediawiki.org/wiki/API",
+ "api-help-main-header": "Main module",
+ "api-help-fallback-description": "$1",
+ "api-help-fallback-parameter": "$1",
+ "api-help-fallback-example": "$1",
+ "api-help-flags": "",
+ "api-help-flag-deprecated": "This module is deprecated.",
+ "api-help-flag-internal": "<strong>This module is internal or unstable.</strong> Its operation may change without notice.",
+ "api-help-flag-readrights": "This module requires read rights.",
+ "api-help-flag-writerights": "This module requires write rights.",
+ "api-help-flag-mustbeposted": "This module only accepts POST requests.",
+ "api-help-flag-generator": "This module can be used as a generator.",
+ "api-help-help-urls": "",
+ "api-help-parameters": "{{PLURAL:$1|Parameter|Parameters}}:",
+ "api-help-param-deprecated": "Deprecated.",
+ "api-help-param-required": "This parameter is required.",
+ "api-help-param-list": "{{PLURAL:$1|1=One value|2=Values (separate with \"{{!}}\")}}: $2",
+ "api-help-param-list-can-be-empty": "{{PLURAL:$1|0=Must be empty|Can be empty, or $2}}",
+ "api-help-param-limit": "No more than $1 allowed.",
+ "api-help-param-limit2": "No more than $1 ($2 for bots) allowed.",
+ "api-help-param-integer-min": "The {{PLURAL:$1|1=value|2=values}} must be no less than $2.",
+ "api-help-param-integer-max": "The {{PLURAL:$1|1=value|2=values}} must be no greater than $3.",
+ "api-help-param-integer-minmax": "The {{PLURAL:$1|1=value|2=values}} must be between $2 and $3.",
+ "api-help-param-upload": "Must be posted as a file upload using multipart/form-data.",
+ "api-help-param-multi-separate": "Separate values with \"|\".",
+ "api-help-param-multi-max": "Maximum number of values is {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} for bots).",
+ "api-help-param-default": "Default: $1",
+ "api-help-param-default-empty": "Default: <span class=\"apihelp-empty\">(empty)</span>",
+ "api-help-param-token": "A \"$1\" token retrieved from [[Special:ApiHelp/query+tokens|action=query&meta=tokens]]",
+ "api-help-param-no-description": "<span class=\"apihelp-empty\">(no description)</span>",
+ "api-help-examples": "{{PLURAL:$1|Example|Examples}}:",
+ "api-help-permissions": "{{PLURAL:$1|Permission|Permissions}}:",
+ "api-help-permissions-granted-to": "{{PLURAL:$1|Granted to}}: $2",
+ "api-help-right-apihighlimits": "Use higher limits in API queries (slow queries: $1; fast queries: $2). The limits for slow queries also apply to multivalue parameters.",
+
+ "api-credits-header": "Credits",
+ "api-credits": "API developers:\n* Roan Kattouw (lead developer Sep 2007–2009)\n* Victor Vasiliev\n* Bryan Tong Minh\n* Sam Reed\n* Yuri Astrakhan (creator, lead developer Sep 2006–Sep 2007)\n* Brad Jorsch (lead developer 2013–present)\n\nPlease send your comments, suggestions and questions to mediawiki-api@lists.wikimedia.org\nor file a bug report at https://bugzilla.wikimedia.org/."
+}
--- /dev/null
+{
+ "@metadata": {
+ "authors": []
+ },
+
+ "apihelp-main-description": "{{doc-apihelp-description|main}}",
+ "apihelp-main-param-action": "{{doc-apihelp-param|main|action}}",
+ "apihelp-main-param-format": "{{doc-apihelp-param|main|format}}",
+ "apihelp-main-param-maxlag": "{{doc-apihelp-param|main|maxlag}}",
+ "apihelp-main-param-smaxage": "{{doc-apihelp-param|main|smaxage}}",
+ "apihelp-main-param-maxage": "{{doc-apihelp-param|main|maxage}}",
+ "apihelp-main-param-assert": "{{doc-apihelp-param|main|assert}}",
+ "apihelp-main-param-requestid": "{{doc-apihelp-param|main|requestid}}",
+ "apihelp-main-param-servedby": "{{doc-apihelp-param|main|servedby}}",
+ "apihelp-main-param-curtimestamp": "{{doc-apihelp-param|main|curtimestamp}}",
+ "apihelp-main-param-origin": "{{doc-apihelp-param|main|origin}}",
+ "apihelp-main-param-uselang": "{{doc-apihelp-param|main|uselang}}",
+
+ "apihelp-help-description": "{{doc-apihelp-description|help}}",
+ "apihelp-help-param-modules": "{{doc-apihelp-param|help|modules}}",
+ "apihelp-help-param-submodules": "{{doc-apihelp-param|help|submodules}}",
+ "apihelp-help-param-recursivesubmodules": "{{doc-apihelp-param|help|recursivesubmodules}}",
+ "apihelp-help-param-helpformat": "{{doc-apihelp-param|help|helpformat}}",
+ "apihelp-help-param-wrap": "{{doc-apihelp-param|help|wrap}}",
+ "apihelp-help-param-toc": "{{doc-apihelp-param|help|toc}}",
+ "apihelp-help-example-main": "{{doc-apihelp-example|help}}",
+ "apihelp-help-example-recursive": "{{doc-apihelp-example|help}}",
+ "apihelp-help-example-help": "{{doc-apihelp-example|help}}",
+ "apihelp-help-example-query": "{{doc-apihelp-example|help}}",
+
+ "api-help-title": "Page title for the auto-generated help output",
+ "api-help-lead": "Text displayed at the top of the API help page",
+ "api-help-main-header": "Text for the header of the main module",
+ "api-help-fallback-description": "{{notranslate}}",
+ "api-help-fallback-parameter": "{{notranslate}}",
+ "api-help-fallback-example": "{{notranslate}}",
+ "api-help-flags": "{{optional}} Label for the API help flags box\n\nParameters:\n* $1 - Number of flags to be displayed",
+ "api-help-flag-deprecated": "Flag displayed for an API module that is deprecated",
+ "api-help-flag-internal": "Flag displayed for an API module that is considered internal or unstable",
+ "api-help-flag-readrights": "Flag displayed for an API module that requires read rights",
+ "api-help-flag-writerights": "Flag displayed for an API module that requires write rights",
+ "api-help-flag-mustbeposted": "Flag displayed for an API module that only accepts POST requests",
+ "api-help-flag-generator": "Flag displayed for an API module that can be used as a generator",
+ "api-help-help-urls": "{{optional}} Label for the API help urls section\n\nParameters:\n* $1 - Number of urls to be displayed",
+ "api-help-parameters": "Label for the API help parameters section\n\nParameters:\n* $1 - Number of parameters to be displayed",
+ "api-help-param-deprecated": "Displayed in the API help for any deprecated parameter",
+ "api-help-param-required": "Displayed in the API help for any required parameter",
+ "api-help-param-list": "Used to display the possible values for a parameter taking a list of values\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Comma-separated list of values, possibly formatted using {{msg-mw|api-help-param-list-can-be-empty}}",
+ "api-help-param-list-can-be-empty": "Used to indicate that one of the possible values in the list is the empty string.\n\nParameters:\n* $1 - Number of items in the rest of the list; may be 0\n* $2 - Remainder of the list as a comma-separated string",
+ "api-help-param-limit": "Used to display the maximum value of a limit parameter\n\nParameters:\n* $1 - Maximum value",
+ "api-help-param-limit2": "Used to display the maximum values of a limit parameter\n\nParameters:\n* $1 - Maximum value without the apihighlimits right\n* $2 - Maximum value with the apihighlimits right",
+ "api-help-param-integer-min": "Used to display an integer parameter with a minimum but no maximum value\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Minimum value\n* $3 - unused\n\nSee also:\n* {{msg-mw|api-help-param-integer-max}}\n* {{msg-mw|api-help-param-integer-minmax}}",
+ "api-help-param-integer-max": "Used to display an integer parameter with a maximum but no minimum value\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - unused\n* $3 - Maximum value\n\nSee also:\n* {{msg-mw|api-help-param-integer-min}}\n* {{msg-mw|api-help-param-integer-minmax}}",
+ "api-help-param-integer-minmax": "Used to display an integer parameter with a maximum and minimum values\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Minimum value\n* $3 - Maximum value\n\nSee also:\n* {{msg-mw|api-help-param-integer-min}}\n* {{msg-mw|api-help-param-integer-max}}",
+ "api-help-param-upload": "{{technical}} Used to indicate that an 'upload'-type parameter must be posted as a file upload using multipart/form-data",
+ "api-help-param-multi-separate": "Used to indicate how to separate multiple values. Not used with {{msg-mw|api-help-param-list}}.",
+ "api-help-param-multi-max": "Used to indicate the maximum number of values accepted for a multi-valued parameter.\n\nParameters:\n* $1 - Maximum value without the apihighlimits right\n* $2 - Maximum value with the apihighlimits right",
+ "api-help-param-default": "Used to display the default value for an API parameter\n\nParameters:\n* $1 - Default value\n\nSee also:\n* {{msg-mw|api-help-param-default-empty}}",
+ "api-help-param-default-empty": "Used to display the default value for an API parameter when that default is an empty value\n\nSee also:\n* {{msg-mw|api-help-param-default}}",
+ "api-help-param-token": "{{doc-apihelp-param|description=any 'token' parameter|paramstart=3|params=\n* $1 - Token type|noseealso=1}}",
+ "api-help-param-no-description": "Displayed on API parameters that lack any description",
+ "api-help-examples": "Label for the API help examples section\n\nParameters:\n* $1 - Number of examples to be displayed",
+ "api-help-permissions": "Label for the \"permissions\" section in the main module's help output.\n\nParameters:\n* $1 - Number of permissions displayed",
+ "api-help-permissions-granted-to": "Used to introduce the list of groups each permission is assigned to.\n\nParameters:\n* $1 - Number of groups\n* $2 - List of group names, comma-separated",
+ "api-help-right-apihighlimits": "{{technical}}{{doc-right|apihighlimits|prefix=api-help}}\nThis message is used instead of {{msg-mw|right-apihighlimits}} in the API help to display the actual limits.\n\nParameters:\n* $1 - Limit for slow queries\n* $2 - Limit for fast queries",
+
+ "api-credits-header": "Header for the API credits section in the API help output",
+ "api-credits": "API credits text, displayed in the API help output"
+}
'Booksources' => 'SpecialBookSources',
// Unlisted / redirects
+ 'ApiHelp' => 'SpecialApiHelp',
'Blankpage' => 'SpecialBlankpage',
'Diff' => 'SpecialDiff',
'Emailuser' => 'SpecialEmailUser',
--- /dev/null
+<?php
+/**
+ * Implements Special:ApiHelp
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup SpecialPage
+ */
+
+/**
+ * Special page to redirect to API help pages, for situations where linking to
+ * the api.php endpoint is not wanted.
+ *
+ * @ingroup SpecialPage
+ */
+class SpecialApiHelp extends UnlistedSpecialPage {
+ public function __construct() {
+ parent::__construct( 'ApiHelp' );
+ }
+
+ public function execute( $par ) {
+ if ( empty( $par ) ) {
+ $par = 'main';
+ }
+
+ // These come from transclusions
+ $request = $this->getRequest();
+ $options = array(
+ 'action' => 'help',
+ 'nolead' => true,
+ 'submodules' => $request->getCheck( 'submodules' ),
+ 'recursivesubmodules' => $request->getCheck( 'recursivesubmodules' ),
+ 'title' => $request->getVal( 'title', $this->getPageTitle( '$1' )->getPrefixedText() ),
+ );
+
+ // These are for linking from wikitext, since url parameters are a pain
+ // to do.
+ while ( true ) {
+ if ( substr( $par, 0, 4 ) === 'sub/' ) {
+ $par = substr( $par, 4 );
+ $options['submodules'] = 1;
+ continue;
+ }
+
+ if ( substr( $par, 0, 5 ) === 'rsub/' ) {
+ $par = substr( $par, 5 );
+ $options['recursivesubmodules'] = 1;
+ continue;
+ }
+
+ $moduleName = $par;
+ break;
+ }
+
+ if ( !$this->including() ) {
+ unset( $options['nolead'], $options['title'] );
+ $options['modules'] = $moduleName;
+ $link = wfAppendQuery( wfExpandUrl( wfScript( 'api' ), PROTO_CURRENT ), $options );
+ $this->getOutput()->redirect( $link );
+ return;
+ }
+
+ $main = new ApiMain( $this->getContext(), false );
+ try {
+ $module = $main->getModuleFromPath( $moduleName );
+ } catch ( UsageException $ex ) {
+ $this->getOutput()->addHTML( Html::rawElement( 'span', array( 'class' => 'error' ),
+ $this->msg( 'apihelp-no-such-module', $moduleName )->inContentLanguage()->parse()
+ ) );
+ return;
+ }
+
+ ApiHelp::getHelp( $this->getContext(), $module, $options );
+ }
+
+ public function isIncludable() {
+ return true;
+ }
+}
"pager-older-n": "{{PLURAL:$1|older 1|older $1}}",
"suppress": "Oversight",
"querypage-disabled": "This special page is disabled for performance reasons.",
+ "apihelp": "API help",
+ "apihelp-summary": "",
+ "apihelp-no-such-module": "Module \"$1\" not found.",
+ "apihelp-link": "[[Special:ApiHelp/$1|$2]]",
"booksources": "Book sources",
"booksources-summary": "",
"booksources-search-legend": "Search for book sources",
"pager-older-n": "This is part of the navigation message on the top and bottom of Special pages which are lists of things in date order, e.g. the User's contributions page. It is passed as the first argument of {{msg-mw|Viewprevnext}}. $1 is the number of items shown per page.",
"suppress": "{{Identical|Oversight}}",
"querypage-disabled": "On special pages that use expensive database queries but are not cacheable, this message is displayed when 'miser mode' is on (i.e. no expensive queries allowed).",
+ "apihelp": "{{doc-special|ApiHelp}}",
+ "apihelp-summary": "{{doc-specialpagesummary|ApiHelp}}",
+ "apihelp-no-such-module": "Used as an error message if the requested API module is not found.\n\nParameters:\n* $1 - Requested module name",
+ "apihelp-link": "{{notranslate}} Used to construct a link to [[Special:ApiHelp]]\n\nParameters:\n* $1 - module to link\n* $2 - link text",
"booksources": "{{doc-special|BookSources}}\n\n'''This message shouldn't be changed unless it has serious mistakes.'''\n\nIt's used as the page name of the configuration page of [[Special:BookSources]]. Changing it breaks existing sites using the default version of this message.\n\nSee also:\n* {{msg-mw|Booksources|title}}\n* {{msg-mw|Booksources-text|text}}",
"booksources-summary": "{{doc-specialpagesummary|booksources}}",
"booksources-search-legend": "Box heading on [[Special:BookSources|book sources]] special page. The box is for searching for places where a particular book can be bought or viewed.",
'Allmessages' => array( 'AllMessages' ),
'AllMyUploads' => array( 'AllMyUploads', 'AllMyFiles' ),
'Allpages' => array( 'AllPages' ),
+ 'ApiHelp' => array( 'ApiHelp' ),
'Ancientpages' => array( 'AncientPages' ),
'Badtitle' => array( 'Badtitle' ),
'Blankpage' => array( 'BlankPage' ),
'raw' => true,
'targets' => array( 'desktop', 'mobile' ),
),
+ 'mediawiki.apihelp' => array(
+ 'styles' => 'resources/src/mediawiki/mediawiki.apihelp.css',
+ 'targets' => array( 'desktop' ),
+ 'dependencies' => array(
+ 'mediawiki.hlist',
+ ),
+ ),
'mediawiki.api' => array(
'scripts' => 'resources/src/mediawiki.api/mediawiki.api.js',
'dependencies' => 'mediawiki.util',
--- /dev/null
+.apihelp-header {
+ clear: both;
+ margin-bottom: 0.1em;
+}
+
+div.apihelp-linktrail {
+ font-size: smaller;
+}
+
+.apihelp-block {
+ margin-top: 0.5em;
+}
+
+.apihelp-block-head {
+ font-weight: bold;
+}
+
+.apihelp-flags {
+ font-size: smaller;
+ float: right;
+ border: 1px solid black;
+ padding: 0.25em;
+ width: 20em;
+}
+
+.apihelp-deprecated, .apihelp-flag-deprecated,
+.apihelp-flag-internal strong {
+ font-weight: bold;
+ color: red;
+}
+
+.apihelp-empty {
+ color: #888;
+}
+
+.apihelp-help-urls ul {
+ list-style-image: none;
+ list-style-type: none;
+ margin-left: 0;
+}
+
+.apihelp-parameters dl,
+.apihelp-examples dl,
+.apihelp-permissions dl {
+ margin-left: 2em;
+}
+
+.apihelp-parameters dt {
+ float: left;
+ clear: left;
+ min-width: 10em;
+ white-space: nowrap;
+ line-height: 1.5em;
+}
+
+.apihelp-parameters dt:after {
+ content: ':\A0'
+}
+
+.apihelp-parameters dd {
+ margin: 0 0 0.5em 10em;
+ line-height: 1.5em;
+}
+
+.apihelp-parameters dd p:first-child {
+ margin-top: 0;
+}
+
+.apihelp-parameters dd.info {
+ margin-left: 12em;
+ text-indent: -2em;
+}
+
+.apihelp-examples dt {
+ font-weight: normal;
+}
+
+.api-main-links {
+ text-align: center;
+}
+.api-main-links ul:before {
+ content: '[';
+}
+.api-main-links ul:after {
+ content: ']';
+}
class ApiMainTest extends ApiTestCase {
/**
- * Test that the API will accept a FauxRequest and execute. The help action
- * (default) throws a UsageException. Just validate we're getting proper XML
- *
- * @expectedException UsageException
+ * Test that the API will accept a FauxRequest and execute.
*/
public function testApi() {
$api = new ApiMain(
- new FauxRequest( array( 'action' => 'help', 'format' => 'xml' ) )
+ new FauxRequest( array( 'action' => 'query', 'meta' => 'siteinfo' ) )
);
$api->execute();
- $api->getPrinter()->setBufferResult( true );
- $api->printResult( false );
- $resp = $api->getPrinter()->getBuffer();
-
- libxml_use_internal_errors( true );
- $sxe = simplexml_load_string( $resp );
- $this->assertNotInternalType( "bool", $sxe );
- $this->assertThat( $sxe, $this->isInstanceOf( "SimpleXMLElement" ) );
+ $data = $api->getResultData();
+ $this->assertInternalType( 'array', $data );
+ $this->assertArrayHasKey( 'query', $data );
}
public static function provideAssert() {
$class = get_class( $module );
$prefix = $module->getModulePrefix();
- if ( isset( $prefixes[$prefix] ) ) {
+ if ( $prefix !== '' && isset( $prefixes[$prefix] ) ) {
$this->fail( "Module prefix '{$prefix}' is shared between {$class} and {$prefixes[$prefix]}" );
}
$prefixes[$module->getModulePrefix()] = $class;
$module = $data[3];
$printer = $module->createPrinterByName( $format );
- $printer->setUnescapeAmps( false );
$printer->initPrinter( false );
dépôts / lhc / web / wiklou.git / commitdiff