MediaWiki REL1_30
ApiHelp.php
Go to the documentation of this file.
1<?php
27use HtmlFormatter\HtmlFormatter;
29
36class ApiHelp extends ApiBase {
37 public function execute() {
39 $modules = [];
40
41 foreach ( $params['modules'] as $path ) {
42 $modules[] = $this->getModuleFromPath( $path );
43 }
44
45 // Get the help
46 $context = new DerivativeContext( $this->getMain()->getContext() );
47 $context->setSkin( SkinFactory::getDefaultInstance()->makeSkin( 'apioutput' ) );
48 $context->setLanguage( $this->getMain()->getLanguage() );
49 $context->setTitle( SpecialPage::getTitleFor( 'ApiHelp' ) );
50 $out = new OutputPage( $context );
51 $out->setCopyrightUrl( 'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
52 $context->setOutput( $out );
53
55
56 // Grab the output from the skin
57 ob_start();
58 $context->getOutput()->output();
59 $html = ob_get_clean();
60
61 $result = $this->getResult();
62 if ( $params['wrap'] ) {
63 $data = [
64 'mime' => 'text/html',
65 'filename' => 'api-help.html',
66 'help' => $html,
67 ];
68 ApiResult::setSubelementsList( $data, 'help' );
69 $result->addValue( null, $this->getModuleName(), $data );
70 } else {
71 $result->reset();
72 $result->addValue( null, 'text', $html, ApiResult::NO_SIZE_CHECK );
73 $result->addValue( null, 'mime', 'text/html', ApiResult::NO_SIZE_CHECK );
74 $result->addValue( null, 'filename', 'api-help.html', ApiResult::NO_SIZE_CHECK );
75 }
76 }
77
97 public static function getHelp( IContextSource $context, $modules, array $options ) {
98 global $wgContLang;
99
100 if ( !is_array( $modules ) ) {
101 $modules = [ $modules ];
102 }
103
105 $out->addModuleStyles( [
106 'mediawiki.hlist',
107 'mediawiki.apihelp',
108 ] );
109 if ( !empty( $options['toc'] ) ) {
110 $out->addModules( 'mediawiki.toc' );
111 }
112 $out->setPageTitle( $context->msg( 'api-help-title' ) );
113
114 $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
115 $cacheKey = null;
116 if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain &&
117 $options['recursivesubmodules'] && $context->getLanguage() === $wgContLang
118 ) {
119 $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
120 if ( $cacheHelpTimeout > 0 ) {
121 // Get help text from cache if present
122 $cacheKey = $cache->makeKey( 'apihelp', $modules[0]->getModulePath(),
123 (int)!empty( $options['toc'] ),
124 str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) ) );
125 $cached = $cache->get( $cacheKey );
126 if ( $cached ) {
127 $out->addHTML( $cached );
128 return;
129 }
130 }
131 }
132 if ( $out->getHTML() !== '' ) {
133 // Don't save to cache, there's someone else's content in the page
134 // already
135 $cacheKey = null;
136 }
137
138 $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
139 $options['submodules'] = $options['recursivesubmodules'] || !empty( $options['submodules'] );
140
141 // Prepend lead
142 if ( empty( $options['nolead'] ) ) {
143 $msg = $context->msg( 'api-help-lead' );
144 if ( !$msg->isDisabled() ) {
145 $out->addHTML( $msg->parseAsBlock() );
146 }
147 }
148
149 $haveModules = [];
151 if ( !empty( $options['toc'] ) && $haveModules ) {
152 $out->addHTML( Linker::generateTOC( $haveModules, $context->getLanguage() ) );
153 }
154 $out->addHTML( $html );
155
156 $helptitle = isset( $options['helptitle'] ) ? $options['helptitle'] : null;
157 $html = self::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
158 $out->clearHTML();
159 $out->addHTML( $html );
160
161 if ( $cacheKey !== null ) {
162 $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
163 }
164 }
165
174 public static function fixHelpLinks( $html, $helptitle = null, $localModules = [] ) {
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' );
181 do {
182 $old = $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] )
190 ->getFullURL();
191 } else {
192 $href = wfAppendQuery( wfScript( 'api' ), [
193 'action' => 'help',
194 'modules' => $m[1],
195 ] ) . $m[2];
196 }
197 $node->setAttribute( 'href', $href );
198 $node->removeAttribute( 'title' );
199 }
200 }
201
202 return $formatter->getText();
203 }
204
213 private static function wrap( Message $msg, $class, $tag = 'span' ) {
214 return Html::rawElement( $tag, [ 'class' => $class ],
215 $msg->parse()
216 );
217 }
218
228 private static function getHelpInternal( IContextSource $context, array $modules,
229 array $options, &$haveModules
230 ) {
231 $out = '';
232
233 $level = empty( $options['headerlevel'] ) ? 2 : $options['headerlevel'];
234 if ( empty( $options['tocnumber'] ) ) {
235 $tocnumber = [ 2 => 0 ];
236 } else {
237 $tocnumber = &$options['tocnumber'];
238 }
239
240 foreach ( $modules as $module ) {
241 $tocnumber[$level]++;
242 $path = $module->getModulePath();
243 $module->setContext( $context );
244 $help = [
245 'header' => '',
246 'flags' => '',
247 'description' => '',
248 'help-urls' => '',
249 'parameters' => '',
250 'examples' => '',
251 'submodules' => '',
252 ];
253
254 if ( empty( $options['noheader'] ) || !empty( $options['toc'] ) ) {
255 $anchor = $path;
256 $i = 1;
257 while ( isset( $haveModules[$anchor] ) ) {
258 $anchor = $path . '|' . ++$i;
259 }
260
261 if ( $module->isMain() ) {
262 $headerContent = $context->msg( 'api-help-main-header' )->parse();
263 $headerAttr = [
264 'class' => 'apihelp-header',
265 ];
266 } else {
267 $name = $module->getModuleName();
268 $headerContent = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
269 "=$name";
270 if ( $module->getModulePrefix() !== '' ) {
271 $headerContent .= ' ' .
272 $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
273 }
274 // Module names are always in English and not localized,
275 // so English language and direction must be set explicitly,
276 // otherwise parentheses will get broken in RTL wikis
277 $headerAttr = [
278 'class' => 'apihelp-header apihelp-module-name',
279 'dir' => 'ltr',
280 'lang' => 'en',
281 ];
282 }
283
284 $headerAttr['id'] = $anchor;
285
286 $haveModules[$anchor] = [
287 'toclevel' => count( $tocnumber ),
288 'level' => $level,
289 'anchor' => $anchor,
290 'line' => $headerContent,
291 'number' => implode( '.', $tocnumber ),
292 'index' => false,
293 ];
294 if ( empty( $options['noheader'] ) ) {
295 $help['header'] .= Html::element(
296 'h' . min( 6, $level ),
297 $headerAttr,
298 $headerContent
299 );
300 }
301 } else {
302 $haveModules[$path] = true;
303 }
304
305 $links = [];
306 $any = false;
307 for ( $m = $module; $m !== null; $m = $m->getParent() ) {
308 $name = $m->getModuleName();
309 if ( $name === 'main_int' ) {
310 $name = 'main';
311 }
312
313 if ( count( $modules ) === 1 && $m === $modules[0] &&
314 !( !empty( $options['submodules'] ) && $m->getModuleManager() )
315 ) {
316 $link = Html::element( 'b', [ 'dir' => 'ltr', 'lang' => 'en' ], $name );
317 } else {
318 $link = SpecialPage::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
319 $link = Html::element( 'a',
320 [ 'href' => $link, 'class' => 'apihelp-linktrail', 'dir' => 'ltr', 'lang' => 'en' ],
321 $name
322 );
323 $any = true;
324 }
325 array_unshift( $links, $link );
326 }
327 if ( $any ) {
328 $help['header'] .= self::wrap(
329 $context->msg( 'parentheses' )
330 ->rawParams( $context->getLanguage()->pipeList( $links ) ),
331 'apihelp-linktrail', 'div'
332 );
333 }
334
335 $flags = $module->getHelpFlags();
336 $help['flags'] .= Html::openElement( 'div',
337 [ 'class' => 'apihelp-block apihelp-flags' ] );
338 $msg = $context->msg( 'api-help-flags' );
339 if ( !$msg->isDisabled() ) {
340 $help['flags'] .= self::wrap(
341 $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
342 );
343 }
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" )
348 );
349 }
350 $sourceInfo = $module->getModuleSourceInfo();
351 if ( $sourceInfo ) {
352 if ( isset( $sourceInfo['namemsg'] ) ) {
353 $extname = $context->msg( $sourceInfo['namemsg'] )->text();
354 } else {
355 // Probably English, so wrap it.
356 $extname = Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['name'] );
357 }
358 $help['flags'] .= Html::rawElement( 'li', null,
359 self::wrap(
360 $context->msg( 'api-help-source', $extname, $sourceInfo['name'] ),
361 'apihelp-source'
362 )
363 );
364
365 $link = SpecialPage::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] );
366 if ( isset( $sourceInfo['license-name'] ) ) {
367 $msg = $context->msg( 'api-help-license', $link,
368 Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['license-name'] )
369 );
370 } elseif ( SpecialVersion::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
371 $msg = $context->msg( 'api-help-license-noname', $link );
372 } else {
373 $msg = $context->msg( 'api-help-license-unknown' );
374 }
375 $help['flags'] .= Html::rawElement( 'li', null,
376 self::wrap( $msg, 'apihelp-license' )
377 );
378 } else {
379 $help['flags'] .= Html::rawElement( 'li', null,
380 self::wrap( $context->msg( 'api-help-source-unknown' ), 'apihelp-source' )
381 );
382 $help['flags'] .= Html::rawElement( 'li', null,
383 self::wrap( $context->msg( 'api-help-license-unknown' ), 'apihelp-license' )
384 );
385 }
386 $help['flags'] .= Html::closeElement( 'ul' );
387 $help['flags'] .= Html::closeElement( 'div' );
388
389 foreach ( $module->getFinalDescription() as $msg ) {
390 $msg->setContext( $context );
391 $help['description'] .= $msg->parseAsBlock();
392 }
393
394 $urls = $module->getHelpUrls();
395 if ( $urls ) {
396 $help['help-urls'] .= Html::openElement( 'div',
397 [ 'class' => 'apihelp-block apihelp-help-urls' ]
398 );
399 $msg = $context->msg( 'api-help-help-urls' );
400 if ( !$msg->isDisabled() ) {
401 $help['help-urls'] .= self::wrap(
402 $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
403 );
404 }
405 if ( !is_array( $urls ) ) {
406 $urls = [ $urls ];
407 }
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 )
412 );
413 }
414 $help['help-urls'] .= Html::closeElement( 'ul' );
415 $help['help-urls'] .= Html::closeElement( 'div' );
416 }
417
418 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
419 $dynamicParams = $module->dynamicParameterDocumentation();
420 $groups = [];
421 if ( $params || $dynamicParams !== null ) {
422 $help['parameters'] .= Html::openElement( 'div',
423 [ 'class' => 'apihelp-block apihelp-parameters' ]
424 );
425 $msg = $context->msg( 'api-help-parameters' );
426 if ( !$msg->isDisabled() ) {
427 $help['parameters'] .= self::wrap(
428 $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
429 );
430 }
431 $help['parameters'] .= Html::openElement( 'dl' );
432
433 $descriptions = $module->getFinalParamDescription();
434
435 foreach ( $params as $name => $settings ) {
436 if ( !is_array( $settings ) ) {
437 $settings = [ ApiBase::PARAM_DFLT => $settings ];
438 }
439
440 $help['parameters'] .= Html::rawElement( 'dt', null,
441 Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $module->encodeParamName( $name ) )
442 );
443
444 // Add description
445 $description = [];
446 if ( isset( $descriptions[$name] ) ) {
447 foreach ( $descriptions[$name] as $msg ) {
448 $msg->setContext( $context );
449 $description[] = $msg->parseAsBlock();
450 }
451 }
452
453 // Add usage info
454 $info = [];
455
456 // Required?
457 if ( !empty( $settings[ApiBase::PARAM_REQUIRED] ) ) {
458 $info[] = $context->msg( 'api-help-param-required' )->parse();
459 }
460
461 // Custom info?
462 if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
463 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
464 $tag = array_shift( $i );
465 $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
466 ->numParams( count( $i ) )
467 ->params( $context->getLanguage()->commaList( $i ) )
468 ->params( $module->getModulePrefix() )
469 ->parse();
470 }
471 }
472
473 // Type documentation
474 if ( !isset( $settings[ApiBase::PARAM_TYPE] ) ) {
475 $dflt = isset( $settings[ApiBase::PARAM_DFLT] )
476 ? $settings[ApiBase::PARAM_DFLT]
477 : null;
478 if ( is_bool( $dflt ) ) {
479 $settings[ApiBase::PARAM_TYPE] = 'boolean';
480 } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
481 $settings[ApiBase::PARAM_TYPE] = 'string';
482 } elseif ( is_int( $dflt ) ) {
483 $settings[ApiBase::PARAM_TYPE] = 'integer';
484 }
485 }
486 if ( isset( $settings[ApiBase::PARAM_TYPE] ) ) {
487 $type = $settings[ApiBase::PARAM_TYPE];
488 $multi = !empty( $settings[ApiBase::PARAM_ISMULTI] );
489 $hintPipeSeparated = true;
490 $count = !empty( $settings[ApiBase::PARAM_ISMULTI_LIMIT2] )
491 ? $settings[ApiBase::PARAM_ISMULTI_LIMIT2] + 1
493
494 if ( is_array( $type ) ) {
495 $count = count( $type );
496 $deprecatedValues = isset( $settings[ApiBase::PARAM_DEPRECATED_VALUES] )
498 : [];
499 $links = isset( $settings[ApiBase::PARAM_VALUE_LINKS] )
500 ? $settings[ApiBase::PARAM_VALUE_LINKS]
501 : [];
502 $values = array_map( function ( $v ) use ( $links, $deprecatedValues ) {
503 $attr = [];
504 if ( $v !== '' ) {
505 // We can't know whether this contains LTR or RTL text.
506 $attr['dir'] = 'auto';
507 }
508 if ( isset( $deprecatedValues[$v] ) ) {
509 $attr['class'] = 'apihelp-deprecated-value';
510 }
511 $ret = $attr ? Html::element( 'span', $attr, $v ) : $v;
512 if ( isset( $links[$v] ) ) {
513 $ret = "[[{$links[$v]}|$ret]]";
514 }
515 return $ret;
516 }, $type );
517 $i = array_search( '', $type, true );
518 if ( $i === false ) {
519 $values = $context->getLanguage()->commaList( $values );
520 } else {
521 unset( $values[$i] );
522 $values = $context->msg( 'api-help-param-list-can-be-empty' )
523 ->numParams( count( $values ) )
524 ->params( $context->getLanguage()->commaList( $values ) )
525 ->parse();
526 }
527 $info[] = $context->msg( 'api-help-param-list' )
528 ->params( $multi ? 2 : 1 )
529 ->params( $values )
530 ->parse();
531 $hintPipeSeparated = false;
532 } else {
533 switch ( $type ) {
534 case 'submodule':
535 $groups[] = $name;
536
537 if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) {
538 $map = $settings[ApiBase::PARAM_SUBMODULE_MAP];
539 $defaultAttrs = [];
540 } else {
541 $prefix = $module->isMain() ? '' : ( $module->getModulePath() . '+' );
542 $map = [];
543 foreach ( $module->getModuleManager()->getNames( $name ) as $submoduleName ) {
544 $map[$submoduleName] = $prefix . $submoduleName;
545 }
546 $defaultAttrs = [ 'dir' => 'ltr', 'lang' => 'en' ];
547 }
548 ksort( $map );
549
550 $submodules = [];
551 $deprecatedSubmodules = [];
552 foreach ( $map as $v => $m ) {
553 $attrs = $defaultAttrs;
554 $arr = &$submodules;
555 try {
556 $submod = $module->getModuleFromPath( $m );
557 if ( $submod ) {
558 if ( $submod->isDeprecated() ) {
559 $arr = &$deprecatedSubmodules;
560 $attrs['class'] = 'apihelp-deprecated-value';
561 }
562 }
563 } catch ( ApiUsageException $ex ) {
564 // Ignore
565 }
566 if ( $attrs ) {
567 $v = Html::element( 'span', $attrs, $v );
568 }
569 $arr[] = "[[Special:ApiHelp/{$m}|{$v}]]";
570 }
571 $submodules = array_merge( $submodules, $deprecatedSubmodules );
572 $count = count( $submodules );
573 $info[] = $context->msg( 'api-help-param-list' )
574 ->params( $multi ? 2 : 1 )
575 ->params( $context->getLanguage()->commaList( $submodules ) )
576 ->parse();
577 $hintPipeSeparated = false;
578 // No type message necessary, we have a list of values.
579 $type = null;
580 break;
581
582 case 'namespace':
583 $namespaces = MWNamespace::getValidNamespaces();
584 if ( isset( $settings[ApiBase::PARAM_EXTRA_NAMESPACES] ) &&
585 is_array( $settings[ApiBase::PARAM_EXTRA_NAMESPACES] )
586 ) {
587 $namespaces = array_merge( $namespaces, $settings[ApiBase::PARAM_EXTRA_NAMESPACES] );
588 }
589 sort( $namespaces );
590 $count = count( $namespaces );
591 $info[] = $context->msg( 'api-help-param-list' )
592 ->params( $multi ? 2 : 1 )
593 ->params( $context->getLanguage()->commaList( $namespaces ) )
594 ->parse();
595 $hintPipeSeparated = false;
596 // No type message necessary, we have a list of values.
597 $type = null;
598 break;
599
600 case 'tags':
602 $count = count( $tags );
603 $info[] = $context->msg( 'api-help-param-list' )
604 ->params( $multi ? 2 : 1 )
605 ->params( $context->getLanguage()->commaList( $tags ) )
606 ->parse();
607 $hintPipeSeparated = false;
608 $type = null;
609 break;
610
611 case 'limit':
612 if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
613 $info[] = $context->msg( 'api-help-param-limit2' )
614 ->numParams( $settings[ApiBase::PARAM_MAX] )
615 ->numParams( $settings[ApiBase::PARAM_MAX2] )
616 ->parse();
617 } else {
618 $info[] = $context->msg( 'api-help-param-limit' )
619 ->numParams( $settings[ApiBase::PARAM_MAX] )
620 ->parse();
621 }
622 break;
623
624 case 'integer':
625 // Possible messages:
626 // api-help-param-integer-min,
627 // api-help-param-integer-max,
628 // api-help-param-integer-minmax
629 $suffix = '';
630 $min = $max = 0;
631 if ( isset( $settings[ApiBase::PARAM_MIN] ) ) {
632 $suffix .= 'min';
633 $min = $settings[ApiBase::PARAM_MIN];
634 }
635 if ( isset( $settings[ApiBase::PARAM_MAX] ) ) {
636 $suffix .= 'max';
637 $max = $settings[ApiBase::PARAM_MAX];
638 }
639 if ( $suffix !== '' ) {
640 $info[] =
641 $context->msg( "api-help-param-integer-$suffix" )
642 ->params( $multi ? 2 : 1 )
643 ->numParams( $min, $max )
644 ->parse();
645 }
646 break;
647
648 case 'upload':
649 $info[] = $context->msg( 'api-help-param-upload' )
650 ->parse();
651 // No type message necessary, api-help-param-upload should handle it.
652 $type = null;
653 break;
654
655 case 'string':
656 case 'text':
657 // Displaying a type message here would be useless.
658 $type = null;
659 break;
660 }
661 }
662
663 // Add type. Messages for grep: api-help-param-type-limit
664 // api-help-param-type-integer api-help-param-type-boolean
665 // api-help-param-type-timestamp api-help-param-type-user
666 // api-help-param-type-password
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();
671 }
672 }
673
674 if ( $multi ) {
675 $extra = [];
676 $lowcount = !empty( $settings[ApiBase::PARAM_ISMULTI_LIMIT1] )
679 $highcount = !empty( $settings[ApiBase::PARAM_ISMULTI_LIMIT2] )
682
683 if ( $hintPipeSeparated ) {
684 $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
685 }
686 if ( $count > $lowcount ) {
687 if ( $lowcount === $highcount ) {
688 $msg = $context->msg( 'api-help-param-multi-max-simple' )
689 ->numParams( $lowcount );
690 } else {
691 $msg = $context->msg( 'api-help-param-multi-max' )
692 ->numParams( $lowcount, $highcount );
693 }
694 $extra[] = $msg->parse();
695 }
696 if ( $extra ) {
697 $info[] = implode( ' ', $extra );
698 }
699
700 $allowAll = isset( $settings[ApiBase::PARAM_ALL] )
701 ? $settings[ApiBase::PARAM_ALL]
702 : false;
703 if ( $allowAll || $settings[ApiBase::PARAM_TYPE] === 'namespace' ) {
704 if ( $settings[ApiBase::PARAM_TYPE] === 'namespace' ) {
705 $allSpecifier = ApiBase::ALL_DEFAULT_STRING;
706 } else {
707 $allSpecifier = ( is_string( $allowAll ) ? $allowAll : ApiBase::ALL_DEFAULT_STRING );
708 }
709 $info[] = $context->msg( 'api-help-param-multi-all' )
710 ->params( $allSpecifier )
711 ->parse();
712 }
713 }
714 }
715
716 // Add default
717 $default = isset( $settings[ApiBase::PARAM_DFLT] )
718 ? $settings[ApiBase::PARAM_DFLT]
719 : null;
720 if ( $default === '' ) {
721 $info[] = $context->msg( 'api-help-param-default-empty' )
722 ->parse();
723 } elseif ( $default !== null && $default !== false ) {
724 // We can't know whether this contains LTR or RTL text.
725 $info[] = $context->msg( 'api-help-param-default' )
726 ->params( Html::element( 'span', [ 'dir' => 'auto' ], $default ) )
727 ->parse();
728 }
729
730 if ( !array_filter( $description ) ) {
731 $description = [ self::wrap(
732 $context->msg( 'api-help-param-no-description' ),
733 'apihelp-empty'
734 ) ];
735 }
736
737 // Add "deprecated" flag
738 if ( !empty( $settings[ApiBase::PARAM_DEPRECATED] ) ) {
739 $help['parameters'] .= Html::openElement( 'dd',
740 [ 'class' => 'info' ] );
741 $help['parameters'] .= self::wrap(
742 $context->msg( 'api-help-param-deprecated' ),
743 'apihelp-deprecated', 'strong'
744 );
745 $help['parameters'] .= Html::closeElement( 'dd' );
746 }
747
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 );
753 }
754
755 foreach ( $info as $i ) {
756 $help['parameters'] .= Html::rawElement( 'dd', [ 'class' => 'info' ], $i );
757 }
758 }
759
760 if ( $dynamicParams !== null ) {
761 $dynamicParams = ApiBase::makeMessage( $dynamicParams, $context, [
762 $module->getModulePrefix(),
763 $module->getModuleName(),
764 $module->getModulePath()
765 ] );
766 $help['parameters'] .= Html::element( 'dt', null, '*' );
767 $help['parameters'] .= Html::rawElement( 'dd',
768 [ 'class' => 'description' ], $dynamicParams->parse() );
769 }
770
771 $help['parameters'] .= Html::closeElement( 'dl' );
772 $help['parameters'] .= Html::closeElement( 'div' );
773 }
774
775 $examples = $module->getExamplesMessages();
776 if ( $examples ) {
777 $help['examples'] .= Html::openElement( 'div',
778 [ 'class' => 'apihelp-block apihelp-examples' ] );
779 $msg = $context->msg( 'api-help-examples' );
780 if ( !$msg->isDisabled() ) {
781 $help['examples'] .= self::wrap(
782 $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
783 );
784 }
785
786 $help['examples'] .= Html::openElement( 'dl' );
787 foreach ( $examples as $qs => $msg ) {
788 $msg = ApiBase::makeMessage( $msg, $context, [
789 $module->getModulePrefix(),
790 $module->getModuleName(),
791 $module->getModulePath()
792 ] );
793
794 $link = wfAppendQuery( wfScript( 'api' ), $qs );
795 $sandbox = SpecialPage::getTitleFor( 'ApiSandbox' )->getLocalURL() . '#' . $qs;
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() )
801 );
802 }
803 $help['examples'] .= Html::closeElement( 'dl' );
804 $help['examples'] .= Html::closeElement( 'div' );
805 }
806
807 $subtocnumber = $tocnumber;
808 $subtocnumber[$level + 1] = 0;
809 $suboptions = [
810 'submodules' => $options['recursivesubmodules'],
811 'headerlevel' => $level + 1,
812 'tocnumber' => &$subtocnumber,
813 'noheader' => false,
814 ] + $options;
815
816 if ( $options['submodules'] && $module->getModuleManager() ) {
817 $manager = $module->getModuleManager();
818 $submodules = [];
819 foreach ( $groups as $group ) {
820 $names = $manager->getNames( $group );
821 sort( $names );
822 foreach ( $names as $name ) {
823 $submodules[] = $manager->getModule( $name );
824 }
825 }
826 $help['submodules'] .= self::getHelpInternal(
827 $context,
828 $submodules,
829 $suboptions,
830 $haveModules
831 );
832 }
833
834 $module->modifyHelp( $help, $suboptions, $haveModules );
835
836 Hooks::run( 'APIHelpModifyOutput', [ $module, &$help, $suboptions, &$haveModules ] );
837
838 $out .= implode( "\n", $help );
839 }
840
841 return $out;
842 }
843
844 public function shouldCheckMaxlag() {
845 return false;
846 }
847
848 public function isReadMode() {
849 return false;
850 }
851
852 public function getCustomPrinter() {
853 $params = $this->extractRequestParams();
854 if ( $params['wrap'] ) {
855 return null;
856 }
857
858 $main = $this->getMain();
859 $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
860 return new ApiFormatRaw( $main, $errorPrinter );
861 }
862
863 public function getAllowedParams() {
864 return [
865 'modules' => [
866 ApiBase::PARAM_DFLT => 'main',
868 ],
869 'submodules' => false,
870 'recursivesubmodules' => false,
871 'wrap' => false,
872 'toc' => false,
873 ];
874 }
875
876 protected function getExamplesMessages() {
877 return [
878 'action=help'
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',
888 ];
889 }
890
891 public function getHelpUrls() {
892 return [
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',
896 ];
897 }
898}
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.
Definition ApiBase.php:41
const PARAM_REQUIRED
(boolean) Is the parameter required?
Definition ApiBase.php:115
const PARAM_MAX2
(integer) Max value allowed for the parameter for users with the apihighlimits right,...
Definition ApiBase.php:100
const PARAM_SUBMODULE_MAP
(string[]) When PARAM_TYPE is 'submodule', map parameter values to submodule paths.
Definition ApiBase.php:168
const PARAM_DEPRECATED
(boolean) Is the parameter deprecated (will show a warning)?
Definition ApiBase.php:109
getModuleFromPath( $path)
Get a module from its module path.
Definition ApiBase.php:594
static makeMessage( $msg, IContextSource $context, array $params=null)
Create a Message from a string or array.
Definition ApiBase.php:1701
const PARAM_MAX
(integer) Max value allowed for the parameter, for PARAM_TYPE 'integer' and 'limit'.
Definition ApiBase.php:94
const PARAM_DEPRECATED_VALUES
(array) When PARAM_TYPE is an array, this indicates which of the values are deprecated.
Definition ApiBase.php:205
const PARAM_ISMULTI_LIMIT1
(integer) Maximum number of values, for normal users.
Definition ApiBase.php:211
getMain()
Get the main module.
Definition ApiBase.php:528
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below.
Definition ApiBase.php:91
const PARAM_HELP_MSG_INFO
(array) Specify additional information tags for the parameter.
Definition ApiBase.php:145
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition ApiBase.php:52
const PARAM_VALUE_LINKS
(string[]) When PARAM_TYPE is an array, this may be an array mapping those values to page titles whic...
Definition ApiBase.php:152
extractRequestParams( $parseLimit=true)
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition ApiBase.php:740
const PARAM_ISMULTI_LIMIT2
(integer) Maximum number of values, for users with the apihighimits right.
Definition ApiBase.php:218
const PARAM_MIN
(integer) Lowest value allowed for the parameter, for PARAM_TYPE 'integer' and 'limit'.
Definition ApiBase.php:103
const LIMIT_SML2
Slow query, apihighlimits limit.
Definition ApiBase.php:231
getResult()
Get the result object.
Definition ApiBase.php:632
getModulePath()
Get the path to this module.
Definition ApiBase.php:576
const PARAM_EXTRA_NAMESPACES
(int[]) When PARAM_TYPE is 'namespace', include these as additional possible values.
Definition ApiBase.php:189
const LIMIT_SML1
Slow query, standard limit.
Definition ApiBase.php:229
const PARAM_ALL
(boolean|string) When PARAM_TYPE has a defined set of values and PARAM_ISMULTI is true,...
Definition ApiBase.php:183
const GET_VALUES_FOR_HELP
getAllowedParams() flag: When set, the result could take longer to generate, but should be more thoro...
Definition ApiBase.php:238
getModuleName()
Get the name of the module being executed by this instance.
Definition ApiBase.php:512
const ALL_DEFAULT_STRING
Definition ApiBase.php:222
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Definition ApiBase.php:55
Formatter that spits out anything you like with any desired MIME type.
Class to output help for an API module.
Definition ApiHelp.php:36
static wrap(Message $msg, $class, $tag='span')
Wrap a message in HTML with a class.
Definition ApiHelp.php:213
isReadMode()
Indicates whether this module requires read rights.
Definition ApiHelp.php:848
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
Definition ApiHelp.php:37
getExamplesMessages()
Returns usage examples for this module.
Definition ApiHelp.php:876
static fixHelpLinks( $html, $helptitle=null, $localModules=[])
Replace Special:ApiHelp links with links to api.php.
Definition ApiHelp.php:174
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
Definition ApiHelp.php:863
getHelpUrls()
Return links to more detailed help pages about the module.
Definition ApiHelp.php:891
static getHelpInternal(IContextSource $context, array $modules, array $options, &$haveModules)
Recursively-called function to actually construct the help.
Definition ApiHelp.php:228
static getHelp(IContextSource $context, $modules, array $options)
Generate help for the specified modules.
Definition ApiHelp.php:97
shouldCheckMaxlag()
Indicates if this module needs maxlag to be checked.
Definition ApiHelp.php:844
getCustomPrinter()
If the module may only be used with a certain format module, it should override this method to return...
Definition ApiHelp.php:852
This is the main API class, used for both external and internal processing.
Definition ApiMain.php:45
const NO_SIZE_CHECK
For addValue() and similar functions, do not check size while adding a value Don't use this unless yo...
Definition ApiResult.php:56
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.
static listExplicitlyDefinedTags()
Lists tags explicitly defined in the valid_tag table of the database.
IContextSource $context
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.
Definition Linker.php:1589
MediaWikiServices is the service locator for the application scope of MediaWiki.
The Message class provides methods which fulfil two basic services:
Definition Message.php:159
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
Definition design.txt:57
namespace and then decline to actually register it & $namespaces
Definition hooks.txt:932
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
Definition hooks.txt:1971
it s the revision text itself In either if gzip is the revision text is gzipped $flags
Definition hooks.txt:2805
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
Definition hooks.txt:1975
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
Definition hooks.txt:862
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
Definition hooks.txt:1983
usually copyright or history_copyright This message must be in HTML not wikitext & $link
Definition hooks.txt:2989
Allows to change the fields on the form that will be generated $name
Definition hooks.txt:302
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.
$cache
Definition mcc.php:33
$help
Definition mcc.php:32
$params