Generates standardized response objects. More...

Public Member Functions
	__construct ( $textFormatters)

	create ()
	Create an unspecified response.

	createFromException (Throwable $exception, array $extraData=[])
	Turn a throwable into a JSON error response.

	createFromReturnValue ( $value)
	Create a JSON response from an arbitrary value.

	createHttpError ( $errorCode, array $bodyData=[])
	Create a HTTP 4xx or 5xx response.

	createJson ( $value, $contentType=null)
	Create a successful JSON response.

	createLegacyTemporaryRedirect ( $target)
	Creates a temporary (302) redirect.

	createLocalizedHttpError ( $errorCode, MessageValue $messageValue, array $extraData=[])
	Create an HTTP 4xx or 5xx response with error message localisation.

	createNoContent ()
	Create a 204 (No Content) response, used to indicate that an operation which does not return anything (e.g.

	createNotModified ()
	Create a 304 (Not Modified) response, used when the client has an up-to-date cached response.

	createPermanentRedirect ( $target)
	Creates a permanent (301) redirect.

	createRedirect ( $target, $code)
	Creates a redirect specifying the code.

	createSeeOther ( $target)
	Creates a See Other (303) redirect.

	createTemporaryRedirect ( $target)
	Creates a temporary (307) redirect.

	encodeJson ( $value)
	Encode a stdClass object or array to a JSON string.

	formatMessage (MessageValue $messageValue)
	Tries to return the formatted string(s) for a message value object using the response factory's text formatters.

	getFormattedMessage (MessageValue $messageValue, string $preferredlang='')
	Tries to return one formatted string for a message value object.

	setShowExceptionDetails (bool $showExceptionDetails)
	Control whether web responses may include a exception messager and backtrace.

Static Public Member Functions
static	getResponseComponents ()
	Returns OpenAPI schema response components object, providing information about the structure of some standard responses, for use in path specs.

Protected Member Functions
	createRedirectBase ( $target)
	Create a redirect response with type / response code unspecified.

	getHyperLink ( $url)
	Returns a minimal HTML document that links to the given URL, as suggested by RFC 7231 for 3xx responses.

Detailed Description

Generates standardized response objects.

Definition at line 17 of file ResponseFactory.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Rest\ResponseFactory::__construct ( $textFormatters )

Parameters

ITextFormatter[] $textFormatters

If there is a relative preference among the input text formatters, the formatters should be ordered from most to least preferred.

Definition at line 33 of file ResponseFactory.php.

Member Function Documentation

◆ create()

MediaWiki\Rest\ResponseFactory::create ( )

Create an unspecified response.

It is the caller's responsibility to set specifics like response code, content type etc.

Returns: Response

Definition at line 69 of file ResponseFactory.php.

◆ createFromException()

MediaWiki\Rest\ResponseFactory::createFromException	(	Throwable	$exception,
		array	$extraData = [] )

Turn a throwable into a JSON error response.

Parameters

Throwable	$exception
array	$extraData	if present, used to generate a RESTbase-style response

Returns: Response

Definition at line 235 of file ResponseFactory.php.

◆ createFromReturnValue()

MediaWiki\Rest\ResponseFactory::createFromReturnValue ( $value )

Create a JSON response from an arbitrary value.

This is a fallback; it's preferable to use createJson() instead.

Parameters

mixed $value A structure containing only scalars, arrays and stdClass objects

Returns: Response

Exceptions

InvalidArgumentException When $value cannot be reasonably represented as JSON

Definition at line 287 of file ResponseFactory.php.

◆ createHttpError()

MediaWiki\Rest\ResponseFactory::createHttpError	(		$errorCode,
		array	$bodyData = [] )

Create a HTTP 4xx or 5xx response.

Parameters

int	$errorCode	HTTP error code
array	$bodyData	An array of data to be included in the JSON response

Returns: Response

Definition at line 195 of file ResponseFactory.php.

◆ createJson()

MediaWiki\Rest\ResponseFactory::createJson	(		$value,
			$contentType = null )

Create a successful JSON response.

Parameters

array \| stdClass \| \\JsonSerializable	$value	JSON value
string \| null	$contentType	HTTP content type (should be 'application/json+...') or null for plain 'application/json'

Returns: Response

Definition at line 80 of file ResponseFactory.php.

◆ createLegacyTemporaryRedirect()

MediaWiki\Rest\ResponseFactory::createLegacyTemporaryRedirect ( $target )

Creates a temporary (302) redirect.

HTTP 302 was underspecified and has been superseded by 303 (when the redirected request should be a GET, regardless of what the current request is) and 307 (when the method should not be changed), but might still be needed for HTTP 1.0 clients or to match legacy behavior.

Parameters

string $target Redirect target (an absolute URL)

Returns: Response

See also: self::createTemporaryRedirect(); self::createSeeOther()

Definition at line 127 of file ResponseFactory.php.

◆ createLocalizedHttpError()

MediaWiki\Rest\ResponseFactory::createLocalizedHttpError	(		$errorCode,
		MessageValue	$messageValue,
		array	$extraData = [] )

Create an HTTP 4xx or 5xx response with error message localisation.

Parameters

int	$errorCode
MessageValue	$messageValue
array	$extraData	An array of additional data to be included in the JSON response

Returns: Response

Definition at line 217 of file ResponseFactory.php.

◆ createNoContent()

MediaWiki\Rest\ResponseFactory::createNoContent ( )

Create a 204 (No Content) response, used to indicate that an operation which does not return anything (e.g.

a PUT request) was successful.

Headers are generally interpreted to refer to the target of the operation. E.g. if this was a PUT request, the caller of this method might want to add an ETag header describing the created resource.

Returns: Response

Definition at line 97 of file ResponseFactory.php.

◆ createNotModified()

MediaWiki\Rest\ResponseFactory::createNotModified ( )

Create a 304 (Not Modified) response, used when the client has an up-to-date cached response.

Per RFC 7232 the response should contain all Cache-Control, Content-Location, Date, ETag, Expires, and Vary headers that would have been sent with the 200 OK answer if the requesting client did not have a valid cached response. This is the responsibility of the caller of this method.

Returns: Response

Definition at line 183 of file ResponseFactory.php.

◆ createPermanentRedirect()

MediaWiki\Rest\ResponseFactory::createPermanentRedirect ( $target )

Creates a permanent (301) redirect.

This indicates that the caller of the API should update their indexes and call the new URL in the future. 301 redirects tend to get cached and are hard to undo. Client behavior for methods other than GET/HEAD is not well-defined and this type of response should be avoided in such cases.

Parameters

string $target Redirect target (an absolute URL)

Returns: Response

Definition at line 112 of file ResponseFactory.php.

◆ createRedirect()

MediaWiki\Rest\ResponseFactory::createRedirect	(		$target,
			$code )

Creates a redirect specifying the code.

This indicates that the operation the client was trying to perform can temporarily be achieved by using a different URL. Clients will preserve the request method when retrying the request with the new URL.

Parameters

string	$target	Redirect target
int	$code	Status code

Returns: Response

Definition at line 141 of file ResponseFactory.php.

◆ createRedirectBase()

MediaWiki\Rest\ResponseFactory::createRedirectBase ( $target )

protected

Create a redirect response with type / response code unspecified.

Parameters

string $target Redirect target (an absolute URL)

Returns: Response

Definition at line 306 of file ResponseFactory.php.

◆ createSeeOther()

MediaWiki\Rest\ResponseFactory::createSeeOther ( $target )

Creates a See Other (303) redirect.

This indicates that the target resource might be of interest to the client, without necessarily implying that it is the same resource. The client will always use GET (or HEAD) when following the redirection. Useful for GET-after-POST.

Parameters

string $target Redirect target (an absolute URL)

Returns: Response

Definition at line 168 of file ResponseFactory.php.

◆ createTemporaryRedirect()

MediaWiki\Rest\ResponseFactory::createTemporaryRedirect ( $target )

Creates a temporary (307) redirect.

This indicates that the operation the client was trying to perform can temporarily be achieved by using a different URL. Clients will preserve the request method when retrying the request with the new URL.

Parameters

string $target Redirect target (an absolute URL)

Returns: Response

Definition at line 155 of file ResponseFactory.php.

◆ encodeJson()

MediaWiki\Rest\ResponseFactory::encodeJson ( $value )

Encode a stdClass object or array to a JSON string.

Parameters

array | stdClass | \\JsonSerializable $value

Returns: string

Exceptions

JsonEncodingException

Definition at line 55 of file ResponseFactory.php.

◆ formatMessage()

MediaWiki\Rest\ResponseFactory::formatMessage ( MessageValue $messageValue )

Tries to return the formatted string(s) for a message value object using the response factory's text formatters.

The returned array will either be empty (if there are no text formatters), or have exactly one key, "messageTranslations", whose value is an array of formatted strings, keyed by the associated language code.

Parameters

MessageValue $messageValue the message value object to format

Returns: array

Definition at line 334 of file ResponseFactory.php.

◆ getFormattedMessage()

MediaWiki\Rest\ResponseFactory::getFormattedMessage	(	MessageValue	$messageValue,
		string	$preferredlang = '' )

Tries to return one formatted string for a message value object.

Return value will be: 1) the formatted string for $preferredLang, if $preferredLang is supplied and the formatted string for that language is available. 2) the first available formatted string, if any are available. 3) the message key string, if no formatted strings are available. Callers who need more specific control should call formatMessage() instead.

Parameters

MessageValue	$messageValue	the message value object to format
string	$preferredlang	preferred language for the formatted string, if available

Returns: string

Definition at line 361 of file ResponseFactory.php.

References Wikimedia\Message\MessageValue\getKey().

◆ getHyperLink()

MediaWiki\Rest\ResponseFactory::getHyperLink ( $url )

protected

Returns a minimal HTML document that links to the given URL, as suggested by RFC 7231 for 3xx responses.

Parameters

string $url An absolute URL

Returns: string

Definition at line 319 of file ResponseFactory.php.

References $url.

◆ getResponseComponents()

static MediaWiki\Rest\ResponseFactory::getResponseComponents ( )

static

Returns OpenAPI schema response components object, providing information about the structure of some standard responses, for use in path specs.

See also: https://swagger.io/specification/#components-object; https://swagger.io/specification/#response-object

Returns: array

Definition at line 387 of file ResponseFactory.php.

◆ setShowExceptionDetails()

MediaWiki\Rest\ResponseFactory::setShowExceptionDetails ( bool $showExceptionDetails )

Control whether web responses may include a exception messager and backtrace.

See also: $wgShowExceptionDetails

Since: 1.39

Parameters

bool $showExceptionDetails

Definition at line 44 of file ResponseFactory.php.

Referenced by MediaWiki\Rest\EntryPoint\doSetup().

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

includes/Rest/ResponseFactory.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ create()

◆ createFromException()

◆ createFromReturnValue()

◆ createHttpError()

◆ createJson()

◆ createLegacyTemporaryRedirect()

◆ createLocalizedHttpError()

◆ createNoContent()

◆ createNotModified()

◆ createPermanentRedirect()

◆ createRedirect()

◆ createRedirectBase()

◆ createSeeOther()

◆ createTemporaryRedirect()

◆ encodeJson()

◆ formatMessage()

◆ getFormattedMessage()

◆ getHyperLink()

◆ getResponseComponents()

◆ setShowExceptionDetails()