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() {
35 $params = $this->extractRequestParams();
38 foreach ( $params['modules'] as $path ) {
39 $modules[] = $this->getModuleFromPath( $path );
43 $context = new DerivativeContext( $this->getMain()->getContext() );
44 $context->setSkin( SkinFactory
::getDefaultInstance()->makeSkin( 'apioutput' ) );
45 $context->setLanguage( $this->getMain()->getLanguage() );
46 $context->setTitle( SpecialPage
::getTitleFor( 'ApiHelp' ) );
47 $out = new OutputPage( $context );
48 $out->setCopyrightUrl( 'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
49 $context->setOutput( $out );
51 self
::getHelp( $context, $modules, $params );
53 // Grab the output from the skin
55 $context->getOutput()->output();
56 $html = ob_get_clean();
58 $result = $this->getResult();
59 if ( $params['wrap'] ) {
61 'mime' => 'text/html',
64 ApiResult
::setSubelementsList( $data, 'help' );
65 $result->addValue( null, $this->getModuleName(), $data );
68 $result->addValue( null, 'text', $html, ApiResult
::NO_SIZE_CHECK
);
69 $result->addValue( null, 'mime', 'text/html', ApiResult
::NO_SIZE_CHECK
);
74 * Generate help for the specified modules
76 * Help is placed into the OutputPage object returned by
77 * $context->getOutput().
79 * Recognized options include:
80 * - headerlevel: (int) Header tag level
81 * - nolead: (bool) Skip the inclusion of api-help-lead
82 * - noheader: (bool) Skip the inclusion of the top-level section headers
83 * - submodules: (bool) Include help for submodules of the current module
84 * - recursivesubmodules: (bool) Include help for submodules recursively
85 * - helptitle: (string) Title to link for additional modules' help. Should contain $1.
86 * - toc: (bool) Include a table of contents
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 if ( !empty( $options['toc'] ) ) {
103 $out->addModules( 'mediawiki.toc' );
105 $out->setPageTitle( $context->msg( 'api-help-title' ) );
108 if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain
&&
109 $options['recursivesubmodules'] && $context->getLanguage() === $wgContLang
111 $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
112 if ( $cacheHelpTimeout > 0 ) {
113 // Get help text from cache if present
114 $cacheKey = wfMemcKey( 'apihelp', $modules[0]->getModulePath(),
115 (int)!empty( $options['toc'] ),
116 str_replace( ' ', '_', SpecialVersion
::getVersion( 'nodb' ) ) );
117 $cached = $wgMemc->get( $cacheKey );
119 $out->addHTML( $cached );
124 if ( $out->getHTML() !== '' ) {
125 // Don't save to cache, there's someone else's content in the page
130 $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
131 $options['submodules'] = $options['recursivesubmodules'] ||
!empty( $options['submodules'] );
134 if ( empty( $options['nolead'] ) ) {
135 $msg = $context->msg( 'api-help-lead' );
136 if ( !$msg->isDisabled() ) {
137 $out->addHTML( $msg->parseAsBlock() );
141 $haveModules = array();
142 $html = self
::getHelpInternal( $context, $modules, $options, $haveModules );
143 if ( !empty( $options['toc'] ) && $haveModules ) {
144 $out->addHTML( Linker
::generateTOC( $haveModules, $context->getLanguage() ) );
146 $out->addHTML( $html );
148 $helptitle = isset( $options['helptitle'] ) ?
$options['helptitle'] : null;
149 $html = self
::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
151 $out->addHTML( $html );
153 if ( $cacheKey !== null ) {
154 $wgMemc->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
159 * Replace Special:ApiHelp links with links to api.php
161 * @param string $html
162 * @param string|null $helptitle Title to link to rather than api.php, must contain '$1'
163 * @param array $localModules Keys are modules to link within the current page, values are ignored
166 public static function fixHelpLinks( $html, $helptitle = null, $localModules = array() ) {
167 $formatter = new HtmlFormatter( $html );
168 $doc = $formatter->getDoc();
169 $xpath = new DOMXPath( $doc );
170 $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
171 foreach ( $nodes as $node ) {
172 $href = $node->getAttribute( 'href' );
175 $href = rawurldecode( $href );
176 } while ( $old !== $href );
177 if ( preg_match( '!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
178 if ( isset( $localModules[$m[1]] ) ) {
179 $href = $m[2] === '' ?
'#' . $m[1] : $m[2];
180 } elseif ( $helptitle !== null ) {
181 $href = Title
::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
184 $href = wfAppendQuery( wfScript( 'api' ), array(
189 $node->setAttribute( 'href', $href );
190 $node->removeAttribute( 'title' );
194 return $formatter->getText();
198 * Wrap a message in HTML with a class.
200 * @param Message $msg
201 * @param string $class
205 private static function wrap( Message
$msg, $class, $tag = 'span' ) {
206 return Html
::rawElement( $tag, array( 'class' => $class ),
212 * Recursively-called function to actually construct the help
214 * @param IContextSource $context
215 * @param ApiBase[] $modules
216 * @param array $options
217 * @param array &$haveModules
220 private static function getHelpInternal( IContextSource
$context, array $modules,
221 array $options, &$haveModules
225 $level = empty( $options['headerlevel'] ) ?
2 : $options['headerlevel'];
226 if ( empty( $options['tocnumber'] ) ) {
227 $tocnumber = array( 2 => 0 );
229 $tocnumber = &$options['tocnumber'];
232 foreach ( $modules as $module ) {
233 $tocnumber[$level]++
;
234 $path = $module->getModulePath();
235 $module->setContext( $context );
246 if ( empty( $options['noheader'] ) ||
!empty( $options['toc'] ) ) {
249 while ( isset( $haveModules[$anchor] ) ) {
250 $anchor = $path . '|' . ++
$i;
253 if ( $module->isMain() ) {
254 $header = $context->msg( 'api-help-main-header' )->parse();
256 $name = $module->getModuleName();
257 $header = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
259 if ( $module->getModulePrefix() !== '' ) {
261 $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
264 $haveModules[$anchor] = array(
265 'toclevel' => count( $tocnumber ),
269 'number' => join( '.', $tocnumber ),
272 if ( empty( $options['noheader'] ) ) {
273 $help['header'] .= Html
::element( 'h' . min( 6, $level ),
274 array( 'id' => $anchor, 'class' => 'apihelp-header' ),
279 $haveModules[$path] = true;
284 for ( $m = $module; $m !== null; $m = $m->getParent() ) {
285 $name = $m->getModuleName();
286 if ( $name === 'main_int' ) {
290 if ( count( $modules ) === 1 && $m === $modules[0] &&
291 !( !empty( $options['submodules'] ) && $m->getModuleManager() )
293 $link = Html
::element( 'b', null, $name );
295 $link = SpecialPage
::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
296 $link = Html
::element( 'a',
297 array( 'href' => $link, 'class' => 'apihelp-linktrail' ),
302 array_unshift( $links, $link );
305 $help['header'] .= self
::wrap(
306 $context->msg( 'parentheses' )
307 ->rawParams( $context->getLanguage()->pipeList( $links ) ),
308 'apihelp-linktrail', 'div'
312 $help['flags'] .= Html
::openElement( 'div',
313 array( 'class' => 'apihelp-block apihelp-flags' ) );
314 $msg = $context->msg( 'api-help-flags' );
315 if ( !$msg->isDisabled() ) {
316 $help['flags'] .= self
::wrap(
317 $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
320 $help['flags'] .= Html
::openElement( 'ul' );
321 foreach ( $module->getHelpFlags() as $flag ) {
322 $help['flags'] .= Html
::rawElement( 'li', null,
323 self
::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
326 $sourceInfo = $module->getModuleSourceInfo();
328 if ( isset( $sourceInfo['namemsg'] ) ) {
329 $extname = $context->msg( $sourceInfo['namemsg'] )->text();
331 $extname = $sourceInfo['name'];
333 $help['flags'] .= Html
::rawElement( 'li', null,
335 $context->msg( 'api-help-source', $extname, $sourceInfo['name'] ),
340 $link = SpecialPage
::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] );
341 if ( isset( $sourceInfo['license-name'] ) ) {
342 $msg = $context->msg( 'api-help-license', $link, $sourceInfo['license-name'] );
343 } elseif ( SpecialVersion
::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
344 $msg = $context->msg( 'api-help-license-noname', $link );
346 $msg = $context->msg( 'api-help-license-unknown' );
348 $help['flags'] .= Html
::rawElement( 'li', null,
349 self
::wrap( $msg, 'apihelp-license' )
352 $help['flags'] .= Html
::rawElement( 'li', null,
353 self
::wrap( $context->msg( 'api-help-source-unknown' ), 'apihelp-source' )
355 $help['flags'] .= Html
::rawElement( 'li', null,
356 self
::wrap( $context->msg( 'api-help-license-unknown' ), 'apihelp-license' )
359 $help['flags'] .= Html
::closeElement( 'ul' );
360 $help['flags'] .= Html
::closeElement( 'div' );
362 foreach ( $module->getFinalDescription() as $msg ) {
363 $msg->setContext( $context );
364 $help['description'] .= $msg->parseAsBlock();
367 $urls = $module->getHelpUrls();
369 $help['help-urls'] .= Html
::openElement( 'div',
370 array( 'class' => 'apihelp-block apihelp-help-urls' )
372 $msg = $context->msg( 'api-help-help-urls' );
373 if ( !$msg->isDisabled() ) {
374 $help['help-urls'] .= self
::wrap(
375 $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
378 if ( !is_array( $urls ) ) {
379 $urls = array( $urls );
381 $help['help-urls'] .= Html
::openElement( 'ul' );
382 foreach ( $urls as $url ) {
383 $help['help-urls'] .= Html
::rawElement( 'li', null,
384 Html
::element( 'a', array( 'href' => $url ), $url )
387 $help['help-urls'] .= Html
::closeElement( 'ul' );
388 $help['help-urls'] .= Html
::closeElement( 'div' );
391 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
394 $help['parameters'] .= Html
::openElement( 'div',
395 array( 'class' => 'apihelp-block apihelp-parameters' )
397 $msg = $context->msg( 'api-help-parameters' );
398 if ( !$msg->isDisabled() ) {
399 $help['parameters'] .= self
::wrap(
400 $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
403 $help['parameters'] .= Html
::openElement( 'dl' );
405 $descriptions = $module->getFinalParamDescription();
407 foreach ( $params as $name => $settings ) {
408 if ( !is_array( $settings ) ) {
409 $settings = array( ApiBase
::PARAM_DFLT
=> $settings );
412 $help['parameters'] .= Html
::element( 'dt', null,
413 $module->encodeParamName( $name ) );
416 $description = array();
417 if ( isset( $descriptions[$name] ) ) {
418 foreach ( $descriptions[$name] as $msg ) {
419 $msg->setContext( $context );
420 $description[] = $msg->parseAsBlock();
428 if ( !empty( $settings[ApiBase
::PARAM_REQUIRED
] ) ) {
429 $info[] = $context->msg( 'api-help-param-required' )->parse();
433 if ( !empty( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] ) ) {
434 foreach ( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] as $i ) {
435 $tag = array_shift( $i );
436 $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
437 ->numParams( count( $i ) )
438 ->params( $context->getLanguage()->commaList( $i ) )
439 ->params( $module->getModulePrefix() )
444 // Type documentation
445 if ( !isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
446 $dflt = isset( $settings[ApiBase
::PARAM_DFLT
] )
447 ?
$settings[ApiBase
::PARAM_DFLT
]
449 if ( is_bool( $dflt ) ) {
450 $settings[ApiBase
::PARAM_TYPE
] = 'boolean';
451 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
452 $settings[ApiBase
::PARAM_TYPE
] = 'string';
453 } elseif ( is_int( $dflt ) ) {
454 $settings[ApiBase
::PARAM_TYPE
] = 'integer';
457 if ( isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
458 $type = $settings[ApiBase
::PARAM_TYPE
];
459 $multi = !empty( $settings[ApiBase
::PARAM_ISMULTI
] );
460 $hintPipeSeparated = true;
461 $count = ApiBase
::LIMIT_SML2 +
1;
463 if ( is_array( $type ) ) {
464 $count = count( $type );
465 $links = isset( $settings[ApiBase
::PARAM_VALUE_LINKS
] )
466 ?
$settings[ApiBase
::PARAM_VALUE_LINKS
]
468 $type = array_map( function ( $v ) use ( $links ) {
469 $ret = wfEscapeWikiText( $v );
470 if ( isset( $links[$v] ) ) {
471 $ret = "[[{$links[$v]}|$ret]]";
475 $i = array_search( '', $type, true );
476 if ( $i === false ) {
477 $type = $context->getLanguage()->commaList( $type );
480 $type = $context->msg( 'api-help-param-list-can-be-empty' )
481 ->numParams( count( $type ) )
482 ->params( $context->getLanguage()->commaList( $type ) )
485 $info[] = $context->msg( 'api-help-param-list' )
486 ->params( $multi ?
2 : 1 )
489 $hintPipeSeparated = false;
494 if ( isset( $settings[ApiBase
::PARAM_SUBMODULE_MAP
] ) ) {
495 $map = $settings[ApiBase
::PARAM_SUBMODULE_MAP
];
497 $submodules = array();
498 foreach ( $map as $v => $m ) {
499 $submodules[] = "[[Special:ApiHelp/{$m}|{$v}]]";
502 $submodules = $module->getModuleManager()->getNames( $name );
504 $prefix = $module->isMain()
505 ?
'' : ( $module->getModulePath() . '+' );
506 $submodules = array_map( function ( $name ) use ( $prefix ) {
507 return "[[Special:ApiHelp/{$prefix}{$name}|{$name}]]";
510 $count = count( $submodules );
511 $info[] = $context->msg( 'api-help-param-list' )
512 ->params( $multi ?
2 : 1 )
513 ->params( $context->getLanguage()->commaList( $submodules ) )
515 $hintPipeSeparated = false;
516 // No type message necessary, we have a list of values.
521 $namespaces = MWNamespace
::getValidNamespaces();
522 $count = count( $namespaces );
523 $info[] = $context->msg( 'api-help-param-list' )
524 ->params( $multi ?
2 : 1 )
525 ->params( $context->getLanguage()->commaList( $namespaces ) )
527 $hintPipeSeparated = false;
528 // No type message necessary, we have a list of values.
533 if ( isset( $settings[ApiBase
::PARAM_MAX2
] ) ) {
534 $info[] = $context->msg( 'api-help-param-limit2' )
535 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
536 ->numParams( $settings[ApiBase
::PARAM_MAX2
] )
539 $info[] = $context->msg( 'api-help-param-limit' )
540 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
546 // Possible messages:
547 // api-help-param-integer-min,
548 // api-help-param-integer-max,
549 // api-help-param-integer-minmax
552 if ( isset( $settings[ApiBase
::PARAM_MIN
] ) ) {
554 $min = $settings[ApiBase
::PARAM_MIN
];
556 if ( isset( $settings[ApiBase
::PARAM_MAX
] ) ) {
558 $max = $settings[ApiBase
::PARAM_MAX
];
560 if ( $suffix !== '' ) {
562 $context->msg( "api-help-param-integer-$suffix" )
563 ->params( $multi ?
2 : 1 )
564 ->numParams( $min, $max )
570 $info[] = $context->msg( 'api-help-param-upload' )
572 // No type message necessary, api-help-param-upload should handle it.
578 // Displaying a type message here would be useless.
584 // Add type. Messages for grep: api-help-param-type-limit
585 // api-help-param-type-integer api-help-param-type-boolean
586 // api-help-param-type-timestamp api-help-param-type-user
587 // api-help-param-type-password
588 if ( is_string( $type ) ) {
589 $msg = $context->msg( "api-help-param-type-$type" );
590 if ( !$msg->isDisabled() ) {
591 $info[] = $msg->params( $multi ?
2 : 1 )->parse();
597 if ( $hintPipeSeparated ) {
598 $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
600 if ( $count > ApiBase
::LIMIT_SML1
) {
601 $extra[] = $context->msg( 'api-help-param-multi-max' )
602 ->numParams( ApiBase
::LIMIT_SML1
, ApiBase
::LIMIT_SML2
)
606 $info[] = join( ' ', $extra );
612 $default = isset( $settings[ApiBase
::PARAM_DFLT
] )
613 ?
$settings[ApiBase
::PARAM_DFLT
]
615 if ( $default === '' ) {
616 $info[] = $context->msg( 'api-help-param-default-empty' )
618 } elseif ( $default !== null && $default !== false ) {
619 $info[] = $context->msg( 'api-help-param-default' )
620 ->params( wfEscapeWikiText( $default ) )
624 if ( !array_filter( $description ) ) {
625 $description = array( self
::wrap(
626 $context->msg( 'api-help-param-no-description' ),
631 // Add "deprecated" flag
632 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED
] ) ) {
633 $help['parameters'] .= Html
::openElement( 'dd',
634 array( 'class' => 'info' ) );
635 $help['parameters'] .= self
::wrap(
636 $context->msg( 'api-help-param-deprecated' ),
637 'apihelp-deprecated', 'strong'
639 $help['parameters'] .= Html
::closeElement( 'dd' );
642 if ( $description ) {
643 $description = join( '', $description );
644 $description = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $description );
645 $help['parameters'] .= Html
::rawElement( 'dd',
646 array( 'class' => 'description' ), $description );
649 foreach ( $info as $i ) {
650 $help['parameters'] .= Html
::rawElement( 'dd', array( 'class' => 'info' ), $i );
654 $help['parameters'] .= Html
::closeElement( 'dl' );
655 $help['parameters'] .= Html
::closeElement( 'div' );
658 $examples = $module->getExamplesMessages();
660 $help['examples'] .= Html
::openElement( 'div',
661 array( 'class' => 'apihelp-block apihelp-examples' ) );
662 $msg = $context->msg( 'api-help-examples' );
663 if ( !$msg->isDisabled() ) {
664 $help['examples'] .= self
::wrap(
665 $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
669 $help['examples'] .= Html
::openElement( 'dl' );
670 foreach ( $examples as $qs => $msg ) {
671 $msg = ApiBase
::makeMessage( $msg, $context, array(
672 $module->getModulePrefix(),
673 $module->getModuleName(),
674 $module->getModulePath()
677 $link = wfAppendQuery( wfScript( 'api' ), $qs );
678 $help['examples'] .= Html
::rawElement( 'dt', null, $msg->parse() );
679 $help['examples'] .= Html
::rawElement( 'dd', null,
680 Html
::element( 'a', array( 'href' => $link ), "api.php?$qs" )
683 $help['examples'] .= Html
::closeElement( 'dl' );
684 $help['examples'] .= Html
::closeElement( 'div' );
687 $subtocnumber = $tocnumber;
688 $subtocnumber[$level +
1] = 0;
690 'submodules' => $options['recursivesubmodules'],
691 'headerlevel' => $level +
1,
692 'tocnumber' => &$subtocnumber,
696 if ( $options['submodules'] && $module->getModuleManager() ) {
697 $manager = $module->getModuleManager();
698 $submodules = array();
699 foreach ( $groups as $group ) {
700 $names = $manager->getNames( $group );
702 foreach ( $names as $name ) {
703 $submodules[] = $manager->getModule( $name );
706 $help['submodules'] .= self
::getHelpInternal( $context, $submodules, $suboptions, $haveModules );
707 $numSubmodules = count( $submodules );
710 $module->modifyHelp( $help, $suboptions, $haveModules );
712 Hooks
::run( 'APIHelpModifyOutput', array( $module, &$help, $suboptions, &$haveModules ) );
714 $out .= join( "\n", $help );
720 public function shouldCheckMaxlag() {
724 public function isReadMode() {
728 public function getCustomPrinter() {
729 $params = $this->extractRequestParams();
730 if ( $params['wrap'] ) {
734 $main = $this->getMain();
735 $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
736 return new ApiFormatRaw( $main, $errorPrinter );
739 public function getAllowedParams() {
742 ApiBase
::PARAM_DFLT
=> 'main',
743 ApiBase
::PARAM_ISMULTI
=> true,
745 'submodules' => false,
746 'recursivesubmodules' => false,
752 protected function getExamplesMessages() {
755 => 'apihelp-help-example-main',
756 'action=help&recursivesubmodules=1'
757 => 'apihelp-help-example-recursive',
758 'action=help&modules=help'
759 => 'apihelp-help-example-help',
760 'action=help&modules=query+info|query+categorymembers'
761 => 'apihelp-help-example-query',
765 public function getHelpUrls() {
767 'https://www.mediawiki.org/wiki/API:Main_page',
768 'https://www.mediawiki.org/wiki/API:FAQ',
769 'https://www.mediawiki.org/wiki/API:Quick_start_guide',