MediaWiki  master
MediaWiki\Rest\ResponseFactory Class Reference

Generates standardized response objects. More...

Collaboration diagram for MediaWiki\Rest\ResponseFactory:

Public Member Functions

 __construct ( $textFormatters)
 
 create ()
 Create an unspecified response. More...
 
 createFromException ( $exception)
 Turn an exception into a JSON error response. More...
 
 createFromReturnValue ( $value)
 Create a JSON response from an arbitrary value. More...
 
 createHttpError ( $errorCode, array $bodyData=[])
 Create a HTTP 4xx or 5xx response. More...
 
 createJson ( $value, $contentType=null)
 Create a successful JSON response. More...
 
 createLegacyTemporaryRedirect ( $target)
 Creates a temporary (302) redirect. More...
 
 createLocalizedHttpError ( $errorCode, MessageValue $messageValue)
 Create an HTTP 4xx or 5xx response with error message localisation. More...
 
 createNoContent ()
 Create a 204 (No Content) response, used to indicate that an operation which does not return anything (e.g. More...
 
 createNotModified ()
 Create a 304 (Not Modified) response, used when the client has an up-to-date cached response. More...
 
 createPermanentRedirect ( $target)
 Creates a permanent (301) redirect. More...
 
 createSeeOther ( $target)
 Creates a See Other (303) redirect. More...
 
 createTemporaryRedirect ( $target)
 Creates a temporary (307) redirect. More...
 
 encodeJson ( $value)
 Encode a stdClass object or array to a JSON string. More...
 
 formatMessage (MessageValue $messageValue)
 

Public Attributes

const CT_HTML = 'text/html; charset=utf-8'
 
const CT_JSON = 'application/json'
 
const CT_PLAIN = 'text/plain; charset=utf-8'
 

Protected Member Functions

 createRedirectBase ( $target)
 Create a redirect response with type / response code unspecified. More...
 
 getHyperLink ( $url)
 Returns a minimal HTML document that links to the given URL, as suggested by RFC 7231 for 3xx responses. More...
 

Private Attributes

ITextFormatter [] $textFormatters
 

Detailed Description

Generates standardized response objects.

Definition at line 18 of file ResponseFactory.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Rest\ResponseFactory::__construct (   $textFormatters)
Parameters
ITextFormatter[]$textFormatters

Definition at line 29 of file ResponseFactory.php.

References MediaWiki\Rest\ResponseFactory\$textFormatters.

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 53 of file ResponseFactory.php.

◆ createFromException()

MediaWiki\Rest\ResponseFactory::createFromException (   $exception)

Turn an exception into a JSON error response.

Parameters
Exception | Throwable$exception
Returns
Response

Definition at line 194 of file ResponseFactory.php.

References $response, MediaWiki\Rest\ResponseFactory\createHttpError(), MediaWiki\Rest\ResponseFactory\createLocalizedHttpError(), and MWExceptionHandler\getStructuredExceptionData().

◆ 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$valueA structure containing only scalars, arrays and stdClass objects
Returns
Response
Exceptions
InvalidArgumentExceptionWhen $value cannot be reasonably represented as JSON

Definition at line 225 of file ResponseFactory.php.

References $response, $type, and MediaWiki\Rest\ResponseFactory\createJson().

◆ createHttpError()

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

Create a HTTP 4xx or 5xx response.

Parameters
int$errorCodeHTTP error code
array$bodyDataAn array of data to be included in the JSON response
Returns
Response
Exceptions
InvalidArgumentException

Definition at line 169 of file ResponseFactory.php.

References $response, MediaWiki\Rest\ResponseFactory\createJson(), and HttpStatus\getMessage().

Referenced by MediaWiki\Rest\ResponseFactory\createFromException(), and MediaWiki\Rest\ResponseFactory\createLocalizedHttpError().

◆ createJson()

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

Create a successful JSON response.

Parameters
array | stdClass$valueJSON value
string | null$contentTypeHTTP content type (should be 'application/json+...') or null for plain 'application/json'
Returns
Response

Definition at line 64 of file ResponseFactory.php.

References $response, and MediaWiki\Rest\ResponseFactory\encodeJson().

Referenced by MediaWiki\Rest\ResponseFactory\createFromReturnValue(), and MediaWiki\Rest\ResponseFactory\createHttpError().

◆ 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$targetRedirect target (an absolute URL)
Returns
Response
See also
self::createTemporaryRedirect()
self::createSeeOther()

Definition at line 112 of file ResponseFactory.php.

References $response, and MediaWiki\Rest\ResponseFactory\createRedirectBase().

◆ createLocalizedHttpError()

MediaWiki\Rest\ResponseFactory::createLocalizedHttpError (   $errorCode,
MessageValue  $messageValue 
)

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

Definition at line 185 of file ResponseFactory.php.

References MediaWiki\Rest\ResponseFactory\createHttpError(), and MediaWiki\Rest\ResponseFactory\formatMessage().

Referenced by MediaWiki\Rest\ResponseFactory\createFromException().

◆ 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 81 of file ResponseFactory.php.

References $response.

◆ 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 156 of file ResponseFactory.php.

References $response.

◆ 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$targetRedirect target (an absolute URL)
Returns
Response

Definition at line 96 of file ResponseFactory.php.

References $response, and MediaWiki\Rest\ResponseFactory\createRedirectBase().

◆ createRedirectBase()

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

Create a redirect response with type / response code unspecified.

Parameters
string$targetRedirect target (an absolute URL)
Returns
Response

Definition at line 247 of file ResponseFactory.php.

References $response, and MediaWiki\Rest\ResponseFactory\getHyperLink().

Referenced by MediaWiki\Rest\ResponseFactory\createLegacyTemporaryRedirect(), MediaWiki\Rest\ResponseFactory\createPermanentRedirect(), MediaWiki\Rest\ResponseFactory\createSeeOther(), and MediaWiki\Rest\ResponseFactory\createTemporaryRedirect().

◆ 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$targetRedirect target (an absolute URL)
Returns
Response

Definition at line 140 of file ResponseFactory.php.

References $response, and MediaWiki\Rest\ResponseFactory\createRedirectBase().

◆ 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$targetRedirect target (an absolute URL)
Returns
Response

Definition at line 126 of file ResponseFactory.php.

References $response, and MediaWiki\Rest\ResponseFactory\createRedirectBase().

◆ encodeJson()

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

Encode a stdClass object or array to a JSON string.

Parameters
array | stdClass$value
Returns
string
Exceptions
JsonEncodingException

Definition at line 40 of file ResponseFactory.php.

Referenced by MediaWiki\Rest\ResponseFactory\createJson().

◆ formatMessage()

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

◆ 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$urlAn absolute URL
Returns
string

Definition at line 260 of file ResponseFactory.php.

Referenced by MediaWiki\Rest\ResponseFactory\createRedirectBase().

Member Data Documentation

◆ $textFormatters

ITextFormatter [] MediaWiki\Rest\ResponseFactory::$textFormatters
private

Definition at line 24 of file ResponseFactory.php.

Referenced by MediaWiki\Rest\ResponseFactory\__construct().

◆ CT_HTML

const MediaWiki\Rest\ResponseFactory::CT_HTML = 'text/html; charset=utf-8'

Definition at line 20 of file ResponseFactory.php.

◆ CT_JSON

const MediaWiki\Rest\ResponseFactory::CT_JSON = 'application/json'

Definition at line 21 of file ResponseFactory.php.

◆ CT_PLAIN

const MediaWiki\Rest\ResponseFactory::CT_PLAIN = 'text/plain; charset=utf-8'

Definition at line 19 of file ResponseFactory.php.


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