27use HtmlFormatter\HtmlFormatter;
41 foreach (
$params[
'modules'] as $path ) {
47 $context->setSkin( SkinFactory::getDefaultInstance()->makeSkin(
'apioutput' ) );
51 $out->setCopyrightUrl(
'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
59 $html = ob_get_clean();
64 'mime' =>
'text/html',
65 'filename' =>
'api-help.html',
105 $out->addModuleStyles( [
110 $out->addModules(
'mediawiki.toc' );
114 $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
120 if ( $cacheHelpTimeout > 0 ) {
125 $cached =
$cache->get( $cacheKey );
127 $out->addHTML( $cached );
132 if (
$out->getHTML() !==
'' ) {
138 $options[
'recursivesubmodules'] = !empty(
$options[
'recursivesubmodules'] );
142 if ( empty(
$options[
'nolead'] ) ) {
144 if ( !$msg->isDisabled() ) {
145 $out->addHTML( $msg->parseAsBlock() );
151 if ( !empty(
$options[
'toc'] ) && $haveModules ) {
161 if ( $cacheKey !==
null ) {
162 $cache->set( $cacheKey,
$out->getHTML(), $cacheHelpTimeout );
175 $formatter =
new HtmlFormatter(
$html );
176 $doc = $formatter->getDoc();
177 $xpath =
new DOMXPath( $doc );
178 $nodes = $xpath->query(
'//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
179 foreach ( $nodes as $node ) {
180 $href = $node->getAttribute(
'href' );
183 $href = rawurldecode( $href );
184 }
while ( $old !== $href );
185 if ( preg_match(
'!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
186 if ( isset( $localModules[$m[1]] ) ) {
187 $href = $m[2] ===
'' ?
'#' . $m[1] : $m[2];
188 } elseif ( $helptitle !==
null ) {
189 $href = Title::newFromText( str_replace(
'$1', $m[1], $helptitle ) . $m[2] )
197 $node->setAttribute(
'href', $href );
198 $node->removeAttribute(
'title' );
202 return $formatter->getText();
213 private static function wrap(
Message $msg, $class, $tag =
'span' ) {
214 return Html::rawElement( $tag, [
'class' => $class ],
234 if ( empty(
$options[
'tocnumber'] ) ) {
235 $tocnumber = [ 2 => 0 ];
237 $tocnumber = &
$options[
'tocnumber'];
241 $tocnumber[$level]++;
242 $path = $module->getModulePath();
257 while ( isset( $haveModules[$anchor] ) ) {
258 $anchor = $path .
'|' . ++$i;
261 if ( $module->isMain() ) {
262 $headerContent =
$context->
msg(
'api-help-main-header' )->parse();
264 'class' =>
'apihelp-header',
267 $name = $module->getModuleName();
268 $headerContent = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
270 if ( $module->getModulePrefix() !==
'' ) {
271 $headerContent .=
' ' .
272 $context->
msg(
'parentheses', $module->getModulePrefix() )->parse();
278 'class' =>
'apihelp-header apihelp-module-name',
284 $headerAttr[
'id'] = $anchor;
286 $haveModules[$anchor] = [
287 'toclevel' => count( $tocnumber ),
290 'line' => $headerContent,
291 'number' => implode(
'.', $tocnumber ),
294 if ( empty(
$options[
'noheader'] ) ) {
295 $help[
'header'] .= Html::element(
296 'h' . min( 6, $level ),
302 $haveModules[
$path] =
true;
307 for ( $m = $module; $m !==
null; $m = $m->getParent() ) {
308 $name = $m->getModuleName();
309 if ( $name ===
'main_int' ) {
314 !( !empty(
$options[
'submodules'] ) && $m->getModuleManager() )
316 $link = Html::element(
'b', [
'dir' =>
'ltr',
'lang' =>
'en' ], $name );
319 $link = Html::element(
'a',
320 [
'href' =>
$link,
'class' =>
'apihelp-linktrail',
'dir' =>
'ltr',
'lang' =>
'en' ],
325 array_unshift( $links,
$link );
331 'apihelp-linktrail',
'div'
335 $flags = $module->getHelpFlags();
336 $help[
'flags'] .= Html::openElement(
'div',
337 [
'class' =>
'apihelp-block apihelp-flags' ] );
339 if ( !$msg->isDisabled() ) {
341 $msg->numParams( count(
$flags ) ),
'apihelp-block-head',
'div'
344 $help[
'flags'] .= Html::openElement(
'ul' );
345 foreach (
$flags as $flag ) {
346 $help[
'flags'] .= Html::rawElement(
'li',
null,
347 self::wrap(
$context->
msg(
"api-help-flag-$flag" ),
"apihelp-flag-$flag" )
350 $sourceInfo = $module->getModuleSourceInfo();
352 if ( isset( $sourceInfo[
'namemsg'] ) ) {
353 $extname =
$context->
msg( $sourceInfo[
'namemsg'] )->text();
356 $extname = Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'name'] );
358 $help[
'flags'] .= Html::rawElement(
'li',
null,
360 $context->
msg(
'api-help-source', $extname, $sourceInfo[
'name'] ),
366 if ( isset( $sourceInfo[
'license-name'] ) ) {
368 Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $sourceInfo[
'license-name'] )
373 $msg =
$context->
msg(
'api-help-license-unknown' );
375 $help[
'flags'] .= Html::rawElement(
'li',
null,
376 self::wrap( $msg,
'apihelp-license' )
379 $help[
'flags'] .= Html::rawElement(
'li',
null,
380 self::wrap(
$context->
msg(
'api-help-source-unknown' ),
'apihelp-source' )
382 $help[
'flags'] .= Html::rawElement(
'li',
null,
383 self::wrap(
$context->
msg(
'api-help-license-unknown' ),
'apihelp-license' )
386 $help[
'flags'] .= Html::closeElement(
'ul' );
387 $help[
'flags'] .= Html::closeElement(
'div' );
389 foreach ( $module->getFinalDescription() as $msg ) {
391 $help[
'description'] .= $msg->parseAsBlock();
394 $urls = $module->getHelpUrls();
396 $help[
'help-urls'] .= Html::openElement(
'div',
397 [
'class' =>
'apihelp-block apihelp-help-urls' ]
400 if ( !$msg->isDisabled() ) {
402 $msg->numParams( count(
$urls ) ),
'apihelp-block-head',
'div'
405 if ( !is_array(
$urls ) ) {
408 $help[
'help-urls'] .= Html::openElement(
'ul' );
409 foreach (
$urls as $url ) {
410 $help[
'help-urls'] .= Html::rawElement(
'li',
null,
411 Html::element(
'a', [
'href' => $url,
'dir' =>
'ltr' ], $url )
414 $help[
'help-urls'] .= Html::closeElement(
'ul' );
415 $help[
'help-urls'] .= Html::closeElement(
'div' );
419 $dynamicParams = $module->dynamicParameterDocumentation();
421 if (
$params || $dynamicParams !==
null ) {
422 $help[
'parameters'] .= Html::openElement(
'div',
423 [
'class' =>
'apihelp-block apihelp-parameters' ]
426 if ( !$msg->isDisabled() ) {
428 $msg->numParams( count(
$params ) ),
'apihelp-block-head',
'div'
431 $help[
'parameters'] .= Html::openElement(
'dl' );
433 $descriptions = $module->getFinalParamDescription();
435 foreach (
$params as $name => $settings ) {
436 if ( !is_array( $settings ) ) {
440 $help[
'parameters'] .= Html::rawElement(
'dt',
null,
441 Html::element(
'span', [
'dir' =>
'ltr',
'lang' =>
'en' ], $module->encodeParamName( $name ) )
446 if ( isset( $descriptions[$name] ) ) {
447 foreach ( $descriptions[$name] as $msg ) {
449 $description[] = $msg->parseAsBlock();
458 $info[] =
$context->
msg(
'api-help-param-required' )->parse();
464 $tag = array_shift( $i );
465 $info[] =
$context->
msg(
"apihelp-{$path}-paraminfo-{$tag}" )
466 ->numParams( count( $i ) )
468 ->params( $module->getModulePrefix() )
478 if ( is_bool( $dflt ) ) {
480 } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
482 } elseif ( is_int( $dflt ) ) {
489 $hintPipeSeparated =
true;
494 if ( is_array(
$type ) ) {
495 $count = count(
$type );
502 $values = array_map(
function ( $v ) use ( $links, $deprecatedValues ) {
506 $attr[
'dir'] =
'auto';
508 if ( isset( $deprecatedValues[$v] ) ) {
509 $attr[
'class'] =
'apihelp-deprecated-value';
511 $ret = $attr ? Html::element(
'span', $attr, $v ) : $v;
512 if ( isset( $links[$v] ) ) {
513 $ret =
"[[{$links[$v]}|$ret]]";
517 $i = array_search(
'',
$type,
true );
518 if ( $i ===
false ) {
521 unset( $values[$i] );
522 $values =
$context->
msg(
'api-help-param-list-can-be-empty' )
523 ->numParams( count( $values ) )
528 ->params( $multi ? 2 : 1 )
531 $hintPipeSeparated =
false;
541 $prefix = $module->isMain() ?
'' : ( $module->getModulePath() .
'+' );
543 foreach ( $module->getModuleManager()->getNames( $name ) as $submoduleName ) {
544 $map[$submoduleName] = $prefix . $submoduleName;
546 $defaultAttrs = [
'dir' =>
'ltr',
'lang' =>
'en' ];
551 $deprecatedSubmodules = [];
552 foreach ( $map as $v => $m ) {
553 $attrs = $defaultAttrs;
556 $submod = $module->getModuleFromPath( $m );
558 if ( $submod->isDeprecated() ) {
559 $arr = &$deprecatedSubmodules;
560 $attrs[
'class'] =
'apihelp-deprecated-value';
567 $v = Html::element(
'span', $attrs, $v );
569 $arr[] =
"[[Special:ApiHelp/{$m}|{$v}]]";
571 $submodules = array_merge( $submodules, $deprecatedSubmodules );
572 $count = count( $submodules );
574 ->params( $multi ? 2 : 1 )
577 $hintPipeSeparated =
false;
592 ->params( $multi ? 2 : 1 )
595 $hintPipeSeparated =
false;
602 $count = count( $tags );
604 ->params( $multi ? 2 : 1 )
607 $hintPipeSeparated =
false;
639 if ( $suffix !==
'' ) {
642 ->params( $multi ? 2 : 1 )
643 ->numParams( $min, $max )
667 if ( is_string(
$type ) ) {
668 $msg =
$context->
msg(
"api-help-param-type-$type" );
669 if ( !$msg->isDisabled() ) {
670 $info[] = $msg->params( $multi ? 2 : 1 )->parse();
683 if ( $hintPipeSeparated ) {
684 $extra[] =
$context->
msg(
'api-help-param-multi-separate' )->parse();
686 if ( $count > $lowcount ) {
687 if ( $lowcount === $highcount ) {
688 $msg =
$context->
msg(
'api-help-param-multi-max-simple' )
689 ->numParams( $lowcount );
692 ->numParams( $lowcount, $highcount );
694 $extra[] = $msg->parse();
697 $info[] = implode(
' ', $extra );
709 $info[] =
$context->
msg(
'api-help-param-multi-all' )
710 ->params( $allSpecifier )
720 if ( $default ===
'' ) {
721 $info[] =
$context->
msg(
'api-help-param-default-empty' )
723 } elseif ( $default !==
null && $default !==
false ) {
725 $info[] =
$context->
msg(
'api-help-param-default' )
726 ->params( Html::element(
'span', [
'dir' =>
'auto' ], $default ) )
730 if ( !array_filter( $description ) ) {
739 $help[
'parameters'] .= Html::openElement(
'dd',
740 [
'class' =>
'info' ] );
743 'apihelp-deprecated',
'strong'
745 $help[
'parameters'] .= Html::closeElement(
'dd' );
748 if ( $description ) {
749 $description = implode(
'', $description );
750 $description = preg_replace(
'!\s*</([oud]l)>\s*<\1>\s*!',
"\n", $description );
751 $help[
'parameters'] .= Html::rawElement(
'dd',
752 [
'class' =>
'description' ], $description );
755 foreach ( $info as $i ) {
756 $help[
'parameters'] .= Html::rawElement(
'dd', [
'class' =>
'info' ], $i );
760 if ( $dynamicParams !==
null ) {
762 $module->getModulePrefix(),
763 $module->getModuleName(),
764 $module->getModulePath()
766 $help[
'parameters'] .= Html::element(
'dt',
null,
'*' );
767 $help[
'parameters'] .= Html::rawElement(
'dd',
768 [
'class' =>
'description' ], $dynamicParams->parse() );
771 $help[
'parameters'] .= Html::closeElement(
'dl' );
772 $help[
'parameters'] .= Html::closeElement(
'div' );
775 $examples = $module->getExamplesMessages();
777 $help[
'examples'] .= Html::openElement(
'div',
778 [
'class' =>
'apihelp-block apihelp-examples' ] );
780 if ( !$msg->isDisabled() ) {
782 $msg->numParams( count( $examples ) ),
'apihelp-block-head',
'div'
786 $help[
'examples'] .= Html::openElement(
'dl' );
787 foreach ( $examples as $qs => $msg ) {
789 $module->getModulePrefix(),
790 $module->getModuleName(),
791 $module->getModulePath()
796 $help[
'examples'] .= Html::rawElement(
'dt',
null, $msg->parse() );
797 $help[
'examples'] .= Html::rawElement(
'dd',
null,
798 Html::element(
'a', [
'href' =>
$link,
'dir' =>
'ltr' ],
"api.php?$qs" ) .
' ' .
799 Html::rawElement(
'a', [
'href' => $sandbox ],
800 $context->
msg(
'api-help-open-in-apisandbox' )->parse() )
803 $help[
'examples'] .= Html::closeElement(
'dl' );
804 $help[
'examples'] .= Html::closeElement(
'div' );
807 $subtocnumber = $tocnumber;
808 $subtocnumber[$level + 1] = 0;
810 'submodules' =>
$options[
'recursivesubmodules'],
811 'headerlevel' => $level + 1,
812 'tocnumber' => &$subtocnumber,
816 if (
$options[
'submodules'] && $module->getModuleManager() ) {
817 $manager = $module->getModuleManager();
819 foreach ( $groups as $group ) {
820 $names = $manager->getNames( $group );
822 foreach ( $names as $name ) {
823 $submodules[] = $manager->getModule( $name );
834 $module->modifyHelp(
$help, $suboptions, $haveModules );
836 Hooks::run(
'APIHelpModifyOutput', [ $module, &
$help, $suboptions, &$haveModules ] );
859 $errorPrinter = $main->createPrinterByName( $main->getParameter(
'format' ) );
869 'submodules' =>
false,
870 'recursivesubmodules' =>
false,
879 =>
'apihelp-help-example-main',
880 'action=help&modules=query&submodules=1'
881 =>
'apihelp-help-example-submodules',
882 'action=help&recursivesubmodules=1'
883 =>
'apihelp-help-example-recursive',
884 'action=help&modules=help'
885 =>
'apihelp-help-example-help',
886 'action=help&modules=query+info|query+categorymembers'
887 =>
'apihelp-help-example-query',
893 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
894 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
895 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',
wfAppendQuery( $url, $query)
Append a query string to an existing URL, which may or may not already have query string parameters a...
wfScript( $script='index')
Get the path to a specified script file, respecting file extensions; this is a wrapper around $wgScri...
This abstract class implements many basic API functions, and is the base of all API classes.
const PARAM_REQUIRED
(boolean) Is the parameter required?
const PARAM_MAX2
(integer) Max value allowed for the parameter for users with the apihighlimits right,...
const PARAM_SUBMODULE_MAP
(string[]) When PARAM_TYPE is 'submodule', map parameter values to submodule paths.
const PARAM_DEPRECATED
(boolean) Is the parameter deprecated (will show a warning)?
getModuleFromPath( $path)
Get a module from its module path.
static makeMessage( $msg, IContextSource $context, array $params=null)
Create a Message from a string or array.
const PARAM_MAX
(integer) Max value allowed for the parameter, for PARAM_TYPE 'integer' and 'limit'.
const PARAM_DEPRECATED_VALUES
(array) When PARAM_TYPE is an array, this indicates which of the values are deprecated.
const PARAM_ISMULTI_LIMIT1
(integer) Maximum number of values, for normal users.
getMain()
Get the main module.
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below.
const PARAM_HELP_MSG_INFO
(array) Specify additional information tags for the parameter.
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
const PARAM_VALUE_LINKS
(string[]) When PARAM_TYPE is an array, this may be an array mapping those values to page titles whic...
extractRequestParams( $parseLimit=true)
Using getAllowedParams(), this function makes an array of the values provided by the user,...
const PARAM_ISMULTI_LIMIT2
(integer) Maximum number of values, for users with the apihighimits right.
const PARAM_MIN
(integer) Lowest value allowed for the parameter, for PARAM_TYPE 'integer' and 'limit'.
const LIMIT_SML2
Slow query, apihighlimits limit.
getResult()
Get the result object.
getModulePath()
Get the path to this module.
const PARAM_EXTRA_NAMESPACES
(int[]) When PARAM_TYPE is 'namespace', include these as additional possible values.
const LIMIT_SML1
Slow query, standard limit.
const PARAM_ALL
(boolean|string) When PARAM_TYPE has a defined set of values and PARAM_ISMULTI is true,...
const GET_VALUES_FOR_HELP
getAllowedParams() flag: When set, the result could take longer to generate, but should be more thoro...
getModuleName()
Get the name of the module being executed by this instance.
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Class to output help for an API module.
static wrap(Message $msg, $class, $tag='span')
Wrap a message in HTML with a class.
isReadMode()
Indicates whether this module requires read rights.
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
getExamplesMessages()
Returns usage examples for this module.
static fixHelpLinks( $html, $helptitle=null, $localModules=[])
Replace Special:ApiHelp links with links to api.php.
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
getHelpUrls()
Return links to more detailed help pages about the module.
static getHelpInternal(IContextSource $context, array $modules, array $options, &$haveModules)
Recursively-called function to actually construct the help.
static getHelp(IContextSource $context, $modules, array $options)
Generate help for the specified modules.
shouldCheckMaxlag()
Indicates if this module needs maxlag to be checked.
getCustomPrinter()
If the module may only be used with a certain format module, it should override this method to return...
This is the main API class, used for both external and internal processing.
const NO_SIZE_CHECK
For addValue() and similar functions, do not check size while adding a value Don't use this unless yo...
static setSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as subelements rather than attributes.
Exception used to abort API execution with an error.
getLanguage()
Get the Language object.
getContext()
Get the base IContextSource object.
An IContextSource implementation which will inherit context from another source but allow individual ...
static generateTOC( $tree, $lang=false)
Generate a table of contents from a section tree.
The Message class provides methods which fulfil two basic services:
This class should be covered by a general architecture document which does not exist as of January 20...
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,...
static getExtLicenseFileName( $extDir)
Obtains the full path of an extensions copying or license file if one exists.
static getVersion( $flags='', $lang=null)
Return a string of the MediaWiki version with Git revision if available.
this class mediates it Skin Encapsulates a look and feel for the wiki All of the functions that render HTML and make choices about how to render it are here and are called from various other places when and is meant to be subclassed with other skins that may override some of its functions The User object contains a reference to a and so rather than having a global skin object we just rely on the global User and get the skin with $wgUser and also has some character encoding functions and other locale stuff The current user interface language is instantiated as and the local content language as $wgContLang
namespace and then decline to actually register it & $namespaces
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped & $options
it s the revision text itself In either if gzip is the revision text is gzipped $flags
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses & $ret
this hook is for auditing only or null if authentication failed before getting that far or null if we can t even determine that probably a stub it is not rendered in wiki pages or galleries in category pages allow injecting custom HTML after the section Any uses of the hook need to handle escaping see BaseTemplate::getToolbox and BaseTemplate::makeListItem for details on the format of individual items inside of this array or by returning and letting standard HTTP rendering take place modifiable or by returning false and taking over the output $out
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses just before the function returns a value If you return an< a > element with HTML attributes $attribs and contents $html will be returned If you return $ret will be returned and may include noclasses & $html
usually copyright or history_copyright This message must be in HTML not wikitext & $link
Allows to change the fields on the form that will be generated $name
Interface for objects which can provide a MediaWiki context on request.
getConfig()
Get the site configuration.
getOutput()
Get the OutputPage object.
getLanguage()
Get the Language object.
msg( $key)
This is the method for getting translated interface messages.