MediaWiki\Rest\Handler Class Reference

Base class for REST route handlers. More...

Inherited by MediaWiki\Rest\Handler\AbstractContributionHandler, MediaWiki\Rest\Handler\ActionModuleBasedHandler, MediaWiki\Rest\Handler\CompareHandler, MediaWiki\Rest\Handler\ParsoidHandler, MediaWiki\Rest\Handler\SearchHandler, and MediaWiki\Rest\SimpleHandler.

Public Member Functions
	applyCacheControl (ResponseInterface $response)
	Apply cache control to enforce privacy.
	applyConditionalResponseHeaders (ResponseInterface $response)
	Apply verifier headers to the response, per RFC 7231 §7.2.
	checkPreconditions ()
	Check the conditional request headers and generate a response if appropriate.
	checkSession ()
	Check the session (and session provider)
	execute ()
	Execute the handler.
	getAuthority ()
	Get the current acting authority.
	getBodyValidator ( $contentType)
	Fetch the BodyValidator.
	getConfig ()
	Get the configuration array for the current route.
	getParamSettings ()
	Fetch ParamValidator settings for parameters.
	getPath ()
	Returns the path this handler is bound to, including path variables.
	getRequest ()
	Get the current request.
	getResponseFactory ()
	Get the ResponseFactory which can be used to generate Response objects.
	getSession ()
	Get the Session.
	getValidatedBody ()
	Fetch the validated body.
	getValidatedParams ()
	Fetch the validated parameters.
	init (Router $router, RequestInterface $request, array $config, Authority $authority, ResponseFactory $responseFactory, HookContainer $hookContainer, Session $session)
	Initialise with dependencies from the Router.
	needsReadAccess ()
	Indicates whether this route requires read rights.
	needsWriteAccess ()
	Indicates whether this route requires write access.
	requireSafeAgainstCsrf ()
	Indicates whether this route can be accessed only by session providers safe vs csrf.
	validate (Validator $restValidator)
	Validate the request parameters/attributes and body.

Public Attributes
const	PARAM_SOURCE = 'rest-param-source'
	(string) ParamValidator constant to specify the source of the parameter.

Protected Member Functions
	getConditionalHeaderUtil ()
	Get a ConditionalHeaderUtil object.
	getETag ()
	The subclass should override this to provide an ETag for the current state of the requested resource.
	getHookContainer ()
	Get a HookContainer, for running extension hooks or for hook metadata.
	getHookRunner ()
	Get a HookRunner for running core hooks.
	getLastModified ()
	The subclass should override this to provide the maximum last modified timestamp of the requested resource.
	getRouter ()
	Get the Router.
	getRouteUrl ( $pathParams=[], $queryParams=[])
	Get the URL of this handler's endpoint.
	hasRepresentation ()
	The subclass should override this to indicate whether the resource exists.
	postInitSetup ()
	The handler can override this to do any necessary setup after init() is called to inject the dependencies.
	postValidationSetup ()
	The handler can override this to do any necessary setup after validate() has been called.
	urlEncodeTitle ( $title)
	URL-encode titles in a "pretty" way.

Detailed Description

Base class for REST route handlers.

Stability: stable

to extend.

Definition at line 20 of file Handler.php.

Member Function Documentation

applyCacheControl()

MediaWiki\Rest\Handler::applyCacheControl

(

ResponseInterface

$response

)

Apply cache control to enforce privacy.

Parameters

ResponseInterface

$response

Definition at line 312 of file Handler.php.

References MediaWiki\Rest\ResponseInterface\getHeaderLine(), getRequest(), and MediaWiki\Rest\ResponseInterface\setHeader().

applyConditionalResponseHeaders()

MediaWiki\Rest\Handler::applyConditionalResponseHeaders

(

ResponseInterface

$response

)

Apply verifier headers to the response, per RFC 7231 §7.2.

This is called after execute() returns.

For GET and HEAD requests, the default behavior is to set the ETag and Last-Modified headers based on the values returned by getETag() and getLastModified() when they were called before execute() was run.

Other request methods are assumed to be state-changing, so no headers will be set per default.

This may be overridden to modify the verifier headers sent in the response. However, handlers that modify the resource's state would typically just set the ETag and Last-Modified headers in the execute() method.

Stability: stable

to override

Parameters

ResponseInterface

$response

Definition at line 300 of file Handler.php.

References getRequest().

checkPreconditions()

MediaWiki\Rest\Handler::checkPreconditions

(

)

Check the conditional request headers and generate a response if appropriate.

This is called by the Router before execute() and may be overridden.

Stability: stable

to override

Returns

ResponseInterface|null

Reimplemented in MediaWiki\Rest\Handler\TransformHandler.

Definition at line 270 of file Handler.php.

References getRequest().

checkSession()

MediaWiki\Rest\Handler::checkSession

(

)

Check the session (and session provider)

Exceptions

HttpException

on failed check

Access: internal

Definition at line 225 of file Handler.php.

execute()

MediaWiki\Rest\Handler::execute ( )

abstract

Execute the handler.

This is called after parameter validation. The return value can either be a Response or any type accepted by ResponseFactory::createFromReturnValue().

To automatically construct an error response, execute() should throw a \MediaWiki\Rest\HttpException. Such exceptions will not be logged like a normal exception.

If execute() throws any other kind of exception, the exception will be logged and a generic 500 error page will be shown.

Stability: stable

to override

Returns

mixed

Reimplemented in MediaWiki\Rest\Handler\ActionModuleBasedHandler, MediaWiki\Rest\Handler\CompareHandler, MediaWiki\Rest\Handler\ContributionsCountHandler, MediaWiki\Rest\Handler\ParsoidHandler, MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\TransformHandler, MediaWiki\Rest\Handler\UserContributionsHandler, and MediaWiki\Rest\SimpleHandler.

getAuthority()

MediaWiki\Rest\Handler::getAuthority

(

)

Get the current acting authority.

The return type declaration causes it to raise a fatal error if init() has not yet been called.

Since

1.36

Returns

Authority

Definition at line 166 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\CompareHandler\execute(), MediaWiki\Rest\Handler\ContributionsCountHandler\execute(), MediaWiki\Rest\Handler\UserContributionsHandler\execute(), MediaWiki\Rest\Handler\AbstractContributionHandler\getTargetUser(), MediaWiki\Rest\Handler\RevisionHTMLHandler\postValidationSetup(), and MediaWiki\Rest\Handler\RevisionSourceHandler\postValidationSetup().

getBodyValidator()

MediaWiki\Rest\Handler::getBodyValidator

(

$contentType

)

Fetch the BodyValidator.

Stability: stable

to override

Parameters

string

$contentType

Content type of the request.

Returns

BodyValidator

Reimplemented in MediaWiki\Rest\Handler\CreationHandler, and MediaWiki\Rest\Handler\UpdateHandler.

Definition at line 360 of file Handler.php.

Referenced by MediaWiki\Rest\Validator\Validator\validateBody().

getConditionalHeaderUtil()

MediaWiki\Rest\Handler::getConditionalHeaderUtil ( )

protected

Get a ConditionalHeaderUtil object.

On the first call to this method, the object will be initialized with validator values by calling getETag(), getLastModified() and hasRepresentation().

Returns

ConditionalHeaderUtil

Definition at line 250 of file Handler.php.

References MediaWiki\Rest\ConditionalHeaderUtil\setValidators().

getConfig()

MediaWiki\Rest\Handler::getConfig

(

)

Get the configuration array for the current route.

The return type declaration causes it to raise a fatal error if init() has not been called.

Returns

array

Definition at line 177 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\ParsoidHandler\assertDomainIsCorrect(), MediaWiki\Rest\Handler\TransformHandler\execute(), MediaWiki\Rest\Handler\getPath(), MediaWiki\Rest\Handler\AbstractContributionHandler\postInitSetup(), and MediaWiki\Rest\Handler\SearchHandler\postInitSetup().

getETag()

MediaWiki\Rest\Handler::getETag ( )

protected

The subclass should override this to provide an ETag for the current state of the requested resource.

This is called before execute() in order to decide whether to send a 304. If the request is going to change the state of the resource, the ETag returned must represent the state before the change. In other words, it must identify the entity that the change is going to be applied to.

For GET and HEAD requests, this ETag will also be included in the response.

Handlers that modify the resource and want to return an ETag header representing the new state in the response should set the header in the execute() method. However, note that responses to PUT requests must not return an ETag unless the new content of the resource is exactly the data that was sent by the client in the request body.

This must be a complete ETag, including double quotes. See RFC 7231 §7.2 and RFC 7232 §2.3 for semantics.

Stability: stable

to override

Returns

string|null

Reimplemented in MediaWiki\Rest\Handler\LanguageLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, and MediaWiki\Rest\Handler\RevisionSourceHandler.

Definition at line 459 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\RevisionSourceHandler\getETag().

getHookContainer()

MediaWiki\Rest\Handler::getHookContainer ( )

protected

Get a HookContainer, for running extension hooks or for hook metadata.

Since

1.35

Returns

HookContainer

Definition at line 393 of file Handler.php.

getHookRunner()

MediaWiki\Rest\Handler::getHookRunner ( )

protected

Get a HookRunner for running core hooks.

Access: internal

This is for use by core only. Hook interfaces may be removed without notice.

Since

1.35

Returns

HookRunner

Definition at line 405 of file Handler.php.

getLastModified()

MediaWiki\Rest\Handler::getLastModified ( )

protected

The subclass should override this to provide the maximum last modified timestamp of the requested resource.

This is called before execute() in order to decide whether to send a 304. If the request is going to change the state of the resource, the time returned must represent the last modification date before the change. In other words, it must provide the timestamp of the entity that the change is going to be applied to.

For GET and HEAD requests, this value will automatically be included in the response in the Last-Modified header.

Handlers that modify the resource and want to return a Last-Modified header representing the new state in the response should set the header in the execute() method.

See RFC 7231 §7.2 and RFC 7232 §2.3 for semantics.

Stability: stable

to override

Returns

bool|string|int|float|DateTime|null

Reimplemented in MediaWiki\Rest\Handler\LanguageLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\PageHistoryCountHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, and MediaWiki\Rest\Handler\RevisionSourceHandler.

Definition at line 431 of file Handler.php.

getParamSettings()

MediaWiki\Rest\Handler::getParamSettings

(

)

Fetch ParamValidator settings for parameters.

Every setting must include self::PARAM_SOURCE to specify which part of the request is to contain the parameter.

Can be used for validating parameters inside an application/x-www-form-urlencoded or multipart/form-data POST body (i.e. parameters which would be present in PHP's $_POST array). For validating other kinds of request bodies, override getBodyValidator().

Stability: stable

to override

Returns

array[] Associative array mapping parameter names to ParamValidator settings arrays

Reimplemented in MediaWiki\Rest\Handler\CompareHandler, MediaWiki\Rest\Handler\ContributionsCountHandler, MediaWiki\Rest\Handler\LanguageLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\PageHistoryCountHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, MediaWiki\Rest\Handler\RevisionSourceHandler, MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\TransformHandler, MediaWiki\Rest\Handler\UpdateHandler, and MediaWiki\Rest\Handler\UserContributionsHandler.

Definition at line 348 of file Handler.php.

Referenced by MediaWiki\Rest\SimpleHandler\execute().

getPath()

MediaWiki\Rest\Handler::getPath

(

)

Returns the path this handler is bound to, including path variables.

Returns

string

Definition at line 95 of file Handler.php.

References MediaWiki\Rest\Handler\getConfig().

getRequest()

MediaWiki\Rest\Handler::getRequest

(

)

Get the current request.

The return type declaration causes it to raise a fatal error if init() has not yet been called.

Returns

RequestInterface

Definition at line 155 of file Handler.php.

Referenced by MediaWiki\Rest\SimpleHandler\execute(), and MediaWiki\Rest\Handler\RevisionHTMLHandler\postValidationSetup().

getResponseFactory()

MediaWiki\Rest\Handler::getResponseFactory

(

)

Get the ResponseFactory which can be used to generate Response objects.

This will raise a fatal error if init() has not been called.

Returns

ResponseFactory

Definition at line 188 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\ActionModuleBasedHandler\execute(), MediaWiki\Rest\Handler\CompareHandler\execute(), MediaWiki\Rest\Handler\MediaLinksHandler\run(), MediaWiki\Rest\Handler\PageHistoryCountHandler\run(), and MediaWiki\Rest\Handler\RevisionSourceHandler\run().

getRouter()

MediaWiki\Rest\Handler::getRouter ( )

protected

Get the Router.

The return type declaration causes it to raise a fatal error if init() has not yet been called.

Returns

Router

Definition at line 104 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\CreationHandler\mapActionModuleResponse().

getRouteUrl()

MediaWiki\Rest\Handler::getRouteUrl (   $pathParams = [],   $queryParams = []  )

protected

Get the URL of this handler's endpoint.

Supports the substitution of path parameters, and additions of query parameters.

See also

Router::getRouteUrl()

Parameters

string[]	$pathParams	Path parameters to be injected into the path
string[]	$queryParams	Query parameters to be attached to the URL

Returns

string

Definition at line 119 of file Handler.php.

getSession()

MediaWiki\Rest\Handler::getSession

(

)

Get the Session.

This will raise a fatal error if init() has not been called.

Returns

Session

Definition at line 199 of file Handler.php.

getValidatedBody()

MediaWiki\Rest\Handler::getValidatedBody

(

)

Fetch the validated body.

Returns

mixed Value returned by the body validator, or null if validate() was not called yet, validation failed, there was no body, or the body was form data.

Definition at line 383 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\CreationHandler\getActionModuleParameters(), MediaWiki\Rest\Handler\UpdateHandler\getActionModuleParameters(), and MediaWiki\Rest\Handler\CreationHandler\getTitleParameter().

getValidatedParams()

MediaWiki\Rest\Handler::getValidatedParams

(

)

Fetch the validated parameters.

This must be called after validate() is called. During execute() is fine.

Returns

array Array mapping parameter names to validated values

Exceptions

\RuntimeException If validate() has not been called

Definition at line 371 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\ContributionsCountHandler\execute(), MediaWiki\Rest\Handler\UserContributionsHandler\execute(), MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Handler\AbstractContributionHandler\getTargetUser(), MediaWiki\Rest\Handler\UpdateHandler\getTitleParameter(), MediaWiki\Rest\Handler\UpdateHandler\mapActionModuleResult(), MediaWiki\Rest\Handler\PageHTMLHandler\postValidationSetup(), MediaWiki\Rest\Handler\PageSourceHandler\postValidationSetup(), MediaWiki\Rest\Handler\RevisionHTMLHandler\postValidationSetup(), MediaWiki\Rest\Handler\RevisionSourceHandler\postValidationSetup(), and MediaWiki\Rest\Handler\PageHistoryCountHandler\run().

hasRepresentation()

MediaWiki\Rest\Handler::hasRepresentation ( )

protected

The subclass should override this to indicate whether the resource exists.

This is used for wildcard validators, for example "If-Match: *" fails if the resource does not exist.

In a state-changing request, the return value of this method should reflect the state before the requested change is applied.

Stability: stable

to override

Returns

bool|null

Reimplemented in MediaWiki\Rest\Handler\LanguageLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, and MediaWiki\Rest\Handler\RevisionSourceHandler.

Definition at line 475 of file Handler.php.

init()

MediaWiki\Rest\Handler::init ( Router  $router, RequestInterface  $request, array  $config, Authority  $authority, ResponseFactory  $responseFactory, HookContainer  $hookContainer, Session  $session  )

final

Initialise with dependencies from the Router.

This is called after construction.

Parameters

Router	$router
RequestInterface	$request
array	$config
Authority	$authority
ResponseFactory	$responseFactory
HookContainer	$hookContainer
Session	$session

Access: internal

Definition at line 75 of file Handler.php.

References MediaWiki\Rest\Handler\postInitSetup().

needsReadAccess()

MediaWiki\Rest\Handler::needsReadAccess

(

)

Indicates whether this route requires read rights.

The handler should override this if it does not need to read from the wiki. This is uncommon, but may be useful for login and other account management APIs.

Stability: stable

to override

Returns

bool

Definition at line 490 of file Handler.php.

needsWriteAccess()

MediaWiki\Rest\Handler::needsWriteAccess

(

)

Indicates whether this route requires write access.

The handler should override this if the route does not need to write to the database.

This should return true for routes that may require synchronous database writes. Modules that do not need such writes should also not rely on primary database access, since only read queries are needed and each primary DB is a single point of failure.

Stability: stable

to override

Returns

bool

Reimplemented in MediaWiki\Rest\Handler\CompareHandler, MediaWiki\Rest\Handler\EditHandler, MediaWiki\Rest\Handler\LanguageLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\PageHistoryCountHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, MediaWiki\Rest\Handler\RevisionSourceHandler, and MediaWiki\Rest\Handler\SearchHandler.

Definition at line 508 of file Handler.php.

Referenced by MediaWiki\Rest\CorsUtils\authorize().

postInitSetup()

MediaWiki\Rest\Handler::postInitSetup ( )

protected

The handler can override this to do any necessary setup after init() is called to inject the dependencies.

Stability: stable

to override

Reimplemented in MediaWiki\Rest\Handler\AbstractContributionHandler, and MediaWiki\Rest\Handler\SearchHandler.

Definition at line 536 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\init().

postValidationSetup()

MediaWiki\Rest\Handler::postValidationSetup ( )

protected

The handler can override this to do any necessary setup after validate() has been called.

This gives the handler an opportunity to do initialization based on parameters before pre-execution calls like getLastModified() or getETag().

Stability: stable

to override

Since

1.36

Reimplemented in MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, and MediaWiki\Rest\Handler\RevisionSourceHandler.

Definition at line 547 of file Handler.php.

requireSafeAgainstCsrf()

MediaWiki\Rest\Handler::requireSafeAgainstCsrf

(

)

Indicates whether this route can be accessed only by session providers safe vs csrf.

The handler should override this if the route must only be accessed by session providers that are safe against csrf.

A return value of false does not necessarily mean the route is vulnerable to csrf attacks. It means the route can be accessed by session providers that are not automatically safe against csrf attacks, so the possibility of csrf attacks must be considered.

Stability: stable

to override

Returns

bool

Definition at line 526 of file Handler.php.

urlEncodeTitle()

MediaWiki\Rest\Handler::urlEncodeTitle (   $title )

protected

URL-encode titles in a "pretty" way.

Keeps intact ;$!*(),~: (urlencode does not, but wfUrlencode does). Encodes spaces as underscores (wfUrlencode does not). Encodes slashes (wfUrlencode does not, but keeping them messes with REST paths). Encodes pluses (this is not necessary, and may change).

See also

wfUrlencode

Parameters

string

$title

Returns

string

Definition at line 138 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\CreationHandler\mapActionModuleResponse().

validate()

MediaWiki\Rest\Handler::validate

(

Validator

$restValidator

)

Validate the request parameters/attributes and body.

If there is a validation failure, a response with an error message should be returned or an HttpException should be thrown.

Stability: stable

to override

Parameters

Validator

$restValidator

Exceptions

HttpException

On validation failure.

Definition at line 212 of file Handler.php.

References MediaWiki\Rest\Validator\Validator\validateBody(), and MediaWiki\Rest\Validator\Validator\validateParams().

Member Data Documentation

PARAM_SOURCE

const MediaWiki\Rest\Handler::PARAM_SOURCE = 'rest-param-source'

(string) ParamValidator constant to specify the source of the parameter.

Value must be 'path', 'query', or 'post'. 'post' refers to application/x-www-form-urlencoded or multipart/form-data encoded parameters in the body of a POST request (in other words, parameters in PHP's $_POST). For other kinds of POST parameters, such as JSON fields, use BodyValidator instead of ParamValidator.

Definition at line 29 of file Handler.php.

Referenced by MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Handler\CompareHandler\getParamSettings(), and MediaWiki\Rest\Validator\Validator\validateParams().

---

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

• includes/Rest/Handler.php