3 * Defines an interface for messages with additional machine-readable data for
4 * use by the API, and provides concrete implementations of that interface.
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.
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.
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
25 * Interface for messages with machine-readable data for use by the API
29 interface IApiMessage
extends MessageSpecifier
{
31 * Returns a machine-readable code for use by the API
33 * The message key is often sufficient, but sometimes there are multiple
34 * messages used for what is really the same underlying condition (e.g.
35 * badaccess-groups and badaccess-group0)
38 public function getApiCode();
41 * Returns additional machine-readable data about the error condition
44 public function getApiData();
47 * Sets the machine-readable code for use by the API
48 * @param string|null $code If null, the message key should be returned by self::getApiCode()
49 * @param array|null $data If non-null, passed to self::setApiData()
51 public function setApiCode( $code, array $data = null );
54 * Sets additional machine-readable data about the error condition
57 public function setApiData( array $data );
61 * Extension of Message implementing IApiMessage
64 * @todo: Would be nice to use a Trait here to avoid code duplication
66 class ApiMessage
extends Message
implements IApiMessage
{
67 protected $apiCode = null;
68 protected $apiData = array();
71 * Create an IApiMessage for the message
73 * This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
74 * $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
76 * @param Message|RawMessage|array|string $msg
77 * @param string|null $code
78 * @param array|null $data
81 public static function create( $msg, $code = null, array $data = null ) {
82 if ( $msg instanceof IApiMessage
) {
84 } elseif ( $msg instanceof RawMessage
) {
85 return new ApiRawMessage( $msg, $code, $data );
87 return new ApiMessage( $msg, $code, $data );
92 * @param Message|string|array $msg
93 * - Message: is cloned
94 * - array: first element is $key, rest are $params to Message::__construct
95 * - string: passed to Message::__construct
96 * @param string|null $code
97 * @param array|null $data
100 public function __construct( $msg, $code = null, array $data = null ) {
101 if ( $msg instanceof Message
) {
102 foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
103 if ( isset( $msg->$key ) ) {
104 $this->$key = $msg->$key;
107 } elseif ( is_array( $msg ) ) {
108 $key = array_shift( $msg );
109 parent
::__construct( $key, $msg );
111 parent
::__construct( $msg );
113 $this->apiCode
= $code;
114 $this->apiData
= (array)$data;
117 public function getApiCode() {
118 return $this->apiCode
=== null ?
$this->getKey() : $this->apiCode
;
121 public function setApiCode( $code, array $data = null ) {
122 $this->apiCode
= $code;
123 if ( $data !== null ) {
124 $this->setApiData( $data );
128 public function getApiData() {
129 return $this->apiData
;
132 public function setApiData( array $data ) {
133 $this->apiData
= $data;
138 * Extension of RawMessage implementing IApiMessage
141 * @todo: Would be nice to use a Trait here to avoid code duplication
143 class ApiRawMessage
extends RawMessage
implements IApiMessage
{
144 protected $apiCode = null;
145 protected $apiData = array();
148 * @param RawMessage|string|array $msg
149 * - RawMessage: is cloned
150 * - array: first element is $key, rest are $params to RawMessage::__construct
151 * - string: passed to RawMessage::__construct
152 * @param string|null $code
153 * @param array|null $data
156 public function __construct( $msg, $code = null, array $data = null ) {
157 if ( $msg instanceof RawMessage
) {
158 foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
159 if ( isset( $msg->$key ) ) {
160 $this->$key = $msg->$key;
163 } elseif ( is_array( $msg ) ) {
164 $key = array_shift( $msg );
165 parent
::__construct( $key, $msg );
167 parent
::__construct( $msg );
169 $this->apiCode
= $code;
170 $this->apiData
= (array)$data;
173 public function getApiCode() {
174 return $this->apiCode
=== null ?
$this->getKey() : $this->apiCode
;
177 public function setApiCode( $code, array $data = null ) {
178 $this->apiCode
= $code;
179 if ( $data !== null ) {
180 $this->setApiData( $data );
184 public function getApiData() {
185 return $this->apiData
;
188 public function setApiData( array $data ) {
189 $this->apiData
= $data;