MediaWiki  master
ApiHelp.php
Go to the documentation of this file.
1 <?php
25 
32 class ApiHelp extends ApiBase {
33  public function execute() {
34  $params = $this->extractRequestParams();
35  $modules = [];
36 
37  foreach ( $params['modules'] as $path ) {
38  $modules[] = $this->getModuleFromPath( $path );
39  }
40 
41  // Get the help
42  $context = new DerivativeContext( $this->getMain()->getContext() );
43  $skinFactory = MediaWikiServices::getInstance()->getSkinFactory();
44  $context->setSkin( $skinFactory->makeSkin( 'apioutput' ) );
45  $context->setLanguage( $this->getMain()->getLanguage() );
46  $context->setTitle( SpecialPage::getTitleFor( 'ApiHelp' ) );
47  $out = new OutputPage( $context );
48  $out->setRobotPolicy( 'noindex,nofollow' );
49  $out->setCopyrightUrl( 'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
50  $context->setOutput( $out );
51 
52  self::getHelp( $context, $modules, $params );
53 
54  // Grab the output from the skin
55  ob_start();
56  $context->getOutput()->output();
57  $html = ob_get_clean();
58 
59  $result = $this->getResult();
60  if ( $params['wrap'] ) {
61  $data = [
62  'mime' => 'text/html',
63  'filename' => 'api-help.html',
64  'help' => $html,
65  ];
66  ApiResult::setSubelementsList( $data, 'help' );
67  $result->addValue( null, $this->getModuleName(), $data );
68  } else {
69  // Show any errors at the top of the HTML
70  $transform = [
71  'Types' => [ 'AssocAsObject' => true ],
72  'Strip' => 'all',
73  ];
74  $errors = array_filter( [
75  'errors' => $this->getResult()->getResultData( [ 'errors' ], $transform ),
76  'warnings' => $this->getResult()->getResultData( [ 'warnings' ], $transform ),
77  ] );
78  if ( $errors ) {
79  $json = FormatJson::encode( $errors, true, FormatJson::UTF8_OK );
80  // Escape any "--", some parsers might interpret that as end-of-comment.
81  // The above already escaped any "<" and ">".
82  $json = str_replace( '--', '-\u002D', $json );
83  $html = "<!-- API warnings and errors:\n$json\n-->\n$html";
84  }
85 
86  $result->reset();
87  $result->addValue( null, 'text', $html, ApiResult::NO_SIZE_CHECK );
88  $result->addValue( null, 'mime', 'text/html', ApiResult::NO_SIZE_CHECK );
89  $result->addValue( null, 'filename', 'api-help.html', ApiResult::NO_SIZE_CHECK );
90  }
91  }
92 
112  public static function getHelp( IContextSource $context, $modules, array $options ) {
113  if ( !is_array( $modules ) ) {
114  $modules = [ $modules ];
115  }
116 
117  $out = $context->getOutput();
118  $out->addModuleStyles( [
119  'mediawiki.hlist',
120  'mediawiki.apipretty',
121  ] );
122  if ( !empty( $options['toc'] ) ) {
123  $out->addModuleStyles( 'mediawiki.toc.styles' );
124  }
125  $out->setPageTitle( $context->msg( 'api-help-title' ) );
126 
127  $services = MediaWikiServices::getInstance();
128  $cache = $services->getMainWANObjectCache();
129  $cacheKey = null;
130  if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain &&
131  $options['recursivesubmodules'] &&
132  $context->getLanguage()->equals( $services->getContentLanguage() )
133  ) {
134  $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
135  if ( $cacheHelpTimeout > 0 ) {
136  // Get help text from cache if present
137  $cacheKey = $cache->makeKey( 'apihelp', $modules[0]->getModulePath(),
138  (int)!empty( $options['toc'] ),
139  str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) ) );
140  $cached = $cache->get( $cacheKey );
141  if ( $cached ) {
142  $out->addHTML( $cached );
143  return;
144  }
145  }
146  }
147  if ( $out->getHTML() !== '' ) {
148  // Don't save to cache, there's someone else's content in the page
149  // already
150  $cacheKey = null;
151  }
152 
153  $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
154  $options['submodules'] = $options['recursivesubmodules'] || !empty( $options['submodules'] );
155 
156  // Prepend lead
157  if ( empty( $options['nolead'] ) ) {
158  $msg = $context->msg( 'api-help-lead' );
159  if ( !$msg->isDisabled() ) {
160  $out->addHTML( $msg->parseAsBlock() );
161  }
162  }
163 
164  $haveModules = [];
165  $html = self::getHelpInternal( $context, $modules, $options, $haveModules );
166  if ( !empty( $options['toc'] ) && $haveModules ) {
167  $out->addHTML( Linker::generateTOC( $haveModules, $context->getLanguage() ) );
168  }
169  $out->addHTML( $html );
170 
171  $helptitle = $options['helptitle'] ?? null;
172  $html = self::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
173  $out->clearHTML();
174  $out->addHTML( $html );
175 
176  if ( $cacheKey !== null ) {
177  $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
178  }
179  }
180 
189  public static function fixHelpLinks( $html, $helptitle = null, $localModules = [] ) {
190  $formatter = new HtmlFormatter( $html );
191  $doc = $formatter->getDoc();
192  $xpath = new DOMXPath( $doc );
193  $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
194  foreach ( $nodes as $node ) {
195  $href = $node->getAttribute( 'href' );
196  do {
197  $old = $href;
198  $href = rawurldecode( $href );
199  } while ( $old !== $href );
200  if ( preg_match( '!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
201  if ( isset( $localModules[$m[1]] ) ) {
202  $href = $m[2] === '' ? '#' . $m[1] : $m[2];
203  } elseif ( $helptitle !== null ) {
204  $href = Title::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
205  ->getFullURL();
206  } else {
207  $href = wfAppendQuery( wfScript( 'api' ), [
208  'action' => 'help',
209  'modules' => $m[1],
210  ] ) . $m[2];
211  }
212  $node->setAttribute( 'href', $href );
213  $node->removeAttribute( 'title' );
214  }
215  }
216 
217  return $formatter->getText();
218  }
219 
228  private static function wrap( Message $msg, $class, $tag = 'span' ) {
229  return Html::rawElement( $tag, [ 'class' => $class ],
230  $msg->parse()
231  );
232  }
233 
243  private static function getHelpInternal( IContextSource $context, array $modules,
244  array $options, &$haveModules
245  ) {
246  $out = '';
247 
248  $level = empty( $options['headerlevel'] ) ? 2 : $options['headerlevel'];
249  if ( empty( $options['tocnumber'] ) ) {
250  $tocnumber = [ 2 => 0 ];
251  } else {
252  $tocnumber = &$options['tocnumber'];
253  }
254 
255  foreach ( $modules as $module ) {
256  $tocnumber[$level]++;
257  $path = $module->getModulePath();
258  $module->setContext( $context );
259  $help = [
260  'header' => '',
261  'flags' => '',
262  'description' => '',
263  'help-urls' => '',
264  'parameters' => '',
265  'examples' => '',
266  'submodules' => '',
267  ];
268 
269  if ( empty( $options['noheader'] ) || !empty( $options['toc'] ) ) {
270  $anchor = $path;
271  $i = 1;
272  while ( isset( $haveModules[$anchor] ) ) {
273  $anchor = $path . '|' . ++$i;
274  }
275 
276  if ( $module->isMain() ) {
277  $headerContent = $context->msg( 'api-help-main-header' )->parse();
278  $headerAttr = [
279  'class' => 'apihelp-header',
280  ];
281  } else {
282  $name = $module->getModuleName();
283  $headerContent = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
284  "=$name";
285  if ( $module->getModulePrefix() !== '' ) {
286  $headerContent .= ' ' .
287  $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
288  }
289  // Module names are always in English and not localized,
290  // so English language and direction must be set explicitly,
291  // otherwise parentheses will get broken in RTL wikis
292  $headerAttr = [
293  'class' => 'apihelp-header apihelp-module-name',
294  'dir' => 'ltr',
295  'lang' => 'en',
296  ];
297  }
298 
299  $headerAttr['id'] = $anchor;
300 
301  $haveModules[$anchor] = [
302  'toclevel' => count( $tocnumber ),
303  'level' => $level,
304  'anchor' => $anchor,
305  'line' => $headerContent,
306  'number' => implode( '.', $tocnumber ),
307  'index' => false,
308  ];
309  if ( empty( $options['noheader'] ) ) {
310  $help['header'] .= Html::element(
311  'h' . min( 6, $level ),
312  $headerAttr,
313  $headerContent
314  );
315  }
316  } else {
317  $haveModules[$path] = true;
318  }
319 
320  $links = [];
321  $any = false;
322  for ( $m = $module; $m !== null; $m = $m->getParent() ) {
323  $name = $m->getModuleName();
324  if ( $name === 'main_int' ) {
325  $name = 'main';
326  }
327 
328  if ( count( $modules ) === 1 && $m === $modules[0] &&
329  !( !empty( $options['submodules'] ) && $m->getModuleManager() )
330  ) {
331  $link = Html::element( 'b', [ 'dir' => 'ltr', 'lang' => 'en' ], $name );
332  } else {
333  $link = SpecialPage::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
334  $link = Html::element( 'a',
335  [ 'href' => $link, 'class' => 'apihelp-linktrail', 'dir' => 'ltr', 'lang' => 'en' ],
336  $name
337  );
338  $any = true;
339  }
340  array_unshift( $links, $link );
341  }
342  if ( $any ) {
343  $help['header'] .= self::wrap(
344  $context->msg( 'parentheses' )
345  ->rawParams( $context->getLanguage()->pipeList( $links ) ),
346  'apihelp-linktrail', 'div'
347  );
348  }
349 
350  $flags = $module->getHelpFlags();
351  $help['flags'] .= Html::openElement( 'div',
352  [ 'class' => 'apihelp-block apihelp-flags' ] );
353  $msg = $context->msg( 'api-help-flags' );
354  if ( !$msg->isDisabled() ) {
355  $help['flags'] .= self::wrap(
356  $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
357  );
358  }
359  $help['flags'] .= Html::openElement( 'ul' );
360  foreach ( $flags as $flag ) {
361  $help['flags'] .= Html::rawElement( 'li', null,
362  self::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
363  );
364  }
365  $sourceInfo = $module->getModuleSourceInfo();
366  if ( $sourceInfo ) {
367  if ( isset( $sourceInfo['namemsg'] ) ) {
368  $extname = $context->msg( $sourceInfo['namemsg'] )->text();
369  } else {
370  // Probably English, so wrap it.
371  $extname = Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['name'] );
372  }
373  $help['flags'] .= Html::rawElement( 'li', null,
374  self::wrap(
375  $context->msg( 'api-help-source', $extname, $sourceInfo['name'] ),
376  'apihelp-source'
377  )
378  );
379 
380  $link = SpecialPage::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] );
381  if ( isset( $sourceInfo['license-name'] ) ) {
382  $msg = $context->msg( 'api-help-license', $link,
383  Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['license-name'] )
384  );
385  } elseif ( SpecialVersion::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
386  $msg = $context->msg( 'api-help-license-noname', $link );
387  } else {
388  $msg = $context->msg( 'api-help-license-unknown' );
389  }
390  $help['flags'] .= Html::rawElement( 'li', null,
391  self::wrap( $msg, 'apihelp-license' )
392  );
393  } else {
394  $help['flags'] .= Html::rawElement( 'li', null,
395  self::wrap( $context->msg( 'api-help-source-unknown' ), 'apihelp-source' )
396  );
397  $help['flags'] .= Html::rawElement( 'li', null,
398  self::wrap( $context->msg( 'api-help-license-unknown' ), 'apihelp-license' )
399  );
400  }
401  $help['flags'] .= Html::closeElement( 'ul' );
402  $help['flags'] .= Html::closeElement( 'div' );
403 
404  foreach ( $module->getFinalDescription() as $msg ) {
405  $msg->setContext( $context );
406  $help['description'] .= $msg->parseAsBlock();
407  }
408 
409  $urls = $module->getHelpUrls();
410  if ( $urls ) {
411  $help['help-urls'] .= Html::openElement( 'div',
412  [ 'class' => 'apihelp-block apihelp-help-urls' ]
413  );
414  $msg = $context->msg( 'api-help-help-urls' );
415  if ( !$msg->isDisabled() ) {
416  $help['help-urls'] .= self::wrap(
417  $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
418  );
419  }
420  if ( !is_array( $urls ) ) {
421  $urls = [ $urls ];
422  }
423  $help['help-urls'] .= Html::openElement( 'ul' );
424  foreach ( $urls as $url ) {
425  $help['help-urls'] .= Html::rawElement( 'li', null,
426  Html::element( 'a', [ 'href' => $url, 'dir' => 'ltr' ], $url )
427  );
428  }
429  $help['help-urls'] .= Html::closeElement( 'ul' );
430  $help['help-urls'] .= Html::closeElement( 'div' );
431  }
432 
433  $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
434  $dynamicParams = $module->dynamicParameterDocumentation();
435  $groups = [];
436  if ( $params || $dynamicParams !== null ) {
437  $help['parameters'] .= Html::openElement( 'div',
438  [ 'class' => 'apihelp-block apihelp-parameters' ]
439  );
440  $msg = $context->msg( 'api-help-parameters' );
441  if ( !$msg->isDisabled() ) {
442  $help['parameters'] .= self::wrap(
443  $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
444  );
445  }
446  $help['parameters'] .= Html::openElement( 'dl' );
447 
448  $descriptions = $module->getFinalParamDescription();
449 
450  foreach ( $params as $name => $settings ) {
451  if ( !is_array( $settings ) ) {
452  $settings = [ ApiBase::PARAM_DFLT => $settings ];
453  }
454 
455  $help['parameters'] .= Html::rawElement( 'dt', null,
456  Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $module->encodeParamName( $name ) )
457  );
458 
459  // Add description
460  $description = [];
461  if ( isset( $descriptions[$name] ) ) {
462  foreach ( $descriptions[$name] as $msg ) {
463  $msg->setContext( $context );
464  $description[] = $msg->parseAsBlock();
465  }
466  }
467 
468  // Add usage info
469  $info = [];
470 
471  // Required?
472  if ( !empty( $settings[ApiBase::PARAM_REQUIRED] ) ) {
473  $info[] = $context->msg( 'api-help-param-required' )->parse();
474  }
475 
476  // Custom info?
477  if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
478  foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
479  $tag = array_shift( $i );
480  $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
481  ->numParams( count( $i ) )
482  ->params( $context->getLanguage()->commaList( $i ) )
483  ->params( $module->getModulePrefix() )
484  ->parse();
485  }
486  }
487 
488  // Templated?
489  if ( !empty( $settings[ApiBase::PARAM_TEMPLATE_VARS] ) ) {
490  $vars = [];
491  $msg = 'api-help-param-templated-var-first';
492  foreach ( $settings[ApiBase::PARAM_TEMPLATE_VARS] as $k => $v ) {
493  $vars[] = $context->msg( $msg, $k, $module->encodeParamName( $v ) );
494  $msg = 'api-help-param-templated-var';
495  }
496  $info[] = $context->msg( 'api-help-param-templated' )
497  ->numParams( count( $vars ) )
498  ->params( Message::listParam( $vars ) )
499  ->parse();
500  }
501 
502  // Type documentation
503  if ( !isset( $settings[ApiBase::PARAM_TYPE] ) ) {
504  $dflt = $settings[ApiBase::PARAM_DFLT] ?? null;
505  if ( is_bool( $dflt ) ) {
506  $settings[ApiBase::PARAM_TYPE] = 'boolean';
507  } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
508  $settings[ApiBase::PARAM_TYPE] = 'string';
509  } elseif ( is_int( $dflt ) ) {
510  $settings[ApiBase::PARAM_TYPE] = 'integer';
511  }
512  }
513  if ( isset( $settings[ApiBase::PARAM_TYPE] ) ) {
514  $type = $settings[ApiBase::PARAM_TYPE];
515  $multi = !empty( $settings[ApiBase::PARAM_ISMULTI] );
516  $hintPipeSeparated = true;
517  $count = !empty( $settings[ApiBase::PARAM_ISMULTI_LIMIT2] )
518  ? $settings[ApiBase::PARAM_ISMULTI_LIMIT2] + 1
519  : ApiBase::LIMIT_SML2 + 1;
520 
521  if ( is_array( $type ) ) {
522  $count = count( $type );
523  $deprecatedValues = $settings[ApiBase::PARAM_DEPRECATED_VALUES] ?? [];
524  $links = $settings[ApiBase::PARAM_VALUE_LINKS] ?? [];
525  $values = array_map( function ( $v ) use ( $links, $deprecatedValues ) {
526  $attr = [];
527  if ( $v !== '' ) {
528  // We can't know whether this contains LTR or RTL text.
529  $attr['dir'] = 'auto';
530  }
531  if ( isset( $deprecatedValues[$v] ) ) {
532  $attr['class'] = 'apihelp-deprecated-value';
533  }
534  $ret = $attr ? Html::element( 'span', $attr, $v ) : $v;
535  if ( isset( $links[$v] ) ) {
536  $ret = "[[{$links[$v]}|$ret]]";
537  }
538  return $ret;
539  }, $type );
540  $i = array_search( '', $type, true );
541  if ( $i === false ) {
542  $values = $context->getLanguage()->commaList( $values );
543  } else {
544  unset( $values[$i] );
545  $values = $context->msg( 'api-help-param-list-can-be-empty' )
546  ->numParams( count( $values ) )
547  ->params( $context->getLanguage()->commaList( $values ) )
548  ->parse();
549  }
550  $info[] = $context->msg( 'api-help-param-list' )
551  ->params( $multi ? 2 : 1 )
552  ->params( $values )
553  ->parse();
554  $hintPipeSeparated = false;
555  } else {
556  switch ( $type ) {
557  case 'submodule':
558  $groups[] = $name;
559 
560  if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) {
561  $map = $settings[ApiBase::PARAM_SUBMODULE_MAP];
562  $defaultAttrs = [];
563  } else {
564  $prefix = $module->isMain() ? '' : ( $module->getModulePath() . '+' );
565  $map = [];
566  foreach ( $module->getModuleManager()->getNames( $name ) as $submoduleName ) {
567  $map[$submoduleName] = $prefix . $submoduleName;
568  }
569  $defaultAttrs = [ 'dir' => 'ltr', 'lang' => 'en' ];
570  }
571 
572  $submodules = [];
573  $submoduleFlags = []; // for sorting: higher flags are sorted later
574  $submoduleNames = []; // for sorting: lexicographical, ascending
575  foreach ( $map as $v => $m ) {
576  $attrs = $defaultAttrs;
577  $flags = 0;
578  try {
579  $submod = $module->getModuleFromPath( $m );
580  if ( $submod && $submod->isDeprecated() ) {
581  $attrs['class'][] = 'apihelp-deprecated-value';
582  $flags |= 1;
583  }
584  if ( $submod && $submod->isInternal() ) {
585  $attrs['class'][] = 'apihelp-internal-value';
586  $flags |= 2;
587  }
588  } catch ( ApiUsageException $ex ) {
589  // Ignore
590  }
591  $v = Html::element( 'span', $attrs, $v );
592  $submodules[] = "[[Special:ApiHelp/{$m}|{$v}]]";
593  $submoduleFlags[] = $flags;
594  $submoduleNames[] = $v;
595  }
596  // sort $submodules by $submoduleFlags and $submoduleNames
597  array_multisort( $submoduleFlags, $submoduleNames, $submodules );
598  $count = count( $submodules );
599  $info[] = $context->msg( 'api-help-param-list' )
600  ->params( $multi ? 2 : 1 )
601  ->params( $context->getLanguage()->commaList( $submodules ) )
602  ->parse();
603  $hintPipeSeparated = false;
604  // No type message necessary, we have a list of values.
605  $type = null;
606  break;
607 
608  case 'namespace':
609  $namespaces = MediaWikiServices::getInstance()->
610  getNamespaceInfo()->getValidNamespaces();
611  if ( isset( $settings[ApiBase::PARAM_EXTRA_NAMESPACES] ) &&
612  is_array( $settings[ApiBase::PARAM_EXTRA_NAMESPACES] )
613  ) {
614  $namespaces = array_merge( $namespaces, $settings[ApiBase::PARAM_EXTRA_NAMESPACES] );
615  }
616  sort( $namespaces );
617  $count = count( $namespaces );
618  $info[] = $context->msg( 'api-help-param-list' )
619  ->params( $multi ? 2 : 1 )
620  ->params( $context->getLanguage()->commaList( $namespaces ) )
621  ->parse();
622  $hintPipeSeparated = false;
623  // No type message necessary, we have a list of values.
624  $type = null;
625  break;
626 
627  case 'tags':
629  $count = count( $tags );
630  $info[] = $context->msg( 'api-help-param-list' )
631  ->params( $multi ? 2 : 1 )
632  ->params( $context->getLanguage()->commaList( $tags ) )
633  ->parse();
634  $hintPipeSeparated = false;
635  $type = null;
636  break;
637 
638  case 'limit':
639  if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
640  $info[] = $context->msg( 'api-help-param-limit2' )
641  ->numParams( $settings[ApiBase::PARAM_MAX] )
642  ->numParams( $settings[ApiBase::PARAM_MAX2] )
643  ->parse();
644  } else {
645  $info[] = $context->msg( 'api-help-param-limit' )
646  ->numParams( $settings[ApiBase::PARAM_MAX] )
647  ->parse();
648  }
649  break;
650 
651  case 'integer':
652  // Possible messages:
653  // api-help-param-integer-min,
654  // api-help-param-integer-max,
655  // api-help-param-integer-minmax
656  $suffix = '';
657  $min = $max = 0;
658  if ( isset( $settings[ApiBase::PARAM_MIN] ) ) {
659  $suffix .= 'min';
660  $min = $settings[ApiBase::PARAM_MIN];
661  }
662  if ( isset( $settings[ApiBase::PARAM_MAX] ) ) {
663  $suffix .= 'max';
664  $max = $settings[ApiBase::PARAM_MAX];
665  }
666  if ( $suffix !== '' ) {
667  $info[] =
668  $context->msg( "api-help-param-integer-$suffix" )
669  ->params( $multi ? 2 : 1 )
670  ->numParams( $min, $max )
671  ->parse();
672  }
673  break;
674 
675  case 'upload':
676  $info[] = $context->msg( 'api-help-param-upload' )
677  ->parse();
678  // No type message necessary, api-help-param-upload should handle it.
679  $type = null;
680  break;
681 
682  case 'string':
683  case 'text':
684  // Displaying a type message here would be useless.
685  $type = null;
686  break;
687  }
688  }
689 
690  // Add type. Messages for grep: api-help-param-type-limit
691  // api-help-param-type-integer api-help-param-type-boolean
692  // api-help-param-type-timestamp api-help-param-type-user
693  // api-help-param-type-password
694  if ( is_string( $type ) ) {
695  $msg = $context->msg( "api-help-param-type-$type" );
696  if ( !$msg->isDisabled() ) {
697  $info[] = $msg->params( $multi ? 2 : 1 )->parse();
698  }
699  }
700 
701  if ( $multi ) {
702  $extra = [];
703  $lowcount = !empty( $settings[ApiBase::PARAM_ISMULTI_LIMIT1] )
704  ? $settings[ApiBase::PARAM_ISMULTI_LIMIT1]
706  $highcount = !empty( $settings[ApiBase::PARAM_ISMULTI_LIMIT2] )
707  ? $settings[ApiBase::PARAM_ISMULTI_LIMIT2]
709 
710  if ( $hintPipeSeparated ) {
711  $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
712  }
713  if ( $count > $lowcount ) {
714  if ( $lowcount === $highcount ) {
715  $msg = $context->msg( 'api-help-param-multi-max-simple' )
716  ->numParams( $lowcount );
717  } else {
718  $msg = $context->msg( 'api-help-param-multi-max' )
719  ->numParams( $lowcount, $highcount );
720  }
721  $extra[] = $msg->parse();
722  }
723  if ( $extra ) {
724  $info[] = implode( ' ', $extra );
725  }
726 
727  $allowAll = $settings[ApiBase::PARAM_ALL] ?? false;
728  if ( $allowAll || $settings[ApiBase::PARAM_TYPE] === 'namespace' ) {
729  if ( $settings[ApiBase::PARAM_TYPE] === 'namespace' ) {
730  $allSpecifier = ApiBase::ALL_DEFAULT_STRING;
731  } else {
732  $allSpecifier = ( is_string( $allowAll ) ? $allowAll : ApiBase::ALL_DEFAULT_STRING );
733  }
734  $info[] = $context->msg( 'api-help-param-multi-all' )
735  ->params( $allSpecifier )
736  ->parse();
737  }
738  }
739  }
740 
741  if ( isset( $settings[self::PARAM_MAX_BYTES] ) ) {
742  $info[] = $context->msg( 'api-help-param-maxbytes' )
743  ->numParams( $settings[self::PARAM_MAX_BYTES] );
744  }
745  if ( isset( $settings[self::PARAM_MAX_CHARS] ) ) {
746  $info[] = $context->msg( 'api-help-param-maxchars' )
747  ->numParams( $settings[self::PARAM_MAX_CHARS] );
748  }
749 
750  // Add default
751  $default = $settings[ApiBase::PARAM_DFLT] ?? null;
752  if ( $default === '' ) {
753  $info[] = $context->msg( 'api-help-param-default-empty' )
754  ->parse();
755  } elseif ( $default !== null && $default !== false ) {
756  // We can't know whether this contains LTR or RTL text.
757  $info[] = $context->msg( 'api-help-param-default' )
758  ->params( Html::element( 'span', [ 'dir' => 'auto' ], $default ) )
759  ->parse();
760  }
761 
762  if ( !array_filter( $description ) ) {
763  $description = [ self::wrap(
764  $context->msg( 'api-help-param-no-description' ),
765  'apihelp-empty'
766  ) ];
767  }
768 
769  // Add "deprecated" flag
770  if ( !empty( $settings[ApiBase::PARAM_DEPRECATED] ) ) {
771  $help['parameters'] .= Html::openElement( 'dd',
772  [ 'class' => 'info' ] );
773  $help['parameters'] .= self::wrap(
774  $context->msg( 'api-help-param-deprecated' ),
775  'apihelp-deprecated', 'strong'
776  );
777  $help['parameters'] .= Html::closeElement( 'dd' );
778  }
779 
780  if ( $description ) {
781  $description = implode( '', $description );
782  $description = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $description );
783  $help['parameters'] .= Html::rawElement( 'dd',
784  [ 'class' => 'description' ], $description );
785  }
786 
787  foreach ( $info as $i ) {
788  $help['parameters'] .= Html::rawElement( 'dd', [ 'class' => 'info' ], $i );
789  }
790  }
791 
792  if ( $dynamicParams !== null ) {
793  $dynamicParams = ApiBase::makeMessage( $dynamicParams, $context, [
794  $module->getModulePrefix(),
795  $module->getModuleName(),
796  $module->getModulePath()
797  ] );
798  $help['parameters'] .= Html::element( 'dt', null, '*' );
799  $help['parameters'] .= Html::rawElement( 'dd',
800  [ 'class' => 'description' ], $dynamicParams->parse() );
801  }
802 
803  $help['parameters'] .= Html::closeElement( 'dl' );
804  $help['parameters'] .= Html::closeElement( 'div' );
805  }
806 
807  $examples = $module->getExamplesMessages();
808  if ( $examples ) {
809  $help['examples'] .= Html::openElement( 'div',
810  [ 'class' => 'apihelp-block apihelp-examples' ] );
811  $msg = $context->msg( 'api-help-examples' );
812  if ( !$msg->isDisabled() ) {
813  $help['examples'] .= self::wrap(
814  $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
815  );
816  }
817 
818  $help['examples'] .= Html::openElement( 'dl' );
819  foreach ( $examples as $qs => $msg ) {
820  $msg = ApiBase::makeMessage( $msg, $context, [
821  $module->getModulePrefix(),
822  $module->getModuleName(),
823  $module->getModulePath()
824  ] );
825 
826  $link = wfAppendQuery( wfScript( 'api' ), $qs );
827  $sandbox = SpecialPage::getTitleFor( 'ApiSandbox' )->getLocalURL() . '#' . $qs;
828  $help['examples'] .= Html::rawElement( 'dt', null, $msg->parse() );
829  $help['examples'] .= Html::rawElement( 'dd', null,
830  Html::element( 'a', [ 'href' => $link, 'dir' => 'ltr' ], "api.php?$qs" ) . ' ' .
831  Html::rawElement( 'a', [ 'href' => $sandbox ],
832  $context->msg( 'api-help-open-in-apisandbox' )->parse() )
833  );
834  }
835  $help['examples'] .= Html::closeElement( 'dl' );
836  $help['examples'] .= Html::closeElement( 'div' );
837  }
838 
839  $subtocnumber = $tocnumber;
840  $subtocnumber[$level + 1] = 0;
841  $suboptions = [
842  'submodules' => $options['recursivesubmodules'],
843  'headerlevel' => $level + 1,
844  'tocnumber' => &$subtocnumber,
845  'noheader' => false,
846  ] + $options;
847 
848  if ( $options['submodules'] && $module->getModuleManager() ) {
849  $manager = $module->getModuleManager();
850  $submodules = [];
851  foreach ( $groups as $group ) {
852  $names = $manager->getNames( $group );
853  sort( $names );
854  foreach ( $names as $name ) {
855  $submodules[] = $manager->getModule( $name );
856  }
857  }
858  $help['submodules'] .= self::getHelpInternal(
859  $context,
860  $submodules,
861  $suboptions,
862  $haveModules
863  );
864  }
865 
866  $module->modifyHelp( $help, $suboptions, $haveModules );
867 
868  Hooks::run( 'APIHelpModifyOutput', [ $module, &$help, $suboptions, &$haveModules ] );
869 
870  $out .= implode( "\n", $help );
871  }
872 
873  return $out;
874  }
875 
876  public function shouldCheckMaxlag() {
877  return false;
878  }
879 
880  public function isReadMode() {
881  return false;
882  }
883 
884  public function getCustomPrinter() {
885  $params = $this->extractRequestParams();
886  if ( $params['wrap'] ) {
887  return null;
888  }
889 
890  $main = $this->getMain();
891  $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
892  return new ApiFormatRaw( $main, $errorPrinter );
893  }
894 
895  public function getAllowedParams() {
896  return [
897  'modules' => [
898  ApiBase::PARAM_DFLT => 'main',
899  ApiBase::PARAM_ISMULTI => true,
900  ],
901  'submodules' => false,
902  'recursivesubmodules' => false,
903  'wrap' => false,
904  'toc' => false,
905  ];
906  }
907 
908  protected function getExamplesMessages() {
909  return [
910  'action=help'
911  => 'apihelp-help-example-main',
912  'action=help&modules=query&submodules=1'
913  => 'apihelp-help-example-submodules',
914  'action=help&recursivesubmodules=1'
915  => 'apihelp-help-example-recursive',
916  'action=help&modules=help'
917  => 'apihelp-help-example-help',
918  'action=help&modules=query+info|query+categorymembers'
919  => 'apihelp-help-example-query',
920  ];
921  }
922 
923  public function getHelpUrls() {
924  return [
925  'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
926  'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
927  'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',
928  ];
929  }
930 }
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:155
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below...
Definition: ApiBase.php:94
static element( $element, $attribs=[], $contents='')
Identical to rawElement(), but HTML-escapes $contents (like Xml::element()).
Definition: Html.php:231
getResult()
Get the result object.
Definition: ApiBase.php:640
static generateTOC( $tree, Language $lang=null)
Generate a table of contents from a section tree.
Definition: Linker.php:1711
The Message class provides methods which fulfil two basic services:
Definition: Message.php:162
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition: ApiBase.php:55
getMain()
Get the main module.
Definition: ApiBase.php:536
const GET_VALUES_FOR_HELP
getAllowedParams() flag: When set, the result could take longer to generate, but should be more thoro...
Definition: ApiBase.php:272
Exception used to abort API execution with an error.
static openElement( $element, $attribs=[])
Identical to rawElement(), but has no third parameter and omits the end tag (and the self-closing &#39;/&#39;...
Definition: Html.php:251
static rawElement( $element, $attribs=[], $contents='')
Returns an HTML element in a string.
Definition: Html.php:209
const PARAM_MAX
(integer) Max value allowed for the parameter, for PARAM_TYPE &#39;integer&#39; and &#39;limit&#39;.
Definition: ApiBase.php:97
An IContextSource implementation which will inherit context from another source but allow individual ...
const PARAM_REQUIRED
(boolean) Is the parameter required?
Definition: ApiBase.php:118
Formatter that spits out anything you like with any desired MIME type.
const PARAM_HELP_MSG_INFO
(array) Specify additional information tags for the parameter.
Definition: ApiBase.php:148
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:761
static encode( $value, $pretty=false, $escaping=0)
Returns the JSON representation of a value.
Definition: FormatJson.php:115
static listExplicitlyDefinedTags()
Lists tags explicitly defined in the change_tag_def table of the database.
const PARAM_ALL
(boolean|string) When PARAM_TYPE has a defined set of values and PARAM_ISMULTI is true...
Definition: ApiBase.php:187
getHelpUrls()
Definition: ApiHelp.php:923
IContextSource $context
static fixHelpLinks( $html, $helptitle=null, $localModules=[])
Replace Special:ApiHelp links with links to api.php.
Definition: ApiHelp.php:189
const PARAM_ISMULTI_LIMIT1
(integer) Maximum number of values, for normal users.
Definition: ApiBase.php:215
static makeMessage( $msg, IContextSource $context, array $params=null)
Create a Message from a string or array.
Definition: ApiBase.php:1791
const UTF8_OK
Skip escaping most characters above U+007F for readability and compactness.
Definition: FormatJson.php:34
wfScript( $script='index')
Get the path to a specified script file, respecting file extensions; this is a wrapper around $wgScri...
wfAppendQuery( $url, $query)
Append a query string to an existing URL, which may or may not already have query string parameters a...
getConfig()
Get the site configuration.
$modules
const PARAM_ISMULTI_LIMIT2
(integer) Maximum number of values, for users with the apihighimits right.
Definition: ApiBase.php:222
getExamplesMessages()
Definition: ApiHelp.php:908
msg( $key,... $params)
This is the method for getting translated interface messages.
static getVersion( $flags='', $lang=null)
Return a string of the MediaWiki version with Git revision if available.
getModulePath()
Get the path to this module.
Definition: ApiBase.php:584
const LIMIT_SML2
Slow query, apihighlimits limit.
Definition: ApiBase.php:265
isReadMode()
Definition: ApiHelp.php:880
const PARAM_SUBMODULE_MAP
(string[]) When PARAM_TYPE is &#39;submodule&#39;, map parameter values to submodule paths.
Definition: ApiBase.php:172
getContext()
Get the base IContextSource object.
$cache
Definition: mcc.php:33
This is the main API class, used for both external and internal processing.
Definition: ApiMain.php:42
static closeElement( $element)
Returns "</$element>".
Definition: Html.php:315
const NO_SIZE_CHECK
For addValue() and similar functions, do not check size while adding a value Don&#39;t use this unless yo...
Definition: ApiResult.php:58
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:520
static getHelp(IContextSource $context, $modules, array $options)
Generate help for the specified modules.
Definition: ApiHelp.php:112
static getExtLicenseFileName( $extDir)
Obtains the full path of an extensions copying or license file if one exists.
$help
Definition: mcc.php:32
const PARAM_MAX2
(integer) Max value allowed for the parameter for users with the apihighlimits right, for PARAM_TYPE &#39;limit&#39;.
Definition: ApiBase.php:103
getModuleFromPath( $path)
Get a module from its module path.
Definition: ApiBase.php:602
static getTitleFor( $name, $subpage=false, $fragment='')
Get a localised Title object for a specified special page name If you don&#39;t need a full Title object...
Definition: SpecialPage.php:83
parse()
Fully parse the text from wikitext to HTML.
Definition: Message.php:930
getAllowedParams()
Definition: ApiHelp.php:895
static setSubelementsList(array &$arr, $names)
Causes the elements with the specified names to be output as subelements rather than attributes...
Definition: ApiResult.php:565
const LIMIT_SML1
Slow query, standard limit.
Definition: ApiBase.php:263
const PARAM_TEMPLATE_VARS
(array) Indicate that this is a templated parameter, and specify replacements.
Definition: ApiBase.php:252
shouldCheckMaxlag()
Definition: ApiHelp.php:876
getCustomPrinter()
Definition: ApiHelp.php:884
const PARAM_DEPRECATED_VALUES
(array) When PARAM_TYPE is an array, this indicates which of the values are deprecated.
Definition: ApiBase.php:209
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Definition: ApiBase.php:58
execute()
Definition: ApiHelp.php:33
const ALL_DEFAULT_STRING
Definition: ApiBase.php:256
This abstract class implements many basic API functions, and is the base of all API classes...
Definition: ApiBase.php:42
const PARAM_EXTRA_NAMESPACES
(int[]) When PARAM_TYPE is &#39;namespace&#39;, include these as additional possible values.
Definition: ApiBase.php:193
const PARAM_DEPRECATED
(boolean) Is the parameter deprecated (will show a warning)?
Definition: ApiBase.php:112
const PARAM_MIN
(integer) Lowest value allowed for the parameter, for PARAM_TYPE &#39;integer&#39; and &#39;limit&#39;.
Definition: ApiBase.php:106
Class to output help for an API module.
Definition: ApiHelp.php:32
static wrap(Message $msg, $class, $tag='span')
Wrap a message in HTML with a class.
Definition: ApiHelp.php:228
static getHelpInternal(IContextSource $context, array $modules, array $options, &$haveModules)
Recursively-called function to actually construct the help.
Definition: ApiHelp.php:243
return true
Definition: router.php:92
static listParam(array $list, $type='text')
Definition: Message.php:1115
static run( $event, array $args=[], $deprecatedVersion=null)
Call hook functions defined in Hooks::register and $wgHooks.
Definition: Hooks.php:200
static newFromText( $text, $defaultNamespace=NS_MAIN)
Create a new Title from text, such as what one would find in a link.
Definition: Title.php:319