Base class for REST route handlers. More...

Inheritance diagram for MediaWiki\Rest\Handler:

[legend]

Collaboration diagram for MediaWiki\Rest\Handler:

[legend]

Public Member Functions
	applyConditionalResponseHeaders (ResponseInterface $response)
	Modify the response, adding Last-Modified and ETag headers as indicated the values previously returned by ETag and getLastModified(). More...

	checkPreconditions ()
	Check the conditional request headers and generate a response if appropriate. More...

	execute ()
	Execute the handler. More...

	getBodyValidator ( $contentType)
	Fetch the BodyValidator. More...

	getConfig ()
	Get the configuration array for the current route. More...

	getParamSettings ()
	Fetch ParamValidator settings for parameters. More...

	getRequest ()
	Get the current request. More...

	getResponseFactory ()
	Get the ResponseFactory which can be used to generate Response objects. More...

	getValidatedBody ()
	Fetch the validated body. More...

	getValidatedParams ()
	Fetch the validated parameters. More...

	init (Router $router, RequestInterface $request, array $config, ResponseFactory $responseFactory, HookContainer $hookContainer)
	Initialise with dependencies from the Router. More...

	needsReadAccess ()
	Indicates whether this route requires read rights. More...

	needsWriteAccess ()
	Indicates whether this route requires write access. More...

	validate (Validator $restValidator)
	Validate the request parameters/attributes and body. More...

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

Protected Member Functions
	getConditionalHeaderUtil ()
	Get a ConditionalHeaderUtil object. More...

	getETag ()
	The subclass should override this to provide an ETag for the current request. More...

	getHookContainer ()
	Get a HookContainer, for running extension hooks or for hook metadata. More...

	getHookRunner ()
	Get a HookRunner for running core hooks. More...

	getLastModified ()
	The subclass should override this to provide the maximum last modified timestamp for the current request. More...

	getRouter ()
	Get the Router. More...

	getRouteUrl ( $pathParams=[], $queryParams=[])
	Get the URL of this handler's endpoint. More...

	hasRepresentation ()
	The subclass should override this to indicate whether the resource exists. More...

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

	urlEncodeTitle ( $title)
	URL-encode titles in a "pretty" way. More...

Private Attributes
ConditionalHeaderUtil	$conditionalHeaderUtil

array	$config

HookContainer	$hookContainer

HookRunner	$hookRunner

RequestInterface	$request

ResponseFactory	$responseFactory

Router	$router

mixed	$validatedBody

array null	$validatedParams

Detailed Description

Base class for REST route handlers.

Stable to extend.

Definition at line 16 of file Handler.php.

Member Function Documentation

◆ applyConditionalResponseHeaders()

MediaWiki\Rest\Handler::applyConditionalResponseHeaders ( ResponseInterface $response )

Modify the response, adding Last-Modified and ETag headers as indicated the values previously returned by ETag and getLastModified().

This is called after execute() returns, and may be overridden.

Stable to override

Parameters

ResponseInterface $response

Definition at line 219 of file Handler.php.

References MediaWiki\Rest\Handler\getConditionalHeaderUtil().

◆ 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.

Stable to override

Returns: ResponseInterface|null

Definition at line 199 of file Handler.php.

References MediaWiki\Rest\Handler\getConditionalHeaderUtil(), MediaWiki\Rest\Handler\getRequest(), and MediaWiki\Rest\Handler\getResponseFactory().

◆ 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 RestException. 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.

Stable to override

Returns: mixed

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

◆ getBodyValidator()

MediaWiki\Rest\Handler::getBodyValidator ( $contentType )

Fetch the BodyValidator.

Stable to override

Parameters

string $contentType Content type of the request.

Returns: BodyValidator

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

Definition at line 246 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 180 of file Handler.php.

References MediaWiki\Rest\Handler\$conditionalHeaderUtil, MediaWiki\Rest\Handler\getETag(), MediaWiki\Rest\Handler\getLastModified(), MediaWiki\Rest\Handler\hasRepresentation(), and MediaWiki\Rest\ConditionalHeaderUtil\setValidators().

Referenced by MediaWiki\Rest\Handler\applyConditionalResponseHeaders(), and MediaWiki\Rest\Handler\checkPreconditions().

◆ 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 140 of file Handler.php.

References MediaWiki\Rest\Handler\$config.

Referenced by MediaWiki\Rest\Handler\PageHTMLHandler\getHtmlType(), MediaWiki\Rest\Handler\getRouteUrl(), 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 request.

This is called before execute() in order to decide whether to send a 304.

This must be a complete ETag, including double quotes.

See RFC 7232 § 2.3 for semantics.

Stable to override

Returns: string|null

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

Definition at line 324 of file Handler.php.

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

◆ 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 279 of file Handler.php.

References MediaWiki\Rest\Handler\$hookContainer.

◆ getHookRunner()

MediaWiki\Rest\Handler::getHookRunner ( )

protected

Get a HookRunner for running core hooks.

Definition at line 291 of file Handler.php.

References MediaWiki\Rest\Handler\$hookRunner.

Referenced by MediaWiki\Rest\Handler\SearchHandler\buildDescriptionsFromPageIdentities(), and MediaWiki\Rest\Handler\SearchHandler\buildThumbnailsFromPageIdentities().

◆ getLastModified()

MediaWiki\Rest\Handler::getLastModified ( )

protected

The subclass should override this to provide the maximum last modified timestamp for the current request.

This is called before execute() in order to decide whether to send a 304.

The timestamp can be in any format accepted by ConvertibleTimestamp, or null to indicate that the timestamp is unknown.

Stable to override

Returns: bool|string|int|float|\DateTime|null

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

Definition at line 307 of file Handler.php.

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

◆ 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.

Stable to override

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

Definition at line 234 of file Handler.php.

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

◆ 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 129 of file Handler.php.

References MediaWiki\Rest\Handler\$request.

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

◆ 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 151 of file Handler.php.

References MediaWiki\Rest\Handler\$responseFactory.

◆ 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 77 of file Handler.php.

References MediaWiki\Rest\Handler\$router.

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 92 of file Handler.php.

References $path, and MediaWiki\Rest\Handler\getConfig().

Referenced by MediaWiki\Rest\Handler\UserContributionsHandler\constructURLs(), and MediaWiki\Rest\Handler\PageHistoryHandler\processDbResults().

◆ 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 269 of file Handler.php.

References MediaWiki\Rest\Handler\$validatedBody.

Referenced by MediaWiki\Rest\Handler\CreationHandler\getActionModuleParameters(), MediaWiki\Rest\Handler\UpdateHandler\getActionModuleParameters(), MediaWiki\Rest\Handler\EditHandler\getActionModuleToken(), MediaWiki\Rest\Handler\UpdateHandler\getConflictData(), 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

Definition at line 257 of file Handler.php.

References MediaWiki\Rest\Handler\$validatedParams.

◆ 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.

Stable to override

Returns: bool|null

Reimplemented in MediaWiki\Rest\Handler\RevisionHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, and MediaWiki\Rest\Handler\LanguageLinksHandler.

Definition at line 337 of file Handler.php.

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

◆ init()

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

final

Initialise with dependencies from the Router.

This is called after construction.

Definition at line 60 of file Handler.php.

References MediaWiki\Rest\Handler\$config, MediaWiki\Rest\Handler\$hookContainer, MediaWiki\Rest\Handler\$request, MediaWiki\Rest\Handler\$responseFactory, MediaWiki\Rest\Handler\$router, and 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.

Stable to override

Returns: bool

Definition at line 352 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 master database access, since only read queries are needed and each master DB is a single point of failure.

Stable to override

Returns: bool

Reimplemented in MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\RevisionHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHistoryCountHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\LatestPageContentHandler, MediaWiki\Rest\Handler\LanguageLinksHandler, and MediaWiki\Rest\Handler\EditHandler.

Definition at line 370 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.

Stable to override

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

Definition at line 380 of file Handler.php.

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

◆ 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 pathes). Encodes pluses (this is not necessary, and may change).

See also: wfUrlencode

Parameters

string $title

Returns: string

Definition at line 111 of file Handler.php.

References $title.

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.

Stable to override

Parameters

Validator $restValidator

Exceptions

HttpException On validation failure.

Definition at line 164 of file Handler.php.

References MediaWiki\Rest\Handler\$validatedBody, MediaWiki\Rest\Handler\$validatedParams, MediaWiki\Rest\Handler\getParamSettings(), MediaWiki\Rest\Validator\Validator\validateBody(), and MediaWiki\Rest\Validator\Validator\validateParams().

Member Data Documentation

◆ $conditionalHeaderUtil

ConditionalHeaderUtil MediaWiki\Rest\Handler::$conditionalHeaderUtil

private

Definition at line 43 of file Handler.php.

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

◆ $config

array MediaWiki\Rest\Handler::$config

private

Definition at line 31 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\SearchHandler\__construct(), MediaWiki\Rest\Handler\getConfig(), and MediaWiki\Rest\Handler\init().

◆ $hookContainer

HookContainer MediaWiki\Rest\Handler::$hookContainer

private

Definition at line 46 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\getHookContainer(), and MediaWiki\Rest\Handler\init().

◆ $hookRunner

HookRunner MediaWiki\Rest\Handler::$hookRunner

private

Definition at line 49 of file Handler.php.

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

◆ $request

RequestInterface MediaWiki\Rest\Handler::$request

private

Definition at line 28 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\ActionModuleBasedHandler\execute(), MediaWiki\Rest\Handler\getRequest(), and MediaWiki\Rest\Handler\init().

◆ $responseFactory

ResponseFactory MediaWiki\Rest\Handler::$responseFactory

private

Definition at line 34 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\getResponseFactory(), and MediaWiki\Rest\Handler\init().

◆ $router

Router MediaWiki\Rest\Handler::$router

private

Definition at line 25 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\getRouter(), and MediaWiki\Rest\Handler\init().

◆ $validatedBody

mixed MediaWiki\Rest\Handler::$validatedBody

private

Definition at line 40 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\getValidatedBody(), and MediaWiki\Rest\Handler\validate().

◆ $validatedParams

array null MediaWiki\Rest\Handler::$validatedParams

private

Definition at line 37 of file Handler.php.

Referenced by MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Handler\getValidatedParams(), and MediaWiki\Rest\Handler\validate().

◆ 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'.

Definition at line 22 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

Public Member Functions

Public Attributes

Protected Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ applyConditionalResponseHeaders()

◆ checkPreconditions()

◆ execute()

◆ getBodyValidator()

◆ getConditionalHeaderUtil()

◆ getConfig()

◆ getETag()

◆ getHookContainer()

◆ getHookRunner()

◆ getLastModified()

◆ getParamSettings()

◆ getRequest()

◆ getResponseFactory()

◆ getRouter()

◆ getRouteUrl()

◆ getValidatedBody()

◆ getValidatedParams()

◆ hasRepresentation()

◆ init()

◆ needsReadAccess()

◆ needsWriteAccess()

◆ postInitSetup()

◆ urlEncodeTitle()

◆ validate()

Member Data Documentation

◆ $conditionalHeaderUtil

◆ $config

◆ $hookContainer

◆ $hookRunner

◆ $request

◆ $responseFactory

◆ $router

◆ $validatedBody

◆ $validatedParams

◆ PARAM_SOURCE