* @file
*/
+use HtmlFormatter\HtmlFormatter;
+
/**
* Class to output help for an API module
*
class ApiHelp extends ApiBase {
public function execute() {
$params = $this->extractRequestParams();
- $modules = array();
+ $modules = [];
foreach ( $params['modules'] as $path ) {
$modules[] = $this->getModuleFromPath( $path );
$result = $this->getResult();
if ( $params['wrap'] ) {
- $data = array(
+ $data = [
'mime' => 'text/html',
'help' => $html,
- );
+ ];
ApiResult::setSubelementsList( $data, 'help' );
$result->addValue( null, $this->getModuleName(), $data );
} else {
global $wgContLang;
if ( !is_array( $modules ) ) {
- $modules = array( $modules );
+ $modules = [ $modules ];
}
$out = $context->getOutput();
- $out->addModuleStyles( 'mediawiki.hlist' );
- $out->addModuleStyles( 'mediawiki.apihelp' );
+ $out->addModuleStyles( [
+ 'mediawiki.hlist',
+ 'mediawiki.apihelp',
+ ] );
if ( !empty( $options['toc'] ) ) {
$out->addModules( 'mediawiki.toc' );
}
}
}
- $haveModules = array();
+ $haveModules = [];
$html = self::getHelpInternal( $context, $modules, $options, $haveModules );
if ( !empty( $options['toc'] ) && $haveModules ) {
$out->addHTML( Linker::generateTOC( $haveModules, $context->getLanguage() ) );
* @param array $localModules Keys are modules to link within the current page, values are ignored
* @return string
*/
- public static function fixHelpLinks( $html, $helptitle = null, $localModules = array() ) {
+ public static function fixHelpLinks( $html, $helptitle = null, $localModules = [] ) {
$formatter = new HtmlFormatter( $html );
$doc = $formatter->getDoc();
$xpath = new DOMXPath( $doc );
$href = Title::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
->getFullURL();
} else {
- $href = wfAppendQuery( wfScript( 'api' ), array(
+ $href = wfAppendQuery( wfScript( 'api' ), [
'action' => 'help',
'modules' => $m[1],
- ) ) . $m[2];
+ ] ) . $m[2];
}
$node->setAttribute( 'href', $href );
$node->removeAttribute( 'title' );
* @return string
*/
private static function wrap( Message $msg, $class, $tag = 'span' ) {
- return Html::rawElement( $tag, array( 'class' => $class ),
+ return Html::rawElement( $tag, [ 'class' => $class ],
$msg->parse()
);
}
$level = empty( $options['headerlevel'] ) ? 2 : $options['headerlevel'];
if ( empty( $options['tocnumber'] ) ) {
- $tocnumber = array( 2 => 0 );
+ $tocnumber = [ 2 => 0 ];
} else {
$tocnumber = &$options['tocnumber'];
}
$tocnumber[$level]++;
$path = $module->getModulePath();
$module->setContext( $context );
- $help = array(
+ $help = [
'header' => '',
'flags' => '',
'description' => '',
'parameters' => '',
'examples' => '',
'submodules' => '',
- );
+ ];
if ( empty( $options['noheader'] ) || !empty( $options['toc'] ) ) {
$anchor = $path;
}
if ( $module->isMain() ) {
- $header = $context->msg( 'api-help-main-header' )->parse();
+ $headerContent = $context->msg( 'api-help-main-header' )->parse();
+ $headerAttr = [
+ 'class' => 'apihelp-header',
+ ];
} else {
$name = $module->getModuleName();
- $header = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
+ $headerContent = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
"=$name";
if ( $module->getModulePrefix() !== '' ) {
- $header .= ' ' .
+ $headerContent .= ' ' .
$context->msg( 'parentheses', $module->getModulePrefix() )->parse();
}
+ // Module names are always in English and not localized,
+ // so English language and direction must be set explicitly,
+ // otherwise parentheses will get broken in RTL wikis
+ $headerAttr = [
+ 'class' => 'apihelp-header apihelp-module-name',
+ 'dir' => 'ltr',
+ 'lang' => 'en',
+ ];
}
- $haveModules[$anchor] = array(
+
+ $headerAttr['id'] = $anchor;
+
+ $haveModules[$anchor] = [
'toclevel' => count( $tocnumber ),
'level' => $level,
'anchor' => $anchor,
- 'line' => $header,
- 'number' => join( '.', $tocnumber ),
+ 'line' => $headerContent,
+ 'number' => implode( '.', $tocnumber ),
'index' => false,
- );
+ ];
if ( empty( $options['noheader'] ) ) {
- $help['header'] .= Html::element( 'h' . min( 6, $level ),
- array( 'id' => $anchor, 'class' => 'apihelp-header' ),
- $header
+ $help['header'] .= Html::element(
+ 'h' . min( 6, $level ),
+ $headerAttr,
+ $headerContent
);
}
} else {
$haveModules[$path] = true;
}
- $links = array();
+ $links = [];
$any = false;
for ( $m = $module; $m !== null; $m = $m->getParent() ) {
$name = $m->getModuleName();
} else {
$link = SpecialPage::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
$link = Html::element( 'a',
- array( 'href' => $link, 'class' => 'apihelp-linktrail' ),
+ [ 'href' => $link, 'class' => 'apihelp-linktrail' ],
$name
);
$any = true;
$flags = $module->getHelpFlags();
$help['flags'] .= Html::openElement( 'div',
- array( 'class' => 'apihelp-block apihelp-flags' ) );
+ [ 'class' => 'apihelp-block apihelp-flags' ] );
$msg = $context->msg( 'api-help-flags' );
if ( !$msg->isDisabled() ) {
$help['flags'] .= self::wrap(
$urls = $module->getHelpUrls();
if ( $urls ) {
$help['help-urls'] .= Html::openElement( 'div',
- array( 'class' => 'apihelp-block apihelp-help-urls' )
+ [ 'class' => 'apihelp-block apihelp-help-urls' ]
);
$msg = $context->msg( 'api-help-help-urls' );
if ( !$msg->isDisabled() ) {
);
}
if ( !is_array( $urls ) ) {
- $urls = array( $urls );
+ $urls = [ $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 )
+ Html::element( 'a', [ 'href' => $url ], $url )
);
}
$help['help-urls'] .= Html::closeElement( 'ul' );
}
$params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
- $groups = array();
- if ( $params ) {
+ $dynamicParams = $module->dynamicParameterDocumentation();
+ $groups = [];
+ if ( $params || $dynamicParams !== null ) {
$help['parameters'] .= Html::openElement( 'div',
- array( 'class' => 'apihelp-block apihelp-parameters' )
+ [ 'class' => 'apihelp-block apihelp-parameters' ]
);
$msg = $context->msg( 'api-help-parameters' );
if ( !$msg->isDisabled() ) {
foreach ( $params as $name => $settings ) {
if ( !is_array( $settings ) ) {
- $settings = array( ApiBase::PARAM_DFLT => $settings );
+ $settings = [ ApiBase::PARAM_DFLT => $settings ];
}
$help['parameters'] .= Html::element( 'dt', null,
$module->encodeParamName( $name ) );
// Add description
- $description = array();
+ $description = [];
if ( isset( $descriptions[$name] ) ) {
foreach ( $descriptions[$name] as $msg ) {
$msg->setContext( $context );
}
// Add usage info
- $info = array();
+ $info = [];
// Required?
if ( !empty( $settings[ApiBase::PARAM_REQUIRED] ) ) {
$count = count( $type );
$links = isset( $settings[ApiBase::PARAM_VALUE_LINKS] )
? $settings[ApiBase::PARAM_VALUE_LINKS]
- : array();
+ : [];
$type = array_map( function ( $v ) use ( $links ) {
$ret = wfEscapeWikiText( $v );
if ( isset( $links[$v] ) ) {
if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) {
$map = $settings[ApiBase::PARAM_SUBMODULE_MAP];
ksort( $map );
- $submodules = array();
+ $submodules = [];
foreach ( $map as $v => $m ) {
$submodules[] = "[[Special:ApiHelp/{$m}|{$v}]]";
}
$type = null;
break;
+ case 'tags':
+ $tags = ChangeTags::listExplicitlyDefinedTags();
+ $count = count( $tags );
+ $info[] = $context->msg( 'api-help-param-list' )
+ ->params( $multi ? 2 : 1 )
+ ->params( $context->getLanguage()->commaList( $tags ) )
+ ->parse();
+ $hintPipeSeparated = false;
+ $type = null;
+ break;
+
case 'limit':
if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
$info[] = $context->msg( 'api-help-param-limit2' )
}
if ( $multi ) {
- $extra = array();
+ $extra = [];
if ( $hintPipeSeparated ) {
$extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
}
->parse();
}
if ( $extra ) {
- $info[] = join( ' ', $extra );
+ $info[] = implode( ' ', $extra );
}
}
}
}
if ( !array_filter( $description ) ) {
- $description = array( self::wrap(
+ $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' ) );
+ [ 'class' => 'info' ] );
$help['parameters'] .= self::wrap(
$context->msg( 'api-help-param-deprecated' ),
'apihelp-deprecated', 'strong'
}
if ( $description ) {
- $description = join( '', $description );
+ $description = implode( '', $description );
$description = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $description );
$help['parameters'] .= Html::rawElement( 'dd',
- array( 'class' => 'description' ), $description );
+ [ 'class' => 'description' ], $description );
}
foreach ( $info as $i ) {
- $help['parameters'] .= Html::rawElement( 'dd', array( 'class' => 'info' ), $i );
+ $help['parameters'] .= Html::rawElement( 'dd', [ 'class' => 'info' ], $i );
}
}
+ if ( $dynamicParams !== null ) {
+ $dynamicParams = ApiBase::makeMessage( $dynamicParams, $context, [
+ $module->getModulePrefix(),
+ $module->getModuleName(),
+ $module->getModulePath()
+ ] );
+ $help['parameters'] .= Html::element( 'dt', null, '*' );
+ $help['parameters'] .= Html::rawElement( 'dd',
+ [ 'class' => 'description' ], $dynamicParams->parse() );
+ }
+
$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' ) );
+ [ 'class' => 'apihelp-block apihelp-examples' ] );
$msg = $context->msg( 'api-help-examples' );
if ( !$msg->isDisabled() ) {
$help['examples'] .= self::wrap(
$help['examples'] .= Html::openElement( 'dl' );
foreach ( $examples as $qs => $msg ) {
- $msg = ApiBase::makeMessage( $msg, $context, array(
+ $msg = ApiBase::makeMessage( $msg, $context, [
$module->getModulePrefix(),
$module->getModuleName(),
$module->getModulePath()
- ) );
+ ] );
$link = wfAppendQuery( wfScript( 'api' ), $qs );
+ $sandbox = SpecialPage::getTitleFor( 'ApiSandbox' )->getLocalURL() . '#' . $qs;
$help['examples'] .= Html::rawElement( 'dt', null, $msg->parse() );
$help['examples'] .= Html::rawElement( 'dd', null,
- Html::element( 'a', array( 'href' => $link ), "api.php?$qs" )
+ Html::element( 'a', [ 'href' => $link ], "api.php?$qs" ) . ' ' .
+ Html::rawElement( 'a', [ 'href' => $sandbox ],
+ $context->msg( 'api-help-open-in-apisandbox' )->parse() )
);
}
$help['examples'] .= Html::closeElement( 'dl' );
$subtocnumber = $tocnumber;
$subtocnumber[$level + 1] = 0;
- $suboptions = array(
+ $suboptions = [
'submodules' => $options['recursivesubmodules'],
'headerlevel' => $level + 1,
'tocnumber' => &$subtocnumber,
'noheader' => false,
- ) + $options;
+ ] + $options;
if ( $options['submodules'] && $module->getModuleManager() ) {
$manager = $module->getModuleManager();
- $submodules = array();
+ $submodules = [];
foreach ( $groups as $group ) {
$names = $manager->getNames( $group );
sort( $names );
$module->modifyHelp( $help, $suboptions, $haveModules );
- Hooks::run( 'APIHelpModifyOutput', array( $module, &$help, $suboptions, &$haveModules ) );
+ Hooks::run( 'APIHelpModifyOutput', [ $module, &$help, $suboptions, &$haveModules ] );
- $out .= join( "\n", $help );
+ $out .= implode( "\n", $help );
}
return $out;
}
public function getAllowedParams() {
- return array(
- 'modules' => array(
+ return [
+ 'modules' => [
ApiBase::PARAM_DFLT => 'main',
ApiBase::PARAM_ISMULTI => true,
- ),
+ ],
'submodules' => false,
'recursivesubmodules' => false,
'wrap' => false,
'toc' => false,
- );
+ ];
}
protected function getExamplesMessages() {
- return array(
+ return [
'action=help'
=> 'apihelp-help-example-main',
'action=help&modules=query&submodules=1'
=> 'apihelp-help-example-help',
'action=help&modules=query+info|query+categorymembers'
=> 'apihelp-help-example-query',
- );
+ ];
}
public function getHelpUrls() {
- return array(
+ return [
'https://www.mediawiki.org/wiki/API:Main_page',
'https://www.mediawiki.org/wiki/API:FAQ',
'https://www.mediawiki.org/wiki/API:Quick_start_guide',
- );
+ ];
}
}