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                 'systemblockedtext' => 'blocked',
 130                 'titleprotected' => 'protectedtitle',
 131                 'undo-failure' => 'undofailure',
 132                 'userrights-nodatabase' => 'nosuchdatabase',
 133                 'userrights-no-interwiki' => 'nointerwikiuserrights',
 134         ];
 135
 136         protected $apiCode = null;
 137         protected $apiData = [];
 138
 139         public function getApiCode() {
 140                 if ( $this->apiCode === null ) {
 141                         $key = $this->getKey();
 142                         if ( isset( self::$messageMap[$key] ) ) {
 143                                 $this->apiCode = self::$messageMap[$key];
 144                         } elseif ( $key === 'apierror-missingparam' ) {
 145                                 /// @todo: Kill this case along with ApiBase::$messageMap
 146                                 $this->apiCode = 'no' . $this->getParams()[0];
 147                         } elseif ( substr( $key, 0, 8 ) === 'apiwarn-' ) {
 148                                 $this->apiCode = substr( $key, 8 );
 149                         } elseif ( substr( $key, 0, 9 ) === 'apierror-' ) {
 150                                 $this->apiCode = substr( $key, 9 );
 151                         } else {
 152                                 $this->apiCode = $key;
 153                         }
 154                 }
 155                 return $this->apiCode;
 156         }
 157
 158         public function setApiCode( $code, array $data = null ) {
 159                 if ( $code !== null && !( is_string( $code ) && $code !== '' ) ) {
 160                         throw new InvalidArgumentException( "Invalid code \"$code\"" );
 161                 }
 162
 163                 $this->apiCode = $code;
 164                 if ( $data !== null ) {
 165                         $this->setApiData( $data );
 166                 }
 167         }
 168
 169         public function getApiData() {
 170                 return $this->apiData;
 171         }
 172
 173         public function setApiData( array $data ) {
 174                 $this->apiData = $data;
 175         }
 176
 177         public function serialize() {
 178                 return serialize( [
 179                         'parent' => parent::serialize(),
 180                         'apiCode' => $this->apiCode,
 181                         'apiData' => $this->apiData,
 182                 ] );
 183         }
 184
 185         public function unserialize( $serialized ) {
 186                 $data = unserialize( $serialized );
 187                 parent::unserialize( $data['parent'] );
 188                 $this->apiCode = $data['apiCode'];
 189                 $this->apiData = $data['apiData'];
 190         }
 191 }
 192
 193 /**
 194  * Extension of Message implementing IApiMessage
 195  * @since 1.25
 196  * @ingroup API
 197  */
 198 class ApiMessage extends Message implements IApiMessage {
 199         use ApiMessageTrait;
 200
 201         /**
 202          * Create an IApiMessage for the message
 203          *
 204          * This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
 205          * $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
 206          *
 207          * @param Message|RawMessage|array|string $msg
 208          * @param string|null $code
 209          * @param array|null $data
 210          * @return IApiMessage
 211          */
 212         public static function create( $msg, $code = null, array $data = null ) {
 213                 if ( is_array( $msg ) ) {
 214                         // From StatusValue
 215                         if ( isset( $msg['message'] ) ) {
 216                                 if ( isset( $msg['params'] ) ) {
 217                                         $msg = array_merge( [ $msg['message'] ], $msg['params'] );
 218                                 } else {
 219                                         $msg = [ $msg['message'] ];
 220                                 }
 221                         }
 222
 223                         // Weirdness that comes in sometimes, including the above
 224                         if ( $msg[0] instanceof MessageSpecifier ) {
 225                                 $msg = $msg[0];
 226                         }
 227                 }
 228
 229                 if ( $msg instanceof IApiMessage ) {
 230                         return $msg;
 231                 } elseif ( $msg instanceof RawMessage ) {
 232                         return new ApiRawMessage( $msg, $code, $data );
 233                 } else {
 234                         return new ApiMessage( $msg, $code, $data );
 235                 }
 236         }
 237
 238         /**
 239          * @param Message|string|array $msg
 240          *  - Message: is cloned
 241          *  - array: first element is $key, rest are $params to Message::__construct
 242          *  - string: passed to Message::__construct
 243          * @param string|null $code
 244          * @param array|null $data
 245          */
 246         public function __construct( $msg, $code = null, array $data = null ) {
 247                 if ( $msg instanceof Message ) {
 248                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 249                                 if ( isset( $msg->$key ) ) {
 250                                         $this->$key = $msg->$key;
 251                                 }
 252                         }
 253                 } elseif ( is_array( $msg ) ) {
 254                         $key = array_shift( $msg );
 255                         parent::__construct( $key, $msg );
 256                 } else {
 257                         parent::__construct( $msg );
 258                 }
 259                 $this->setApiCode( $code, $data );
 260         }
 261 }
 262
 263 /**
 264  * Extension of RawMessage implementing IApiMessage
 265  * @since 1.25
 266  * @ingroup API
 267  */
 268 class ApiRawMessage extends RawMessage implements IApiMessage {
 269         use ApiMessageTrait;
 270
 271         /**
 272          * @param RawMessage|string|array $msg
 273          *  - RawMessage: is cloned
 274          *  - array: first element is $key, rest are $params to RawMessage::__construct
 275          *  - string: passed to RawMessage::__construct
 276          * @param string|null $code
 277          * @param array|null $data
 278          */
 279         public function __construct( $msg, $code = null, array $data = null ) {
 280                 if ( $msg instanceof RawMessage ) {
 281                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 282                                 if ( isset( $msg->$key ) ) {
 283                                         $this->$key = $msg->$key;
 284                                 }
 285                         }
 286                 } elseif ( is_array( $msg ) ) {
 287                         $key = array_shift( $msg );
 288                         parent::__construct( $key, $msg );
 289                 } else {
 290                         parent::__construct( $msg );
 291                 }
 292                 $this->setApiCode( $code, $data );
 293         }
 294 }