3 * Copyright © 2014 Wikimedia Foundation and contributors
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
23 use HtmlFormatter\HtmlFormatter
;
24 use MediaWiki\MediaWikiServices
;
27 * Class to output help for an API module
29 * @since 1.25 completely rewritten
32 class ApiHelp
extends ApiBase
{
33 public function execute() {
34 $params = $this->extractRequestParams();
37 foreach ( $params['modules'] as $path ) {
38 $modules[] = $this->getModuleFromPath( $path );
42 $context = new DerivativeContext( $this->getMain()->getContext() );
43 $skinFactory = MediaWikiServices
::getInstance()->getSkinFactory();
44 $context->setSkin( $skinFactory->makeSkin( 'apioutput' ) );
45 $context->setLanguage( $this->getMain()->getLanguage() );
46 $context->setTitle( SpecialPage
::getTitleFor( 'ApiHelp' ) );
47 $out = new OutputPage( $context );
48 $out->setRobotPolicy( 'noindex,nofollow' );
49 $out->setCopyrightUrl( 'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
50 $context->setOutput( $out );
52 self
::getHelp( $context, $modules, $params );
54 // Grab the output from the skin
56 $context->getOutput()->output();
57 $html = ob_get_clean();
59 $result = $this->getResult();
60 if ( $params['wrap'] ) {
62 'mime' => 'text/html',
63 'filename' => 'api-help.html',
66 ApiResult
::setSubelementsList( $data, 'help' );
67 $result->addValue( null, $this->getModuleName(), $data );
69 // Show any errors at the top of the HTML
71 'Types' => [ 'AssocAsObject' => true ],
74 $errors = array_filter( [
75 'errors' => $this->getResult()->getResultData( [ 'errors' ], $transform ),
76 'warnings' => $this->getResult()->getResultData( [ 'warnings' ], $transform ),
79 $json = FormatJson
::encode( $errors, true, FormatJson
::UTF8_OK
);
80 // Escape any "--", some parsers might interpret that as end-of-comment.
81 // The above already escaped any "<" and ">".
82 $json = str_replace( '--', '-\u002D', $json );
83 $html = "<!-- API warnings and errors:\n$json\n-->\n$html";
87 $result->addValue( null, 'text', $html, ApiResult
::NO_SIZE_CHECK
);
88 $result->addValue( null, 'mime', 'text/html', ApiResult
::NO_SIZE_CHECK
);
89 $result->addValue( null, 'filename', 'api-help.html', ApiResult
::NO_SIZE_CHECK
);
94 * Generate help for the specified modules
96 * Help is placed into the OutputPage object returned by
97 * $context->getOutput().
99 * Recognized options include:
100 * - headerlevel: (int) Header tag level
101 * - nolead: (bool) Skip the inclusion of api-help-lead
102 * - noheader: (bool) Skip the inclusion of the top-level section headers
103 * - submodules: (bool) Include help for submodules of the current module
104 * - recursivesubmodules: (bool) Include help for submodules recursively
105 * - helptitle: (string) Title to link for additional modules' help. Should contain $1.
106 * - toc: (bool) Include a table of contents
108 * @param IContextSource $context
109 * @param ApiBase[]|ApiBase $modules
110 * @param array $options Formatting options (described above)
112 public static function getHelp( IContextSource
$context, $modules, array $options ) {
113 if ( !is_array( $modules ) ) {
114 $modules = [ $modules ];
117 $out = $context->getOutput();
118 $out->addModuleStyles( [
120 'mediawiki.apipretty',
122 if ( !empty( $options['toc'] ) ) {
123 $out->addModuleStyles( 'mediawiki.toc.styles' );
125 $out->setPageTitle( $context->msg( 'api-help-title' ) );
127 $services = MediaWikiServices
::getInstance();
128 $cache = $services->getMainWANObjectCache();
130 if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain
&&
131 $options['recursivesubmodules'] &&
132 $context->getLanguage()->equals( $services->getContentLanguage() )
134 $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
135 if ( $cacheHelpTimeout > 0 ) {
136 // Get help text from cache if present
137 $cacheKey = $cache->makeKey( 'apihelp', $modules[0]->getModulePath(),
138 (int)!empty( $options['toc'] ),
139 str_replace( ' ', '_', SpecialVersion
::getVersion( 'nodb' ) ) );
140 $cached = $cache->get( $cacheKey );
142 $out->addHTML( $cached );
147 if ( $out->getHTML() !== '' ) {
148 // Don't save to cache, there's someone else's content in the page
153 $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
154 $options['submodules'] = $options['recursivesubmodules'] ||
!empty( $options['submodules'] );
157 if ( empty( $options['nolead'] ) ) {
158 $msg = $context->msg( 'api-help-lead' );
159 if ( !$msg->isDisabled() ) {
160 $out->addHTML( $msg->parseAsBlock() );
165 $html = self
::getHelpInternal( $context, $modules, $options, $haveModules );
166 if ( !empty( $options['toc'] ) && $haveModules ) {
167 $out->addHTML( Linker
::generateTOC( $haveModules, $context->getLanguage() ) );
169 $out->addHTML( $html );
171 $helptitle = $options['helptitle'] ??
null;
172 $html = self
::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
174 $out->addHTML( $html );
176 if ( $cacheKey !== null ) {
177 $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
182 * Replace Special:ApiHelp links with links to api.php
184 * @param string $html
185 * @param string|null $helptitle Title to link to rather than api.php, must contain '$1'
186 * @param array $localModules Keys are modules to link within the current page, values are ignored
189 public static function fixHelpLinks( $html, $helptitle = null, $localModules = [] ) {
190 $formatter = new HtmlFormatter( $html );
191 $doc = $formatter->getDoc();
192 $xpath = new DOMXPath( $doc );
193 $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
194 foreach ( $nodes as $node ) {
195 $href = $node->getAttribute( 'href' );
198 $href = rawurldecode( $href );
199 } while ( $old !== $href );
200 if ( preg_match( '!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
201 if ( isset( $localModules[$m[1]] ) ) {
202 $href = $m[2] === '' ?
'#' . $m[1] : $m[2];
203 } elseif ( $helptitle !== null ) {
204 $href = Title
::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
207 $href = wfAppendQuery( wfScript( 'api' ), [
212 $node->setAttribute( 'href', $href );
213 $node->removeAttribute( 'title' );
217 return $formatter->getText();
221 * Wrap a message in HTML with a class.
223 * @param Message $msg
224 * @param string $class
228 private static function wrap( Message
$msg, $class, $tag = 'span' ) {
229 return Html
::rawElement( $tag, [ 'class' => $class ],
235 * Recursively-called function to actually construct the help
237 * @param IContextSource $context
238 * @param ApiBase[] $modules
239 * @param array $options
240 * @param array &$haveModules
243 private static function getHelpInternal( IContextSource
$context, array $modules,
244 array $options, &$haveModules
248 $level = empty( $options['headerlevel'] ) ?
2 : $options['headerlevel'];
249 if ( empty( $options['tocnumber'] ) ) {
250 $tocnumber = [ 2 => 0 ];
252 $tocnumber = &$options['tocnumber'];
255 foreach ( $modules as $module ) {
256 $tocnumber[$level]++
;
257 $path = $module->getModulePath();
258 $module->setContext( $context );
269 if ( empty( $options['noheader'] ) ||
!empty( $options['toc'] ) ) {
272 while ( isset( $haveModules[$anchor] ) ) {
273 $anchor = $path . '|' . ++
$i;
276 if ( $module->isMain() ) {
277 $headerContent = $context->msg( 'api-help-main-header' )->parse();
279 'class' => 'apihelp-header',
282 $name = $module->getModuleName();
283 $headerContent = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
285 if ( $module->getModulePrefix() !== '' ) {
286 $headerContent .= ' ' .
287 $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
289 // Module names are always in English and not localized,
290 // so English language and direction must be set explicitly,
291 // otherwise parentheses will get broken in RTL wikis
293 'class' => 'apihelp-header apihelp-module-name',
299 $headerAttr['id'] = $anchor;
301 $haveModules[$anchor] = [
302 'toclevel' => count( $tocnumber ),
305 'line' => $headerContent,
306 'number' => implode( '.', $tocnumber ),
309 if ( empty( $options['noheader'] ) ) {
310 $help['header'] .= Html
::element(
311 'h' . min( 6, $level ),
317 $haveModules[$path] = true;
322 for ( $m = $module; $m !== null; $m = $m->getParent() ) {
323 $name = $m->getModuleName();
324 if ( $name === 'main_int' ) {
328 if ( count( $modules ) === 1 && $m === $modules[0] &&
329 !( !empty( $options['submodules'] ) && $m->getModuleManager() )
331 $link = Html
::element( 'b', [ 'dir' => 'ltr', 'lang' => 'en' ], $name );
333 $link = SpecialPage
::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
334 $link = Html
::element( 'a',
335 [ 'href' => $link, 'class' => 'apihelp-linktrail', 'dir' => 'ltr', 'lang' => 'en' ],
340 array_unshift( $links, $link );
343 $help['header'] .= self
::wrap(
344 $context->msg( 'parentheses' )
345 ->rawParams( $context->getLanguage()->pipeList( $links ) ),
346 'apihelp-linktrail', 'div'
350 $flags = $module->getHelpFlags();
351 $help['flags'] .= Html
::openElement( 'div',
352 [ 'class' => 'apihelp-block apihelp-flags' ] );
353 $msg = $context->msg( 'api-help-flags' );
354 if ( !$msg->isDisabled() ) {
355 $help['flags'] .= self
::wrap(
356 $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
359 $help['flags'] .= Html
::openElement( 'ul' );
360 foreach ( $flags as $flag ) {
361 $help['flags'] .= Html
::rawElement( 'li', null,
362 self
::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
365 $sourceInfo = $module->getModuleSourceInfo();
367 if ( isset( $sourceInfo['namemsg'] ) ) {
368 $extname = $context->msg( $sourceInfo['namemsg'] )->text();
370 // Probably English, so wrap it.
371 $extname = Html
::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['name'] );
373 $help['flags'] .= Html
::rawElement( 'li', null,
375 $context->msg( 'api-help-source', $extname, $sourceInfo['name'] ),
380 $link = SpecialPage
::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] );
381 if ( isset( $sourceInfo['license-name'] ) ) {
382 $msg = $context->msg( 'api-help-license', $link,
383 Html
::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['license-name'] )
385 } elseif ( SpecialVersion
::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
386 $msg = $context->msg( 'api-help-license-noname', $link );
388 $msg = $context->msg( 'api-help-license-unknown' );
390 $help['flags'] .= Html
::rawElement( 'li', null,
391 self
::wrap( $msg, 'apihelp-license' )
394 $help['flags'] .= Html
::rawElement( 'li', null,
395 self
::wrap( $context->msg( 'api-help-source-unknown' ), 'apihelp-source' )
397 $help['flags'] .= Html
::rawElement( 'li', null,
398 self
::wrap( $context->msg( 'api-help-license-unknown' ), 'apihelp-license' )
401 $help['flags'] .= Html
::closeElement( 'ul' );
402 $help['flags'] .= Html
::closeElement( 'div' );
404 foreach ( $module->getFinalDescription() as $msg ) {
405 $msg->setContext( $context );
406 $help['description'] .= $msg->parseAsBlock();
409 $urls = $module->getHelpUrls();
411 $help['help-urls'] .= Html
::openElement( 'div',
412 [ 'class' => 'apihelp-block apihelp-help-urls' ]
414 $msg = $context->msg( 'api-help-help-urls' );
415 if ( !$msg->isDisabled() ) {
416 $help['help-urls'] .= self
::wrap(
417 $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
420 if ( !is_array( $urls ) ) {
423 $help['help-urls'] .= Html
::openElement( 'ul' );
424 foreach ( $urls as $url ) {
425 $help['help-urls'] .= Html
::rawElement( 'li', null,
426 Html
::element( 'a', [ 'href' => $url, 'dir' => 'ltr' ], $url )
429 $help['help-urls'] .= Html
::closeElement( 'ul' );
430 $help['help-urls'] .= Html
::closeElement( 'div' );
433 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
434 $dynamicParams = $module->dynamicParameterDocumentation();
436 if ( $params ||
$dynamicParams !== null ) {
437 $help['parameters'] .= Html
::openElement( 'div',
438 [ 'class' => 'apihelp-block apihelp-parameters' ]
440 $msg = $context->msg( 'api-help-parameters' );
441 if ( !$msg->isDisabled() ) {
442 $help['parameters'] .= self
::wrap(
443 $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
446 $help['parameters'] .= Html
::openElement( 'dl' );
448 $descriptions = $module->getFinalParamDescription();
450 foreach ( $params as $name => $settings ) {
451 if ( !is_array( $settings ) ) {
452 $settings = [ ApiBase
::PARAM_DFLT
=> $settings ];
455 $help['parameters'] .= Html
::rawElement( 'dt', null,
456 Html
::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $module->encodeParamName( $name ) )
461 if ( isset( $descriptions[$name] ) ) {
462 foreach ( $descriptions[$name] as $msg ) {
463 $msg->setContext( $context );
464 $description[] = $msg->parseAsBlock();
472 if ( !empty( $settings[ApiBase
::PARAM_REQUIRED
] ) ) {
473 $info[] = $context->msg( 'api-help-param-required' )->parse();
477 if ( !empty( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] ) ) {
478 foreach ( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] as $i ) {
479 $tag = array_shift( $i );
480 $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
481 ->numParams( count( $i ) )
482 ->params( $context->getLanguage()->commaList( $i ) )
483 ->params( $module->getModulePrefix() )
489 if ( !empty( $settings[ApiBase
::PARAM_TEMPLATE_VARS
] ) ) {
491 $msg = 'api-help-param-templated-var-first';
492 foreach ( $settings[ApiBase
::PARAM_TEMPLATE_VARS
] as $k => $v ) {
493 $vars[] = $context->msg( $msg, $k, $module->encodeParamName( $v ) );
494 $msg = 'api-help-param-templated-var';
496 $info[] = $context->msg( 'api-help-param-templated' )
497 ->numParams( count( $vars ) )
498 ->params( Message
::listParam( $vars ) )
502 // Type documentation
503 if ( !isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
504 $dflt = $settings[ApiBase
::PARAM_DFLT
] ??
null;
505 if ( is_bool( $dflt ) ) {
506 $settings[ApiBase
::PARAM_TYPE
] = 'boolean';
507 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
508 $settings[ApiBase
::PARAM_TYPE
] = 'string';
509 } elseif ( is_int( $dflt ) ) {
510 $settings[ApiBase
::PARAM_TYPE
] = 'integer';
513 if ( isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
514 $type = $settings[ApiBase
::PARAM_TYPE
];
515 $multi = !empty( $settings[ApiBase
::PARAM_ISMULTI
] );
516 $hintPipeSeparated = true;
517 $count = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] )
518 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] +
1
519 : ApiBase
::LIMIT_SML2 +
1;
521 if ( is_array( $type ) ) {
522 $count = count( $type );
523 $deprecatedValues = $settings[ApiBase
::PARAM_DEPRECATED_VALUES
] ??
[];
524 $links = $settings[ApiBase
::PARAM_VALUE_LINKS
] ??
[];
525 $values = array_map( function ( $v ) use ( $links, $deprecatedValues ) {
528 // We can't know whether this contains LTR or RTL text.
529 $attr['dir'] = 'auto';
531 if ( isset( $deprecatedValues[$v] ) ) {
532 $attr['class'] = 'apihelp-deprecated-value';
534 $ret = $attr ? Html
::element( 'span', $attr, $v ) : $v;
535 if ( isset( $links[$v] ) ) {
536 $ret = "[[{$links[$v]}|$ret]]";
540 $i = array_search( '', $type, true );
541 if ( $i === false ) {
542 $values = $context->getLanguage()->commaList( $values );
544 unset( $values[$i] );
545 $values = $context->msg( 'api-help-param-list-can-be-empty' )
546 ->numParams( count( $values ) )
547 ->params( $context->getLanguage()->commaList( $values ) )
550 $info[] = $context->msg( 'api-help-param-list' )
551 ->params( $multi ?
2 : 1 )
554 $hintPipeSeparated = false;
560 if ( isset( $settings[ApiBase
::PARAM_SUBMODULE_MAP
] ) ) {
561 $map = $settings[ApiBase
::PARAM_SUBMODULE_MAP
];
564 $prefix = $module->isMain() ?
'' : ( $module->getModulePath() . '+' );
566 foreach ( $module->getModuleManager()->getNames( $name ) as $submoduleName ) {
567 $map[$submoduleName] = $prefix . $submoduleName;
569 $defaultAttrs = [ 'dir' => 'ltr', 'lang' => 'en' ];
574 $deprecatedSubmodules = [];
575 foreach ( $map as $v => $m ) {
576 $attrs = $defaultAttrs;
579 $submod = $module->getModuleFromPath( $m );
580 if ( $submod && $submod->isDeprecated() ) {
581 $arr = &$deprecatedSubmodules;
582 $attrs['class'] = 'apihelp-deprecated-value';
584 } catch ( ApiUsageException
$ex ) {
588 $v = Html
::element( 'span', $attrs, $v );
590 $arr[] = "[[Special:ApiHelp/{$m}|{$v}]]";
592 $submodules = array_merge( $submodules, $deprecatedSubmodules );
593 $count = count( $submodules );
594 $info[] = $context->msg( 'api-help-param-list' )
595 ->params( $multi ?
2 : 1 )
596 ->params( $context->getLanguage()->commaList( $submodules ) )
598 $hintPipeSeparated = false;
599 // No type message necessary, we have a list of values.
604 $namespaces = MediaWikiServices
::getInstance()->
605 getNamespaceInfo()->getValidNamespaces();
606 if ( isset( $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] ) &&
607 is_array( $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] )
609 $namespaces = array_merge( $namespaces, $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] );
612 $count = count( $namespaces );
613 $info[] = $context->msg( 'api-help-param-list' )
614 ->params( $multi ?
2 : 1 )
615 ->params( $context->getLanguage()->commaList( $namespaces ) )
617 $hintPipeSeparated = false;
618 // No type message necessary, we have a list of values.
623 $tags = ChangeTags
::listExplicitlyDefinedTags();
624 $count = count( $tags );
625 $info[] = $context->msg( 'api-help-param-list' )
626 ->params( $multi ?
2 : 1 )
627 ->params( $context->getLanguage()->commaList( $tags ) )
629 $hintPipeSeparated = false;
634 if ( isset( $settings[ApiBase
::PARAM_MAX2
] ) ) {
635 $info[] = $context->msg( 'api-help-param-limit2' )
636 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
637 ->numParams( $settings[ApiBase
::PARAM_MAX2
] )
640 $info[] = $context->msg( 'api-help-param-limit' )
641 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
647 // Possible messages:
648 // api-help-param-integer-min,
649 // api-help-param-integer-max,
650 // api-help-param-integer-minmax
653 if ( isset( $settings[ApiBase
::PARAM_MIN
] ) ) {
655 $min = $settings[ApiBase
::PARAM_MIN
];
657 if ( isset( $settings[ApiBase
::PARAM_MAX
] ) ) {
659 $max = $settings[ApiBase
::PARAM_MAX
];
661 if ( $suffix !== '' ) {
663 $context->msg( "api-help-param-integer-$suffix" )
664 ->params( $multi ?
2 : 1 )
665 ->numParams( $min, $max )
671 $info[] = $context->msg( 'api-help-param-upload' )
673 // No type message necessary, api-help-param-upload should handle it.
679 // Displaying a type message here would be useless.
685 // Add type. Messages for grep: api-help-param-type-limit
686 // api-help-param-type-integer api-help-param-type-boolean
687 // api-help-param-type-timestamp api-help-param-type-user
688 // api-help-param-type-password
689 if ( is_string( $type ) ) {
690 $msg = $context->msg( "api-help-param-type-$type" );
691 if ( !$msg->isDisabled() ) {
692 $info[] = $msg->params( $multi ?
2 : 1 )->parse();
698 $lowcount = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT1
] )
699 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT1
]
700 : ApiBase
::LIMIT_SML1
;
701 $highcount = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] )
702 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT2
]
703 : ApiBase
::LIMIT_SML2
;
705 if ( $hintPipeSeparated ) {
706 $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
708 if ( $count > $lowcount ) {
709 if ( $lowcount === $highcount ) {
710 $msg = $context->msg( 'api-help-param-multi-max-simple' )
711 ->numParams( $lowcount );
713 $msg = $context->msg( 'api-help-param-multi-max' )
714 ->numParams( $lowcount, $highcount );
716 $extra[] = $msg->parse();
719 $info[] = implode( ' ', $extra );
722 $allowAll = $settings[ApiBase
::PARAM_ALL
] ??
false;
723 if ( $allowAll ||
$settings[ApiBase
::PARAM_TYPE
] === 'namespace' ) {
724 if ( $settings[ApiBase
::PARAM_TYPE
] === 'namespace' ) {
725 $allSpecifier = ApiBase
::ALL_DEFAULT_STRING
;
727 $allSpecifier = ( is_string( $allowAll ) ?
$allowAll : ApiBase
::ALL_DEFAULT_STRING
);
729 $info[] = $context->msg( 'api-help-param-multi-all' )
730 ->params( $allSpecifier )
736 if ( isset( $settings[self
::PARAM_MAX_BYTES
] ) ) {
737 $info[] = $context->msg( 'api-help-param-maxbytes' )
738 ->numParams( $settings[self
::PARAM_MAX_BYTES
] );
740 if ( isset( $settings[self
::PARAM_MAX_CHARS
] ) ) {
741 $info[] = $context->msg( 'api-help-param-maxchars' )
742 ->numParams( $settings[self
::PARAM_MAX_CHARS
] );
746 $default = $settings[ApiBase
::PARAM_DFLT
] ??
null;
747 if ( $default === '' ) {
748 $info[] = $context->msg( 'api-help-param-default-empty' )
750 } elseif ( $default !== null && $default !== false ) {
751 // We can't know whether this contains LTR or RTL text.
752 $info[] = $context->msg( 'api-help-param-default' )
753 ->params( Html
::element( 'span', [ 'dir' => 'auto' ], $default ) )
757 if ( !array_filter( $description ) ) {
758 $description = [ self
::wrap(
759 $context->msg( 'api-help-param-no-description' ),
764 // Add "deprecated" flag
765 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED
] ) ) {
766 $help['parameters'] .= Html
::openElement( 'dd',
767 [ 'class' => 'info' ] );
768 $help['parameters'] .= self
::wrap(
769 $context->msg( 'api-help-param-deprecated' ),
770 'apihelp-deprecated', 'strong'
772 $help['parameters'] .= Html
::closeElement( 'dd' );
775 if ( $description ) {
776 $description = implode( '', $description );
777 $description = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $description );
778 $help['parameters'] .= Html
::rawElement( 'dd',
779 [ 'class' => 'description' ], $description );
782 foreach ( $info as $i ) {
783 $help['parameters'] .= Html
::rawElement( 'dd', [ 'class' => 'info' ], $i );
787 if ( $dynamicParams !== null ) {
788 $dynamicParams = ApiBase
::makeMessage( $dynamicParams, $context, [
789 $module->getModulePrefix(),
790 $module->getModuleName(),
791 $module->getModulePath()
793 $help['parameters'] .= Html
::element( 'dt', null, '*' );
794 $help['parameters'] .= Html
::rawElement( 'dd',
795 [ 'class' => 'description' ], $dynamicParams->parse() );
798 $help['parameters'] .= Html
::closeElement( 'dl' );
799 $help['parameters'] .= Html
::closeElement( 'div' );
802 $examples = $module->getExamplesMessages();
804 $help['examples'] .= Html
::openElement( 'div',
805 [ 'class' => 'apihelp-block apihelp-examples' ] );
806 $msg = $context->msg( 'api-help-examples' );
807 if ( !$msg->isDisabled() ) {
808 $help['examples'] .= self
::wrap(
809 $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
813 $help['examples'] .= Html
::openElement( 'dl' );
814 foreach ( $examples as $qs => $msg ) {
815 $msg = ApiBase
::makeMessage( $msg, $context, [
816 $module->getModulePrefix(),
817 $module->getModuleName(),
818 $module->getModulePath()
821 $link = wfAppendQuery( wfScript( 'api' ), $qs );
822 $sandbox = SpecialPage
::getTitleFor( 'ApiSandbox' )->getLocalURL() . '#' . $qs;
823 $help['examples'] .= Html
::rawElement( 'dt', null, $msg->parse() );
824 $help['examples'] .= Html
::rawElement( 'dd', null,
825 Html
::element( 'a', [ 'href' => $link, 'dir' => 'ltr' ], "api.php?$qs" ) . ' ' .
826 Html
::rawElement( 'a', [ 'href' => $sandbox ],
827 $context->msg( 'api-help-open-in-apisandbox' )->parse() )
830 $help['examples'] .= Html
::closeElement( 'dl' );
831 $help['examples'] .= Html
::closeElement( 'div' );
834 $subtocnumber = $tocnumber;
835 $subtocnumber[$level +
1] = 0;
837 'submodules' => $options['recursivesubmodules'],
838 'headerlevel' => $level +
1,
839 'tocnumber' => &$subtocnumber,
843 if ( $options['submodules'] && $module->getModuleManager() ) {
844 $manager = $module->getModuleManager();
846 foreach ( $groups as $group ) {
847 $names = $manager->getNames( $group );
849 foreach ( $names as $name ) {
850 $submodules[] = $manager->getModule( $name );
853 $help['submodules'] .= self
::getHelpInternal(
861 $module->modifyHelp( $help, $suboptions, $haveModules );
863 Hooks
::run( 'APIHelpModifyOutput', [ $module, &$help, $suboptions, &$haveModules ] );
865 $out .= implode( "\n", $help );
871 public function shouldCheckMaxlag() {
875 public function isReadMode() {
879 public function getCustomPrinter() {
880 $params = $this->extractRequestParams();
881 if ( $params['wrap'] ) {
885 $main = $this->getMain();
886 $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
887 return new ApiFormatRaw( $main, $errorPrinter );
890 public function getAllowedParams() {
893 ApiBase
::PARAM_DFLT
=> 'main',
894 ApiBase
::PARAM_ISMULTI
=> true,
896 'submodules' => false,
897 'recursivesubmodules' => false,
903 protected function getExamplesMessages() {
906 => 'apihelp-help-example-main',
907 'action=help&modules=query&submodules=1'
908 => 'apihelp-help-example-submodules',
909 'action=help&recursivesubmodules=1'
910 => 'apihelp-help-example-recursive',
911 'action=help&modules=help'
912 => 'apihelp-help-example-help',
913 'action=help&modules=query+info|query+categorymembers'
914 => 'apihelp-help-example-query',
918 public function getHelpUrls() {
920 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
921 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
922 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',