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.

Copyright: GPL-2.0-or-later

Author: Daniel Kinzler

Constructor & Destructor Documentation

◆ __construct()

Wikibase\Repo\Api\ApiErrorReporter::__construct	(	ApiBase	$apiModule,
		ExceptionLocalizer	$localizer,
		Language	$language
	)

Parameters

ApiBase	$apiModule	the 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 $messageSpecs a 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 $messageSpec The 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 $messageSpecs a 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	$description	An english, plain text description of the error, for use in logs.
string	$errorCode	A code identifying the error
int	$httpRespCode	The HTTP error code to send to the client
array \| null	$extraData	Any extra data to include in the error report

Exceptions

ApiUsageException	always
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	$ex	The exception to report. $ex->getMessage() will be used as the error's free form description.
string	$errorCode	A code identifying the error.
int	$httpRespCode	The HTTP error code to send to the client
array \| null	$extraData	Any 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	$status	The status to report. $status->getMessage() will be used to generate the error's free form description.
string	$errorCode	A 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	$errorCode	A code identifying the error.
int	$httpRespCode	The HTTP error code to send to the client
array \| null	$extraData	Any extra data to include in the error report

Exceptions

ApiUsageException	always
LogicException

◆ getMessageForCode()

Wikibase\Repo\Api\ApiErrorReporter::getMessageForCode	(		$errorCode,
			$description,
		array	$extraData = `null`
	)

private

Parameters

string	$errorCode	A code identifying the error.
string \| null	$description	Plain text english message
array \| null	$extraData	Any 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	$warningData	Warning 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:

repo/includes/Api/ApiErrorReporter.php

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addMessageToResult()

◆ addStatusToResult()

◆ convertMessagesToResult()

◆ convertMessageToResult()

◆ convertToMessage()

◆ convertToMessageList()

◆ dieError()

◆ dieException()

◆ dieStatus()

◆ dieWithError()

◆ getMessageForCode()

◆ getPlainErrorMessageFromStatus()

◆ reportStatusWarnings()

◆ setWarning()

Member Data Documentation

◆ $apiModule

◆ $language

◆ $localizer