43 parent::__construct( $main, $action );
44 $this->skinFactory = $skinFactory;
51 foreach ( $params[
'modules'] as
$path ) {
57 $context->setSkin( $this->skinFactory->makeSkin(
'apioutput' ) );
61 $out->setRobotPolicy(
'noindex,nofollow' );
62 $out->setCopyrightUrl(
'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
63 $out->disallowUserJs();
64 $context->setOutput( $out );
71 $html = ob_get_clean();
74 if ( $params[
'wrap'] ) {
76 'mime' =>
'text/html',
77 'filename' =>
'api-help.html',
85 'Types' => [
'AssocAsObject' => true ],
88 $errors = array_filter( [
89 'errors' => $this->
getResult()->getResultData( [
'errors' ], $transform ),
90 'warnings' => $this->
getResult()->getResultData( [
'warnings' ], $transform ),
93 $json = FormatJson::encode( $errors,
true, FormatJson::UTF8_OK );
96 $json = str_replace(
'--',
'-\u002D', $json );
97 $html =
"<!-- API warnings and errors:\n$json\n-->\n$html";
127 if ( !is_array( $modules ) ) {
128 $modules = [ $modules ];
132 $out->addModuleStyles( [
134 'mediawiki.apipretty',
136 $out->setPageTitleMsg( $context->
msg(
'api-help-title' ) );
139 $cache = $services->getMainWANObjectCache();
141 if ( count( $modules ) == 1 && $modules[0] instanceof
ApiMain &&
142 $options[
'recursivesubmodules'] &&
143 $context->
getLanguage()->equals( $services->getContentLanguage() )
146 if ( $cacheHelpTimeout > 0 ) {
148 $cacheKey = $cache->makeKey(
'apihelp', $modules[0]->
getModulePath(),
149 (
int)!empty( $options[
'toc'] ),
150 str_replace(
' ',
'_', SpecialVersion::getVersion(
'nodb' ) ) );
151 $cached = $cache->get( $cacheKey );
153 $out->addHTML( $cached );
158 if ( $out->getHTML() !==
'' ) {
164 $options[
'recursivesubmodules'] = !empty( $options[
'recursivesubmodules'] );
165 $options[
'submodules'] = $options[
'recursivesubmodules'] || !empty( $options[
'submodules'] );
168 if ( empty( $options[
'nolead'] ) ) {
169 $msg = $context->
msg(
'api-help-lead' );
170 if ( !$msg->isDisabled() ) {
171 $out->addHTML( $msg->parseAsBlock() );
176 $html = self::getHelpInternal( $context, $modules, $options, $haveModules );
177 if ( !empty( $options[
'toc'] ) && $haveModules ) {
178 $out->addTOCPlaceholder( TOCData::fromLegacy( array_values( $haveModules ) ) );
180 $out->addHTML( $html );
182 $helptitle = $options[
'helptitle'] ??
null;
185 $out->addHTML( $html );
187 if ( $cacheKey !==
null ) {
189 $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
201 public static function fixHelpLinks( $html, $helptitle =
null, $localModules = [] ) {
204 static function ( SerializerNode $node ):
bool {
205 return $node->name ===
'a'
206 && isset( $node->attrs[
'href'] )
207 && !str_contains( $node->attrs[
'class'] ??
'',
'apihelp-linktrail' );
209 static function ( SerializerNode $node ) use ( $helptitle, $localModules ): SerializerNode {
210 $href = $node->attrs[
'href'];
214 $href = rawurldecode( $href );
215 }
while ( $old !== $href );
216 if ( preg_match(
'!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
217 if ( isset( $localModules[$m[1]] ) ) {
218 $href = $m[2] ===
'' ?
'#' . $m[1] : $m[2];
219 } elseif ( $helptitle !==
null ) {
220 $href = Title::newFromText( str_replace(
'$1', $m[1], $helptitle ) . $m[2] )
228 $node->attrs[
'href'] = $href;
229 unset( $node->attrs[
'title'] );
245 private static function wrap(
Message $msg, $class, $tag =
'span' ) {
246 return Html::rawElement( $tag, [
'class' => $class ],
260 private static function getHelpInternal(
IContextSource $context, array $modules,
261 array $options, &$haveModules
265 $level = empty( $options[
'headerlevel'] ) ? 2 : $options[
'headerlevel'];
266 if ( empty( $options[
'tocnumber'] ) ) {
267 $tocnumber = [ 2 => 0 ];
269 $tocnumber = &$options[
'tocnumber'];
272 foreach ( $modules as $module ) {
273 $paramValidator = $module->getMain()->getParamValidator();
274 $tocnumber[$level]++;
275 $path = $module->getModulePath();
276 $module->setContext( $context );
287 if ( empty( $options[
'noheader'] ) || !empty( $options[
'toc'] ) ) {
290 while ( isset( $haveModules[$anchor] ) ) {
291 $anchor =
$path .
'|' . ++$i;
294 if ( $module->isMain() ) {
295 $headerContent = $context->
msg(
'api-help-main-header' )->parse();
297 'class' =>
'apihelp-header',
300 $name = $module->getModuleName();
301 $headerContent = htmlspecialchars(
302 $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
"=$name"
304 if ( $module->getModulePrefix() !==
'' ) {
305 $headerContent .=
' ' .
306 $context->
msg(
'parentheses', $module->getModulePrefix() )->parse();
312 'class' => [
'apihelp-header',
'apihelp-module-name' ],
318 $headerAttr[
'id'] = $anchor;
321 $haveModules[$anchor] = [
322 'toclevel' => count( $tocnumber ),
325 'line' => $headerContent,
326 'number' => implode(
'.', $tocnumber ),
329 if ( empty( $options[
'noheader'] ) ) {
330 $help[
'header'] .= Html::rawElement(
331 'h' . min( 6, $level ),
337 $haveModules[
$path] =
true;
342 for ( $m = $module; $m !==
null; $m = $m->getParent() ) {
343 $name = $m->getModuleName();
344 if ( $name ===
'main_int' ) {
348 if ( count( $modules ) === 1 && $m === $modules[0] &&
349 !( !empty( $options[
'submodules'] ) && $m->getModuleManager() )
351 $link =
Html::element(
'b', [
'dir' =>
'ltr',
'lang' =>
'en' ], $name );
355 [
'href' => $link,
'class' =>
'apihelp-linktrail',
'dir' =>
'ltr',
'lang' =>
'en' ],
360 array_unshift( $links, $link );
363 $help[
'header'] .= self::wrap(
364 $context->
msg(
'parentheses' )
365 ->rawParams( $context->
getLanguage()->pipeList( $links ) ),
366 'apihelp-linktrail',
'div'
370 $flags = $module->getHelpFlags();
371 $help[
'flags'] .= Html::openElement(
'div',
372 [
'class' => [
'apihelp-block',
'apihelp-flags' ] ] );
373 $msg = $context->
msg(
'api-help-flags' );
374 if ( !$msg->isDisabled() ) {
375 $help[
'flags'] .= self::wrap(
376 $msg->numParams( count( $flags ) ),
'apihelp-block-head',
'div'
379 $help[
'flags'] .= Html::openElement(
'ul' );
380 foreach ( $flags as $flag ) {
381 $help[
'flags'] .= Html::rawElement(
'li', [],
388 self::wrap( $context->
msg(
"api-help-flag-$flag" ),
"apihelp-flag-$flag" )
391 $sourceInfo = $module->getModuleSourceInfo();
393 if ( isset( $sourceInfo[
'namemsg'] ) ) {
394 $extname = $context->
msg( $sourceInfo[
'namemsg'] )->text();
397 $extname =
Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'name'] );
399 $help[
'flags'] .= Html::rawElement(
'li', [],
401 $context->
msg(
'api-help-source', $extname, $sourceInfo[
'name'] ),
408 if ( isset( $sourceInfo[
'license-name'] ) ) {
409 $msg = $context->
msg(
'api-help-license', $linkText,
410 Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'license-name'] )
412 } elseif ( ExtensionInfo::getLicenseFileNames( dirname( $sourceInfo[
'path'] ) ) ) {
413 $msg = $context->
msg(
'api-help-license-noname', $linkText );
415 $msg = $context->
msg(
'api-help-license-unknown' );
417 $help[
'flags'] .= Html::rawElement(
'li', [],
418 self::wrap( $msg,
'apihelp-license' )
421 $help[
'flags'] .= Html::rawElement(
'li', [],
422 self::wrap( $context->
msg(
'api-help-source-unknown' ),
'apihelp-source' )
424 $help[
'flags'] .= Html::rawElement(
'li', [],
425 self::wrap( $context->
msg(
'api-help-license-unknown' ),
'apihelp-license' )
428 $help[
'flags'] .= Html::closeElement(
'ul' );
429 $help[
'flags'] .= Html::closeElement(
'div' );
431 foreach ( $module->getFinalDescription() as $msg ) {
432 $msg->setContext( $context );
433 $help[
'description'] .= $msg->parseAsBlock();
436 $urls = $module->getHelpUrls();
438 if ( !is_array( $urls ) ) {
441 $help[
'help-urls'] .= Html::openElement(
'div',
442 [
'class' => [
'apihelp-block',
'apihelp-help-urls' ] ]
444 $msg = $context->
msg(
'api-help-help-urls' );
445 if ( !$msg->isDisabled() ) {
446 $help[
'help-urls'] .= self::wrap(
447 $msg->numParams( count( $urls ) ),
'apihelp-block-head',
'div'
450 $help[
'help-urls'] .= Html::openElement(
'ul' );
451 foreach ( $urls as
$url ) {
452 $help[
'help-urls'] .= Html::rawElement(
'li', [],
456 $help[
'help-urls'] .= Html::closeElement(
'ul' );
457 $help[
'help-urls'] .= Html::closeElement(
'div' );
461 $dynamicParams = $module->dynamicParameterDocumentation();
463 if ( $params || $dynamicParams !==
null ) {
464 $help[
'parameters'] .= Html::openElement(
'div',
465 [
'class' => [
'apihelp-block',
'apihelp-parameters' ] ]
467 $msg = $context->
msg(
'api-help-parameters' );
468 if ( !$msg->isDisabled() ) {
469 $help[
'parameters'] .= self::wrap(
470 $msg->numParams( count( $params ) ),
'apihelp-block-head',
'div'
472 if ( !$module->isMain() ) {
474 $help[
'parameters'] .= self::wrap(
475 $context->
msg(
'api-help-parameters-note' ),
'apihelp-block-header',
'div'
479 $help[
'parameters'] .= Html::openElement(
'dl' );
481 $descriptions = $module->getFinalParamDescription();
483 foreach ( $params as $name => $settings ) {
484 $settings = $paramValidator->normalizeSettings( $settings );
486 if ( $settings[ParamValidator::PARAM_TYPE] ===
'submodule' ) {
490 $encodedParamName = $module->encodeParamName( $name );
491 $paramNameAttribs = [
'dir' =>
'ltr',
'lang' =>
'en' ];
492 if ( isset( $anchor ) ) {
493 $paramNameAttribs[
'id'] =
"$anchor:$encodedParamName";
495 $help[
'parameters'] .= Html::rawElement(
'dt', [],
496 Html::element(
'span', $paramNameAttribs, $encodedParamName )
501 if ( isset( $descriptions[$name] ) ) {
502 foreach ( $descriptions[$name] as $msg ) {
503 $msg->setContext( $context );
504 $description[] = $msg->parseAsBlock();
507 if ( !array_filter( $description ) ) {
508 $description = [ self::wrap(
509 $context->
msg(
'api-help-param-no-description' ),
515 if ( !empty( $settings[ParamValidator::PARAM_DEPRECATED] ) ) {
516 $help[
'parameters'] .= Html::openElement(
'dd',
517 [
'class' =>
'info' ] );
518 $help[
'parameters'] .= self::wrap(
519 $context->
msg(
'api-help-param-deprecated' ),
520 'apihelp-deprecated',
'strong'
522 $help[
'parameters'] .= Html::closeElement(
'dd' );
525 if ( $description ) {
526 $description = implode(
'', $description );
527 $description = preg_replace(
'!\s*</([oud]l)>\s*<\1>\s*!',
"\n", $description );
528 $help[
'parameters'] .= Html::rawElement(
'dd',
529 [
'class' =>
'description' ], $description );
534 $paramHelp = $paramValidator->getHelpInfo( $module, $name, $settings, [] );
536 unset( $paramHelp[ParamValidator::PARAM_DEPRECATED] );
538 if ( isset( $paramHelp[ParamValidator::PARAM_REQUIRED] ) ) {
539 $paramHelp[ParamValidator::PARAM_REQUIRED]->setContext( $context );
540 $info[] = $paramHelp[ParamValidator::PARAM_REQUIRED];
541 unset( $paramHelp[ParamValidator::PARAM_REQUIRED] );
547 $tag = array_shift( $i );
548 $info[] = $context->
msg(
"apihelp-{$path}-paraminfo-{$tag}" )
549 ->numParams( count( $i ) )
550 ->params( $context->
getLanguage()->commaList( $i ) )
551 ->params( $module->getModulePrefix() )
559 $msg =
'api-help-param-templated-var-first';
561 $vars[] = $context->
msg( $msg, $k, $module->encodeParamName( $v ) );
562 $msg =
'api-help-param-templated-var';
564 $info[] = $context->
msg(
'api-help-param-templated' )
565 ->numParams( count( $vars ) )
571 foreach ( $paramHelp as $m ) {
572 $m->setContext( $context );
573 $info[] = $m->parse();
576 foreach ( $info as $i ) {
577 $help[
'parameters'] .= Html::rawElement(
'dd', [
'class' =>
'info' ], $i );
581 if ( $dynamicParams !==
null ) {
582 $dynamicParams = $context->
msg(
584 $module->getModulePrefix(),
585 $module->getModuleName(),
586 $module->getModulePath()
589 $help[
'parameters'] .= Html::rawElement(
'dd',
590 [
'class' =>
'description' ], $dynamicParams->parse() );
593 $help[
'parameters'] .= Html::closeElement(
'dl' );
594 $help[
'parameters'] .= Html::closeElement(
'div' );
597 $examples = $module->getExamplesMessages();
599 $help[
'examples'] .= Html::openElement(
'div',
600 [
'class' => [
'apihelp-block',
'apihelp-examples' ] ] );
601 $msg = $context->
msg(
'api-help-examples' );
602 if ( !$msg->isDisabled() ) {
603 $help[
'examples'] .= self::wrap(
604 $msg->numParams( count( $examples ) ),
'apihelp-block-head',
'div'
608 $help[
'examples'] .= Html::openElement(
'dl' );
609 foreach ( $examples as $qs => $msg ) {
610 $msg = $context->
msg(
612 $module->getModulePrefix(),
613 $module->getModuleName(),
614 $module->getModulePath()
619 $help[
'examples'] .= Html::rawElement(
'dt', [], $msg->parse() );
620 $help[
'examples'] .= Html::rawElement(
'dd', [],
625 ],
"api.php?$qs" ) .
' ' .
626 Html::rawElement(
'a', [
'href' => $sandbox ],
627 $context->
msg(
'api-help-open-in-apisandbox' )->parse() )
630 $help[
'examples'] .= Html::closeElement(
'dl' );
631 $help[
'examples'] .= Html::closeElement(
'div' );
634 $subtocnumber = $tocnumber;
635 $subtocnumber[$level + 1] = 0;
637 'submodules' => $options[
'recursivesubmodules'],
638 'headerlevel' => $level + 1,
639 'tocnumber' => &$subtocnumber,
644 if ( $options[
'submodules'] && $module->getModuleManager() ) {
645 $manager = $module->getModuleManager();
647 foreach ( $groups as $group ) {
648 $names = $manager->getNames( $group );
650 foreach ( $names as $name ) {
651 $submodules[] = $manager->getModule( $name );
654 $help[
'submodules'] .= self::getHelpInternal(
662 $module->modifyHelp( $help, $suboptions, $haveModules );
664 $module->getHookRunner()->onAPIHelpModifyOutput( $module, $help,
665 $suboptions, $haveModules );
667 $out .= implode(
"\n", $help );
686 if ( $params[
'wrap'] ) {
691 $errorPrinter = $main->createPrinterByName( $main->getParameter(
'format' ) );
699 ParamValidator::PARAM_DEFAULT =>
'main',
700 ParamValidator::PARAM_ISMULTI =>
true,
702 'submodules' =>
false,
703 'recursivesubmodules' =>
false,
713 =>
'apihelp-help-example-main',
714 'action=help&modules=query&submodules=1'
715 =>
'apihelp-help-example-submodules',
716 'action=help&recursivesubmodules=1'
717 =>
'apihelp-help-example-recursive',
718 'action=help&modules=help'
719 =>
'apihelp-help-example-help',
720 'action=help&modules=query+info|query+categorymembers'
721 =>
'apihelp-help-example-query',
728 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
729 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
730 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',