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  * Trait to implement the IApiMessage interface for Message subclasses
  68  * @since 1.27
  69  * @ingroup API
  70  */
  71 trait ApiMessageTrait {
  72         protected $apiCode = null;
  73         protected $apiData = [];
  74
  75         public function getApiCode() {
  76                 return $this->apiCode === null ? $this->getKey() : $this->apiCode;
  77         }
  78
  79         public function setApiCode( $code, array $data = null ) {
  80                 $this->apiCode = $code;
  81                 if ( $data !== null ) {
  82                         $this->setApiData( $data );
  83                 }
  84         }
  85
  86         public function getApiData() {
  87                 return $this->apiData;
  88         }
  89
  90         public function setApiData( array $data ) {
  91                 $this->apiData = $data;
  92         }
  93
  94         public function serialize() {
  95                 return serialize( [
  96                         'parent' => parent::serialize(),
  97                         'apiCode' => $this->apiCode,
  98                         'apiData' => $this->apiData,
  99                 ] );
 100         }
 101
 102         public function unserialize( $serialized ) {
 103                 $data = unserialize( $serialized );
 104                 parent::unserialize( $data['parent'] );
 105                 $this->apiCode = $data['apiCode'];
 106                 $this->apiData = $data['apiData'];
 107         }
 108 }
 109
 110 /**
 111  * Extension of Message implementing IApiMessage
 112  * @since 1.25
 113  * @ingroup API
 114  */
 115 class ApiMessage extends Message implements IApiMessage {
 116         use ApiMessageTrait;
 117
 118         /**
 119          * Create an IApiMessage for the message
 120          *
 121          * This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
 122          * $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
 123          *
 124          * @param Message|RawMessage|array|string $msg
 125          * @param string|null $code
 126          * @param array|null $data
 127          * @return ApiMessage
 128          */
 129         public static function create( $msg, $code = null, array $data = null ) {
 130                 if ( $msg instanceof IApiMessage ) {
 131                         return $msg;
 132                 } elseif ( $msg instanceof RawMessage ) {
 133                         return new ApiRawMessage( $msg, $code, $data );
 134                 } else {
 135                         return new ApiMessage( $msg, $code, $data );
 136                 }
 137         }
 138
 139         /**
 140          * @param Message|string|array $msg
 141          *  - Message: is cloned
 142          *  - array: first element is $key, rest are $params to Message::__construct
 143          *  - string: passed to Message::__construct
 144          * @param string|null $code
 145          * @param array|null $data
 146          * @return ApiMessage
 147          */
 148         public function __construct( $msg, $code = null, array $data = null ) {
 149                 if ( $msg instanceof Message ) {
 150                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 151                                 if ( isset( $msg->$key ) ) {
 152                                         $this->$key = $msg->$key;
 153                                 }
 154                         }
 155                 } elseif ( is_array( $msg ) ) {
 156                         $key = array_shift( $msg );
 157                         parent::__construct( $key, $msg );
 158                 } else {
 159                         parent::__construct( $msg );
 160                 }
 161                 $this->apiCode = $code;
 162                 $this->apiData = (array)$data;
 163         }
 164 }
 165
 166 /**
 167  * Extension of RawMessage implementing IApiMessage
 168  * @since 1.25
 169  * @ingroup API
 170  */
 171 class ApiRawMessage extends RawMessage implements IApiMessage {
 172         use ApiMessageTrait;
 173
 174         /**
 175          * @param RawMessage|string|array $msg
 176          *  - RawMessage: is cloned
 177          *  - array: first element is $key, rest are $params to RawMessage::__construct
 178          *  - string: passed to RawMessage::__construct
 179          * @param string|null $code
 180          * @param array|null $data
 181          */
 182         public function __construct( $msg, $code = null, array $data = null ) {
 183                 if ( $msg instanceof RawMessage ) {
 184                         foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
 185                                 if ( isset( $msg->$key ) ) {
 186                                         $this->$key = $msg->$key;
 187                                 }
 188                         }
 189                 } elseif ( is_array( $msg ) ) {
 190                         $key = array_shift( $msg );
 191                         parent::__construct( $key, $msg );
 192                 } else {
 193                         parent::__construct( $msg );
 194                 }
 195                 $this->apiCode = $code;
 196                 $this->apiData = (array)$data;
 197         }
 198 }