includes/api/ApiMessage.php

   1 <?php
   2 /**
   3  * Defines an interface for messages with additional machine-readable data for
   4  * use by the API, and provides concrete implementations of that interface.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @file
  22  */
  23
  24 /**
  25  * Interface for messages with machine-readable data for use by the API
  26  *
  27  * The idea is that it's a Message that has some extra data for the API to use when interpreting it
  28  * as an error (or, in the future, as a warning). Internals of MediaWiki often use messages (or
  29  * message keys, or Status objects containing messages) to pass information about errors to the user
  30  * (see e.g. Title::getUserPermissionsErrors()) and the API has to make do with that.
  31  *
  32  * @since 1.25
  33  * @ingroup API
  34  */
  35 interface IApiMessage extends MessageSpecifier {
  36         /**
  37          * Returns a machine-readable code for use by the API
  38          *
  39          * If no code was specifically set, the message key is used as the code
  40          * after removing "apiwarn-" or "apierror-" prefixes and applying
  41          * backwards-compatibility mappings.
  42          *
  43          * @return string
  44          */
  45         public function getApiCode();
  46
  47         /**
  48          * Returns additional machine-readable data about the error condition
  49          * @return array
  50          */
  51         public function getApiData();
  52
  53         /**
  54          * Sets the machine-readable code for use by the API
  55          * @param string|null $code If null, uses the default (see self::getApiCode())
  56          * @param array|null $data If non-null, passed to self::setApiData()
  57          */
  58         public function setApiCode( $code, array $data = null );
  59
  60         /**
  61          * Sets additional machine-readable data about the error condition
  62          * @param array $data
  63          */
  64         public function setApiData( array $data );
  65 }
  66
  67 /**
  68  * Trait to implement the IApiMessage interface for Message subclasses
  69  * @since 1.27
  70  * @ingroup API
  71  */
  72 trait ApiMessageTrait {
  73
  74         /**
  75          * Compatibility code mappings for various MW messages.
  76          * @todo Ideally anything relying on this should be changed to use ApiMessage.
  77          */
  78         protected static $messageMap = [
  79                 'actionthrottledtext' => 'ratelimited',
  80                 'autoblockedtext' => 'autoblocked',
  81                 'badaccess-group0' => 'permissiondenied',
  82                 'badaccess-groups' => 'permissiondenied',
  83                 'badipaddress' => 'invalidip',
  84                 'blankpage' => 'emptypage',
  85                 'blockedtext' => 'blocked',
  86                 'cannotdelete' => 'cantdelete',
  87                 'cannotundelete' => 'cantundelete',
  88                 'cantmove-titleprotected' => 'protectedtitle',
  89                 'cantrollback' => 'onlyauthor',
  90                 'confirmedittext' => 'confirmemail',
  91                 'content-not-allowed-here' => 'contentnotallowedhere',
  92                 'deleteprotected' => 'cantedit',
  93                 'delete-toobig' => 'bigdelete',
  94                 'edit-conflict' => 'editconflict',
  95                 'imagenocrossnamespace' => 'nonfilenamespace',
  96                 'imagetypemismatch' => 'filetypemismatch',
  97                 'importbadinterwiki' => 'badinterwiki',
  98                 'importcantopen' => 'cantopenfile',
  99                 'import-noarticle' => 'badinterwiki',
 100                 'importnofile' => 'nofile',
 101                 'importuploaderrorpartial' => 'partialupload',
 102                 'importuploaderrorsize' => 'filetoobig',
 103                 'importuploaderrortemp' => 'notempdir',
 104                 'ipb_already_blocked' => 'alreadyblocked',
 105                 'ipb_blocked_as_range' => 'blockedasrange',
 106                 'ipb_cant_unblock' => 'cantunblock',
 107                 'ipb_expiry_invalid' => 'invalidexpiry',
 108                 'ip_range_invalid' => 'invalidrange',
 109                 'mailnologin' => 'cantsend',
 110                 'markedaspatrollederror-noautopatrol' => 'noautopatrol',
 111                 'movenologintext' => 'cantmove-anon',
 112                 'movenotallowed' => 'cantmove',
 113                 'movenotallowedfile' => 'cantmovefile',
 114                 'namespaceprotected' => 'protectednamespace',
 115                 'nocreate-loggedin' => 'cantcreate',
 116                 'nocreatetext' => 'cantcreate-anon',
 117                 'noname' => 'invaliduser',
 118                 'nosuchusershort' => 'nosuchuser',
 119                 'notanarticle' => 'missingtitle',
 120                 'nouserspecified' => 'invaliduser',
 121                 'ns-specialprotected' => 'unsupportednamespace',
 122                 'protect-cantedit' => 'cantedit',
 123                 'protectedinterface' => 'protectednamespace-interface',
 124                 'protectedpagetext' => 'protectedpage',
 125                 'range_block_disabled' => 'rangedisabled',
 126                 'rcpatroldisabled' => 'patroldisabled',
 127                 'readonlytext' => 'readonly',
 128                 'sessionfailure' => 'badtoken',
 129                 'titleprotected' => 'protectedtitle',
 130                 'undo-failure' => 'undofailure',
 131                 'userrights-nodatabase' => 'nosuchdatabase',
 132                 'userrights-no-interwiki' => 'nointerwikiuserrights',
 133         ];
 134
 135         protected $apiCode = null;
 136         protected $apiData = [];
 137
 138         public function getApiCode() {
 139                 if ( $this->apiCode === null ) {
 140                         $key = $this->getKey();
 141                         if ( isset( self::$messageMap[$key] ) ) {
 142                                 $this->apiCode = self::$messageMap[$key];
 143                         } elseif ( $key === 'apierror-missingparam' ) {
 144                                 /// @todo: Kill this case along with ApiBase::$messageMap
 145                                 $this->apiCode = 'no' . $this->getParams()[0];
 146                         } elseif ( substr( $key, 0, 8 ) === 'apiwarn-' ) {
 147                                 $this->apiCode = substr( $key, 8 );
 148                         } elseif ( substr( $key, 0, 9 ) === 'apierror-' ) {
 149                                 $this->apiCode = substr( $key, 9 );
 150                         } else {
 151                                 $this->apiCode = $key;
 152                         }
 153                 }
 154                 return $this->apiCode;
 155         }
 156
 157         public function setApiCode( $code, array $data = null ) {
 158                 if ( $code !== null && !( is_string( $code ) && $code !== '' ) ) {
 159                         throw new InvalidArgumentException( "Invalid code \"$code\"" );
 160                 }
 161
 162                 $this->apiCode = $code;
 163                 if ( $data !== null ) {
 164                         $this->setApiData( $data );
 165                 }
 166         }
 167
 168         public function getApiData() {
 169                 return $this->apiData;
 170         }
 171
 172         public function setApiData( array $data ) {
 173                 $this->apiData = $data;
 174         }
 175
 176         public function serialize() {
 177                 return serialize( [
 178                         'parent' => parent::serialize(),
 179                         'apiCode' => $this->apiCode,
 180                         'apiData' => $this->apiData,
 181                 ] );
 182         }
 183
 184         public function unserialize( $serialized ) {
 185                 $data = unserialize( $serialized );
 186                 parent::unserialize( $data['parent'] );
 187                 $this->apiCode = $data['apiCode'];
 188                 $this->apiData = $data['apiData'];
 189         }
 190 }
 191
 192 /**
 193  * Extension of Message implementing IApiMessage
 194  * @since 1.25
 195  * @ingroup API
 196  */
 197 class ApiMessage extends Message implements IApiMessage {
 198         use ApiMessageTrait;
 199
 200         /**
 201          * Create an IApiMessage for the message
 202          *
 203          * This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
 204          * $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
 205          *
 206          * @param Message|RawMessage|array|string $msg
 207          * @param string|null $code
 208          * @param array|null $data
 209          * @return IApiMessage
 210          */
 211         public static function create( $msg, $code = null, array $data = null ) {
 212                 if ( is_array( $msg ) ) {
 213                         // From StatusValue
 214                         if ( isset( $msg['message'] ) ) {
 215                                 if ( isset( $msg['params'] ) ) {
 216                                         $msg = array_merge( [ $msg['message'] ], $msg['params'] );
 217                                 } else {
 218                                         $msg = [ $msg['message'] ];
 219                                 }
 220                         }
 221
 222                         // Weirdness that comes in sometimes, including the above
 223                         if ( $msg[0] instanceof MessageSpecifier ) {
 224                                 $msg = $msg[0];
 225                         }
 226                 }
 227
 228                 if ( $msg instanceof IApiMessage ) {
 229                         return $msg;
 230                 } elseif ( $msg instanceof RawMessage ) {
 231                         return new ApiRawMessage( $msg, $code, $data );
 232                 } else {
 233                         return new ApiMessage( $msg, $code, $data );
 234                 }
 235         }
 236
 237         /**
 238          * @param Message|string|array $msg
 239          *  - Message: is cloned
 240          *  - array: first element is $key, rest are $params to Message::__construct
 241          *  - string: passed to Message::__construct
 242          * @param string|null $code
 243          * @param array|null $data
 244          */
 245         public function __construct( $msg, $code = null, array $data = null ) {
 246                 if ( $msg instanceof Message ) {
 247                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 248                                 if ( isset( $msg->$key ) ) {
 249                                         $this->$key = $msg->$key;
 250                                 }
 251                         }
 252                 } elseif ( is_array( $msg ) ) {
 253                         $key = array_shift( $msg );
 254                         parent::__construct( $key, $msg );
 255                 } else {
 256                         parent::__construct( $msg );
 257                 }
 258                 $this->setApiCode( $code, $data );
 259         }
 260 }
 261
 262 /**
 263  * Extension of RawMessage implementing IApiMessage
 264  * @since 1.25
 265  * @ingroup API
 266  */
 267 class ApiRawMessage extends RawMessage implements IApiMessage {
 268         use ApiMessageTrait;
 269
 270         /**
 271          * @param RawMessage|string|array $msg
 272          *  - RawMessage: is cloned
 273          *  - array: first element is $key, rest are $params to RawMessage::__construct
 274          *  - string: passed to RawMessage::__construct
 275          * @param string|null $code
 276          * @param array|null $data
 277          */
 278         public function __construct( $msg, $code = null, array $data = null ) {
 279                 if ( $msg instanceof RawMessage ) {
 280                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 281                                 if ( isset( $msg->$key ) ) {
 282                                         $this->$key = $msg->$key;
 283                                 }
 284                         }
 285                 } elseif ( is_array( $msg ) ) {
 286                         $key = array_shift( $msg );
 287                         parent::__construct( $key, $msg );
 288                 } else {
 289                         parent::__construct( $msg );
 290                 }
 291                 $this->setApiCode( $code, $data );
 292         }
 293 }