includes/api/ApiHelp.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on Aug 29, 2014
   6  *
   7  * Copyright © 2014 Brad Jorsch <bjorsch@wikimedia.org>
   8  *
   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.
  13  *
  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.
  18  *
  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
  23  *
  24  * @file
  25  */
  26
  27 /**
  28  * Class to output help for an API module
  29  *
  30  * @since 1.25 completely rewritten
  31  * @ingroup API
  32  */
  33 class ApiHelp extends ApiBase {
  34         public function execute() {
  35                 $params = $this->extractRequestParams();
  36                 $modules = array();
  37
  38                 foreach ( $params['modules'] as $path ) {
  39                         $modules[] = $this->getModuleFromPath( $path );
  40                 }
  41
  42                 // Get the help
  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 );
  50
  51                 self::getHelp( $context, $modules, $params );
  52
  53                 // Grab the output from the skin
  54                 ob_start();
  55                 $context->getOutput()->output();
  56                 $html = ob_get_clean();
  57
  58                 $result = $this->getResult();
  59                 if ( $params['wrap'] ) {
  60                         $data = array(
  61                                 'mime' => 'text/html',
  62                                 'help' => $html,
  63                         );
  64                         ApiResult::setSubelementsList( $data, 'help' );
  65                         $result->addValue( null, $this->getModuleName(), $data );
  66                 } else {
  67                         $result->reset();
  68                         $result->addValue( null, 'text', $html, ApiResult::NO_SIZE_CHECK );
  69                         $result->addValue( null, 'mime', 'text/html', ApiResult::NO_SIZE_CHECK );
  70                 }
  71         }
  72
  73         /**
  74          * Generate help for the specified modules
  75          *
  76          * Help is placed into the OutputPage object returned by
  77          * $context->getOutput().
  78          *
  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
  87          *
  88          * @param IContextSource $context
  89          * @param ApiBase[]|ApiBase $modules
  90          * @param array $options Formatting options (described above)
  91          * @return string
  92          */
  93         public static function getHelp( IContextSource $context, $modules, array $options ) {
  94                 global $wgContLang;
  95
  96                 if ( !is_array( $modules ) ) {
  97                         $modules = array( $modules );
  98                 }
  99
 100                 $out = $context->getOutput();
 101                 $out->addModuleStyles( 'mediawiki.hlist' );
 102                 $out->addModuleStyles( 'mediawiki.apihelp' );
 103                 if ( !empty( $options['toc'] ) ) {
 104                         $out->addModules( 'mediawiki.toc' );
 105                 }
 106                 $out->setPageTitle( $context->msg( 'api-help-title' ) );
 107
 108                 $cache = ObjectCache::getMainWANInstance();
 109                 $cacheKey = null;
 110                 if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain &&
 111                         $options['recursivesubmodules'] && $context->getLanguage() === $wgContLang
 112                 ) {
 113                         $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
 114                         if ( $cacheHelpTimeout > 0 ) {
 115                                 // Get help text from cache if present
 116                                 $cacheKey = wfMemcKey( 'apihelp', $modules[0]->getModulePath(),
 117                                         (int)!empty( $options['toc'] ),
 118                                         str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) ) );
 119                                 $cached = $cache->get( $cacheKey );
 120                                 if ( $cached ) {
 121                                         $out->addHTML( $cached );
 122                                         return;
 123                                 }
 124                         }
 125                 }
 126                 if ( $out->getHTML() !== '' ) {
 127                         // Don't save to cache, there's someone else's content in the page
 128                         // already
 129                         $cacheKey = null;
 130                 }
 131
 132                 $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
 133                 $options['submodules'] = $options['recursivesubmodules'] || !empty( $options['submodules'] );
 134
 135                 // Prepend lead
 136                 if ( empty( $options['nolead'] ) ) {
 137                         $msg = $context->msg( 'api-help-lead' );
 138                         if ( !$msg->isDisabled() ) {
 139                                 $out->addHTML( $msg->parseAsBlock() );
 140                         }
 141                 }
 142
 143                 $haveModules = array();
 144                 $html = self::getHelpInternal( $context, $modules, $options, $haveModules );
 145                 if ( !empty( $options['toc'] ) && $haveModules ) {
 146                         $out->addHTML( Linker::generateTOC( $haveModules, $context->getLanguage() ) );
 147                 }
 148                 $out->addHTML( $html );
 149
 150                 $helptitle = isset( $options['helptitle'] ) ? $options['helptitle'] : null;
 151                 $html = self::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
 152                 $out->clearHTML();
 153                 $out->addHTML( $html );
 154
 155                 if ( $cacheKey !== null ) {
 156                         $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
 157                 }
 158         }
 159
 160         /**
 161          * Replace Special:ApiHelp links with links to api.php
 162          *
 163          * @param string $html
 164          * @param string|null $helptitle Title to link to rather than api.php, must contain '$1'
 165          * @param array $localModules Keys are modules to link within the current page, values are ignored
 166          * @return string
 167          */
 168         public static function fixHelpLinks( $html, $helptitle = null, $localModules = array() ) {
 169                 $formatter = new HtmlFormatter( $html );
 170                 $doc = $formatter->getDoc();
 171                 $xpath = new DOMXPath( $doc );
 172                 $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
 173                 foreach ( $nodes as $node ) {
 174                         $href = $node->getAttribute( 'href' );
 175                         do {
 176                                 $old = $href;
 177                                 $href = rawurldecode( $href );
 178                         } while ( $old !== $href );
 179                         if ( preg_match( '!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
 180                                 if ( isset( $localModules[$m[1]] ) ) {
 181                                         $href = $m[2] === '' ? '#' . $m[1] : $m[2];
 182                                 } elseif ( $helptitle !== null ) {
 183                                         $href = Title::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
 184                                                 ->getFullURL();
 185                                 } else {
 186                                         $href = wfAppendQuery( wfScript( 'api' ), array(
 187                                                 'action' => 'help',
 188                                                 'modules' => $m[1],
 189                                         ) ) . $m[2];
 190                                 }
 191                                 $node->setAttribute( 'href', $href );
 192                                 $node->removeAttribute( 'title' );
 193                         }
 194                 }
 195
 196                 return $formatter->getText();
 197         }
 198
 199         /**
 200          * Wrap a message in HTML with a class.
 201          *
 202          * @param Message $msg
 203          * @param string $class
 204          * @param string $tag
 205          * @return string
 206          */
 207         private static function wrap( Message $msg, $class, $tag = 'span' ) {
 208                 return Html::rawElement( $tag, array( 'class' => $class ),
 209                         $msg->parse()
 210                 );
 211         }
 212
 213         /**
 214          * Recursively-called function to actually construct the help
 215          *
 216          * @param IContextSource $context
 217          * @param ApiBase[] $modules
 218          * @param array $options
 219          * @param array &$haveModules
 220          * @return string
 221          */
 222         private static function getHelpInternal( IContextSource $context, array $modules,
 223                 array $options, &$haveModules
 224         ) {
 225                 $out = '';
 226
 227                 $level = empty( $options['headerlevel'] ) ? 2 : $options['headerlevel'];
 228                 if ( empty( $options['tocnumber'] ) ) {
 229                         $tocnumber = array( 2 => 0 );
 230                 } else {
 231                         $tocnumber = &$options['tocnumber'];
 232                 }
 233
 234                 foreach ( $modules as $module ) {
 235                         $tocnumber[$level]++;
 236                         $path = $module->getModulePath();
 237                         $module->setContext( $context );
 238                         $help = array(
 239                                 'header' => '',
 240                                 'flags' => '',
 241                                 'description' => '',
 242                                 'help-urls' => '',
 243                                 'parameters' => '',
 244                                 'examples' => '',
 245                                 'submodules' => '',
 246                         );
 247
 248                         if ( empty( $options['noheader'] ) || !empty( $options['toc'] ) ) {
 249                                 $anchor = $path;
 250                                 $i = 1;
 251                                 while ( isset( $haveModules[$anchor] ) ) {
 252                                         $anchor = $path . '|' . ++$i;
 253                                 }
 254
 255                                 if ( $module->isMain() ) {
 256                                         $header = $context->msg( 'api-help-main-header' )->parse();
 257                                 } else {
 258                                         $name = $module->getModuleName();
 259                                         $header = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
 260                                                 "=$name";
 261                                         if ( $module->getModulePrefix() !== '' ) {
 262                                                 $header .= ' ' .
 263                                                         $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
 264                                         }
 265                                 }
 266                                 $haveModules[$anchor] = array(
 267                                         'toclevel' => count( $tocnumber ),
 268                                         'level' => $level,
 269                                         'anchor' => $anchor,
 270                                         'line' => $header,
 271                                         'number' => join( '.', $tocnumber ),
 272                                         'index' => false,
 273                                 );
 274                                 if ( empty( $options['noheader'] ) ) {
 275                                         $help['header'] .= Html::element( 'h' . min( 6, $level ),
 276                                                 array( 'id' => $anchor, 'class' => 'apihelp-header' ),
 277                                                 $header
 278                                         );
 279                                 }
 280                         } else {
 281                                 $haveModules[$path] = true;
 282                         }
 283
 284                         $links = array();
 285                         $any = false;
 286                         for ( $m = $module; $m !== null; $m = $m->getParent() ) {
 287                                 $name = $m->getModuleName();
 288                                 if ( $name === 'main_int' ) {
 289                                         $name = 'main';
 290                                 }
 291
 292                                 if ( count( $modules ) === 1 && $m === $modules[0] &&
 293                                         !( !empty( $options['submodules'] ) && $m->getModuleManager() )
 294                                 ) {
 295                                         $link = Html::element( 'b', null, $name );
 296                                 } else {
 297                                         $link = SpecialPage::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
 298                                         $link = Html::element( 'a',
 299                                                 array( 'href' => $link, 'class' => 'apihelp-linktrail' ),
 300                                                 $name
 301                                         );
 302                                         $any = true;
 303                                 }
 304                                 array_unshift( $links, $link );
 305                         }
 306                         if ( $any ) {
 307                                 $help['header'] .= self::wrap(
 308                                         $context->msg( 'parentheses' )
 309                                                 ->rawParams( $context->getLanguage()->pipeList( $links ) ),
 310                                         'apihelp-linktrail', 'div'
 311                                 );
 312                         }
 313
 314                         $flags = $module->getHelpFlags();
 315                         $help['flags'] .= Html::openElement( 'div',
 316                                 array( 'class' => 'apihelp-block apihelp-flags' ) );
 317                         $msg = $context->msg( 'api-help-flags' );
 318                         if ( !$msg->isDisabled() ) {
 319                                 $help['flags'] .= self::wrap(
 320                                         $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
 321                                 );
 322                         }
 323                         $help['flags'] .= Html::openElement( 'ul' );
 324                         foreach ( $flags as $flag ) {
 325                                 $help['flags'] .= Html::rawElement( 'li', null,
 326                                         self::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
 327                                 );
 328                         }
 329                         $sourceInfo = $module->getModuleSourceInfo();
 330                         if ( $sourceInfo ) {
 331                                 if ( isset( $sourceInfo['namemsg'] ) ) {
 332                                         $extname = $context->msg( $sourceInfo['namemsg'] )->text();
 333                                 } else {
 334                                         $extname = $sourceInfo['name'];
 335                                 }
 336                                 $help['flags'] .= Html::rawElement( 'li', null,
 337                                         self::wrap(
 338                                                 $context->msg( 'api-help-source', $extname, $sourceInfo['name'] ),
 339                                                 'apihelp-source'
 340                                         )
 341                                 );
 342
 343                                 $link = SpecialPage::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] );
 344                                 if ( isset( $sourceInfo['license-name'] ) ) {
 345                                         $msg = $context->msg( 'api-help-license', $link, $sourceInfo['license-name'] );
 346                                 } elseif ( SpecialVersion::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
 347                                         $msg = $context->msg( 'api-help-license-noname', $link );
 348                                 } else {
 349                                         $msg = $context->msg( 'api-help-license-unknown' );
 350                                 }
 351                                 $help['flags'] .= Html::rawElement( 'li', null,
 352                                         self::wrap( $msg, 'apihelp-license' )
 353                                 );
 354                         } else {
 355                                 $help['flags'] .= Html::rawElement( 'li', null,
 356                                         self::wrap( $context->msg( 'api-help-source-unknown' ), 'apihelp-source' )
 357                                 );
 358                                 $help['flags'] .= Html::rawElement( 'li', null,
 359                                         self::wrap( $context->msg( 'api-help-license-unknown' ), 'apihelp-license' )
 360                                 );
 361                         }
 362                         $help['flags'] .= Html::closeElement( 'ul' );
 363                         $help['flags'] .= Html::closeElement( 'div' );
 364
 365                         foreach ( $module->getFinalDescription() as $msg ) {
 366                                 $msg->setContext( $context );
 367                                 $help['description'] .= $msg->parseAsBlock();
 368                         }
 369
 370                         $urls = $module->getHelpUrls();
 371                         if ( $urls ) {
 372                                 $help['help-urls'] .= Html::openElement( 'div',
 373                                         array( 'class' => 'apihelp-block apihelp-help-urls' )
 374                                 );
 375                                 $msg = $context->msg( 'api-help-help-urls' );
 376                                 if ( !$msg->isDisabled() ) {
 377                                         $help['help-urls'] .= self::wrap(
 378                                                 $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
 379                                         );
 380                                 }
 381                                 if ( !is_array( $urls ) ) {
 382                                         $urls = array( $urls );
 383                                 }
 384                                 $help['help-urls'] .= Html::openElement( 'ul' );
 385                                 foreach ( $urls as $url ) {
 386                                         $help['help-urls'] .= Html::rawElement( 'li', null,
 387                                                 Html::element( 'a', array( 'href' => $url ), $url )
 388                                         );
 389                                 }
 390                                 $help['help-urls'] .= Html::closeElement( 'ul' );
 391                                 $help['help-urls'] .= Html::closeElement( 'div' );
 392                         }
 393
 394                         $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
 395                         $dynamicParams = $module->dynamicParameterDocumentation();
 396                         $groups = array();
 397                         if ( $params || $dynamicParams !== null ) {
 398                                 $help['parameters'] .= Html::openElement( 'div',
 399                                         array( 'class' => 'apihelp-block apihelp-parameters' )
 400                                 );
 401                                 $msg = $context->msg( 'api-help-parameters' );
 402                                 if ( !$msg->isDisabled() ) {
 403                                         $help['parameters'] .= self::wrap(
 404                                                 $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
 405                                         );
 406                                 }
 407                                 $help['parameters'] .= Html::openElement( 'dl' );
 408
 409                                 $descriptions = $module->getFinalParamDescription();
 410
 411                                 foreach ( $params as $name => $settings ) {
 412                                         if ( !is_array( $settings ) ) {
 413                                                 $settings = array( ApiBase::PARAM_DFLT => $settings );
 414                                         }
 415
 416                                         $help['parameters'] .= Html::element( 'dt', null,
 417                                                 $module->encodeParamName( $name ) );
 418
 419                                         // Add description
 420                                         $description = array();
 421                                         if ( isset( $descriptions[$name] ) ) {
 422                                                 foreach ( $descriptions[$name] as $msg ) {
 423                                                         $msg->setContext( $context );
 424                                                         $description[] = $msg->parseAsBlock();
 425                                                 }
 426                                         }
 427
 428                                         // Add usage info
 429                                         $info = array();
 430
 431                                         // Required?
 432                                         if ( !empty( $settings[ApiBase::PARAM_REQUIRED] ) ) {
 433                                                 $info[] = $context->msg( 'api-help-param-required' )->parse();
 434                                         }
 435
 436                                         // Custom info?
 437                                         if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
 438                                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
 439                                                         $tag = array_shift( $i );
 440                                                         $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
 441                                                                 ->numParams( count( $i ) )
 442                                                                 ->params( $context->getLanguage()->commaList( $i ) )
 443                                                                 ->params( $module->getModulePrefix() )
 444                                                                 ->parse();
 445                                                 }
 446                                         }
 447
 448                                         // Type documentation
 449                                         if ( !isset( $settings[ApiBase::PARAM_TYPE] ) ) {
 450                                                 $dflt = isset( $settings[ApiBase::PARAM_DFLT] )
 451                                                         ? $settings[ApiBase::PARAM_DFLT]
 452                                                         : null;
 453                                                 if ( is_bool( $dflt ) ) {
 454                                                         $settings[ApiBase::PARAM_TYPE] = 'boolean';
 455                                                 } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
 456                                                         $settings[ApiBase::PARAM_TYPE] = 'string';
 457                                                 } elseif ( is_int( $dflt ) ) {
 458                                                         $settings[ApiBase::PARAM_TYPE] = 'integer';
 459                                                 }
 460                                         }
 461                                         if ( isset( $settings[ApiBase::PARAM_TYPE] ) ) {
 462                                                 $type = $settings[ApiBase::PARAM_TYPE];
 463                                                 $multi = !empty( $settings[ApiBase::PARAM_ISMULTI] );
 464                                                 $hintPipeSeparated = true;
 465                                                 $count = ApiBase::LIMIT_SML2 + 1;
 466
 467                                                 if ( is_array( $type ) ) {
 468                                                         $count = count( $type );
 469                                                         $links = isset( $settings[ApiBase::PARAM_VALUE_LINKS] )
 470                                                                 ? $settings[ApiBase::PARAM_VALUE_LINKS]
 471                                                                 : array();
 472                                                         $type = array_map( function ( $v ) use ( $links ) {
 473                                                                 $ret = wfEscapeWikiText( $v );
 474                                                                 if ( isset( $links[$v] ) ) {
 475                                                                         $ret = "[[{$links[$v]}|$ret]]";
 476                                                                 }
 477                                                                 return $ret;
 478                                                         }, $type );
 479                                                         $i = array_search( '', $type, true );
 480                                                         if ( $i === false ) {
 481                                                                 $type = $context->getLanguage()->commaList( $type );
 482                                                         } else {
 483                                                                 unset( $type[$i] );
 484                                                                 $type = $context->msg( 'api-help-param-list-can-be-empty' )
 485                                                                         ->numParams( count( $type ) )
 486                                                                         ->params( $context->getLanguage()->commaList( $type ) )
 487                                                                         ->parse();
 488                                                         }
 489                                                         $info[] = $context->msg( 'api-help-param-list' )
 490                                                                 ->params( $multi ? 2 : 1 )
 491                                                                 ->params( $type )
 492                                                                 ->parse();
 493                                                         $hintPipeSeparated = false;
 494                                                 } else {
 495                                                         switch ( $type ) {
 496                                                                 case 'submodule':
 497                                                                         $groups[] = $name;
 498                                                                         if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) {
 499                                                                                 $map = $settings[ApiBase::PARAM_SUBMODULE_MAP];
 500                                                                                 ksort( $map );
 501                                                                                 $submodules = array();
 502                                                                                 foreach ( $map as $v => $m ) {
 503                                                                                         $submodules[] = "[[Special:ApiHelp/{$m}|{$v}]]";
 504                                                                                 }
 505                                                                         } else {
 506                                                                                 $submodules = $module->getModuleManager()->getNames( $name );
 507                                                                                 sort( $submodules );
 508                                                                                 $prefix = $module->isMain()
 509                                                                                         ? '' : ( $module->getModulePath() . '+' );
 510                                                                                 $submodules = array_map( function ( $name ) use ( $prefix ) {
 511                                                                                         return "[[Special:ApiHelp/{$prefix}{$name}|{$name}]]";
 512                                                                                 }, $submodules );
 513                                                                         }
 514                                                                         $count = count( $submodules );
 515                                                                         $info[] = $context->msg( 'api-help-param-list' )
 516                                                                                 ->params( $multi ? 2 : 1 )
 517                                                                                 ->params( $context->getLanguage()->commaList( $submodules ) )
 518                                                                                 ->parse();
 519                                                                         $hintPipeSeparated = false;
 520                                                                         // No type message necessary, we have a list of values.
 521                                                                         $type = null;
 522                                                                         break;
 523
 524                                                                 case 'namespace':
 525                                                                         $namespaces = MWNamespace::getValidNamespaces();
 526                                                                         $count = count( $namespaces );
 527                                                                         $info[] = $context->msg( 'api-help-param-list' )
 528                                                                                 ->params( $multi ? 2 : 1 )
 529                                                                                 ->params( $context->getLanguage()->commaList( $namespaces ) )
 530                                                                                 ->parse();
 531                                                                         $hintPipeSeparated = false;
 532                                                                         // No type message necessary, we have a list of values.
 533                                                                         $type = null;
 534                                                                         break;
 535
 536                                                                 case 'limit':
 537                                                                         if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
 538                                                                                 $info[] = $context->msg( 'api-help-param-limit2' )
 539                                                                                         ->numParams( $settings[ApiBase::PARAM_MAX] )
 540                                                                                         ->numParams( $settings[ApiBase::PARAM_MAX2] )
 541                                                                                         ->parse();
 542                                                                         } else {
 543                                                                                 $info[] = $context->msg( 'api-help-param-limit' )
 544                                                                                         ->numParams( $settings[ApiBase::PARAM_MAX] )
 545                                                                                         ->parse();
 546                                                                         }
 547                                                                         break;
 548
 549                                                                 case 'integer':
 550                                                                         // Possible messages:
 551                                                                         // api-help-param-integer-min,
 552                                                                         // api-help-param-integer-max,
 553                                                                         // api-help-param-integer-minmax
 554                                                                         $suffix = '';
 555                                                                         $min = $max = 0;
 556                                                                         if ( isset( $settings[ApiBase::PARAM_MIN] ) ) {
 557                                                                                 $suffix .= 'min';
 558                                                                                 $min = $settings[ApiBase::PARAM_MIN];
 559                                                                         }
 560                                                                         if ( isset( $settings[ApiBase::PARAM_MAX] ) ) {
 561                                                                                 $suffix .= 'max';
 562                                                                                 $max = $settings[ApiBase::PARAM_MAX];
 563                                                                         }
 564                                                                         if ( $suffix !== '' ) {
 565                                                                                 $info[] =
 566                                                                                         $context->msg( "api-help-param-integer-$suffix" )
 567                                                                                                 ->params( $multi ? 2 : 1 )
 568                                                                                                 ->numParams( $min, $max )
 569                                                                                                 ->parse();
 570                                                                         }
 571                                                                         break;
 572
 573                                                                 case 'upload':
 574                                                                         $info[] = $context->msg( 'api-help-param-upload' )
 575                                                                                 ->parse();
 576                                                                         // No type message necessary, api-help-param-upload should handle it.
 577                                                                         $type = null;
 578                                                                         break;
 579
 580                                                                 case 'string':
 581                                                                 case 'text':
 582                                                                         // Displaying a type message here would be useless.
 583                                                                         $type = null;
 584                                                                         break;
 585                                                         }
 586                                                 }
 587
 588                                                 // Add type. Messages for grep: api-help-param-type-limit
 589                                                 // api-help-param-type-integer api-help-param-type-boolean
 590                                                 // api-help-param-type-timestamp api-help-param-type-user
 591                                                 // api-help-param-type-password
 592                                                 if ( is_string( $type ) ) {
 593                                                         $msg = $context->msg( "api-help-param-type-$type" );
 594                                                         if ( !$msg->isDisabled() ) {
 595                                                                 $info[] = $msg->params( $multi ? 2 : 1 )->parse();
 596                                                         }
 597                                                 }
 598
 599                                                 if ( $multi ) {
 600                                                         $extra = array();
 601                                                         if ( $hintPipeSeparated ) {
 602                                                                 $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
 603                                                         }
 604                                                         if ( $count > ApiBase::LIMIT_SML1 ) {
 605                                                                 $extra[] = $context->msg( 'api-help-param-multi-max' )
 606                                                                         ->numParams( ApiBase::LIMIT_SML1, ApiBase::LIMIT_SML2 )
 607                                                                         ->parse();
 608                                                         }
 609                                                         if ( $extra ) {
 610                                                                 $info[] = join( ' ', $extra );
 611                                                         }
 612                                                 }
 613                                         }
 614
 615                                         // Add default
 616                                         $default = isset( $settings[ApiBase::PARAM_DFLT] )
 617                                                 ? $settings[ApiBase::PARAM_DFLT]
 618                                                 : null;
 619                                         if ( $default === '' ) {
 620                                                 $info[] = $context->msg( 'api-help-param-default-empty' )
 621                                                         ->parse();
 622                                         } elseif ( $default !== null && $default !== false ) {
 623                                                 $info[] = $context->msg( 'api-help-param-default' )
 624                                                         ->params( wfEscapeWikiText( $default ) )
 625                                                         ->parse();
 626                                         }
 627
 628                                         if ( !array_filter( $description ) ) {
 629                                                 $description = array( self::wrap(
 630                                                         $context->msg( 'api-help-param-no-description' ),
 631                                                         'apihelp-empty'
 632                                                 ) );
 633                                         }
 634
 635                                         // Add "deprecated" flag
 636                                         if ( !empty( $settings[ApiBase::PARAM_DEPRECATED] ) ) {
 637                                                 $help['parameters'] .= Html::openElement( 'dd',
 638                                                         array( 'class' => 'info' ) );
 639                                                 $help['parameters'] .= self::wrap(
 640                                                         $context->msg( 'api-help-param-deprecated' ),
 641                                                         'apihelp-deprecated', 'strong'
 642                                                 );
 643                                                 $help['parameters'] .= Html::closeElement( 'dd' );
 644                                         }
 645
 646                                         if ( $description ) {
 647                                                 $description = join( '', $description );
 648                                                 $description = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $description );
 649                                                 $help['parameters'] .= Html::rawElement( 'dd',
 650                                                         array( 'class' => 'description' ), $description );
 651                                         }
 652
 653                                         foreach ( $info as $i ) {
 654                                                 $help['parameters'] .= Html::rawElement( 'dd', array( 'class' => 'info' ), $i );
 655                                         }
 656                                 }
 657
 658                                 if ( $dynamicParams !== null ) {
 659                                         $dynamicParams = ApiBase::makeMessage( $dynamicParams, $context, array(
 660                                                 $module->getModulePrefix(),
 661                                                 $module->getModuleName(),
 662                                                 $module->getModulePath()
 663                                         ) );
 664                                         $help['parameters'] .= Html::element( 'dt', null, '*' );
 665                                         $help['parameters'] .= Html::rawElement( 'dd',
 666                                                 array( 'class' => 'description' ), $dynamicParams->parse() );
 667                                 }
 668
 669                                 $help['parameters'] .= Html::closeElement( 'dl' );
 670                                 $help['parameters'] .= Html::closeElement( 'div' );
 671                         }
 672
 673                         $examples = $module->getExamplesMessages();
 674                         if ( $examples ) {
 675                                 $help['examples'] .= Html::openElement( 'div',
 676                                         array( 'class' => 'apihelp-block apihelp-examples' ) );
 677                                 $msg = $context->msg( 'api-help-examples' );
 678                                 if ( !$msg->isDisabled() ) {
 679                                         $help['examples'] .= self::wrap(
 680                                                 $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
 681                                         );
 682                                 }
 683
 684                                 $help['examples'] .= Html::openElement( 'dl' );
 685                                 foreach ( $examples as $qs => $msg ) {
 686                                         $msg = ApiBase::makeMessage( $msg, $context, array(
 687                                                 $module->getModulePrefix(),
 688                                                 $module->getModuleName(),
 689                                                 $module->getModulePath()
 690                                         ) );
 691
 692                                         $link = wfAppendQuery( wfScript( 'api' ), $qs );
 693                                         $help['examples'] .= Html::rawElement( 'dt', null, $msg->parse() );
 694                                         $help['examples'] .= Html::rawElement( 'dd', null,
 695                                                 Html::element( 'a', array( 'href' => $link ), "api.php?$qs" )
 696                                         );
 697                                 }
 698                                 $help['examples'] .= Html::closeElement( 'dl' );
 699                                 $help['examples'] .= Html::closeElement( 'div' );
 700                         }
 701
 702                         $subtocnumber = $tocnumber;
 703                         $subtocnumber[$level + 1] = 0;
 704                         $suboptions = array(
 705                                 'submodules' => $options['recursivesubmodules'],
 706                                 'headerlevel' => $level + 1,
 707                                 'tocnumber' => &$subtocnumber,
 708                                 'noheader' => false,
 709                         ) + $options;
 710
 711                         if ( $options['submodules'] && $module->getModuleManager() ) {
 712                                 $manager = $module->getModuleManager();
 713                                 $submodules = array();
 714                                 foreach ( $groups as $group ) {
 715                                         $names = $manager->getNames( $group );
 716                                         sort( $names );
 717                                         foreach ( $names as $name ) {
 718                                                 $submodules[] = $manager->getModule( $name );
 719                                         }
 720                                 }
 721                                 $help['submodules'] .= self::getHelpInternal(
 722                                         $context,
 723                                         $submodules,
 724                                         $suboptions,
 725                                         $haveModules
 726                                 );
 727                         }
 728
 729                         $module->modifyHelp( $help, $suboptions, $haveModules );
 730
 731                         Hooks::run( 'APIHelpModifyOutput', array( $module, &$help, $suboptions, &$haveModules ) );
 732
 733                         $out .= join( "\n", $help );
 734                 }
 735
 736                 return $out;
 737         }
 738
 739         public function shouldCheckMaxlag() {
 740                 return false;
 741         }
 742
 743         public function isReadMode() {
 744                 return false;
 745         }
 746
 747         public function getCustomPrinter() {
 748                 $params = $this->extractRequestParams();
 749                 if ( $params['wrap'] ) {
 750                         return null;
 751                 }
 752
 753                 $main = $this->getMain();
 754                 $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
 755                 return new ApiFormatRaw( $main, $errorPrinter );
 756         }
 757
 758         public function getAllowedParams() {
 759                 return array(
 760                         'modules' => array(
 761                                 ApiBase::PARAM_DFLT => 'main',
 762                                 ApiBase::PARAM_ISMULTI => true,
 763                         ),
 764                         'submodules' => false,
 765                         'recursivesubmodules' => false,
 766                         'wrap' => false,
 767                         'toc' => false,
 768                 );
 769         }
 770
 771         protected function getExamplesMessages() {
 772                 return array(
 773                         'action=help'
 774                                 => 'apihelp-help-example-main',
 775                         'action=help&modules=query&submodules=1'
 776                                 => 'apihelp-help-example-submodules',
 777                         'action=help&recursivesubmodules=1'
 778                                 => 'apihelp-help-example-recursive',
 779                         'action=help&modules=help'
 780                                 => 'apihelp-help-example-help',
 781                         'action=help&modules=query+info|query+categorymembers'
 782                                 => 'apihelp-help-example-query',
 783                 );
 784         }
 785
 786         public function getHelpUrls() {
 787                 return array(
 788                         'https://www.mediawiki.org/wiki/API:Main_page',
 789                         'https://www.mediawiki.org/wiki/API:FAQ',
 790                         'https://www.mediawiki.org/wiki/API:Quick_start_guide',
 791                 );
 792         }
 793 }