4b42896be4
It was created for a specific purpose, and apparently this is confusing some people who're inexplicably trying to implement it outside of that purpose. So, this patch more clearly documents that purpose. Change-Id: I638482327370522bedea1ec514ecbb9d98207382
301 lines
9.4 KiB
PHP
301 lines
9.4 KiB
PHP
<?php
|
|
/**
|
|
* Defines an interface for messages with additional machine-readable data for
|
|
* use by the API, and provides concrete implementations of that interface.
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
/**
|
|
* Interface for messages with machine-readable data for use by the API
|
|
*
|
|
* The idea is that it's a Message that has some extra data for the API to use when interpreting it
|
|
* as an error (or, in the future, as a warning). Internals of MediaWiki often use messages (or
|
|
* message keys, or Status objects containing messages) to pass information about errors to the user
|
|
* (see e.g. Title::getUserPermissionsErrors()) and the API has to make do with that.
|
|
*
|
|
* @since 1.25
|
|
* @note This interface exists to work around PHP's inheritance, so ApiMessage
|
|
* can extend Message and ApiRawMessage can extend RawMessage while still
|
|
* allowing an instanceof check for a Message object including this
|
|
* functionality. If for some reason you feel the need to implement this
|
|
* interface on some other class, that class must also implement all the
|
|
* public methods the Message class provides (not just those from
|
|
* MessageSpecifier, which as written is fairly useless).
|
|
* @ingroup API
|
|
*/
|
|
interface IApiMessage extends MessageSpecifier {
|
|
/**
|
|
* Returns a machine-readable code for use by the API
|
|
*
|
|
* If no code was specifically set, the message key is used as the code
|
|
* after removing "apiwarn-" or "apierror-" prefixes and applying
|
|
* backwards-compatibility mappings.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function getApiCode();
|
|
|
|
/**
|
|
* Returns additional machine-readable data about the error condition
|
|
* @return array
|
|
*/
|
|
public function getApiData();
|
|
|
|
/**
|
|
* Sets the machine-readable code for use by the API
|
|
* @param string|null $code If null, uses the default (see self::getApiCode())
|
|
* @param array|null $data If non-null, passed to self::setApiData()
|
|
*/
|
|
public function setApiCode( $code, array $data = null );
|
|
|
|
/**
|
|
* Sets additional machine-readable data about the error condition
|
|
* @param array $data
|
|
*/
|
|
public function setApiData( array $data );
|
|
}
|
|
|
|
/**
|
|
* Trait to implement the IApiMessage interface for Message subclasses
|
|
* @since 1.27
|
|
* @ingroup API
|
|
*/
|
|
trait ApiMessageTrait {
|
|
|
|
/**
|
|
* Compatibility code mappings for various MW messages.
|
|
* @todo Ideally anything relying on this should be changed to use ApiMessage.
|
|
*/
|
|
protected static $messageMap = [
|
|
'actionthrottledtext' => 'ratelimited',
|
|
'autoblockedtext' => 'autoblocked',
|
|
'badaccess-group0' => 'permissiondenied',
|
|
'badaccess-groups' => 'permissiondenied',
|
|
'badipaddress' => 'invalidip',
|
|
'blankpage' => 'emptypage',
|
|
'blockedtext' => 'blocked',
|
|
'cannotdelete' => 'cantdelete',
|
|
'cannotundelete' => 'cantundelete',
|
|
'cantmove-titleprotected' => 'protectedtitle',
|
|
'cantrollback' => 'onlyauthor',
|
|
'confirmedittext' => 'confirmemail',
|
|
'content-not-allowed-here' => 'contentnotallowedhere',
|
|
'deleteprotected' => 'cantedit',
|
|
'delete-toobig' => 'bigdelete',
|
|
'edit-conflict' => 'editconflict',
|
|
'imagenocrossnamespace' => 'nonfilenamespace',
|
|
'imagetypemismatch' => 'filetypemismatch',
|
|
'importbadinterwiki' => 'badinterwiki',
|
|
'importcantopen' => 'cantopenfile',
|
|
'import-noarticle' => 'badinterwiki',
|
|
'importnofile' => 'nofile',
|
|
'importuploaderrorpartial' => 'partialupload',
|
|
'importuploaderrorsize' => 'filetoobig',
|
|
'importuploaderrortemp' => 'notempdir',
|
|
'ipb_already_blocked' => 'alreadyblocked',
|
|
'ipb_blocked_as_range' => 'blockedasrange',
|
|
'ipb_cant_unblock' => 'cantunblock',
|
|
'ipb_expiry_invalid' => 'invalidexpiry',
|
|
'ip_range_invalid' => 'invalidrange',
|
|
'mailnologin' => 'cantsend',
|
|
'markedaspatrollederror-noautopatrol' => 'noautopatrol',
|
|
'movenologintext' => 'cantmove-anon',
|
|
'movenotallowed' => 'cantmove',
|
|
'movenotallowedfile' => 'cantmovefile',
|
|
'namespaceprotected' => 'protectednamespace',
|
|
'nocreate-loggedin' => 'cantcreate',
|
|
'nocreatetext' => 'cantcreate-anon',
|
|
'noname' => 'invaliduser',
|
|
'nosuchusershort' => 'nosuchuser',
|
|
'notanarticle' => 'missingtitle',
|
|
'nouserspecified' => 'invaliduser',
|
|
'ns-specialprotected' => 'unsupportednamespace',
|
|
'protect-cantedit' => 'cantedit',
|
|
'protectedinterface' => 'protectednamespace-interface',
|
|
'protectedpagetext' => 'protectedpage',
|
|
'range_block_disabled' => 'rangedisabled',
|
|
'rcpatroldisabled' => 'patroldisabled',
|
|
'readonlytext' => 'readonly',
|
|
'sessionfailure' => 'badtoken',
|
|
'systemblockedtext' => 'blocked',
|
|
'titleprotected' => 'protectedtitle',
|
|
'undo-failure' => 'undofailure',
|
|
'userrights-nodatabase' => 'nosuchdatabase',
|
|
'userrights-no-interwiki' => 'nointerwikiuserrights',
|
|
];
|
|
|
|
protected $apiCode = null;
|
|
protected $apiData = [];
|
|
|
|
public function getApiCode() {
|
|
if ( $this->apiCode === null ) {
|
|
$key = $this->getKey();
|
|
if ( isset( self::$messageMap[$key] ) ) {
|
|
$this->apiCode = self::$messageMap[$key];
|
|
} elseif ( $key === 'apierror-missingparam' ) {
|
|
/// @todo: Kill this case along with ApiBase::$messageMap
|
|
$this->apiCode = 'no' . $this->getParams()[0];
|
|
} elseif ( substr( $key, 0, 8 ) === 'apiwarn-' ) {
|
|
$this->apiCode = substr( $key, 8 );
|
|
} elseif ( substr( $key, 0, 9 ) === 'apierror-' ) {
|
|
$this->apiCode = substr( $key, 9 );
|
|
} else {
|
|
$this->apiCode = $key;
|
|
}
|
|
}
|
|
return $this->apiCode;
|
|
}
|
|
|
|
public function setApiCode( $code, array $data = null ) {
|
|
if ( $code !== null && !( is_string( $code ) && $code !== '' ) ) {
|
|
throw new InvalidArgumentException( "Invalid code \"$code\"" );
|
|
}
|
|
|
|
$this->apiCode = $code;
|
|
if ( $data !== null ) {
|
|
$this->setApiData( $data );
|
|
}
|
|
}
|
|
|
|
public function getApiData() {
|
|
return $this->apiData;
|
|
}
|
|
|
|
public function setApiData( array $data ) {
|
|
$this->apiData = $data;
|
|
}
|
|
|
|
public function serialize() {
|
|
return serialize( [
|
|
'parent' => parent::serialize(),
|
|
'apiCode' => $this->apiCode,
|
|
'apiData' => $this->apiData,
|
|
] );
|
|
}
|
|
|
|
public function unserialize( $serialized ) {
|
|
$data = unserialize( $serialized );
|
|
parent::unserialize( $data['parent'] );
|
|
$this->apiCode = $data['apiCode'];
|
|
$this->apiData = $data['apiData'];
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Extension of Message implementing IApiMessage
|
|
* @since 1.25
|
|
* @ingroup API
|
|
*/
|
|
class ApiMessage extends Message implements IApiMessage {
|
|
use ApiMessageTrait;
|
|
|
|
/**
|
|
* Create an IApiMessage for the message
|
|
*
|
|
* This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
|
|
* $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
|
|
*
|
|
* @param Message|RawMessage|array|string $msg
|
|
* @param string|null $code
|
|
* @param array|null $data
|
|
* @return IApiMessage
|
|
*/
|
|
public static function create( $msg, $code = null, array $data = null ) {
|
|
if ( is_array( $msg ) ) {
|
|
// From StatusValue
|
|
if ( isset( $msg['message'] ) ) {
|
|
if ( isset( $msg['params'] ) ) {
|
|
$msg = array_merge( [ $msg['message'] ], $msg['params'] );
|
|
} else {
|
|
$msg = [ $msg['message'] ];
|
|
}
|
|
}
|
|
|
|
// Weirdness that comes in sometimes, including the above
|
|
if ( $msg[0] instanceof MessageSpecifier ) {
|
|
$msg = $msg[0];
|
|
}
|
|
}
|
|
|
|
if ( $msg instanceof IApiMessage ) {
|
|
return $msg;
|
|
} elseif ( $msg instanceof RawMessage ) {
|
|
return new ApiRawMessage( $msg, $code, $data );
|
|
} else {
|
|
return new ApiMessage( $msg, $code, $data );
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @param Message|string|array $msg
|
|
* - Message: is cloned
|
|
* - array: first element is $key, rest are $params to Message::__construct
|
|
* - string: passed to Message::__construct
|
|
* @param string|null $code
|
|
* @param array|null $data
|
|
*/
|
|
public function __construct( $msg, $code = null, array $data = null ) {
|
|
if ( $msg instanceof Message ) {
|
|
foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
|
|
if ( isset( $msg->$key ) ) {
|
|
$this->$key = $msg->$key;
|
|
}
|
|
}
|
|
} elseif ( is_array( $msg ) ) {
|
|
$key = array_shift( $msg );
|
|
parent::__construct( $key, $msg );
|
|
} else {
|
|
parent::__construct( $msg );
|
|
}
|
|
$this->setApiCode( $code, $data );
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Extension of RawMessage implementing IApiMessage
|
|
* @since 1.25
|
|
* @ingroup API
|
|
*/
|
|
class ApiRawMessage extends RawMessage implements IApiMessage {
|
|
use ApiMessageTrait;
|
|
|
|
/**
|
|
* @param RawMessage|string|array $msg
|
|
* - RawMessage: is cloned
|
|
* - array: first element is $key, rest are $params to RawMessage::__construct
|
|
* - string: passed to RawMessage::__construct
|
|
* @param string|null $code
|
|
* @param array|null $data
|
|
*/
|
|
public function __construct( $msg, $code = null, array $data = null ) {
|
|
if ( $msg instanceof RawMessage ) {
|
|
foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
|
|
if ( isset( $msg->$key ) ) {
|
|
$this->$key = $msg->$key;
|
|
}
|
|
}
|
|
} elseif ( is_array( $msg ) ) {
|
|
$key = array_shift( $msg );
|
|
parent::__construct( $key, $msg );
|
|
} else {
|
|
parent::__construct( $msg );
|
|
}
|
|
$this->setApiCode( $code, $data );
|
|
}
|
|
}
|