Wikibase
MediaWiki Wikibase extension
Wikibase\Repo\Api\ApiErrorReporter Class Reference

ApiErrorReporter is a component for API modules that handles error reporting. More...

Public Member Functions

 __construct (ApiBase $apiModule, ExceptionLocalizer $localizer, Language $language)
 
 reportStatusWarnings (StatusValue $status)
 Reports any warnings in the StatusValue object on the warnings section of the result. More...
 
 dieStatus (StatusValue $status, $errorCode)
 Aborts the request with an error based on the given (fatal) StatusValue. More...
 
 dieException (Exception $ex, $errorCode, $httpRespCode=0, $extraData=[])
 Aborts the request with an error based on the given Exception. More...
 
 dieWithError ( $msg, $errorCode, $httpRespCode=0, $extraData=[])
 
 dieError ( $description, $errorCode, $httpRespCode=0, $extraData=[])
 Aborts the request with an error code. More...
 
 addStatusToResult (StatusValue $status, &$data)
 Add the messages from the given StatusValue object to the $data array, for use in an error report. More...
 

Private Member Functions

 setWarning ( $key, $warningData)
 Set warning section for this module. More...
 
 getPlainErrorMessageFromStatus (StatusValue $status)
 
 getMessageForCode ( $errorCode, $description, array $extraData=null)
 
 addMessageToResult (Message $message, &$data)
 Add the given message to the $data array, for use in an error report. More...
 
 convertMessagesToResult (array $messageSpecs)
 Utility method for compiling a list of messages into a form suitable for use in an API result structure. More...
 
 convertToMessageList (array $messageSpecs)
 Utility method for building a list of Message objects from an array of message specs. More...
 
 convertMessageToResult (Message $message)
 Constructs a result structure from the given Message. More...
 
 convertToMessage ( $messageSpec)
 Utility function for converting a message specified as a string or array to a Message object. More...
 

Private Attributes

 $apiModule
 
 $localizer
 
 $language
 

Detailed Description

ApiErrorReporter is a component for API modules that handles error reporting.

It supports localization of error messages.

Author
Daniel Kinzler

Constructor & Destructor Documentation

◆ __construct()

Wikibase\Repo\Api\ApiErrorReporter::__construct ( ApiBase  $apiModule,
ExceptionLocalizer  $localizer,
Language  $language 
)
Parameters
ApiBase$apiModulethe API module for collaboration
ExceptionLocalizer$localizer
Language$language

Member Function Documentation

◆ addMessageToResult()

Wikibase\Repo\Api\ApiErrorReporter::addMessageToResult ( Message  $message,
$data 
)
private

Add the given message to the $data array, for use in an error report.

Parameters
Message$message
array | null&$data
Exceptions
InvalidArgumentException

◆ addStatusToResult()

Wikibase\Repo\Api\ApiErrorReporter::addStatusToResult ( StatusValue  $status,
$data 
)

Add the messages from the given StatusValue object to the $data array, for use in an error report.

Parameters
StatusValue$status
array | null&$data
Exceptions
InvalidArgumentException

◆ convertMessagesToResult()

Wikibase\Repo\Api\ApiErrorReporter::convertMessagesToResult ( array  $messageSpecs)
private

Utility method for compiling a list of messages into a form suitable for use in an API result structure.

The $errors parameters is a list of (error) messages. Each entry in that array represents on message; the message can be represented as:

  • a message key, as a string
  • an indexed array with the message key as the first element, and the remaining elements acting as message parameters
  • an associative array with the following fields:
    • message: the message key (as a string); may also be a Message object, see below for that.
    • params: a list of parameters (optional)
    • type: the type of message (warning or error) (optional)
    • html: an HTML rendering of the message (optional)
  • an associative array like above, but containing a Message object in the 'message' field. In that case, the 'params' field is ignored and the parameter list is taken from the Message object.

This provides support for message lists coming from StatusValue::getErrorsByType() as well as Title::getUserPermissionsErrors() etc.

Parameters
array$messageSpecsa list of errors, as returned by StatusValue::getErrorsByType() or Title::getUserPermissionsErrors()
Returns
array a result structure containing the messages from $errors as well as what was already present in the $messages parameter.

◆ convertMessageToResult()

Wikibase\Repo\Api\ApiErrorReporter::convertMessageToResult ( Message  $message)
private

Constructs a result structure from the given Message.

Parameters
Message$message
Returns
array

◆ convertToMessage()

Wikibase\Repo\Api\ApiErrorReporter::convertToMessage (   $messageSpec)
private

Utility function for converting a message specified as a string or array to a Message object.

Returns null if this is not possible.

The formats supported by this method are the formats used by the StatusValue class as well as the one used by Title::getUserPermissionsErrors().

The spec may be structured as follows:

  • a message key, as a string
  • an indexed array with the message key as the first element, and the remaining elements acting as message parameters
  • an associative array with the following fields:
    • message: the message key (as a string); may also be a Message object, see below for that.
    • params: a list of parameters (optional)
    • type: the type of message (warning or error) (optional)
    • html: an HTML rendering of the message (optional)
  • an associative array like above, but containing a Message object in the 'message' field. In that case, the 'params' field is ignored and the parameter list is taken from the Message object.
Parameters
string | array$messageSpecThe message spec.
Returns
Message|null

◆ convertToMessageList()

Wikibase\Repo\Api\ApiErrorReporter::convertToMessageList ( array  $messageSpecs)
private

Utility method for building a list of Message objects from an array of message specs.

See also
convertToMessage()
Parameters
array$messageSpecsa list of errors, as returned by StatusValue::getErrorsByType() or Title::getUserPermissionsErrors().
Returns
array a result structure containing the messages from $errors as well as what was already present in the $messages parameter.

◆ dieError()

Wikibase\Repo\Api\ApiErrorReporter::dieError (   $description,
  $errorCode,
  $httpRespCode = 0,
  $extraData = [] 
)

Aborts the request with an error code.

This is intended as a drop-in replacement for ApiBase::dieUsage().

Localization of the error code is attempted by looking up a message key constructed using the given code in "wikibase-api-$errorCode". If such a message exists, it is included in the error's extra data.

See also
ApiBase::dieUsage()
Deprecated:
Use dieWithError() instead.
Parameters
string$descriptionAn english, plain text description of the error, for use in logs.
string$errorCodeA code identifying the error
int$httpRespCodeThe HTTP error code to send to the client
array | null$extraDataAny extra data to include in the error report
Exceptions
ApiUsageExceptionalways
LogicException

◆ dieException()

Wikibase\Repo\Api\ApiErrorReporter::dieException ( Exception  $ex,
  $errorCode,
  $httpRespCode = 0,
  $extraData = [] 
)

Aborts the request with an error based on the given Exception.

This is intended as an alternative for ApiBase::dieUsage().

If possible, a localized error message based on the exception is included in the error sent to the client. Localization of errors is attempted using the ExceptionLocalizer service provided to the constructor. If that fails, dieUsage() is called, which in turn attempts localization based on the error code.

See also
ApiBase::dieUsage()
Parameters
Exception$exThe exception to report. $ex->getMessage() will be used as the error's free form description.
string$errorCodeA code identifying the error.
int$httpRespCodeThe HTTP error code to send to the client
array | null$extraDataAny extra data to include in the error report
Exceptions
ApiUsageException
LogicException

◆ dieStatus()

Wikibase\Repo\Api\ApiErrorReporter::dieStatus ( StatusValue  $status,
  $errorCode 
)

Aborts the request with an error based on the given (fatal) StatusValue.

This is intended as an alternative for ApiBase::dieUsage().

If possible, a localized error message based on the exception is included in the error sent to the client. Localization of errors is attempted using the ExceptionLocalizer service provided to the constructor. If that fails, dieUsage() is called, which in turn attempts localization based on the error code.

See also
ApiBase::dieUsage()
Parameters
StatusValue$statusThe status to report. $status->getMessage() will be used to generate the error's free form description.
string$errorCodeA code identifying the error.
Exceptions
ApiUsageException
LogicException

◆ dieWithError()

Wikibase\Repo\Api\ApiErrorReporter::dieWithError (   $msg,
  $errorCode,
  $httpRespCode = 0,
  $extraData = [] 
)
See also
ApiBase::dieWithError
Parameters
string | string[] | MessageSpecifier$msg
string$errorCodeA code identifying the error.
int$httpRespCodeThe HTTP error code to send to the client
array | null$extraDataAny extra data to include in the error report
Exceptions
ApiUsageExceptionalways
LogicException

◆ getMessageForCode()

Wikibase\Repo\Api\ApiErrorReporter::getMessageForCode (   $errorCode,
  $description,
array  $extraData = null 
)
private
Parameters
string$errorCodeA code identifying the error.
string | null$descriptionPlain text english message
array | null$extraDataAny extra data to include in the error report
Returns
ApiMessage

◆ getPlainErrorMessageFromStatus()

Wikibase\Repo\Api\ApiErrorReporter::getPlainErrorMessageFromStatus ( StatusValue  $status)
private
Parameters
StatusValue$status
Returns
string|null a plain text english error message, or null

◆ reportStatusWarnings()

Wikibase\Repo\Api\ApiErrorReporter::reportStatusWarnings ( StatusValue  $status)

Reports any warnings in the StatusValue object on the warnings section of the result.

Parameters
StatusValue$status

◆ setWarning()

Wikibase\Repo\Api\ApiErrorReporter::setWarning (   $key,
  $warningData 
)
private

Set warning section for this module.

Note
Only needed when ApiErrorFormatter_BackCompat is in use.
Parameters
string$key
string | array$warningDataWarning message

Member Data Documentation

◆ $apiModule

Wikibase\Repo\Api\ApiErrorReporter::$apiModule
private

◆ $language

Wikibase\Repo\Api\ApiErrorReporter::$language
private

◆ $localizer

Wikibase\Repo\Api\ApiErrorReporter::$localizer
private

The documentation for this class was generated from the following file: