59 parent::__construct( $main, $action );
60 $this->skinFactory = $skinFactory;
73 $context->setSkin( $this->skinFactory->makeSkin(
'apioutput' ) );
75 $context->setTitle( SpecialPage::getTitleFor(
'ApiHelp' ) );
77 $out->setRobotPolicy(
'noindex,nofollow' );
78 $out->setCopyrightUrl(
'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
79 $out->disallowUserJs();
80 $context->setOutput( $out );
82 self::getHelp( $context, $modules,
$params );
87 $html = ob_get_clean();
92 'mime' =>
'text/html',
93 'filename' =>
'api-help.html',
96 ApiResult::setSubelementsList( $data,
'help' );
101 'Types' => [
'AssocAsObject' => true ],
104 $errors = array_filter( [
105 'errors' => $this->
getResult()->getResultData( [
'errors' ], $transform ),
106 'warnings' => $this->
getResult()->getResultData( [
'warnings' ], $transform ),
109 $json = FormatJson::encode( $errors,
true, FormatJson::UTF8_OK );
112 $json = str_replace(
'--',
'-\u002D', $json );
113 $html =
"<!-- API warnings and errors:\n$json\n-->\n$html";
117 $result->addValue(
null,
'text', $html, ApiResult::NO_SIZE_CHECK );
118 $result->addValue(
null,
'mime',
'text/html', ApiResult::NO_SIZE_CHECK );
119 $result->addValue(
null,
'filename',
'api-help.html', ApiResult::NO_SIZE_CHECK );
143 if ( !is_array( $modules ) ) {
144 $modules = [ $modules ];
148 $out->addModuleStyles( [
150 'mediawiki.apipretty',
152 $out->setPageTitleMsg( $context->
msg(
'api-help-title' ) );
154 $services = MediaWikiServices::getInstance();
155 $cache = $services->getMainWANObjectCache();
157 if ( count( $modules ) == 1 && $modules[0] instanceof
ApiMain &&
158 $options[
'recursivesubmodules'] &&
159 $context->
getLanguage()->equals( $services->getContentLanguage() )
161 $cacheHelpTimeout = $context->
getConfig()->get( MainConfigNames::APICacheHelpTimeout );
162 if ( $cacheHelpTimeout > 0 ) {
164 $cacheKey = $cache->makeKey(
'apihelp', $modules[0]->
getModulePath(),
165 (
int)!empty( $options[
'toc'] ),
166 str_replace(
' ',
'_', SpecialVersion::getVersion(
'nodb' ) ) );
167 $cached = $cache->get( $cacheKey );
169 $out->addHTML( $cached );
174 if ( $out->getHTML() !==
'' ) {
180 $options[
'recursivesubmodules'] = !empty( $options[
'recursivesubmodules'] );
181 $options[
'submodules'] = $options[
'recursivesubmodules'] || !empty( $options[
'submodules'] );
184 if ( empty( $options[
'nolead'] ) ) {
185 $msg = $context->
msg(
'api-help-lead' );
186 if ( !$msg->isDisabled() ) {
187 $out->addHTML( $msg->parseAsBlock() );
192 $html = self::getHelpInternal( $context, $modules, $options, $haveModules );
193 if ( !empty( $options[
'toc'] ) && $haveModules ) {
195 $pout->
setTOCData( TOCData::fromLegacy( array_values( $haveModules ) ) );
196 $pout->setOutputFlag( ParserOutputFlags::SHOW_TOC );
197 $pout->setText( Parser::TOC_PLACEHOLDER );
198 $out->addParserOutput( $pout );
200 $out->addHTML( $html );
202 $helptitle = $options[
'helptitle'] ??
null;
203 $html = self::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
205 $out->addHTML( $html );
207 if ( $cacheKey !==
null ) {
209 $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
221 public static function fixHelpLinks( $html, $helptitle =
null, $localModules = [] ) {
222 return HtmlHelper::modifyElements(
224 static function ( SerializerNode $node ):
bool {
225 return $node->name ===
'a'
226 && isset( $node->attrs[
'href'] )
227 && !str_contains( $node->attrs[
'class'] ??
'',
'apihelp-linktrail' );
229 static function ( SerializerNode $node ) use ( $helptitle, $localModules ): SerializerNode {
230 $href = $node->attrs[
'href'];
234 $href = rawurldecode( $href );
235 }
while ( $old !== $href );
236 if ( preg_match(
'!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
237 if ( isset( $localModules[$m[1]] ) ) {
238 $href = $m[2] ===
'' ?
'#' . $m[1] : $m[2];
239 } elseif ( $helptitle !==
null ) {
240 $href = Title::newFromText( str_replace(
'$1', $m[1], $helptitle ) . $m[2] )
248 $node->attrs[
'href'] = $href;
249 unset( $node->attrs[
'title'] );
265 private static function wrap( Message $msg, $class, $tag =
'span' ) {
266 return Html::rawElement( $tag, [
'class' => $class ],
280 private static function getHelpInternal(
IContextSource $context, array $modules,
281 array $options, &$haveModules
285 $level = empty( $options[
'headerlevel'] ) ? 2 : $options[
'headerlevel'];
286 if ( empty( $options[
'tocnumber'] ) ) {
287 $tocnumber = [ 2 => 0 ];
289 $tocnumber = &$options[
'tocnumber'];
292 foreach ( $modules as $module ) {
293 $paramValidator = $module->getMain()->getParamValidator();
294 $tocnumber[$level]++;
295 $path = $module->getModulePath();
296 $module->setContext( $context );
307 if ( empty( $options[
'noheader'] ) || !empty( $options[
'toc'] ) ) {
310 while ( isset( $haveModules[$anchor] ) ) {
311 $anchor =
$path .
'|' . ++$i;
314 if ( $module->isMain() ) {
315 $headerContent = $context->
msg(
'api-help-main-header' )->parse();
317 'class' =>
'apihelp-header',
320 $name = $module->getModuleName();
321 $headerContent = htmlspecialchars(
322 $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
"=$name"
324 if ( $module->getModulePrefix() !==
'' ) {
325 $headerContent .=
' ' .
326 $context->
msg(
'parentheses', $module->getModulePrefix() )->parse();
332 'class' => [
'apihelp-header',
'apihelp-module-name' ],
338 $headerAttr[
'id'] = $anchor;
341 $haveModules[$anchor] = [
342 'toclevel' => count( $tocnumber ),
345 'line' => $headerContent,
346 'number' => implode(
'.', $tocnumber ),
349 if ( empty( $options[
'noheader'] ) ) {
350 $help[
'header'] .= Html::rawElement(
351 'h' . min( 6, $level ),
357 $haveModules[
$path] =
true;
362 for ( $m = $module; $m !==
null; $m = $m->getParent() ) {
363 $name = $m->getModuleName();
364 if ( $name ===
'main_int' ) {
368 if ( count( $modules ) === 1 && $m === $modules[0] &&
369 !( !empty( $options[
'submodules'] ) && $m->getModuleManager() )
371 $link = Html::element(
'b', [
'dir' =>
'ltr',
'lang' =>
'en' ], $name );
373 $link = SpecialPage::getTitleFor(
'ApiHelp', $m->getModulePath() )->getLocalURL();
374 $link = Html::element(
'a',
375 [
'href' => $link,
'class' =>
'apihelp-linktrail',
'dir' =>
'ltr',
'lang' =>
'en' ],
380 array_unshift( $links, $link );
383 $help[
'header'] .= self::wrap(
384 $context->
msg(
'parentheses' )
385 ->rawParams( $context->
getLanguage()->pipeList( $links ) ),
386 'apihelp-linktrail',
'div'
390 $flags = $module->getHelpFlags();
391 $help[
'flags'] .= Html::openElement(
'div',
392 [
'class' => [
'apihelp-block',
'apihelp-flags' ] ] );
393 $msg = $context->
msg(
'api-help-flags' );
394 if ( !$msg->isDisabled() ) {
395 $help[
'flags'] .= self::wrap(
396 $msg->numParams( count( $flags ) ),
'apihelp-block-head',
'div'
399 $help[
'flags'] .= Html::openElement(
'ul' );
400 foreach ( $flags as $flag ) {
401 $help[
'flags'] .= Html::rawElement(
'li', [],
408 self::wrap( $context->
msg(
"api-help-flag-$flag" ),
"apihelp-flag-$flag" )
411 $sourceInfo = $module->getModuleSourceInfo();
413 if ( isset( $sourceInfo[
'namemsg'] ) ) {
414 $extname = $context->
msg( $sourceInfo[
'namemsg'] )->text();
417 $extname = Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'name'] );
419 $help[
'flags'] .= Html::rawElement(
'li', [],
421 $context->
msg(
'api-help-source', $extname, $sourceInfo[
'name'] ),
426 $link = SpecialPage::getTitleFor(
'Version',
'License/' . $sourceInfo[
'name'] );
427 if ( isset( $sourceInfo[
'license-name'] ) ) {
428 $msg = $context->
msg(
'api-help-license', $link,
429 Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'license-name'] )
431 } elseif ( ExtensionInfo::getLicenseFileNames( dirname( $sourceInfo[
'path'] ) ) ) {
432 $msg = $context->
msg(
'api-help-license-noname', $link );
434 $msg = $context->
msg(
'api-help-license-unknown' );
436 $help[
'flags'] .= Html::rawElement(
'li', [],
437 self::wrap( $msg,
'apihelp-license' )
440 $help[
'flags'] .= Html::rawElement(
'li', [],
441 self::wrap( $context->
msg(
'api-help-source-unknown' ),
'apihelp-source' )
443 $help[
'flags'] .= Html::rawElement(
'li', [],
444 self::wrap( $context->
msg(
'api-help-license-unknown' ),
'apihelp-license' )
447 $help[
'flags'] .= Html::closeElement(
'ul' );
448 $help[
'flags'] .= Html::closeElement(
'div' );
450 foreach ( $module->getFinalDescription() as $msg ) {
451 $msg->setContext( $context );
452 $help[
'description'] .= $msg->parseAsBlock();
455 $urls = $module->getHelpUrls();
457 if ( !is_array( $urls ) ) {
460 $help[
'help-urls'] .= Html::openElement(
'div',
461 [
'class' => [
'apihelp-block',
'apihelp-help-urls' ] ]
463 $msg = $context->
msg(
'api-help-help-urls' );
464 if ( !$msg->isDisabled() ) {
465 $help[
'help-urls'] .= self::wrap(
466 $msg->numParams( count( $urls ) ),
'apihelp-block-head',
'div'
469 $help[
'help-urls'] .= Html::openElement(
'ul' );
470 foreach ( $urls as $url ) {
471 $help[
'help-urls'] .= Html::rawElement(
'li', [],
472 Html::element(
'a', [
'href' => $url,
'dir' =>
'ltr' ], $url )
475 $help[
'help-urls'] .= Html::closeElement(
'ul' );
476 $help[
'help-urls'] .= Html::closeElement(
'div' );
479 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
480 $dynamicParams = $module->dynamicParameterDocumentation();
482 if (
$params || $dynamicParams !==
null ) {
483 $help[
'parameters'] .= Html::openElement(
'div',
484 [
'class' => [
'apihelp-block',
'apihelp-parameters' ] ]
486 $msg = $context->
msg(
'api-help-parameters' );
487 if ( !$msg->isDisabled() ) {
488 $help[
'parameters'] .= self::wrap(
489 $msg->numParams( count(
$params ) ),
'apihelp-block-head',
'div'
491 if ( !$module->isMain() ) {
493 $help[
'parameters'] .= self::wrap(
494 $context->
msg(
'api-help-parameters-note' ),
'apihelp-block-header',
'div'
498 $help[
'parameters'] .= Html::openElement(
'dl' );
500 $descriptions = $module->getFinalParamDescription();
502 foreach (
$params as $name => $settings ) {
503 $settings = $paramValidator->normalizeSettings( $settings );
505 if ( $settings[ParamValidator::PARAM_TYPE] ===
'submodule' ) {
509 $encodedParamName = $module->encodeParamName( $name );
510 $paramNameAttribs = [
'dir' =>
'ltr',
'lang' =>
'en' ];
511 if ( isset( $anchor ) ) {
512 $paramNameAttribs[
'id'] =
"$anchor:$encodedParamName";
514 $help[
'parameters'] .= Html::rawElement(
'dt', [],
515 Html::element(
'span', $paramNameAttribs, $encodedParamName )
520 if ( isset( $descriptions[$name] ) ) {
521 foreach ( $descriptions[$name] as $msg ) {
522 $msg->setContext( $context );
523 $description[] = $msg->parseAsBlock();
526 if ( !array_filter( $description ) ) {
527 $description = [ self::wrap(
528 $context->
msg(
'api-help-param-no-description' ),
534 if ( !empty( $settings[ParamValidator::PARAM_DEPRECATED] ) ) {
535 $help[
'parameters'] .= Html::openElement(
'dd',
536 [
'class' =>
'info' ] );
537 $help[
'parameters'] .= self::wrap(
538 $context->
msg(
'api-help-param-deprecated' ),
539 'apihelp-deprecated',
'strong'
541 $help[
'parameters'] .= Html::closeElement(
'dd' );
544 if ( $description ) {
545 $description = implode(
'', $description );
546 $description = preg_replace(
'!\s*</([oud]l)>\s*<\1>\s*!',
"\n", $description );
547 $help[
'parameters'] .= Html::rawElement(
'dd',
548 [
'class' =>
'description' ], $description );
553 $paramHelp = $paramValidator->getHelpInfo( $module, $name, $settings, [] );
555 unset( $paramHelp[ParamValidator::PARAM_DEPRECATED] );
557 if ( isset( $paramHelp[ParamValidator::PARAM_REQUIRED] ) ) {
558 $paramHelp[ParamValidator::PARAM_REQUIRED]->setContext( $context );
559 $info[] = $paramHelp[ParamValidator::PARAM_REQUIRED];
560 unset( $paramHelp[ParamValidator::PARAM_REQUIRED] );
564 if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
565 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
566 $tag = array_shift( $i );
567 $info[] = $context->
msg(
"apihelp-{$path}-paraminfo-{$tag}" )
568 ->numParams( count( $i ) )
569 ->params( $context->
getLanguage()->commaList( $i ) )
570 ->params( $module->getModulePrefix() )
576 if ( !empty( $settings[ApiBase::PARAM_TEMPLATE_VARS] ) ) {
578 $msg =
'api-help-param-templated-var-first';
579 foreach ( $settings[ApiBase::PARAM_TEMPLATE_VARS] as $k => $v ) {
580 $vars[] = $context->
msg( $msg, $k, $module->encodeParamName( $v ) );
581 $msg =
'api-help-param-templated-var';
583 $info[] = $context->
msg(
'api-help-param-templated' )
584 ->numParams( count( $vars ) )
585 ->params( Message::listParam( $vars ) )
590 foreach ( $paramHelp as $m ) {
591 $m->setContext( $context );
592 $info[] = $m->parse();
595 foreach ( $info as $i ) {
596 $help[
'parameters'] .= Html::rawElement(
'dd', [
'class' =>
'info' ], $i );
600 if ( $dynamicParams !==
null ) {
602 $module->getModulePrefix(),
603 $module->getModuleName(),
604 $module->getModulePath()
606 $help[
'parameters'] .= Html::element(
'dt', [],
'*' );
607 $help[
'parameters'] .= Html::rawElement(
'dd',
608 [
'class' =>
'description' ], $dynamicParams->parse() );
611 $help[
'parameters'] .= Html::closeElement(
'dl' );
612 $help[
'parameters'] .= Html::closeElement(
'div' );
615 $examples = $module->getExamplesMessages();
617 $help[
'examples'] .= Html::openElement(
'div',
618 [
'class' => [
'apihelp-block',
'apihelp-examples' ] ] );
619 $msg = $context->
msg(
'api-help-examples' );
620 if ( !$msg->isDisabled() ) {
621 $help[
'examples'] .= self::wrap(
622 $msg->numParams( count( $examples ) ),
'apihelp-block-head',
'div'
626 $help[
'examples'] .= Html::openElement(
'dl' );
627 foreach ( $examples as $qs => $msg ) {
629 $module->getModulePrefix(),
630 $module->getModuleName(),
631 $module->getModulePath()
635 $sandbox = SpecialPage::getTitleFor(
'ApiSandbox' )->getLocalURL() .
'#' . $qs;
636 $help[
'examples'] .= Html::rawElement(
'dt', [], $msg->parse() );
637 $help[
'examples'] .= Html::rawElement(
'dd', [],
638 Html::element(
'a', [
642 ],
"api.php?$qs" ) .
' ' .
643 Html::rawElement(
'a', [
'href' => $sandbox ],
644 $context->
msg(
'api-help-open-in-apisandbox' )->parse() )
647 $help[
'examples'] .= Html::closeElement(
'dl' );
648 $help[
'examples'] .= Html::closeElement(
'div' );
651 $subtocnumber = $tocnumber;
652 $subtocnumber[$level + 1] = 0;
654 'submodules' => $options[
'recursivesubmodules'],
655 'headerlevel' => $level + 1,
656 'tocnumber' => &$subtocnumber,
661 if ( $options[
'submodules'] && $module->getModuleManager() ) {
662 $manager = $module->getModuleManager();
664 foreach ( $groups as $group ) {
665 $names = $manager->getNames( $group );
667 foreach ( $names as $name ) {
668 $submodules[] = $manager->getModule( $name );
671 $help[
'submodules'] .= self::getHelpInternal(
679 $module->modifyHelp( $help, $suboptions, $haveModules );
681 $module->getHookRunner()->onAPIHelpModifyOutput( $module, $help,
682 $suboptions, $haveModules );
684 $out .= implode(
"\n", $help );
705 $errorPrinter = $main->createPrinterByName( $main->getParameter(
'format' ) );
712 ParamValidator::PARAM_DEFAULT =>
'main',
713 ParamValidator::PARAM_ISMULTI =>
true,
715 'submodules' =>
false,
716 'recursivesubmodules' =>
false,
725 =>
'apihelp-help-example-main',
726 'action=help&modules=query&submodules=1'
727 =>
'apihelp-help-example-submodules',
728 'action=help&recursivesubmodules=1'
729 =>
'apihelp-help-example-recursive',
730 'action=help&modules=help'
731 =>
'apihelp-help-example-help',
732 'action=help&modules=query+info|query+categorymembers'
733 =>
'apihelp-help-example-query',
739 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
740 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
741 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',
This is the main API class, used for both external and internal processing.