includes/api/ApiUsageException.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 /**
  22  * Exception used to abort API execution with an error
  23  *
  24  * If possible, use ApiBase::dieWithError() instead of throwing this directly.
  25  *
  26  * @ingroup API
  27  * @note This currently extends UsageException for backwards compatibility, so
  28  *  all the existing code that catches UsageException won't break when stuff
  29  *  starts throwing ApiUsageException. Eventually UsageException will go away
  30  *  and this will (probably) extend MWException directly.
  31  */
  32 class ApiUsageException extends UsageException implements ILocalizedException {
  33
  34         protected $modulePath;
  35         protected $status;
  36
  37         /**
  38          * @param ApiBase|null $module API module responsible for the error, if known
  39          * @param StatusValue $status Status holding errors
  40          * @param int $httpCode HTTP error code to use
  41          */
  42         public function __construct(
  43                 ApiBase $module = null, StatusValue $status, $httpCode = 0
  44         ) {
  45                 if ( $status->isOK() ) {
  46                         throw new InvalidArgumentException( __METHOD__ . ' requires a fatal Status' );
  47                 }
  48
  49                 $this->modulePath = $module ? $module->getModulePath() : null;
  50                 $this->status = $status;
  51
  52                 // Bug T46111: Messages in the log files should be in English and not
  53                 // customized by the local wiki.
  54                 $enMsg = clone $this->getApiMessage();
  55                 $enMsg->inLanguage( 'en' )->useDatabase( false );
  56                 parent::__construct(
  57                         ApiErrorFormatter::stripMarkup( $enMsg->text() ),
  58                         $enMsg->getApiCode(),
  59                         $httpCode,
  60                         $enMsg->getApiData()
  61                 );
  62         }
  63
  64         /**
  65          * @param ApiBase|null $module API module responsible for the error, if known
  66          * @param string|array|Message $msg See ApiMessage::create()
  67          * @param string|null $code See ApiMessage::create()
  68          * @param array|null $data See ApiMessage::create()
  69          * @param int $httpCode HTTP error code to use
  70          * @return static
  71          */
  72         public static function newWithMessage(
  73                 ApiBase $module = null, $msg, $code = null, $data = null, $httpCode = 0
  74         ) {
  75                 return new static(
  76                         $module,
  77                         StatusValue::newFatal( ApiMessage::create( $msg, $code, $data ) ),
  78                         $httpCode
  79                 );
  80         }
  81
  82         /**
  83          * @return ApiMessage
  84          */
  85         private function getApiMessage() {
  86                 $errors = $this->status->getErrorsByType( 'error' );
  87                 if ( !$errors ) {
  88                         $errors = $this->status->getErrors();
  89                 }
  90                 if ( !$errors ) {
  91                         $msg = new ApiMessage( 'apierror-unknownerror-nocode', 'unknownerror' );
  92                 } else {
  93                         $msg = ApiMessage::create( $errors[0] );
  94                 }
  95                 return $msg;
  96         }
  97
  98         /**
  99          * Fetch the responsible module name
 100          * @return string|null
 101          */
 102         public function getModulePath() {
 103                 return $this->modulePath;
 104         }
 105
 106         /**
 107          * Fetch the error status
 108          * @return StatusValue
 109          */
 110         public function getStatusValue() {
 111                 return $this->status;
 112         }
 113
 114         /**
 115          * @deprecated Do not use. This only exists here because UsageException is in
 116          *  the inheritance chain for backwards compatibility.
 117          * @inheritDoc
 118          */
 119         public function getCodeString() {
 120                 wfDeprecated( __METHOD__, '1.29' );
 121                 return $this->getApiMessage()->getApiCode();
 122         }
 123
 124         /**
 125          * @deprecated Do not use. This only exists here because UsageException is in
 126          *  the inheritance chain for backwards compatibility.
 127          * @inheritDoc
 128          */
 129         public function getMessageArray() {
 130                 wfDeprecated( __METHOD__, '1.29' );
 131                 $enMsg = clone $this->getApiMessage();
 132                 $enMsg->inLanguage( 'en' )->useDatabase( false );
 133
 134                 return [
 135                         'code' => $enMsg->getApiCode(),
 136                         'info' => ApiErrorFormatter::stripMarkup( $enMsg->text() ),
 137                 ] + $enMsg->getApiData();
 138         }
 139
 140         /**
 141          * @inheritDoc
 142          */
 143         public function getMessageObject() {
 144                 return Status::wrap( $this->status )->getMessage();
 145         }
 146
 147         /**
 148          * @return string
 149          */
 150         public function __toString() {
 151                 $enMsg = clone $this->getApiMessage();
 152                 $enMsg->inLanguage( 'en' )->useDatabase( false );
 153                 $text = ApiErrorFormatter::stripMarkup( $enMsg->text() );
 154
 155                 return get_class( $this ) . ": {$enMsg->getApiCode()}: {$text} "
 156                         . "in {$this->getFile()}:{$this->getLine()}\n"
 157                         . "Stack trace:\n{$this->getTraceAsString()}";
 158         }
 159
 160 }