1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20
21	/**
22	* Interface for messages with machine-readable data for use by the API
23	*
24	* The idea is that it's a Message that has some extra data for the API to use when interpreting it
25	* as an error (or, in the future, as a warning). Internals of MediaWiki often use messages (or
26	* message keys, or Status objects containing messages) to pass information about errors to the user
27	* (see e.g. PermissionManager::getPermissionErrors()) and the API has to make do with that.
28	*
29	* @since 1.25
30	* @note This interface exists to work around PHP's inheritance, so ApiMessage
31	*  can extend Message and ApiRawMessage can extend RawMessage while still
32	*  allowing an instanceof check for a Message object including this
33	*  functionality. If for some reason you feel the need to implement this
34	*  interface on some other class, that class must also implement all the
35	*  public methods the Message class provides (not just those from
36	*  MessageSpecifier, which as written is fairly useless).
37	* @ingroup API
38	*/
39	interface IApiMessage extends MessageSpecifier {
40	/**
41	* Returns a machine-readable code for use by the API
42	*
43	* If no code was specifically set, the message key is used as the code
44	* after removing "apiwarn-" or "apierror-" prefixes and applying
45	* backwards-compatibility mappings.
46	*
47	* @return string
48	*/
49	public function getApiCode();
50
51	/**
52	* Returns additional machine-readable data about the error condition
53	* @return array
54	*/
55	public function getApiData();
56
57	/**
58	* Sets the machine-readable code for use by the API
59	* @param string|null $code If null, uses the default (see self::getApiCode())
60	* @param array|null $data If non-null, passed to self::setApiData()
61	*/
62	public function setApiCode( $code, array $data = null );
63
64	/**
65	* Sets additional machine-readable data about the error condition
66	* @param array $data
67	*/
68	public function setApiData( array $data );
69	}