5 * Created on Aug 29, 2014
7 * Copyright © 2014 Brad Jorsch <bjorsch@wikimedia.org>
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
28 * Class to output help for an API module
30 * @since 1.25 completely rewritten
33 class ApiHelp
extends ApiBase
{
34 public function execute() {
37 $params = $this->extractRequestParams();
40 foreach ( $params['modules'] as $path ) {
41 $modules[] = $this->getModuleFromPath( $path );
45 $context = new DerivativeContext( $this->getMain()->getContext() );
46 $context->setSkin( SkinFactory
::getDefaultInstance()->makeSkin( 'apioutput' ) );
47 $context->setLanguage( $this->getMain()->getLanguage() );
48 $context->setTitle( SpecialPage
::getTitleFor( 'ApiHelp' ) );
49 $out = new OutputPage( $context );
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',
65 $result->setSubelements( $data, 'help' );
66 $result->addValue( null, $this->getModuleName(), $data );
69 $result->addValue( null, 'text', $html, ApiResult
::NO_SIZE_CHECK
);
70 $result->addValue( null, 'mime', 'text/html', ApiResult
::NO_SIZE_CHECK
);
75 * Generate help for the specified modules
77 * Help is placed into the OutputPage object returned by
78 * $context->getOutput().
80 * Recognized options include:
81 * - headerlevel: (int) Header tag level
82 * - nolead: (bool) Skip the inclusion of api-help-lead
83 * - noheader: (bool) Skip the inclusion of the top-level section headers
84 * - submodules: (bool) Include help for submodules of the current module
85 * - recursivesubmodules: (bool) Include help for submodules recursively
86 * - helptitle: (string) Title to link for additional modules' help. Should contain $1.
88 * @param IContextSource $context
89 * @param ApiBase[]|ApiBase $modules
90 * @param array $options Formatting options (described above)
93 public static function getHelp( IContextSource
$context, $modules, array $options ) {
94 global $wgMemc, $wgContLang;
96 if ( !is_array( $modules ) ) {
97 $modules = array( $modules );
100 $out = $context->getOutput();
101 $out->addModules( 'mediawiki.apihelp' );
102 $out->setPageTitle( $context->msg( 'api-help-title' ) );
105 if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain
&&
106 $options['recursivesubmodules'] && $context->getLanguage() === $wgContLang
108 $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
109 if ( $cacheHelpTimeout > 0 ) {
110 // Get help text from cache if present
111 $cacheKey = wfMemcKey( 'apihelp', $modules[0]->getModulePath(),
112 str_replace( ' ', '_', SpecialVersion
::getVersion( 'nodb' ) ) );
113 $cached = $wgMemc->get( $cacheKey );
115 $out->addHTML( $cached );
120 if ( $out->getHTML() !== '' ) {
121 // Don't save to cache, there's someone else's content in the page
126 $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
127 $options['submodules'] = $options['recursivesubmodules'] ||
!empty( $options['submodules'] );
130 if ( empty( $options['nolead'] ) ) {
131 $msg = $context->msg( 'api-help-lead' );
132 if ( !$msg->isDisabled() ) {
133 $out->addHTML( $msg->parseAsBlock() );
137 $haveModules = array();
138 $out->addHTML( self
::getHelpInternal( $context, $modules, $options, $haveModules ) );
140 $helptitle = isset( $options['helptitle'] ) ?
$options['helptitle'] : null;
141 $html = self
::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
143 $out->addHTML( $html );
145 if ( $cacheKey !== null ) {
146 $wgMemc->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
151 * Replace Special:ApiHelp links with links to api.php
153 * @param string $html
154 * @param string|null $helptitle Title to link to rather than api.php, must contain '$1'
155 * @param array $localModules Modules to link within the current page
158 public static function fixHelpLinks( $html, $helptitle = null, $localModules = array() ) {
159 $formatter = new HtmlFormatter( $html );
160 $doc = $formatter->getDoc();
161 $xpath = new DOMXPath( $doc );
162 $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
163 foreach ( $nodes as $node ) {
164 $href = $node->getAttribute( 'href' );
167 $href = rawurldecode( $href );
168 } while ( $old !== $href );
169 if ( preg_match( '!Special:ApiHelp/([^&/|]+)!', $href, $m ) ) {
170 if ( isset( $localModules[$m[1]] ) ) {
172 } elseif ( $helptitle !== null ) {
173 $href = Title
::newFromText( str_replace( '$1', $m[1], $helptitle ) )
176 $href = wfAppendQuery( wfScript( 'api' ), array(
181 $node->setAttribute( 'href', $href );
182 $node->removeAttribute( 'title' );
186 return $formatter->getText();
190 * Wrap a message in HTML with a class.
192 * @param Message $msg
193 * @param string $class
197 private static function wrap( Message
$msg, $class, $tag = 'span' ) {
198 return Html
::rawElement( $tag, array( 'class' => $class ),
204 * Recursively-called function to actually construct the help
206 * @param IContextSource $context
207 * @param ApiBase[] $modules
208 * @param array $options
209 * @param array &$haveModules
212 private static function getHelpInternal( IContextSource
$context, array $modules,
213 array $options, &$haveModules
217 $level = min( 6, empty( $options['headerlevel'] ) ?
2 : $options['headerlevel'] );
218 $options['headerlevel'] = $level;
220 foreach ( $modules as $module ) {
221 $haveModules[$module->getModulePath()] = true;
222 $module->setContext( $context );
233 if ( empty( $options['noheader'] ) ) {
234 $path = $module->getModulePath();
235 if ( $module->isMain() ) {
236 $header = $context->msg( 'api-help-main-header' )->parse();
238 $name = $module->getModuleName();
239 $header = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
241 if ( $module->getModulePrefix() !== '' ) {
243 $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
246 $help['header'] .= Html
::element( "h$level",
247 array( 'id' => $path, 'class' => 'apihelp-header' ),
254 for ( $m = $module; $m !== null; $m = $m->getParent() ) {
255 $name = $m->getModuleName();
256 if ( $name === 'main_int' ) {
260 if ( count( $modules ) === 1 && $m === $modules[0] &&
261 !( !empty( $options['submodules'] ) && $m->getModuleManager() )
263 $link = Html
::element( 'b', null, $name );
265 $link = SpecialPage
::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
266 $link = Html
::element( 'a',
267 array( 'href' => $link, 'class' => 'apihelp-linktrail' ),
272 array_unshift( $links, $link );
275 $help['header'] .= self
::wrap(
276 $context->msg( 'parentheses' )
277 ->rawParams( $context->getLanguage()->pipeList( $links ) ),
278 'apihelp-linktrail', 'div'
282 $flags = $module->getHelpFlags();
284 $help['flags'] .= Html
::openElement( 'div',
285 array( 'class' => 'apihelp-block apihelp-flags' ) );
286 $msg = $context->msg( 'api-help-flags' );
287 if ( !$msg->isDisabled() ) {
288 $help['flags'] .= self
::wrap(
289 $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
292 $help['flags'] .= Html
::openElement( 'ul' );
293 foreach ( $flags as $flag ) {
294 $help['flags'] .= Html
::rawElement( 'li', null,
295 self
::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
298 $help['flags'] .= Html
::closeElement( 'ul' );
299 $help['flags'] .= Html
::closeElement( 'div' );
302 foreach ( $module->getFinalDescription() as $msg ) {
303 $msg->setContext( $context );
304 $help['description'] .= $msg->parseAsBlock();
307 $urls = $module->getHelpUrls();
309 $help['help-urls'] .= Html
::openElement( 'div',
310 array( 'class' => 'apihelp-block apihelp-help-urls' )
312 $msg = $context->msg( 'api-help-help-urls' );
313 if ( !$msg->isDisabled() ) {
314 $help['help-urls'] .= self
::wrap(
315 $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
318 if ( !is_array( $urls ) ) {
319 $urls = array( $urls );
321 $help['help-urls'] .= Html
::openElement( 'ul' );
322 foreach ( $urls as $url ) {
323 $help['help-urls'] .= Html
::rawElement( 'li', null,
324 Html
::element( 'a', array( 'href' => $url ), $url )
327 $help['help-urls'] .= Html
::closeElement( 'ul' );
328 $help['help-urls'] .= Html
::closeElement( 'div' );
331 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
334 $help['parameters'] .= Html
::openElement( 'div',
335 array( 'class' => 'apihelp-block apihelp-parameters' )
337 $msg = $context->msg( 'api-help-parameters' );
338 if ( !$msg->isDisabled() ) {
339 $help['parameters'] .= self
::wrap(
340 $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
343 $help['parameters'] .= Html
::openElement( 'dl' );
345 $descriptions = $module->getFinalParamDescription();
347 foreach ( $params as $name => $settings ) {
348 if ( !is_array( $settings ) ) {
349 $settings = array( ApiBase
::PARAM_DFLT
=> $settings );
352 $help['parameters'] .= Html
::element( 'dt', null,
353 $module->encodeParamName( $name ) );
356 $description = array();
357 if ( isset( $descriptions[$name] ) ) {
358 foreach ( $descriptions[$name] as $msg ) {
359 $msg->setContext( $context );
360 $description[] = $msg->parseAsBlock();
368 if ( !empty( $settings[ApiBase
::PARAM_REQUIRED
] ) ) {
369 $info[] = $context->msg( 'api-help-param-required' )->parse();
373 if ( !empty( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] ) ) {
374 foreach ( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] as $i ) {
375 $tag = array_shift( $i );
376 $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
377 ->numParams( count( $i ) )
378 ->params( $context->getLanguage()->commaList( $i ) )
383 // Type documentation
384 if ( !isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
385 $dflt = isset( $settings[ApiBase
::PARAM_DFLT
] )
386 ?
$settings[ApiBase
::PARAM_DFLT
]
388 if ( is_bool( $dflt ) ) {
389 $settings[ApiBase
::PARAM_TYPE
] = 'boolean';
390 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
391 $settings[ApiBase
::PARAM_TYPE
] = 'string';
392 } elseif ( is_int( $dflt ) ) {
393 $settings[ApiBase
::PARAM_TYPE
] = 'integer';
396 if ( isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
397 $type = $settings[ApiBase
::PARAM_TYPE
];
398 $multi = !empty( $settings[ApiBase
::PARAM_ISMULTI
] );
399 $hintPipeSeparated = true;
400 $count = ApiBase
::LIMIT_SML2 +
1;
402 if ( is_array( $type ) ) {
403 $count = count( $type );
404 $links = isset( $settings[ApiBase
::PARAM_VALUE_LINKS
] )
405 ?
$settings[ApiBase
::PARAM_VALUE_LINKS
]
407 $type = array_map( function ( $v ) use ( $links ) {
408 $ret = wfEscapeWikiText( $v );
409 if ( isset( $links[$v] ) ) {
410 $ret = "[[{$links[$v]}|$ret]]";
414 $i = array_search( '', $type, true );
415 if ( $i === false ) {
416 $type = $context->getLanguage()->commaList( $type );
419 $type = $context->msg( 'api-help-param-list-can-be-empty' )
420 ->numParams( count( $type ) )
421 ->params( $context->getLanguage()->commaList( $type ) )
424 $info[] = $context->msg( 'api-help-param-list' )
425 ->params( $multi ?
2 : 1 )
428 $hintPipeSeparated = false;
433 $submodules = $module->getModuleManager()->getNames( $name );
434 $count = count( $submodules );
436 $prefix = $module->isMain()
437 ?
'' : ( $module->getModulePath() . '+' );
438 $submodules = array_map( function ( $name ) use ( $prefix ) {
439 return "[[Special:ApiHelp/{$prefix}{$name}|{$name}]]";
441 $info[] = $context->msg( 'api-help-param-list' )
442 ->params( $multi ?
2 : 1 )
443 ->params( $context->getLanguage()->commaList( $submodules ) )
445 $hintPipeSeparated = false;
449 $namespaces = MWNamespace
::getValidNamespaces();
450 $count = count( $namespaces );
451 $info[] = $context->msg( 'api-help-param-list' )
452 ->params( $multi ?
2 : 1 )
453 ->params( $context->getLanguage()->commaList( $namespaces ) )
455 $hintPipeSeparated = false;
459 if ( isset( $settings[ApiBase
::PARAM_MAX2
] ) ) {
460 $info[] = $context->msg( 'api-help-param-limit2' )
461 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
462 ->numParams( $settings[ApiBase
::PARAM_MAX2
] )
465 $info[] = $context->msg( 'api-help-param-limit' )
466 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
472 // Possible messages:
473 // api-help-param-integer-min,
474 // api-help-param-integer-max,
475 // api-help-param-integer-minmax
478 if ( isset( $settings[ApiBase
::PARAM_MIN
] ) ) {
480 $min = $settings[ApiBase
::PARAM_MIN
];
482 if ( isset( $settings[ApiBase
::PARAM_MAX
] ) ) {
484 $max = $settings[ApiBase
::PARAM_MAX
];
486 if ( $suffix !== '' ) {
488 $context->msg( "api-help-param-integer-$suffix" )
489 ->params( $multi ?
2 : 1 )
490 ->numParams( $min, $max )
496 $info[] = $context->msg( 'api-help-param-upload' )
504 if ( $hintPipeSeparated ) {
505 $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
507 if ( $count > ApiBase
::LIMIT_SML1
) {
508 $extra[] = $context->msg( 'api-help-param-multi-max' )
509 ->numParams( ApiBase
::LIMIT_SML1
, ApiBase
::LIMIT_SML2
)
513 $info[] = join( ' ', $extra );
519 $default = isset( $settings[ApiBase
::PARAM_DFLT
] )
520 ?
$settings[ApiBase
::PARAM_DFLT
]
522 if ( $default === '' ) {
523 $info[] = $context->msg( 'api-help-param-default-empty' )
525 } elseif ( $default !== null && $default !== false ) {
526 $info[] = $context->msg( 'api-help-param-default' )
527 ->params( wfEscapeWikiText( $default ) )
531 if ( !array_filter( $description ) ) {
532 $description = array( self
::wrap(
533 $context->msg( 'api-help-param-no-description' ),
538 // Add "deprecated" flag
539 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED
] ) ) {
540 $help['parameters'] .= Html
::openElement( 'dd',
541 array( 'class' => 'info' ) );
542 $help['parameters'] .= self
::wrap(
543 $context->msg( 'api-help-param-deprecated' ),
544 'apihelp-deprecated', 'strong'
546 $help['parameters'] .= Html
::closeElement( 'dd' );
549 if ( $description ) {
550 $help['parameters'] .= Html
::openElement( 'dd',
551 array( 'class' => 'description' ) );
552 $help['parameters'] .= join( '', $description );
553 $help['parameters'] .= Html
::closeElement( 'dd' );
556 foreach ( $info as $i ) {
557 $help['parameters'] .= Html
::rawElement( 'dd', array( 'class' => 'info' ), $i );
561 $help['parameters'] .= Html
::closeElement( 'dl' );
562 $help['parameters'] .= Html
::closeElement( 'div' );
565 $examples = $module->getExamplesMessages();
567 $help['examples'] .= Html
::openElement( 'div',
568 array( 'class' => 'apihelp-block apihelp-examples' ) );
569 $msg = $context->msg( 'api-help-examples' );
570 if ( !$msg->isDisabled() ) {
571 $help['examples'] .= self
::wrap(
572 $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
576 $help['examples'] .= Html
::openElement( 'dl' );
577 foreach ( $examples as $qs => $msg ) {
578 $msg = ApiBase
::makeMessage( $msg, $context, array(
579 $module->getModulePrefix(),
580 $module->getModuleName(),
581 $module->getModulePath()
584 $link = wfAppendQuery( wfScript( 'api' ), $qs );
585 $help['examples'] .= Html
::rawElement( 'dt', null, $msg->parse() );
586 $help['examples'] .= Html
::rawElement( 'dd', null,
587 Html
::element( 'a', array( 'href' => $link ), "api.php?$qs" )
590 $help['examples'] .= Html
::closeElement( 'dl' );
591 $help['examples'] .= Html
::closeElement( 'div' );
594 if ( $options['submodules'] && $module->getModuleManager() ) {
595 $manager = $module->getModuleManager();
596 $submodules = array();
597 foreach ( $groups as $group ) {
598 $names = $manager->getNames( $group );
600 foreach ( $names as $name ) {
601 $submodules[] = $manager->getModule( $name );
604 $help['submodules'] .= self
::getHelpInternal( $context, $submodules, array(
605 'submodules' => $options['recursivesubmodules'],
606 'headerlevel' => $level +
1,
608 ) +
$options, $haveModules );
611 $module->modifyHelp( $help, $options );
613 wfRunHooks( 'APIHelpModifyOutput', array( $module, &$help, $options ) );
615 $out .= join( "\n", $help );
621 public function shouldCheckMaxlag() {
625 public function isReadMode() {
629 public function getCustomPrinter() {
630 $params = $this->extractRequestParams();
631 if ( $params['wrap'] ) {
635 $main = $this->getMain();
636 $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
637 return new ApiFormatRaw( $main, $errorPrinter );
640 public function getAllowedParams() {
643 ApiBase
::PARAM_DFLT
=> 'main',
644 ApiBase
::PARAM_ISMULTI
=> true,
646 'submodules' => false,
647 'recursivesubmodules' => false,
653 protected function getExamplesMessages() {
656 => 'apihelp-help-example-main',
657 'action=help&recursivesubmodules=1'
658 => 'apihelp-help-example-recursive',
659 'action=help&modules=help'
660 => 'apihelp-help-example-help',
661 'action=help&modules=query+info|query+categorymembers'
662 => 'apihelp-help-example-query',
666 public function getHelpUrls() {
668 'https://www.mediawiki.org/wiki/API:Main_page',
669 'https://www.mediawiki.org/wiki/API:FAQ',
670 'https://www.mediawiki.org/wiki/API:Quick_start_guide',