includes/api/ApiMain.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on Sep 4, 2006
   6  *
   7  * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   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  * @defgroup API API
  26  */
  27
  28 /**
  29  * This is the main API class, used for both external and internal processing.
  30  * When executed, it will create the requested formatter object,
  31  * instantiate and execute an object associated with the needed action,
  32  * and use formatter to print results.
  33  * In case of an exception, an error message will be printed using the same formatter.
  34  *
  35  * To use API from another application, run it using FauxRequest object, in which
  36  * case any internal exceptions will not be handled but passed up to the caller.
  37  * After successful execution, use getResult() for the resulting data.
  38  *
  39  * @ingroup API
  40  */
  41 class ApiMain extends ApiBase {
  42
  43         /**
  44          * When no format parameter is given, this format will be used
  45          */
  46         const API_DEFAULT_FORMAT = 'xmlfm';
  47
  48         /**
  49          * List of available modules: action name => module class
  50          */
  51         private static $Modules = array(
  52                 'login' => 'ApiLogin',
  53                 'logout' => 'ApiLogout',
  54                 'createaccount' => 'ApiCreateAccount',
  55                 'query' => 'ApiQuery',
  56                 'expandtemplates' => 'ApiExpandTemplates',
  57                 'parse' => 'ApiParse',
  58                 'opensearch' => 'ApiOpenSearch',
  59                 'feedcontributions' => 'ApiFeedContributions',
  60                 'feedwatchlist' => 'ApiFeedWatchlist',
  61                 'help' => 'ApiHelp',
  62                 'paraminfo' => 'ApiParamInfo',
  63                 'rsd' => 'ApiRsd',
  64                 'compare' => 'ApiComparePages',
  65                 'tokens' => 'ApiTokens',
  66
  67                 // Write modules
  68                 'purge' => 'ApiPurge',
  69                 'setnotificationtimestamp' => 'ApiSetNotificationTimestamp',
  70                 'rollback' => 'ApiRollback',
  71                 'delete' => 'ApiDelete',
  72                 'undelete' => 'ApiUndelete',
  73                 'protect' => 'ApiProtect',
  74                 'block' => 'ApiBlock',
  75                 'unblock' => 'ApiUnblock',
  76                 'move' => 'ApiMove',
  77                 'edit' => 'ApiEditPage',
  78                 'upload' => 'ApiUpload',
  79                 'filerevert' => 'ApiFileRevert',
  80                 'emailuser' => 'ApiEmailUser',
  81                 'watch' => 'ApiWatch',
  82                 'patrol' => 'ApiPatrol',
  83                 'import' => 'ApiImport',
  84                 'userrights' => 'ApiUserrights',
  85                 'options' => 'ApiOptions',
  86                 'imagerotate' => 'ApiImageRotate',
  87         );
  88
  89         /**
  90          * List of available formats: format name => format class
  91          */
  92         private static $Formats = array(
  93                 'json' => 'ApiFormatJson',
  94                 'jsonfm' => 'ApiFormatJson',
  95                 'php' => 'ApiFormatPhp',
  96                 'phpfm' => 'ApiFormatPhp',
  97                 'wddx' => 'ApiFormatWddx',
  98                 'wddxfm' => 'ApiFormatWddx',
  99                 'xml' => 'ApiFormatXml',
 100                 'xmlfm' => 'ApiFormatXml',
 101                 'yaml' => 'ApiFormatYaml',
 102                 'yamlfm' => 'ApiFormatYaml',
 103                 'rawfm' => 'ApiFormatJson',
 104                 'txt' => 'ApiFormatTxt',
 105                 'txtfm' => 'ApiFormatTxt',
 106                 'dbg' => 'ApiFormatDbg',
 107                 'dbgfm' => 'ApiFormatDbg',
 108                 'dump' => 'ApiFormatDump',
 109                 'dumpfm' => 'ApiFormatDump',
 110                 'none' => 'ApiFormatNone',
 111         );
 112
 113         // @codingStandardsIgnoreStart String contenation on "msg" not allowed to break long line
 114         /**
 115          * List of user roles that are specifically relevant to the API.
 116          * array( 'right' => array ( 'msg'    => 'Some message with a $1',
 117          *                           'params' => array ( $someVarToSubst ) ),
 118          *                          );
 119          */
 120         private static $mRights = array(
 121                 'writeapi' => array(
 122                         'msg' => 'Use of the write API',
 123                         'params' => array()
 124                 ),
 125                 'apihighlimits' => array(
 126                         'msg' => 'Use higher limits in API queries (Slow queries: $1 results; Fast queries: $2 results). The limits for slow queries also apply to multivalue parameters.',
 127                         'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
 128                 )
 129         );
 130         // @codingStandardsIgnoreEnd
 131
 132         /**
 133          * @var ApiFormatBase
 134          */
 135         private $mPrinter;
 136
 137         private $mModuleMgr, $mResult;
 138         private $mAction;
 139         private $mEnableWrite;
 140         private $mInternalMode, $mSquidMaxage, $mModule;
 141
 142         private $mCacheMode = 'private';
 143         private $mCacheControl = array();
 144         private $mParamsUsed = array();
 145
 146         /**
 147          * Constructs an instance of ApiMain that utilizes the module and format specified by $request.
 148          *
 149          * @param $context IContextSource|WebRequest - if this is an instance of
 150          *    FauxRequest, errors are thrown and no printing occurs
 151          * @param bool $enableWrite should be set to true if the api may modify data
 152          */
 153         public function __construct( $context = null, $enableWrite = false ) {
 154                 if ( $context === null ) {
 155                         $context = RequestContext::getMain();
 156                 } elseif ( $context instanceof WebRequest ) {
 157                         // BC for pre-1.19
 158                         $request = $context;
 159                         $context = RequestContext::getMain();
 160                 }
 161                 // We set a derivative context so we can change stuff later
 162                 $this->setContext( new DerivativeContext( $context ) );
 163
 164                 if ( isset( $request ) ) {
 165                         $this->getContext()->setRequest( $request );
 166                 }
 167
 168                 $this->mInternalMode = ( $this->getRequest() instanceof FauxRequest );
 169
 170                 // Special handling for the main module: $parent === $this
 171                 parent::__construct( $this, $this->mInternalMode ? 'main_int' : 'main' );
 172
 173                 if ( !$this->mInternalMode ) {
 174                         // Impose module restrictions.
 175                         // If the current user cannot read,
 176                         // Remove all modules other than login
 177                         global $wgUser;
 178
 179                         if ( $this->getVal( 'callback' ) !== null ) {
 180                                 // JSON callback allows cross-site reads.
 181                                 // For safety, strip user credentials.
 182                                 wfDebug( "API: stripping user credentials for JSON callback\n" );
 183                                 $wgUser = new User();
 184                                 $this->getContext()->setUser( $wgUser );
 185                         }
 186                 }
 187
 188                 global $wgAPIModules;
 189                 $this->mModuleMgr = new ApiModuleManager( $this );
 190                 $this->mModuleMgr->addModules( self::$Modules, 'action' );
 191                 $this->mModuleMgr->addModules( $wgAPIModules, 'action' );
 192                 $this->mModuleMgr->addModules( self::$Formats, 'format' );
 193
 194                 $this->mResult = new ApiResult( $this );
 195                 $this->mEnableWrite = $enableWrite;
 196
 197                 $this->mSquidMaxage = -1; // flag for executeActionWithErrorHandling()
 198                 $this->mCommit = false;
 199         }
 200
 201         /**
 202          * Return true if the API was started by other PHP code using FauxRequest
 203          * @return bool
 204          */
 205         public function isInternalMode() {
 206                 return $this->mInternalMode;
 207         }
 208
 209         /**
 210          * Get the ApiResult object associated with current request
 211          *
 212          * @return ApiResult
 213          */
 214         public function getResult() {
 215                 return $this->mResult;
 216         }
 217
 218         /**
 219          * Get the API module object. Only works after executeAction()
 220          *
 221          * @return ApiBase
 222          */
 223         public function getModule() {
 224                 return $this->mModule;
 225         }
 226
 227         /**
 228          * Get the result formatter object. Only works after setupExecuteAction()
 229          *
 230          * @return ApiFormatBase
 231          */
 232         public function getPrinter() {
 233                 return $this->mPrinter;
 234         }
 235
 236         /**
 237          * Set how long the response should be cached.
 238          *
 239          * @param $maxage
 240          */
 241         public function setCacheMaxAge( $maxage ) {
 242                 $this->setCacheControl( array(
 243                         'max-age' => $maxage,
 244                         's-maxage' => $maxage
 245                 ) );
 246         }
 247
 248         /**
 249          * Set the type of caching headers which will be sent.
 250          *
 251          * @param string $mode One of:
 252          *    - 'public':     Cache this object in public caches, if the maxage or smaxage
 253          *         parameter is set, or if setCacheMaxAge() was called. If a maximum age is
 254          *         not provided by any of these means, the object will be private.
 255          *    - 'private':    Cache this object only in private client-side caches.
 256          *    - 'anon-public-user-private': Make this object cacheable for logged-out
 257          *         users, but private for logged-in users. IMPORTANT: If this is set, it must be
 258          *         set consistently for a given URL, it cannot be set differently depending on
 259          *         things like the contents of the database, or whether the user is logged in.
 260          *
 261          *  If the wiki does not allow anonymous users to read it, the mode set here
 262          *  will be ignored, and private caching headers will always be sent. In other words,
 263          *  the "public" mode is equivalent to saying that the data sent is as public as a page
 264          *  view.
 265          *
 266          *  For user-dependent data, the private mode should generally be used. The
 267          *  anon-public-user-private mode should only be used where there is a particularly
 268          *  good performance reason for caching the anonymous response, but where the
 269          *  response to logged-in users may differ, or may contain private data.
 270          *
 271          *  If this function is never called, then the default will be the private mode.
 272          */
 273         public function setCacheMode( $mode ) {
 274                 if ( !in_array( $mode, array( 'private', 'public', 'anon-public-user-private' ) ) ) {
 275                         wfDebug( __METHOD__ . ": unrecognised cache mode \"$mode\"\n" );
 276
 277                         // Ignore for forwards-compatibility
 278                         return;
 279                 }
 280
 281                 if ( !User::isEveryoneAllowed( 'read' ) ) {
 282                         // Private wiki, only private headers
 283                         if ( $mode !== 'private' ) {
 284                                 wfDebug( __METHOD__ . ": ignoring request for $mode cache mode, private wiki\n" );
 285
 286                                 return;
 287                         }
 288                 }
 289
 290                 wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
 291                 $this->mCacheMode = $mode;
 292         }
 293
 294         /**
 295          * @deprecated since 1.17 Private caching is now the default, so there is usually no
 296          * need to call this function. If there is a need, you can use
 297          * $this->setCacheMode('private')
 298          */
 299         public function setCachePrivate() {
 300                 wfDeprecated( __METHOD__, '1.17' );
 301                 $this->setCacheMode( 'private' );
 302         }
 303
 304         /**
 305          * Set directives (key/value pairs) for the Cache-Control header.
 306          * Boolean values will be formatted as such, by including or omitting
 307          * without an equals sign.
 308          *
 309          * Cache control values set here will only be used if the cache mode is not
 310          * private, see setCacheMode().
 311          *
 312          * @param $directives array
 313          */
 314         public function setCacheControl( $directives ) {
 315                 $this->mCacheControl = $directives + $this->mCacheControl;
 316         }
 317
 318         /**
 319          * Make sure Vary: Cookie and friends are set. Use this when the output of a request
 320          * may be cached for anons but may not be cached for logged-in users.
 321          *
 322          * WARNING: This function must be called CONSISTENTLY for a given URL. This means that a
 323          * given URL must either always or never call this function; if it sometimes does and
 324          * sometimes doesn't, stuff will break.
 325          *
 326          * @deprecated since 1.17 Use setCacheMode( 'anon-public-user-private' )
 327          */
 328         public function setVaryCookie() {
 329                 wfDeprecated( __METHOD__, '1.17' );
 330                 $this->setCacheMode( 'anon-public-user-private' );
 331         }
 332
 333         /**
 334          * Create an instance of an output formatter by its name
 335          *
 336          * @param $format string
 337          *
 338          * @return ApiFormatBase
 339          */
 340         public function createPrinterByName( $format ) {
 341                 $printer = $this->mModuleMgr->getModule( $format, 'format' );
 342                 if ( $printer === null ) {
 343                         $this->dieUsage( "Unrecognized format: {$format}", 'unknown_format' );
 344                 }
 345
 346                 return $printer;
 347         }
 348
 349         /**
 350          * Execute api request. Any errors will be handled if the API was called by the remote client.
 351          */
 352         public function execute() {
 353                 $this->profileIn();
 354                 if ( $this->mInternalMode ) {
 355                         $this->executeAction();
 356                 } else {
 357                         $this->executeActionWithErrorHandling();
 358                 }
 359
 360                 $this->profileOut();
 361         }
 362
 363         /**
 364          * Execute an action, and in case of an error, erase whatever partial results
 365          * have been accumulated, and replace it with an error message and a help screen.
 366          */
 367         protected function executeActionWithErrorHandling() {
 368                 // Verify the CORS header before executing the action
 369                 if ( !$this->handleCORS() ) {
 370                         // handleCORS() has sent a 403, abort
 371                         return;
 372                 }
 373
 374                 // Exit here if the request method was OPTIONS
 375                 // (assume there will be a followup GET or POST)
 376                 if ( $this->getRequest()->getMethod() === 'OPTIONS' ) {
 377                         return;
 378                 }
 379
 380                 // In case an error occurs during data output,
 381                 // clear the output buffer and print just the error information
 382                 ob_start();
 383
 384                 $t = microtime( true );
 385                 try {
 386                         $this->executeAction();
 387                 } catch ( Exception $e ) {
 388                         // Allow extra cleanup and logging
 389                         wfRunHooks( 'ApiMain::onException', array( $this, $e ) );
 390
 391                         // Log it
 392                         if ( !( $e instanceof UsageException ) ) {
 393                                 MWExceptionHandler::logException( $e );
 394                         }
 395
 396                         // Handle any kind of exception by outputting properly formatted error message.
 397                         // If this fails, an unhandled exception should be thrown so that global error
 398                         // handler will process and log it.
 399
 400                         $errCode = $this->substituteResultWithError( $e );
 401
 402                         // Error results should not be cached
 403                         $this->setCacheMode( 'private' );
 404
 405                         $response = $this->getRequest()->response();
 406                         $headerStr = 'MediaWiki-API-Error: ' . $errCode;
 407                         if ( $e->getCode() === 0 ) {
 408                                 $response->header( $headerStr );
 409                         } else {
 410                                 $response->header( $headerStr, true, $e->getCode() );
 411                         }
 412
 413                         // Reset and print just the error message
 414                         ob_clean();
 415
 416                         // If the error occurred during printing, do a printer->profileOut()
 417                         $this->mPrinter->safeProfileOut();
 418                         $this->printResult( true );
 419                 }
 420
 421                 // Log the request whether or not there was an error
 422                 $this->logRequest( microtime( true ) - $t );
 423
 424                 // Send cache headers after any code which might generate an error, to
 425                 // avoid sending public cache headers for errors.
 426                 $this->sendCacheHeaders();
 427
 428                 if ( $this->mPrinter->getIsHtml() && !$this->mPrinter->isDisabled() ) {
 429                         echo wfReportTime();
 430                 }
 431
 432                 ob_end_flush();
 433         }
 434
 435         /**
 436          * Check the &origin= query parameter against the Origin: HTTP header and respond appropriately.
 437          *
 438          * If no origin parameter is present, nothing happens.
 439          * If an origin parameter is present but doesn't match the Origin header, a 403 status code
 440          * is set and false is returned.
 441          * If the parameter and the header do match, the header is checked against $wgCrossSiteAJAXdomains
 442          * and $wgCrossSiteAJAXdomainExceptions, and if the origin qualifies, the appropriate CORS
 443          * headers are set.
 444          *
 445          * @return bool False if the caller should abort (403 case), true otherwise (all other cases)
 446          */
 447         protected function handleCORS() {
 448                 global $wgCrossSiteAJAXdomains, $wgCrossSiteAJAXdomainExceptions;
 449
 450                 $originParam = $this->getParameter( 'origin' ); // defaults to null
 451                 if ( $originParam === null ) {
 452                         // No origin parameter, nothing to do
 453                         return true;
 454                 }
 455
 456                 $request = $this->getRequest();
 457                 $response = $request->response();
 458                 // Origin: header is a space-separated list of origins, check all of them
 459                 $originHeader = $request->getHeader( 'Origin' );
 460                 if ( $originHeader === false ) {
 461                         $origins = array();
 462                 } else {
 463                         $origins = explode( ' ', $originHeader );
 464                 }
 465
 466                 if ( !in_array( $originParam, $origins ) ) {
 467                         // origin parameter set but incorrect
 468                         // Send a 403 response
 469                         $message = HttpStatus::getMessage( 403 );
 470                         $response->header( "HTTP/1.1 403 $message", true, 403 );
 471                         $response->header( 'Cache-Control: no-cache' );
 472                         echo "'origin' parameter does not match Origin header\n";
 473
 474                         return false;
 475                 }
 476
 477                 $matchOrigin = self::matchOrigin(
 478                         $originParam,
 479                         $wgCrossSiteAJAXdomains,
 480                         $wgCrossSiteAJAXdomainExceptions
 481                 );
 482
 483                 if ( $matchOrigin ) {
 484                         $response->header( "Access-Control-Allow-Origin: $originParam" );
 485                         $response->header( 'Access-Control-Allow-Credentials: true' );
 486                         $this->getOutput()->addVaryHeader( 'Origin' );
 487                 }
 488
 489                 return true;
 490         }
 491
 492         /**
 493          * Attempt to match an Origin header against a set of rules and a set of exceptions
 494          * @param string $value Origin header
 495          * @param array $rules Set of wildcard rules
 496          * @param array $exceptions Set of wildcard rules
 497          * @return bool True if $value matches a rule in $rules and doesn't match
 498          *    any rules in $exceptions, false otherwise
 499          */
 500         protected static function matchOrigin( $value, $rules, $exceptions ) {
 501                 foreach ( $rules as $rule ) {
 502                         if ( preg_match( self::wildcardToRegex( $rule ), $value ) ) {
 503                                 // Rule matches, check exceptions
 504                                 foreach ( $exceptions as $exc ) {
 505                                         if ( preg_match( self::wildcardToRegex( $exc ), $value ) ) {
 506                                                 return false;
 507                                         }
 508                                 }
 509
 510                                 return true;
 511                         }
 512                 }
 513
 514                 return false;
 515         }
 516
 517         /**
 518          * Helper function to convert wildcard string into a regex
 519          * '*' => '.*?'
 520          * '?' => '.'
 521          *
 522          * @param string $wildcard String with wildcards
 523          * @return string Regular expression
 524          */
 525         protected static function wildcardToRegex( $wildcard ) {
 526                 $wildcard = preg_quote( $wildcard, '/' );
 527                 $wildcard = str_replace(
 528                         array( '\*', '\?' ),
 529                         array( '.*?', '.' ),
 530                         $wildcard
 531                 );
 532
 533                 return "/https?:\/\/$wildcard/";
 534         }
 535
 536         protected function sendCacheHeaders() {
 537                 global $wgUseXVO, $wgVaryOnXFP;
 538                 $response = $this->getRequest()->response();
 539                 $out = $this->getOutput();
 540
 541                 if ( $wgVaryOnXFP ) {
 542                         $out->addVaryHeader( 'X-Forwarded-Proto' );
 543                 }
 544
 545                 if ( $this->mCacheMode == 'private' ) {
 546                         $response->header( 'Cache-Control: private' );
 547
 548                         return;
 549                 }
 550
 551                 if ( $this->mCacheMode == 'anon-public-user-private' ) {
 552                         $out->addVaryHeader( 'Cookie' );
 553                         $response->header( $out->getVaryHeader() );
 554                         if ( $wgUseXVO ) {
 555                                 $response->header( $out->getXVO() );
 556                                 if ( $out->haveCacheVaryCookies() ) {
 557                                         // Logged in, mark this request private
 558                                         $response->header( 'Cache-Control: private' );
 559
 560                                         return;
 561                                 }
 562                                 // Logged out, send normal public headers below
 563                         } elseif ( session_id() != '' ) {
 564                                 // Logged in or otherwise has session (e.g. anonymous users who have edited)
 565                                 // Mark request private
 566                                 $response->header( 'Cache-Control: private' );
 567
 568                                 return;
 569                         } // else no XVO and anonymous, send public headers below
 570                 }
 571
 572                 // Send public headers
 573                 $response->header( $out->getVaryHeader() );
 574                 if ( $wgUseXVO ) {
 575                         $response->header( $out->getXVO() );
 576                 }
 577
 578                 // If nobody called setCacheMaxAge(), use the (s)maxage parameters
 579                 if ( !isset( $this->mCacheControl['s-maxage'] ) ) {
 580                         $this->mCacheControl['s-maxage'] = $this->getParameter( 'smaxage' );
 581                 }
 582                 if ( !isset( $this->mCacheControl['max-age'] ) ) {
 583                         $this->mCacheControl['max-age'] = $this->getParameter( 'maxage' );
 584                 }
 585
 586                 if ( !$this->mCacheControl['s-maxage'] && !$this->mCacheControl['max-age'] ) {
 587                         // Public cache not requested
 588                         // Sending a Vary header in this case is harmless, and protects us
 589                         // against conditional calls of setCacheMaxAge().
 590                         $response->header( 'Cache-Control: private' );
 591
 592                         return;
 593                 }
 594
 595                 $this->mCacheControl['public'] = true;
 596
 597                 // Send an Expires header
 598                 $maxAge = min( $this->mCacheControl['s-maxage'], $this->mCacheControl['max-age'] );
 599                 $expiryUnixTime = ( $maxAge == 0 ? 1 : time() + $maxAge );
 600                 $response->header( 'Expires: ' . wfTimestamp( TS_RFC2822, $expiryUnixTime ) );
 601
 602                 // Construct the Cache-Control header
 603                 $ccHeader = '';
 604                 $separator = '';
 605                 foreach ( $this->mCacheControl as $name => $value ) {
 606                         if ( is_bool( $value ) ) {
 607                                 if ( $value ) {
 608                                         $ccHeader .= $separator . $name;
 609                                         $separator = ', ';
 610                                 }
 611                         } else {
 612                                 $ccHeader .= $separator . "$name=$value";
 613                                 $separator = ', ';
 614                         }
 615                 }
 616
 617                 $response->header( "Cache-Control: $ccHeader" );
 618         }
 619
 620         /**
 621          * Replace the result data with the information about an exception.
 622          * Returns the error code
 623          * @param $e Exception
 624          * @return string
 625          */
 626         protected function substituteResultWithError( $e ) {
 627                 global $wgShowHostnames;
 628
 629                 $result = $this->getResult();
 630                 // Printer may not be initialized if the extractRequestParams() fails for the main module
 631                 if ( !isset( $this->mPrinter ) ) {
 632                         // The printer has not been created yet. Try to manually get formatter value.
 633                         $value = $this->getRequest()->getVal( 'format', self::API_DEFAULT_FORMAT );
 634                         if ( !$this->mModuleMgr->isDefined( $value, 'format' ) ) {
 635                                 $value = self::API_DEFAULT_FORMAT;
 636                         }
 637
 638                         $this->mPrinter = $this->createPrinterByName( $value );
 639                         if ( $this->mPrinter->getNeedsRawData() ) {
 640                                 $result->setRawMode();
 641                         }
 642                 }
 643
 644                 if ( $e instanceof UsageException ) {
 645                         // User entered incorrect parameters - print usage screen
 646                         $errMessage = $e->getMessageArray();
 647
 648                         // Only print the help message when this is for the developer, not runtime
 649                         if ( $this->mPrinter->getWantsHelp() || $this->mAction == 'help' ) {
 650                                 ApiResult::setContent( $errMessage, $this->makeHelpMsg() );
 651                         }
 652                 } else {
 653                         global $wgShowSQLErrors, $wgShowExceptionDetails;
 654                         // Something is seriously wrong
 655                         if ( ( $e instanceof DBQueryError ) && !$wgShowSQLErrors ) {
 656                                 $info = 'Database query error';
 657                         } else {
 658                                 $info = "Exception Caught: {$e->getMessage()}";
 659                         }
 660
 661                         $errMessage = array(
 662                                 'code' => 'internal_api_error_' . get_class( $e ),
 663                                 'info' => $info,
 664                         );
 665                         ApiResult::setContent(
 666                                 $errMessage,
 667                                 $wgShowExceptionDetails ? "\n\n{$e->getTraceAsString()}\n\n" : ''
 668                         );
 669                 }
 670
 671                 // Remember all the warnings to re-add them later
 672                 $oldResult = $result->getData();
 673                 $warnings = isset( $oldResult['warnings'] ) ? $oldResult['warnings'] : null;
 674
 675                 $result->reset();
 676                 $result->disableSizeCheck();
 677                 // Re-add the id
 678                 $requestid = $this->getParameter( 'requestid' );
 679                 if ( !is_null( $requestid ) ) {
 680                         $result->addValue( null, 'requestid', $requestid );
 681                 }
 682                 if ( $wgShowHostnames ) {
 683                         // servedby is especially useful when debugging errors
 684                         $result->addValue( null, 'servedby', wfHostName() );
 685                 }
 686                 if ( $warnings !== null ) {
 687                         $result->addValue( null, 'warnings', $warnings );
 688                 }
 689
 690                 $result->addValue( null, 'error', $errMessage );
 691
 692                 return $errMessage['code'];
 693         }
 694
 695         /**
 696          * Set up for the execution.
 697          * @return array
 698          */
 699         protected function setupExecuteAction() {
 700                 global $wgShowHostnames;
 701
 702                 // First add the id to the top element
 703                 $result = $this->getResult();
 704                 $requestid = $this->getParameter( 'requestid' );
 705                 if ( !is_null( $requestid ) ) {
 706                         $result->addValue( null, 'requestid', $requestid );
 707                 }
 708
 709                 if ( $wgShowHostnames ) {
 710                         $servedby = $this->getParameter( 'servedby' );
 711                         if ( $servedby ) {
 712                                 $result->addValue( null, 'servedby', wfHostName() );
 713                         }
 714                 }
 715
 716                 $params = $this->extractRequestParams();
 717
 718                 $this->mAction = $params['action'];
 719
 720                 if ( !is_string( $this->mAction ) ) {
 721                         $this->dieUsage( 'The API requires a valid action parameter', 'unknown_action' );
 722                 }
 723
 724                 return $params;
 725         }
 726
 727         /**
 728          * Set up the module for response
 729          * @return ApiBase The module that will handle this action
 730          */
 731         protected function setupModule() {
 732                 // Instantiate the module requested by the user
 733                 $module = $this->mModuleMgr->getModule( $this->mAction, 'action' );
 734                 if ( $module === null ) {
 735                         $this->dieUsage( 'The API requires a valid action parameter', 'unknown_action' );
 736                 }
 737                 $moduleParams = $module->extractRequestParams();
 738
 739                 // Die if token required, but not provided
 740                 $salt = $module->getTokenSalt();
 741                 if ( $salt !== false ) {
 742                         if ( !isset( $moduleParams['token'] ) ) {
 743                                 $this->dieUsageMsg( array( 'missingparam', 'token' ) );
 744                         }
 745
 746                         if ( !$this->getUser()->matchEditToken( $moduleParams['token'], $salt, $this->getContext()->getRequest() ) ) {
 747                                 $this->dieUsageMsg( 'sessionfailure' );
 748                         }
 749                 }
 750
 751                 return $module;
 752         }
 753
 754         /**
 755          * Check the max lag if necessary
 756          * @param $module ApiBase object: Api module being used
 757          * @param array $params an array containing the request parameters.
 758          * @return boolean True on success, false should exit immediately
 759          */
 760         protected function checkMaxLag( $module, $params ) {
 761                 if ( $module->shouldCheckMaxlag() && isset( $params['maxlag'] ) ) {
 762                         // Check for maxlag
 763                         global $wgShowHostnames;
 764                         $maxLag = $params['maxlag'];
 765                         list( $host, $lag ) = wfGetLB()->getMaxLag();
 766                         if ( $lag > $maxLag ) {
 767                                 $response = $this->getRequest()->response();
 768
 769                                 $response->header( 'Retry-After: ' . max( intval( $maxLag ), 5 ) );
 770                                 $response->header( 'X-Database-Lag: ' . intval( $lag ) );
 771
 772                                 if ( $wgShowHostnames ) {
 773                                         $this->dieUsage( "Waiting for $host: $lag seconds lagged", 'maxlag' );
 774                                 }
 775
 776                                 $this->dieUsage( "Waiting for a database server: $lag seconds lagged", 'maxlag' );
 777                         }
 778                 }
 779
 780                 return true;
 781         }
 782
 783         /**
 784          * Check for sufficient permissions to execute
 785          * @param $module ApiBase An Api module
 786          */
 787         protected function checkExecutePermissions( $module ) {
 788                 $user = $this->getUser();
 789                 if ( $module->isReadMode() && !User::isEveryoneAllowed( 'read' ) &&
 790                         !$user->isAllowed( 'read' )
 791                 ) {
 792                         $this->dieUsageMsg( 'readrequired' );
 793                 }
 794                 if ( $module->isWriteMode() ) {
 795                         if ( !$this->mEnableWrite ) {
 796                                 $this->dieUsageMsg( 'writedisabled' );
 797                         }
 798                         if ( !$user->isAllowed( 'writeapi' ) ) {
 799                                 $this->dieUsageMsg( 'writerequired' );
 800                         }
 801                         if ( wfReadOnly() ) {
 802                                 $this->dieReadOnly();
 803                         }
 804                 }
 805
 806                 // Allow extensions to stop execution for arbitrary reasons.
 807                 $message = false;
 808                 if ( !wfRunHooks( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
 809                         $this->dieUsageMsg( $message );
 810                 }
 811         }
 812
 813         /**
 814          * Check POST for external response and setup result printer
 815          * @param $module ApiBase An Api module
 816          * @param array $params an array with the request parameters
 817          */
 818         protected function setupExternalResponse( $module, $params ) {
 819                 if ( !$this->getRequest()->wasPosted() && $module->mustBePosted() ) {
 820                         // Module requires POST. GET request might still be allowed
 821                         // if $wgDebugApi is true, otherwise fail.
 822                         $this->dieUsageMsgOrDebug( array( 'mustbeposted', $this->mAction ) );
 823                 }
 824
 825                 // See if custom printer is used
 826                 $this->mPrinter = $module->getCustomPrinter();
 827                 if ( is_null( $this->mPrinter ) ) {
 828                         // Create an appropriate printer
 829                         $this->mPrinter = $this->createPrinterByName( $params['format'] );
 830                 }
 831
 832                 if ( $this->mPrinter->getNeedsRawData() ) {
 833                         $this->getResult()->setRawMode();
 834                 }
 835         }
 836
 837         /**
 838          * Execute the actual module, without any error handling
 839          */
 840         protected function executeAction() {
 841                 $params = $this->setupExecuteAction();
 842                 $module = $this->setupModule();
 843                 $this->mModule = $module;
 844
 845                 $this->checkExecutePermissions( $module );
 846
 847                 if ( !$this->checkMaxLag( $module, $params ) ) {
 848                         return;
 849                 }
 850
 851                 if ( !$this->mInternalMode ) {
 852                         $this->setupExternalResponse( $module, $params );
 853                 }
 854
 855                 // Execute
 856                 $module->profileIn();
 857                 $module->execute();
 858                 wfRunHooks( 'APIAfterExecute', array( &$module ) );
 859                 $module->profileOut();
 860
 861                 $this->reportUnusedParams();
 862
 863                 if ( !$this->mInternalMode ) {
 864                         //append Debug information
 865                         MWDebug::appendDebugInfoToApiResult( $this->getContext(), $this->getResult() );
 866
 867                         // Print result data
 868                         $this->printResult( false );
 869                 }
 870         }
 871
 872         /**
 873          * Log the preceding request
 874          * @param int $time Time in seconds
 875          */
 876         protected function logRequest( $time ) {
 877                 $request = $this->getRequest();
 878                 $milliseconds = $time === null ? '?' : round( $time * 1000 );
 879                 $s = 'API' .
 880                         ' ' . $request->getMethod() .
 881                         ' ' . wfUrlencode( str_replace( ' ', '_', $this->getUser()->getName() ) ) .
 882                         ' ' . $request->getIP() .
 883                         ' T=' . $milliseconds . 'ms';
 884                 foreach ( $this->getParamsUsed() as $name ) {
 885                         $value = $request->getVal( $name );
 886                         if ( $value === null ) {
 887                                 continue;
 888                         }
 889                         $s .= ' ' . $name . '=';
 890                         if ( strlen( $value ) > 256 ) {
 891                                 $encValue = $this->encodeRequestLogValue( substr( $value, 0, 256 ) );
 892                                 $s .= $encValue . '[...]';
 893                         } else {
 894                                 $s .= $this->encodeRequestLogValue( $value );
 895                         }
 896                 }
 897                 $s .= "\n";
 898                 wfDebugLog( 'api', $s, false );
 899         }
 900
 901         /**
 902          * Encode a value in a format suitable for a space-separated log line.
 903          */
 904         protected function encodeRequestLogValue( $s ) {
 905                 static $table;
 906                 if ( !$table ) {
 907                         $chars = ';@$!*(),/:';
 908                         $numChars = strlen( $chars );
 909                         for ( $i = 0; $i < $numChars; $i++ ) {
 910                                 $table[rawurlencode( $chars[$i] )] = $chars[$i];
 911                         }
 912                 }
 913
 914                 return strtr( rawurlencode( $s ), $table );
 915         }
 916
 917         /**
 918          * Get the request parameters used in the course of the preceding execute() request
 919          */
 920         protected function getParamsUsed() {
 921                 return array_keys( $this->mParamsUsed );
 922         }
 923
 924         /**
 925          * Get a request value, and register the fact that it was used, for logging.
 926          */
 927         public function getVal( $name, $default = null ) {
 928                 $this->mParamsUsed[$name] = true;
 929
 930                 return $this->getRequest()->getVal( $name, $default );
 931         }
 932
 933         /**
 934          * Get a boolean request value, and register the fact that the parameter
 935          * was used, for logging.
 936          */
 937         public function getCheck( $name ) {
 938                 $this->mParamsUsed[$name] = true;
 939
 940                 return $this->getRequest()->getCheck( $name );
 941         }
 942
 943         /**
 944          * Get a request upload, and register the fact that it was used, for logging.
 945          *
 946          * @since 1.21
 947          * @param string $name Parameter name
 948          * @return WebRequestUpload
 949          */
 950         public function getUpload( $name ) {
 951                 $this->mParamsUsed[$name] = true;
 952
 953                 return $this->getRequest()->getUpload( $name );
 954         }
 955
 956         /**
 957          * Report unused parameters, so the client gets a hint in case it gave us parameters we don't know,
 958          * for example in case of spelling mistakes or a missing 'g' prefix for generators.
 959          */
 960         protected function reportUnusedParams() {
 961                 $paramsUsed = $this->getParamsUsed();
 962                 $allParams = $this->getRequest()->getValueNames();
 963
 964                 if ( !$this->mInternalMode ) {
 965                         // Printer has not yet executed; don't warn that its parameters are unused
 966                         $printerParams = array_map(
 967                                 array( $this->mPrinter, 'encodeParamName' ),
 968                                 array_keys( $this->mPrinter->getFinalParams() ?: array() )
 969                         );
 970                         $unusedParams = array_diff( $allParams, $paramsUsed, $printerParams );
 971                 } else {
 972                         $unusedParams = array_diff( $allParams, $paramsUsed );
 973                 }
 974
 975                 if ( count( $unusedParams ) ) {
 976                         $s = count( $unusedParams ) > 1 ? 's' : '';
 977                         $this->setWarning( "Unrecognized parameter$s: '" . implode( $unusedParams, "', '" ) . "'" );
 978                 }
 979         }
 980
 981         /**
 982          * Print results using the current printer
 983          *
 984          * @param $isError bool
 985          */
 986         protected function printResult( $isError ) {
 987                 global $wgDebugAPI;
 988                 if ( $wgDebugAPI !== false ) {
 989                         $this->setWarning( 'SECURITY WARNING: $wgDebugAPI is enabled' );
 990                 }
 991
 992                 $this->getResult()->cleanUpUTF8();
 993                 $printer = $this->mPrinter;
 994                 $printer->profileIn();
 995
 996                 /**
 997                  * If the help message is requested in the default (xmlfm) format,
 998                  * tell the printer not to escape ampersands so that our links do
 999                  * not break.
1000                  */
1001                 $isHelp = $isError || $this->mAction == 'help';
1002                 $printer->setUnescapeAmps( $isHelp && $printer->getFormat() == 'XML' && $printer->getIsHtml() );
1003
1004                 $printer->initPrinter( $isHelp );
1005
1006                 $printer->execute();
1007                 $printer->closePrinter();
1008                 $printer->profileOut();
1009         }
1010
1011         /**
1012          * @return bool
1013          */
1014         public function isReadMode() {
1015                 return false;
1016         }
1017
1018         /**
1019          * See ApiBase for description.
1020          *
1021          * @return array
1022          */
1023         public function getAllowedParams() {
1024                 return array(
1025                         'format' => array(
1026                                 ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
1027                                 ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'format' )
1028                         ),
1029                         'action' => array(
1030                                 ApiBase::PARAM_DFLT => 'help',
1031                                 ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'action' )
1032                         ),
1033                         'maxlag' => array(
1034                                 ApiBase::PARAM_TYPE => 'integer'
1035                         ),
1036                         'smaxage' => array(
1037                                 ApiBase::PARAM_TYPE => 'integer',
1038                                 ApiBase::PARAM_DFLT => 0
1039                         ),
1040                         'maxage' => array(
1041                                 ApiBase::PARAM_TYPE => 'integer',
1042                                 ApiBase::PARAM_DFLT => 0
1043                         ),
1044                         'requestid' => null,
1045                         'servedby' => false,
1046                         'origin' => null,
1047                 );
1048         }
1049
1050         /**
1051          * See ApiBase for description.
1052          *
1053          * @return array
1054          */
1055         public function getParamDescription() {
1056                 return array(
1057                         'format' => 'The format of the output',
1058                         'action' => 'What action you would like to perform. See below for module help',
1059                         'maxlag' => array(
1060                                 'Maximum lag can be used when MediaWiki is installed on a database replicated cluster.',
1061                                 'To save actions causing any more site replication lag, this parameter can make the client',
1062                                 'wait until the replication lag is less than the specified value.',
1063                                 'In case of a replag error, error code "maxlag" is returned, with the message like',
1064                                 '"Waiting for $host: $lag seconds lagged\n".',
1065                                 'See https://www.mediawiki.org/wiki/Manual:Maxlag_parameter for more information',
1066                         ),
1067                         'smaxage' => 'Set the s-maxage header to this many seconds. Errors are never cached',
1068                         'maxage' => 'Set the max-age header to this many seconds. Errors are never cached',
1069                         'requestid' => 'Request ID to distinguish requests. This will just be output back to you',
1070                         'servedby' => 'Include the hostname that served the request in the ' .
1071                                 'results. Unconditionally shown on error',
1072                         'origin' => array(
1073                                 'When accessing the API using a cross-domain AJAX request (CORS), set this to the',
1074                                 'originating domain. This must be included in any pre-flight request, and',
1075                                 'therefore must be part of the request URI (not the POST body). This must match',
1076                                 'one of the origins in the Origin: header exactly, so it has to be set to ',
1077                                 'something like http://en.wikipedia.org or https://meta.wikimedia.org . If this',
1078                                 'parameter does not match the Origin: header, a 403 response will be returned. If',
1079                                 'this parameter matches the Origin: header and the origin is whitelisted, an',
1080                                 'Access-Control-Allow-Origin header will be set.',
1081                         ),
1082                 );
1083         }
1084
1085         /**
1086          * See ApiBase for description.
1087          *
1088          * @return array
1089          */
1090         public function getDescription() {
1091                 return array(
1092                         '',
1093                         '',
1094                         '**********************************************************************************************',
1095                         '**                                                                                          **',
1096                         '**                This is an auto-generated MediaWiki API documentation page                **',
1097                         '**                                                                                          **',
1098                         '**                               Documentation and Examples:                                **',
1099                         '**                            https://www.mediawiki.org/wiki/API                            **',
1100                         '**                                                                                          **',
1101                         '**********************************************************************************************',
1102                         '',
1103                         'Status:                All features shown on this page should be working, but the API',
1104                         '                       is still in active development, and may change at any time.',
1105                         '                       Make sure to monitor our mailing list for any updates',
1106                         '',
1107                         'Erroneous requests:    When erroneous requests are sent to the API, a HTTP header will be sent',
1108                         '                       with the key "MediaWiki-API-Error" and then both the value of the',
1109                         '                       header and the error code sent back will be set to the same value',
1110                         '',
1111                         '                       In the case of an invalid action being passed, these will have a value',
1112                         '                       of "unknown_action"',
1113                         '',
1114                         '                       For more information see https://www.mediawiki.org' .
1115                                 '/wiki/API:Errors_and_warnings',
1116                         '',
1117                         'Documentation:         https://www.mediawiki.org/wiki/API:Main_page',
1118                         'FAQ                    https://www.mediawiki.org/wiki/API:FAQ',
1119                         'Mailing list:          https://lists.wikimedia.org/mailman/listinfo/mediawiki-api',
1120                         'Api Announcements:     https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce',
1121                         'Bugs & Requests:       https://bugzilla.wikimedia.org/buglist.cgi?component=API&' .
1122                                 'bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&order=bugs.delta_ts',
1123                         '',
1124                         '',
1125                         '',
1126                         '',
1127                         '',
1128                 );
1129         }
1130
1131         /**
1132          * @return array
1133          */
1134         public function getPossibleErrors() {
1135                 return array_merge( parent::getPossibleErrors(), array(
1136                         array( 'readonlytext' ),
1137                         array( 'code' => 'unknown_format', 'info' => 'Unrecognized format: format' ),
1138                         array( 'code' => 'unknown_action', 'info' => 'The API requires a valid action parameter' ),
1139                         array( 'code' => 'maxlag', 'info' => 'Waiting for host: x seconds lagged' ),
1140                         array( 'code' => 'maxlag', 'info' => 'Waiting for a database server: x seconds lagged' ),
1141                 ) );
1142         }
1143
1144         /**
1145          * Returns an array of strings with credits for the API
1146          * @return array
1147          */
1148         protected function getCredits() {
1149                 return array(
1150                         'API developers:',
1151                         '    Roan Kattouw - roan . kattouw @ gmail . com (lead developer Sep 2007-2009)',
1152                         '    Victor Vasiliev - vasilvv @ gmail . com',
1153                         '    Bryan Tong Minh - bryan . tongminh @ gmail . com',
1154                         '    Sam Reed - sam @ reedyboy . net',
1155                         '    Yuri Astrakhan - yuri . astrakhan @ gmail . com (creator, lead ' .
1156                                 'developer Sep 2006-Sep 2007, 2012-present)',
1157                         '',
1158                         'Please send your comments, suggestions and questions to mediawiki-api@lists.wikimedia.org',
1159                         'or file a bug report at https://bugzilla.wikimedia.org/'
1160                 );
1161         }
1162
1163         /**
1164          * Sets whether the pretty-printer should format *bold* and $italics$
1165          *
1166          * @param $help bool
1167          */
1168         public function setHelp( $help = true ) {
1169                 $this->mPrinter->setHelp( $help );
1170         }
1171
1172         /**
1173          * Override the parent to generate help messages for all available modules.
1174          *
1175          * @return string
1176          */
1177         public function makeHelpMsg() {
1178                 global $wgMemc, $wgAPICacheHelpTimeout;
1179                 $this->setHelp();
1180                 // Get help text from cache if present
1181                 $key = wfMemcKey( 'apihelp', $this->getModuleName(),
1182                         str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) ) );
1183                 if ( $wgAPICacheHelpTimeout > 0 ) {
1184                         $cached = $wgMemc->get( $key );
1185                         if ( $cached ) {
1186                                 return $cached;
1187                         }
1188                 }
1189                 $retval = $this->reallyMakeHelpMsg();
1190                 if ( $wgAPICacheHelpTimeout > 0 ) {
1191                         $wgMemc->set( $key, $retval, $wgAPICacheHelpTimeout );
1192                 }
1193
1194                 return $retval;
1195         }
1196
1197         /**
1198          * @return mixed|string
1199          */
1200         public function reallyMakeHelpMsg() {
1201                 $this->setHelp();
1202
1203                 // Use parent to make default message for the main module
1204                 $msg = parent::makeHelpMsg();
1205
1206                 $astriks = str_repeat( '*** ', 14 );
1207                 $msg .= "\n\n$astriks Modules  $astriks\n\n";
1208
1209                 foreach ( $this->mModuleMgr->getNames( 'action' ) as $name ) {
1210                         $module = $this->mModuleMgr->getModule( $name );
1211                         $msg .= self::makeHelpMsgHeader( $module, 'action' );
1212
1213                         $msg2 = $module->makeHelpMsg();
1214                         if ( $msg2 !== false ) {
1215                                 $msg .= $msg2;
1216                         }
1217                         $msg .= "\n";
1218                 }
1219
1220                 $msg .= "\n$astriks Permissions $astriks\n\n";
1221                 foreach ( self::$mRights as $right => $rightMsg ) {
1222                         $groups = User::getGroupsWithPermission( $right );
1223                         $msg .= "* " . $right . " *\n  " . wfMsgReplaceArgs( $rightMsg['msg'], $rightMsg['params'] ) .
1224                                 "\nGranted to:\n  " . str_replace( '*', 'all', implode( ', ', $groups ) ) . "\n\n";
1225                 }
1226
1227                 $msg .= "\n$astriks Formats  $astriks\n\n";
1228                 foreach ( $this->mModuleMgr->getNames( 'format' ) as $name ) {
1229                         $module = $this->mModuleMgr->getModule( $name );
1230                         $msg .= self::makeHelpMsgHeader( $module, 'format' );
1231                         $msg2 = $module->makeHelpMsg();
1232                         if ( $msg2 !== false ) {
1233                                 $msg .= $msg2;
1234                         }
1235                         $msg .= "\n";
1236                 }
1237
1238                 $msg .= "\n*** Credits: ***\n   " . implode( "\n   ", $this->getCredits() ) . "\n";
1239
1240                 return $msg;
1241         }
1242
1243         /**
1244          * @param $module ApiBase
1245          * @param string $paramName What type of request is this? e.g. action,
1246          *    query, list, prop, meta, format
1247          * @return string
1248          */
1249         public static function makeHelpMsgHeader( $module, $paramName ) {
1250                 $modulePrefix = $module->getModulePrefix();
1251                 if ( strval( $modulePrefix ) !== '' ) {
1252                         $modulePrefix = "($modulePrefix) ";
1253                 }
1254
1255                 return "* $paramName={$module->getModuleName()} $modulePrefix*";
1256         }
1257
1258         private $mCanApiHighLimits = null;
1259
1260         /**
1261          * Check whether the current user is allowed to use high limits
1262          * @return bool
1263          */
1264         public function canApiHighLimits() {
1265                 if ( !isset( $this->mCanApiHighLimits ) ) {
1266                         $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
1267                 }
1268
1269                 return $this->mCanApiHighLimits;
1270         }
1271
1272         /**
1273          * Check whether the user wants us to show version information in the API help
1274          * @return bool
1275          * @deprecated since 1.21, always returns false
1276          */
1277         public function getShowVersions() {
1278                 wfDeprecated( __METHOD__, '1.21' );
1279
1280                 return false;
1281         }
1282
1283         /**
1284          * Overrides to return this instance's module manager.
1285          * @return ApiModuleManager
1286          */
1287         public function getModuleManager() {
1288                 return $this->mModuleMgr;
1289         }
1290
1291         /**
1292          * Add or overwrite a module in this ApiMain instance. Intended for use by extending
1293          * classes who wish to add their own modules to their lexicon or override the
1294          * behavior of inherent ones.
1295          *
1296          * @deprecated since 1.21, Use getModuleManager()->addModule() instead.
1297          * @param string $name The identifier for this module.
1298          * @param $class ApiBase The class where this module is implemented.
1299          */
1300         protected function addModule( $name, $class ) {
1301                 $this->getModuleManager()->addModule( $name, 'action', $class );
1302         }
1303
1304         /**
1305          * Add or overwrite an output format for this ApiMain. Intended for use by extending
1306          * classes who wish to add to or modify current formatters.
1307          *
1308          * @deprecated since 1.21, Use getModuleManager()->addModule() instead.
1309          * @param string $name The identifier for this format.
1310          * @param $class ApiFormatBase The class implementing this format.
1311          */
1312         protected function addFormat( $name, $class ) {
1313                 $this->getModuleManager()->addModule( $name, 'format', $class );
1314         }
1315
1316         /**
1317          * Get the array mapping module names to class names
1318          * @deprecated since 1.21, Use getModuleManager()'s methods instead.
1319          * @return array
1320          */
1321         function getModules() {
1322                 return $this->getModuleManager()->getNamesWithClasses( 'action' );
1323         }
1324
1325         /**
1326          * Returns the list of supported formats in form ( 'format' => 'ClassName' )
1327          *
1328          * @since 1.18
1329          * @deprecated since 1.21, Use getModuleManager()'s methods instead.
1330          * @return array
1331          */
1332         public function getFormats() {
1333                 return $this->getModuleManager()->getNamesWithClasses( 'format' );
1334         }
1335 }
1336
1337 /**
1338  * This exception will be thrown when dieUsage is called to stop module execution.
1339  * The exception handling code will print a help screen explaining how this API may be used.
1340  *
1341  * @ingroup API
1342  */
1343 class UsageException extends MWException {
1344
1345         private $mCodestr;
1346
1347         /**
1348          * @var null|array
1349          */
1350         private $mExtraData;
1351
1352         /**
1353          * @param $message string
1354          * @param $codestr string
1355          * @param $code int
1356          * @param $extradata array|null
1357          */
1358         public function __construct( $message, $codestr, $code = 0, $extradata = null ) {
1359                 parent::__construct( $message, $code );
1360                 $this->mCodestr = $codestr;
1361                 $this->mExtraData = $extradata;
1362         }
1363
1364         /**
1365          * @return string
1366          */
1367         public function getCodeString() {
1368                 return $this->mCodestr;
1369         }
1370
1371         /**
1372          * @return array
1373          */
1374         public function getMessageArray() {
1375                 $result = array(
1376                         'code' => $this->mCodestr,
1377                         'info' => $this->getMessage()
1378                 );
1379                 if ( is_array( $this->mExtraData ) ) {
1380                         $result = array_merge( $result, $this->mExtraData );
1381                 }
1382
1383                 return $result;
1384         }
1385
1386         /**
1387          * @return string
1388          */
1389         public function __toString() {
1390                 return "{$this->getCodeString()}: {$this->getMessage()}";
1391         }
1392 }