54 parent::__construct( $main, $action );
55 $this->skinFactory = $skinFactory;
62 foreach ( $params[
'modules'] as
$path ) {
68 $context->setSkin( $this->skinFactory->makeSkin(
'apioutput' ) );
72 $out->setRobotPolicy(
'noindex,nofollow' );
73 $out->setCopyrightUrl(
'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
74 $out->disallowUserJs();
75 $context->setOutput( $out );
82 $html = ob_get_clean();
85 if ( $params[
'wrap'] ) {
87 'mime' =>
'text/html',
88 'filename' =>
'api-help.html',
91 ApiResult::setSubelementsList( $data,
'help' );
96 'Types' => [
'AssocAsObject' =>
true ],
99 $errors = array_filter( [
100 'errors' => $this->
getResult()->getResultData( [
'errors' ], $transform ),
101 'warnings' => $this->
getResult()->getResultData( [
'warnings' ], $transform ),
104 $json = FormatJson::encode( $errors,
true, FormatJson::UTF8_OK );
107 $json = str_replace(
'--',
'-\u002D', $json );
108 $html =
"<!-- API warnings and errors:\n$json\n-->\n$html";
112 $result->addValue(
null,
'text', $html, ApiResult::NO_SIZE_CHECK );
113 $result->addValue(
null,
'mime',
'text/html', ApiResult::NO_SIZE_CHECK );
114 $result->addValue(
null,
'filename',
'api-help.html', ApiResult::NO_SIZE_CHECK );
143 $out->addModuleStyles( [
145 'mediawiki.apipretty',
147 $out->setPageTitle( $context->
msg(
'api-help-title' ) );
149 $services = MediaWikiServices::getInstance();
150 $cache = $services->getMainWANObjectCache();
153 $options[
'recursivesubmodules'] &&
154 $context->
getLanguage()->equals( $services->getContentLanguage() )
156 $cacheHelpTimeout = $context->
getConfig()->get( MainConfigNames::APICacheHelpTimeout );
157 if ( $cacheHelpTimeout > 0 ) {
160 (
int)!empty( $options[
'toc'] ),
162 $cached = $cache->get( $cacheKey );
164 $out->addHTML( $cached );
169 if ( $out->getHTML() !==
'' ) {
175 $options[
'recursivesubmodules'] = !empty( $options[
'recursivesubmodules'] );
176 $options[
'submodules'] = $options[
'recursivesubmodules'] || !empty( $options[
'submodules'] );
179 if ( empty( $options[
'nolead'] ) ) {
180 $msg = $context->
msg(
'api-help-lead' );
181 if ( !$msg->isDisabled() ) {
182 $out->addHTML( $msg->parseAsBlock() );
187 $html = self::getHelpInternal( $context,
$modules, $options, $haveModules );
188 if ( !empty( $options[
'toc'] ) && $haveModules ) {
189 $out->addHTML( Linker::generateTOC( TOCData::fromLegacy( $haveModules ), $context->
getLanguage() ) );
191 $out->addHTML( $html );
193 $helptitle = $options[
'helptitle'] ??
null;
196 $out->addHTML( $html );
198 if ( $cacheKey !==
null ) {
200 $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
212 public static function fixHelpLinks( $html, $helptitle =
null, $localModules = [] ) {
213 return HtmlHelper::modifyElements(
215 static function ( SerializerNode $node ):
bool {
216 return $node->name ===
'a'
217 && isset( $node->attrs[
'href'] )
218 && !str_contains( $node->attrs[
'class'] ??
'',
'apihelp-linktrail' );
220 static function ( SerializerNode $node ) use ( $helptitle, $localModules ): SerializerNode {
221 $href = $node->attrs[
'href'];
225 $href = rawurldecode( $href );
226 }
while ( $old !== $href );
227 if ( preg_match(
'!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
228 if ( isset( $localModules[$m[1]] ) ) {
229 $href = $m[2] ===
'' ?
'#' . $m[1] : $m[2];
230 } elseif ( $helptitle !==
null ) {
231 $href = Title::newFromText( str_replace(
'$1', $m[1], $helptitle ) . $m[2] )
239 $node->attrs[
'href'] = $href;
240 unset( $node->attrs[
'title'] );
256 private static function wrap(
Message $msg, $class, $tag =
'span' ) {
257 return Html::rawElement( $tag, [
'class' => $class ],
272 array $options, &$haveModules
276 $level = empty( $options[
'headerlevel'] ) ? 2 : $options[
'headerlevel'];
277 if ( empty( $options[
'tocnumber'] ) ) {
278 $tocnumber = [ 2 => 0 ];
280 $tocnumber = &$options[
'tocnumber'];
284 $paramValidator = $module->getMain()->getParamValidator();
285 $tocnumber[$level]++;
286 $path = $module->getModulePath();
287 $module->setContext( $context );
298 if ( empty( $options[
'noheader'] ) || !empty( $options[
'toc'] ) ) {
301 while ( isset( $haveModules[$anchor] ) ) {
302 $anchor =
$path .
'|' . ++$i;
305 if ( $module->isMain() ) {
306 $headerContent = $context->
msg(
'api-help-main-header' )->parse();
308 'class' =>
'apihelp-header',
311 $name = $module->getModuleName();
312 $headerContent = htmlspecialchars(
313 $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
"=$name"
315 if ( $module->getModulePrefix() !==
'' ) {
316 $headerContent .=
' ' .
317 $context->
msg(
'parentheses', $module->getModulePrefix() )->parse();
323 'class' => [
'apihelp-header',
'apihelp-module-name' ],
329 $headerAttr[
'id'] = $anchor;
332 $haveModules[$anchor] = [
333 'toclevel' => count( $tocnumber ),
336 'line' => $headerContent,
337 'number' => implode(
'.', $tocnumber ),
340 if ( empty( $options[
'noheader'] ) ) {
341 $help[
'header'] .= Html::rawElement(
342 'h' . min( 6, $level ),
348 $haveModules[
$path] =
true;
353 for ( $m = $module; $m !==
null; $m = $m->getParent() ) {
354 $name = $m->getModuleName();
355 if ( $name ===
'main_int' ) {
360 !( !empty( $options[
'submodules'] ) && $m->getModuleManager() )
362 $link = Html::element(
'b', [
'dir' =>
'ltr',
'lang' =>
'en' ], $name );
365 $link = Html::element(
'a',
366 [
'href' => $link,
'class' =>
'apihelp-linktrail',
'dir' =>
'ltr',
'lang' =>
'en' ],
371 array_unshift( $links, $link );
374 $help[
'header'] .= self::wrap(
375 $context->
msg(
'parentheses' )
376 ->rawParams( $context->
getLanguage()->pipeList( $links ) ),
377 'apihelp-linktrail',
'div'
381 $flags = $module->getHelpFlags();
382 $help[
'flags'] .= Html::openElement(
'div',
383 [
'class' => [
'apihelp-block',
'apihelp-flags' ] ] );
384 $msg = $context->
msg(
'api-help-flags' );
385 if ( !$msg->isDisabled() ) {
386 $help[
'flags'] .= self::wrap(
387 $msg->numParams( count( $flags ) ),
'apihelp-block-head',
'div'
390 $help[
'flags'] .= Html::openElement(
'ul' );
391 foreach ( $flags as $flag ) {
392 $help[
'flags'] .= Html::rawElement(
'li', [],
399 self::wrap( $context->
msg(
"api-help-flag-$flag" ),
"apihelp-flag-$flag" )
402 $sourceInfo = $module->getModuleSourceInfo();
404 if ( isset( $sourceInfo[
'namemsg'] ) ) {
405 $extname = $context->
msg( $sourceInfo[
'namemsg'] )->text();
408 $extname = Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'name'] );
410 $help[
'flags'] .= Html::rawElement(
'li', [],
412 $context->
msg(
'api-help-source', $extname, $sourceInfo[
'name'] ),
418 if ( isset( $sourceInfo[
'license-name'] ) ) {
419 $msg = $context->
msg(
'api-help-license', $link,
420 Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'license-name'] )
422 } elseif ( ExtensionInfo::getLicenseFileNames( dirname( $sourceInfo[
'path'] ) ) ) {
423 $msg = $context->
msg(
'api-help-license-noname', $link );
425 $msg = $context->
msg(
'api-help-license-unknown' );
427 $help[
'flags'] .= Html::rawElement(
'li', [],
428 self::wrap( $msg,
'apihelp-license' )
431 $help[
'flags'] .= Html::rawElement(
'li', [],
432 self::wrap( $context->
msg(
'api-help-source-unknown' ),
'apihelp-source' )
434 $help[
'flags'] .= Html::rawElement(
'li', [],
435 self::wrap( $context->
msg(
'api-help-license-unknown' ),
'apihelp-license' )
438 $help[
'flags'] .= Html::closeElement(
'ul' );
439 $help[
'flags'] .= Html::closeElement(
'div' );
441 foreach ( $module->getFinalDescription() as $msg ) {
442 $msg->setContext( $context );
443 $help[
'description'] .= $msg->parseAsBlock();
446 $urls = $module->getHelpUrls();
448 if ( !is_array( $urls ) ) {
451 $help[
'help-urls'] .= Html::openElement(
'div',
452 [
'class' => [
'apihelp-block',
'apihelp-help-urls' ] ]
454 $msg = $context->
msg(
'api-help-help-urls' );
455 if ( !$msg->isDisabled() ) {
456 $help[
'help-urls'] .= self::wrap(
457 $msg->numParams( count( $urls ) ),
'apihelp-block-head',
'div'
460 $help[
'help-urls'] .= Html::openElement(
'ul' );
461 foreach ( $urls as $url ) {
462 $help[
'help-urls'] .= Html::rawElement(
'li', [],
463 Html::element(
'a', [
'href' => $url,
'dir' =>
'ltr' ], $url )
466 $help[
'help-urls'] .= Html::closeElement(
'ul' );
467 $help[
'help-urls'] .= Html::closeElement(
'div' );
470 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
471 $dynamicParams = $module->dynamicParameterDocumentation();
473 if ( $params || $dynamicParams !==
null ) {
474 $help[
'parameters'] .= Html::openElement(
'div',
475 [
'class' => [
'apihelp-block',
'apihelp-parameters' ] ]
477 $msg = $context->
msg(
'api-help-parameters' );
478 if ( !$msg->isDisabled() ) {
479 $help[
'parameters'] .= self::wrap(
480 $msg->numParams( count( $params ) ),
'apihelp-block-head',
'div'
482 if ( !$module->isMain() ) {
484 $help[
'parameters'] .= self::wrap(
485 $context->
msg(
'api-help-parameters-note' ),
'apihelp-block-header',
'div'
489 $help[
'parameters'] .= Html::openElement(
'dl' );
491 $descriptions = $module->getFinalParamDescription();
493 foreach ( $params as $name => $settings ) {
494 $settings = $paramValidator->normalizeSettings( $settings );
496 if ( $settings[ParamValidator::PARAM_TYPE] ===
'submodule' ) {
500 $help[
'parameters'] .= Html::rawElement(
'dt', [],
501 Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $module->encodeParamName( $name ) )
506 if ( isset( $descriptions[$name] ) ) {
507 foreach ( $descriptions[$name] as $msg ) {
508 $msg->setContext( $context );
509 $description[] = $msg->parseAsBlock();
512 if ( !array_filter( $description ) ) {
513 $description = [ self::wrap(
514 $context->
msg(
'api-help-param-no-description' ),
520 if ( !empty( $settings[ParamValidator::PARAM_DEPRECATED] ) ) {
521 $help[
'parameters'] .= Html::openElement(
'dd',
522 [
'class' =>
'info' ] );
523 $help[
'parameters'] .= self::wrap(
524 $context->
msg(
'api-help-param-deprecated' ),
525 'apihelp-deprecated',
'strong'
527 $help[
'parameters'] .= Html::closeElement(
'dd' );
530 if ( $description ) {
531 $description = implode(
'', $description );
532 $description = preg_replace(
'!\s*</([oud]l)>\s*<\1>\s*!',
"\n", $description );
533 $help[
'parameters'] .= Html::rawElement(
'dd',
534 [
'class' =>
'description' ], $description );
539 $paramHelp = $paramValidator->getHelpInfo( $module, $name, $settings, [] );
541 unset( $paramHelp[ParamValidator::PARAM_DEPRECATED] );
543 if ( isset( $paramHelp[ParamValidator::PARAM_REQUIRED] ) ) {
544 $paramHelp[ParamValidator::PARAM_REQUIRED]->setContext( $context );
545 $info[] = $paramHelp[ParamValidator::PARAM_REQUIRED];
546 unset( $paramHelp[ParamValidator::PARAM_REQUIRED] );
550 if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
551 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
552 $tag = array_shift( $i );
553 $info[] = $context->
msg(
"apihelp-{$path}-paraminfo-{$tag}" )
554 ->numParams( count( $i ) )
555 ->params( $context->
getLanguage()->commaList( $i ) )
556 ->params( $module->getModulePrefix() )
562 if ( !empty( $settings[ApiBase::PARAM_TEMPLATE_VARS] ) ) {
564 $msg =
'api-help-param-templated-var-first';
565 foreach ( $settings[ApiBase::PARAM_TEMPLATE_VARS] as $k => $v ) {
566 $vars[] = $context->
msg( $msg, $k, $module->encodeParamName( $v ) );
567 $msg =
'api-help-param-templated-var';
569 $info[] = $context->
msg(
'api-help-param-templated' )
570 ->numParams( count( $vars ) )
576 foreach ( $paramHelp as $m ) {
577 $m->setContext( $context );
581 foreach ( $info as $i ) {
582 $help[
'parameters'] .= Html::rawElement(
'dd', [
'class' =>
'info' ], $i );
586 if ( $dynamicParams !==
null ) {
588 $module->getModulePrefix(),
589 $module->getModuleName(),
590 $module->getModulePath()
592 $help[
'parameters'] .= Html::element(
'dt', [],
'*' );
593 $help[
'parameters'] .= Html::rawElement(
'dd',
594 [
'class' =>
'description' ], $dynamicParams->parse() );
597 $help[
'parameters'] .= Html::closeElement(
'dl' );
598 $help[
'parameters'] .= Html::closeElement(
'div' );
601 $examples = $module->getExamplesMessages();
603 $help[
'examples'] .= Html::openElement(
'div',
604 [
'class' => [
'apihelp-block',
'apihelp-examples' ] ] );
605 $msg = $context->
msg(
'api-help-examples' );
606 if ( !$msg->isDisabled() ) {
607 $help[
'examples'] .= self::wrap(
608 $msg->numParams( count( $examples ) ),
'apihelp-block-head',
'div'
612 $help[
'examples'] .= Html::openElement(
'dl' );
613 foreach ( $examples as $qs => $msg ) {
615 $module->getModulePrefix(),
616 $module->getModuleName(),
617 $module->getModulePath()
622 $help[
'examples'] .= Html::rawElement(
'dt', [], $msg->parse() );
623 $help[
'examples'] .= Html::rawElement(
'dd', [],
624 Html::element(
'a', [
628 ],
"api.php?$qs" ) .
' ' .
629 Html::rawElement(
'a', [
'href' => $sandbox ],
630 $context->
msg(
'api-help-open-in-apisandbox' )->parse() )
633 $help[
'examples'] .= Html::closeElement(
'dl' );
634 $help[
'examples'] .= Html::closeElement(
'div' );
637 $subtocnumber = $tocnumber;
638 $subtocnumber[$level + 1] = 0;
640 'submodules' => $options[
'recursivesubmodules'],
641 'headerlevel' => $level + 1,
642 'tocnumber' => &$subtocnumber,
647 if ( $options[
'submodules'] && $module->getModuleManager() ) {
648 $manager = $module->getModuleManager();
650 foreach ( $groups as $group ) {
651 $names = $manager->getNames( $group );
653 foreach ( $names as $name ) {
654 $submodules[] = $manager->getModule( $name );
657 $help[
'submodules'] .= self::getHelpInternal(
665 $module->modifyHelp( $help, $suboptions, $haveModules );
667 $module->getHookRunner()->onAPIHelpModifyOutput( $module, $help,
668 $suboptions, $haveModules );
670 $out .= implode(
"\n", $help );
686 if ( $params[
'wrap'] ) {
691 $errorPrinter = $main->createPrinterByName( $main->getParameter(
'format' ) );
698 ParamValidator::PARAM_DEFAULT =>
'main',
699 ParamValidator::PARAM_ISMULTI =>
true,
701 'submodules' =>
false,
702 'recursivesubmodules' =>
false,
711 =>
'apihelp-help-example-main',
712 'action=help&modules=query&submodules=1'
713 =>
'apihelp-help-example-submodules',
714 'action=help&recursivesubmodules=1'
715 =>
'apihelp-help-example-recursive',
716 'action=help&modules=help'
717 =>
'apihelp-help-example-help',
718 'action=help&modules=query+info|query+categorymembers'
719 =>
'apihelp-help-example-query',
725 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
726 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
727 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',
This is the main API class, used for both external and internal processing.
An IContextSource implementation which will inherit context from another source but allow individual ...
This is one of the Core classes and should be read at least once by any new developers.
static getTitleFor( $name, $subpage=false, $fragment='')
Get a localised Title object for a specified special page name If you don't need a full Title object,...