Page Menu
Home
WickedGov Phorge
Search
Configure Global Search
Log In
Files
F6111249
ApiErrorFormatter.php
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Flag For Later
Award Token
Size
12 KB
Referenced Files
None
Subscribers
None
ApiErrorFormatter.php
View Options
<?php
/**
* This file contains the ApiErrorFormatter definition, plus implementations of
* specific formatters.
*
* 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
*/
namespace
MediaWiki\Api
;
use
ILocalizedException
;
use
MediaWiki\Language\Language
;
use
MediaWiki\Language\RawMessage
;
use
MediaWiki\Message\Message
;
use
MediaWiki\Page\PageReference
;
use
MediaWiki\Page\PageReferenceValue
;
use
MediaWiki\Parser\Sanitizer
;
use
StatusValue
;
use
Throwable
;
use
Wikimedia\Message\MessageSpecifier
;
/**
* Formats errors and warnings for the API, and add them to the associated
* ApiResult.
* @since 1.25
* @ingroup API
* @phan-file-suppress PhanUndeclaredMethod Undeclared methods in IApiMessage
*/
class
ApiErrorFormatter
{
/** @var PageReference Dummy title to silence warnings from MessageCache::parse() */
private
static
$dummyTitle
=
null
;
/** @var ApiResult */
protected
$result
;
/** @var Language */
protected
$lang
;
/** @var PageReference|null page used for rendering error messages, or null to use the dummy title */
private
$title
=
null
;
/** @var bool */
protected
$useDB
=
false
;
/** @var string */
protected
$format
=
'none'
;
/**
* @param ApiResult $result Into which data will be added
* @param Language $lang Used for i18n
* @param string $format
* - plaintext: Error message as something vaguely like plaintext
* (it's basically wikitext with HTML tags stripped and entities decoded)
* - wikitext: Error message as wikitext
* - html: Error message as HTML
* - raw: Raw message key and parameters, no human-readable text
* - none: Code and data only, no human-readable text
* @param bool $useDB Whether to use local translations for errors and warnings.
*/
public
function
__construct
(
ApiResult
$result
,
Language
$lang
,
$format
,
$useDB
=
false
)
{
$this
->
result
=
$result
;
$this
->
lang
=
$lang
;
$this
->
useDB
=
$useDB
;
$this
->
format
=
$format
;
}
/**
* Test whether a code is a valid API error code
*
* A valid code contains only ASCII letters, numbers, underscore, and
* hyphen and is not the empty string.
*
* For backwards compatibility, any code beginning 'internal_api_error_' is
* also allowed.
*
* @param string $code
* @return bool
*/
public
static
function
isValidApiCode
(
$code
)
{
return
is_string
(
$code
)
&&
(
preg_match
(
'/^[a-zA-Z0-9_-]+$/'
,
$code
)
||
// TODO: Deprecate this
preg_match
(
'/^internal_api_error_[^
\0\r\n
]+$/'
,
$code
)
);
}
/**
* Return a formatter like this one but with a different format
*
* @since 1.32
* @param string $format New format.
* @return ApiErrorFormatter
*/
public
function
newWithFormat
(
$format
)
{
return
new
self
(
$this
->
result
,
$this
->
lang
,
$format
,
$this
->
useDB
);
}
/**
* Fetch the format for this formatter
* @since 1.32
* @return string
*/
public
function
getFormat
()
{
return
$this
->
format
;
}
/**
* Fetch the Language for this formatter
* @since 1.29
* @return Language
*/
public
function
getLanguage
()
{
return
$this
->
lang
;
}
/**
* Fetch a dummy title to set on Messages
* @return PageReference
*/
protected
function
getDummyTitle
():
PageReference
{
if
(
self
::
$dummyTitle
===
null
)
{
self
::
$dummyTitle
=
PageReferenceValue
::
localReference
(
NS_SPECIAL
,
'Badtitle/'
.
__METHOD__
);
}
return
self
::
$dummyTitle
;
}
/**
* Get the page used for rendering error messages, e.g. for wikitext magic words like {{PAGENAME}}
* @since 1.37
* @return PageReference
*/
public
function
getContextTitle
():
PageReference
{
return
$this
->
title
?:
$this
->
getDummyTitle
();
}
/**
* Set the page used for rendering error messages, e.g. for wikitext magic words like {{PAGENAME}}
* @since 1.37
* @param PageReference $title
*/
public
function
setContextTitle
(
PageReference
$title
)
{
$this
->
title
=
$title
;
}
/**
* Add a warning to the result
* @param string|null $modulePath
* @param MessageSpecifier|array|string $msg Warning message. See ApiMessage::create().
* @param string|null $code See ApiMessage::create().
* @param array|null $data See ApiMessage::create().
*/
public
function
addWarning
(
$modulePath
,
$msg
,
$code
=
null
,
$data
=
null
)
{
$msg
=
ApiMessage
::
create
(
$msg
,
$code
,
$data
)
->
inLanguage
(
$this
->
lang
)
->
page
(
$this
->
getContextTitle
()
)
->
useDatabase
(
$this
->
useDB
);
$this
->
addWarningOrError
(
'warning'
,
$modulePath
,
$msg
);
}
/**
* Add an error to the result
* @param string|null $modulePath
* @param MessageSpecifier|array|string $msg Warning message. See ApiMessage::create().
* @param string|null $code See ApiMessage::create().
* @param array|null $data See ApiMessage::create().
*/
public
function
addError
(
$modulePath
,
$msg
,
$code
=
null
,
$data
=
null
)
{
$msg
=
ApiMessage
::
create
(
$msg
,
$code
,
$data
)
->
inLanguage
(
$this
->
lang
)
->
page
(
$this
->
getContextTitle
()
)
->
useDatabase
(
$this
->
useDB
);
$this
->
addWarningOrError
(
'error'
,
$modulePath
,
$msg
);
}
/**
* Add warnings and errors from a StatusValue object to the result
* @param string|null $modulePath
* @param StatusValue $status
* @param string[]|string $types 'warning' and/or 'error'
* @param string[] $filter Messages to filter out (since 1.33)
*/
public
function
addMessagesFromStatus
(
$modulePath
,
StatusValue
$status
,
$types
=
[
'warning'
,
'error'
],
array
$filter
=
[]
)
{
if
(
$status
->
isGood
()
)
{
return
;
}
$types
=
array_unique
(
(
array
)
$types
);
foreach
(
$types
as
$type
)
{
foreach
(
$status
->
getMessages
(
$type
)
as
$msg
)
{
$msg
=
ApiMessage
::
create
(
$msg
)
->
inLanguage
(
$this
->
lang
)
->
page
(
$this
->
getContextTitle
()
)
->
useDatabase
(
$this
->
useDB
);
if
(
!
in_array
(
$msg
->
getKey
(),
$filter
,
true
)
)
{
$this
->
addWarningOrError
(
$type
,
$modulePath
,
$msg
);
}
}
}
}
/**
* Get an ApiMessage from a throwable
* @since 1.29
* @param Throwable $exception
* @param array $options
* - wrap: (string|array|MessageSpecifier) Used to wrap the throwable's
* message if it's not an ILocalizedException. The throwable's message
* will be added as the final parameter.
* - code: (string) Default code
* - data: (array) Default extra data
* @return IApiMessage
*/
public
function
getMessageFromException
(
Throwable
$exception
,
array
$options
=
[]
)
{
$options
+=
[
'code'
=>
null
,
'data'
=>
[]
];
if
(
$exception
instanceof
ILocalizedException
)
{
$msg
=
$exception
->
getMessageObject
();
$params
=
[];
}
elseif
(
$exception
instanceof
MessageSpecifier
)
{
$msg
=
Message
::
newFromSpecifier
(
$exception
);
$params
=
[];
}
else
{
if
(
isset
(
$options
[
'wrap'
]
)
)
{
$msg
=
$options
[
'wrap'
];
}
else
{
$msg
=
new
RawMessage
(
'$1'
);
if
(
!
isset
(
$options
[
'code'
]
)
)
{
$class
=
preg_replace
(
'#^Wikimedia
\\\\
Rdbms
\\\\
#'
,
''
,
get_class
(
$exception
)
);
$options
[
'code'
]
=
'internal_api_error_'
.
$class
;
$options
[
'data'
][
'errorclass'
]
=
get_class
(
$exception
);
}
}
$params
=
[
wfEscapeWikiText
(
$exception
->
getMessage
()
)
];
}
return
ApiMessage
::
create
(
$msg
,
$options
[
'code'
],
$options
[
'data'
]
)
->
params
(
$params
)
->
inLanguage
(
$this
->
lang
)
->
page
(
$this
->
getContextTitle
()
)
->
useDatabase
(
$this
->
useDB
);
}
/**
* Format a throwable as an array
* @since 1.29
* @param Throwable $exception
* @param array $options See self::getMessageFromException(), plus
* - format: (string) Format override
* @return array
*/
public
function
formatException
(
Throwable
$exception
,
array
$options
=
[]
)
{
return
$this
->
formatMessage
(
// @phan-suppress-next-line PhanTypeMismatchArgument
$this
->
getMessageFromException
(
$exception
,
$options
),
$options
[
'format'
]
??
null
);
}
/**
* Format a message as an array
* @param Message|array|string $msg Message. See ApiMessage::create().
* @param string|null $format
* @return array
*/
public
function
formatMessage
(
$msg
,
$format
=
null
)
{
$msg
=
ApiMessage
::
create
(
$msg
)
->
inLanguage
(
$this
->
lang
)
->
page
(
$this
->
getContextTitle
()
)
->
useDatabase
(
$this
->
useDB
);
return
$this
->
formatMessageInternal
(
$msg
,
$format
?:
$this
->
format
);
}
/**
* Format messages from a StatusValue as an array
* @param StatusValue $status
* @param string $type 'warning' or 'error'
* @param string|null $format
* @return array
*/
public
function
arrayFromStatus
(
StatusValue
$status
,
$type
=
'error'
,
$format
=
null
)
{
if
(
$status
->
isGood
()
||
!
$status
->
getMessages
()
)
{
return
[];
}
$result
=
new
ApiResult
(
1
_000_000
);
$formatter
=
new
ApiErrorFormatter
(
$result
,
$this
->
lang
,
$format
?:
$this
->
format
,
$this
->
useDB
);
$formatter
->
addMessagesFromStatus
(
null
,
$status
,
[
$type
]
);
switch
(
$type
)
{
case
'error'
:
return
(
array
)
$result
->
getResultData
(
[
'errors'
]
);
case
'warning'
:
return
(
array
)
$result
->
getResultData
(
[
'warnings'
]
);
}
}
/**
* Turn wikitext into something resembling plaintext
* @since 1.29
* @param string $text
* @return string
*/
public
static
function
stripMarkup
(
$text
)
{
// Turn semantic quoting tags to quotes
$ret
=
preg_replace
(
'!</?(var|kbd|samp|code)>!'
,
'"'
,
$text
);
// Strip tags and decode.
return
Sanitizer
::
stripAllTags
(
$ret
);
}
/**
* Format a Message object for raw format
* @param MessageSpecifier $msg
* @return array
*/
private
function
formatRawMessage
(
MessageSpecifier
$msg
)
{
$ret
=
[
'key'
=>
$msg
->
getKey
(),
'params'
=>
$msg
->
getParams
(),
];
ApiResult
::
setIndexedTagName
(
$ret
[
'params'
],
'param'
);
// Transform Messages as parameters in the style of Message::fooParam().
foreach
(
$ret
[
'params'
]
as
$i
=>
$param
)
{
if
(
$param
instanceof
MessageSpecifier
)
{
$ret
[
'params'
][
$i
]
=
[
'message'
=>
$this
->
formatRawMessage
(
$param
)
];
}
}
return
$ret
;
}
/**
* Format a message as an array
* @since 1.29
* @param ApiMessage|ApiRawMessage $msg
* @param string|null $format
* @return array
*/
protected
function
formatMessageInternal
(
$msg
,
$format
)
{
$value
=
[
'code'
=>
$msg
->
getApiCode
()
];
switch
(
$format
)
{
case
'plaintext'
:
$value
+=
[
'text'
=>
self
::
stripMarkup
(
$msg
->
text
()
),
ApiResult
::
META_CONTENT
=>
'text'
,
];
break
;
case
'wikitext'
:
$value
+=
[
'text'
=>
$msg
->
text
(),
ApiResult
::
META_CONTENT
=>
'text'
,
];
break
;
case
'html'
:
$value
+=
[
'html'
=>
$msg
->
parse
(),
ApiResult
::
META_CONTENT
=>
'html'
,
];
break
;
case
'raw'
:
$value
+=
$this
->
formatRawMessage
(
$msg
);
break
;
case
'none'
:
break
;
}
$data
=
$msg
->
getApiData
();
if
(
$data
)
{
$value
[
'data'
]
=
$msg
->
getApiData
()
+
[
ApiResult
::
META_TYPE
=>
'assoc'
,
];
}
return
$value
;
}
/**
* Actually add the warning or error to the result
* @param string $tag 'warning' or 'error'
* @param string|null $modulePath
* @param ApiMessage|ApiRawMessage $msg
*/
protected
function
addWarningOrError
(
$tag
,
$modulePath
,
$msg
)
{
$value
=
$this
->
formatMessageInternal
(
$msg
,
$this
->
format
);
if
(
$modulePath
!==
null
)
{
$value
+=
[
'module'
=>
$modulePath
];
}
$path
=
[
$tag
.
's'
];
$existing
=
$this
->
result
->
getResultData
(
$path
);
if
(
$existing
===
null
||
!
in_array
(
$value
,
$existing
)
)
{
$flags
=
ApiResult
::
NO_SIZE_CHECK
;
if
(
$existing
===
null
)
{
$flags
|=
ApiResult
::
ADD_ON_TOP
;
}
$this
->
result
->
addValue
(
$path
,
null
,
$value
,
$flags
);
$this
->
result
->
addIndexedTagName
(
$path
,
$tag
);
}
}
}
/** @deprecated class alias since 1.43 */
class_alias
(
ApiErrorFormatter
::
class
,
'ApiErrorFormatter'
);
File Metadata
Details
Attached
Mime Type
text/x-php
Expires
Oct 6 2026, 19:04 (6 w, 3 d ago)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
fc/37/dc16e68bcdc3976cf9c4015e0142
Default Alt Text
ApiErrorFormatter.php (12 KB)
Attached To
Mode
rMWPROD MediaWiki Production
Attached
Detach File
Event Timeline
Log In to Comment