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          * The message key is often sufficient, but sometimes there are multiple
  40          * messages used for what is really the same underlying condition (e.g.
  41          * badaccess-groups and badaccess-group0)
  42          * @return string
  43          */
  44         public function getApiCode();
  45
  46         /**
  47          * Returns additional machine-readable data about the error condition
  48          * @return array
  49          */
  50         public function getApiData();
  51
  52         /**
  53          * Sets the machine-readable code for use by the API
  54          * @param string|null $code If null, the message key should be returned by self::getApiCode()
  55          * @param array|null $data If non-null, passed to self::setApiData()
  56          */
  57         public function setApiCode( $code, array $data = null );
  58
  59         /**
  60          * Sets additional machine-readable data about the error condition
  61          * @param array $data
  62          */
  63         public function setApiData( array $data );
  64 }
  65
  66 /**
  67  * Extension of Message implementing IApiMessage
  68  * @since 1.25
  69  * @ingroup API
  70  * @todo: Would be nice to use a Trait here to avoid code duplication
  71  */
  72 class ApiMessage extends Message implements IApiMessage {
  73         protected $apiCode = null;
  74         protected $apiData = array();
  75
  76         /**
  77          * Create an IApiMessage for the message
  78          *
  79          * This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
  80          * $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
  81          *
  82          * @param Message|RawMessage|array|string $msg
  83          * @param string|null $code
  84          * @param array|null $data
  85          * @return ApiMessage
  86          */
  87         public static function create( $msg, $code = null, array $data = null ) {
  88                 if ( $msg instanceof IApiMessage ) {
  89                         return $msg;
  90                 } elseif ( $msg instanceof RawMessage ) {
  91                         return new ApiRawMessage( $msg, $code, $data );
  92                 } else {
  93                         return new ApiMessage( $msg, $code, $data );
  94                 }
  95         }
  96
  97         /**
  98          * @param Message|string|array $msg
  99          *  - Message: is cloned
 100          *  - array: first element is $key, rest are $params to Message::__construct
 101          *  - string: passed to Message::__construct
 102          * @param string|null $code
 103          * @param array|null $data
 104          * @return ApiMessage
 105          */
 106         public function __construct( $msg, $code = null, array $data = null ) {
 107                 if ( $msg instanceof Message ) {
 108                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 109                                 if ( isset( $msg->$key ) ) {
 110                                         $this->$key = $msg->$key;
 111                                 }
 112                         }
 113                 } elseif ( is_array( $msg ) ) {
 114                         $key = array_shift( $msg );
 115                         parent::__construct( $key, $msg );
 116                 } else {
 117                         parent::__construct( $msg );
 118                 }
 119                 $this->apiCode = $code;
 120                 $this->apiData = (array)$data;
 121         }
 122
 123         public function getApiCode() {
 124                 return $this->apiCode === null ? $this->getKey() : $this->apiCode;
 125         }
 126
 127         public function setApiCode( $code, array $data = null ) {
 128                 $this->apiCode = $code;
 129                 if ( $data !== null ) {
 130                         $this->setApiData( $data );
 131                 }
 132         }
 133
 134         public function getApiData() {
 135                 return $this->apiData;
 136         }
 137
 138         public function setApiData( array $data ) {
 139                 $this->apiData = $data;
 140         }
 141
 142         public function serialize() {
 143                 return serialize( array(
 144                         'parent' => parent::serialize(),
 145                         'apiCode' => $this->apiCode,
 146                         'apiData' => $this->apiData,
 147                 ) );
 148         }
 149
 150         public function unserialize( $serialized ) {
 151                 $data = unserialize( $serialized );
 152                 parent::unserialize( $data['parent'] );
 153                 $this->apiCode = $data['apiCode'];
 154                 $this->apiData = $data['apiData'];
 155         }
 156 }
 157
 158 /**
 159  * Extension of RawMessage implementing IApiMessage
 160  * @since 1.25
 161  * @ingroup API
 162  * @todo: Would be nice to use a Trait here to avoid code duplication
 163  */
 164 class ApiRawMessage extends RawMessage implements IApiMessage {
 165         protected $apiCode = null;
 166         protected $apiData = array();
 167
 168         /**
 169          * @param RawMessage|string|array $msg
 170          *  - RawMessage: is cloned
 171          *  - array: first element is $key, rest are $params to RawMessage::__construct
 172          *  - string: passed to RawMessage::__construct
 173          * @param string|null $code
 174          * @param array|null $data
 175          */
 176         public function __construct( $msg, $code = null, array $data = null ) {
 177                 if ( $msg instanceof RawMessage ) {
 178                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 179                                 if ( isset( $msg->$key ) ) {
 180                                         $this->$key = $msg->$key;
 181                                 }
 182                         }
 183                 } elseif ( is_array( $msg ) ) {
 184                         $key = array_shift( $msg );
 185                         parent::__construct( $key, $msg );
 186                 } else {
 187                         parent::__construct( $msg );
 188                 }
 189                 $this->apiCode = $code;
 190                 $this->apiData = (array)$data;
 191         }
 192
 193         public function getApiCode() {
 194                 return $this->apiCode === null ? $this->getKey() : $this->apiCode;
 195         }
 196
 197         public function setApiCode( $code, array $data = null ) {
 198                 $this->apiCode = $code;
 199                 if ( $data !== null ) {
 200                         $this->setApiData( $data );
 201                 }
 202         }
 203
 204         public function getApiData() {
 205                 return $this->apiData;
 206         }
 207
 208         public function setApiData( array $data ) {
 209                 $this->apiData = $data;
 210         }
 211
 212         public function serialize() {
 213                 return serialize( array(
 214                         'parent' => parent::serialize(),
 215                         'apiCode' => $this->apiCode,
 216                         'apiData' => $this->apiData,
 217                 ) );
 218         }
 219
 220         public function unserialize( $serialized ) {
 221                 $data = unserialize( $serialized );
 222                 parent::unserialize( $data['parent'] );
 223                 $this->apiCode = $data['apiCode'];
 224                 $this->apiData = $data['apiData'];
 225         }
 226 }