MediaWiki  master
MediaWiki\Rest\Handler Class Reference

Base class for REST route handlers. More...

Inheritance diagram for MediaWiki\Rest\Handler:
Collaboration diagram for MediaWiki\Rest\Handler:

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...
 
 getAuthority ()
 Get the current acting authority. 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, Authority $authority, 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...
 
 postValidationSetup ()
 The handler can override this to do any necessary setup after validate() has been called. More...
 
 urlEncodeTitle ( $title)
 URL-encode titles in a "pretty" way. More...
 

Private Attributes

Authority $authority
 
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.

Stability: stable
to extend.

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

Stability: stable
to override
Parameters
ResponseInterface$response

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

Stability: stable
to override
Returns
ResponseInterface|null

Definition at line 220 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 \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\SimpleHandler, MediaWiki\Rest\Handler\UserContributionsHandler, MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\ContributionsCountHandler, MediaWiki\Rest\Handler\CompareHandler, and MediaWiki\Rest\Handler\ActionModuleBasedHandler.

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

References MediaWiki\Rest\Handler\$authority.

Referenced by MediaWiki\Rest\Handler\SearchHandler\buildPageInfosFromSearchResults(), MediaWiki\Rest\Handler\SearchHandler\buildPageInfosFromSuggestions(), MediaWiki\Rest\Handler\CompareHandler\execute(), MediaWiki\Rest\Handler\ContributionsCountHandler\execute(), MediaWiki\Rest\Handler\UserContributionsHandler\execute(), MediaWiki\Rest\Handler\PageHistoryHandler\getBitmask(), MediaWiki\Rest\Handler\UpdateHandler\getConflictData(), MediaWiki\Rest\Handler\PageHistoryCountHandler\getEditorsCount(), MediaWiki\Rest\Handler\MediaFileHandler\getFile(), MediaWiki\Rest\Handler\MediaFileHandler\getResponse(), MediaWiki\Rest\Handler\CompareHandler\getRevisionText(), MediaWiki\Rest\Handler\AbstractContributionHandler\getTargetUser(), MediaWiki\Rest\Handler\CompareHandler\isAccessible(), MediaWiki\Rest\Handler\PageHTMLHandler\postValidationSetup(), MediaWiki\Rest\Handler\PageSourceHandler\postValidationSetup(), MediaWiki\Rest\Handler\RevisionHTMLHandler\postValidationSetup(), MediaWiki\Rest\Handler\RevisionSourceHandler\postValidationSetup(), MediaWiki\Rest\Handler\PageHistoryHandler\processDbResults(), MediaWiki\Rest\Handler\MediaLinksHandler\processDbResults(), MediaWiki\Rest\Handler\LanguageLinksHandler\run(), MediaWiki\Rest\Handler\MediaFileHandler\run(), MediaWiki\Rest\Handler\MediaLinksHandler\run(), MediaWiki\Rest\Handler\PageHistoryHandler\run(), and MediaWiki\Rest\Handler\PageHistoryCountHandler\run().

◆ getBodyValidator()

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

Fetch the BodyValidator.

Stability: stable
to override
Parameters
string$contentTypeContent type of the request.
Returns
BodyValidator

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

Definition at line 271 of file Handler.php.

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

◆ getConditionalHeaderUtil()

◆ getConfig()

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

Stability: stable
to override
Returns
string|null

Reimplemented in MediaWiki\Rest\Handler\RevisionSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, 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 349 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 304 of file Handler.php.

References MediaWiki\Rest\Handler\$hookContainer.

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

Stability: stable
to override
Returns
bool|string|int|float|\DateTime|null

Reimplemented in MediaWiki\Rest\Handler\RevisionSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, 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 332 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.

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\UserContributionsHandler, MediaWiki\Rest\Handler\UpdateHandler, MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\RevisionSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHistoryCountHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\LanguageLinksHandler, MediaWiki\Rest\Handler\ContributionsCountHandler, and MediaWiki\Rest\Handler\CompareHandler.

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

References MediaWiki\Rest\Handler\$request.

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

◆ getResponseFactory()

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

References MediaWiki\Rest\Handler\$router.

Referenced by MediaWiki\Rest\Handler\PageSourceHandler\constructHtmlUrl(), MediaWiki\Rest\Handler\RevisionSourceHandler\constructHtmlUrl(), and 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[]$pathParamsPath parameters to be injected into the path
string[]$queryParamsQuery parameters to be attached to the URL
Returns
string

Definition at line 101 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 294 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 282 of file Handler.php.

References MediaWiki\Rest\Handler\$validatedParams.

Referenced by MediaWiki\Rest\Handler\UserContributionsHandler\constructURLs(), MediaWiki\Rest\Handler\SearchHandler\createSearchEngine(), MediaWiki\Rest\Handler\SearchHandler\doSearch(), MediaWiki\Rest\Handler\ContributionsCountHandler\execute(), MediaWiki\Rest\Handler\UserContributionsHandler\execute(), MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Handler\UpdateHandler\getConflictData(), MediaWiki\Rest\Handler\PageHistoryCountHandler\getCount(), MediaWiki\Rest\Handler\LanguageLinksHandler\getPage(), MediaWiki\Rest\Handler\MediaFileHandler\getPage(), MediaWiki\Rest\Handler\MediaLinksHandler\getPage(), MediaWiki\Rest\Handler\PageHistoryCountHandler\getPage(), MediaWiki\Rest\Handler\PageHistoryHandler\getPage(), MediaWiki\Rest\Handler\CompareHandler\getRevision(), 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(), MediaWiki\Rest\Handler\PageHistoryHandler\run(), and MediaWiki\Rest\Handler\PageHistoryCountHandler\validateParameterCombination().

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

Stability: stable
to override
Returns
bool|null

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

Definition at line 362 of file Handler.php.

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

◆ init()

MediaWiki\Rest\Handler::init ( Router  $router,
RequestInterface  $request,
array  $config,
Authority  $authority,
ResponseFactory  $responseFactory,
HookContainer  $hookContainer 
)
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
Access: internal

Definition at line 68 of file Handler.php.

References MediaWiki\Rest\Handler\$authority, 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.

Stability: stable
to override
Returns
bool

Definition at line 377 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\SearchHandler, MediaWiki\Rest\Handler\RevisionSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\PageHistoryHandler, MediaWiki\Rest\Handler\PageHistoryCountHandler, MediaWiki\Rest\Handler\MediaLinksHandler, MediaWiki\Rest\Handler\MediaFileHandler, MediaWiki\Rest\Handler\LanguageLinksHandler, and MediaWiki\Rest\Handler\EditHandler.

Definition at line 395 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\SearchHandler, and MediaWiki\Rest\Handler\AbstractContributionHandler.

Definition at line 405 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\RevisionSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, and MediaWiki\Rest\Handler\PageHTMLHandler.

Definition at line 416 of file Handler.php.

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

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

Stability: stable
to override
Parameters
Validator$restValidator
Exceptions
HttpExceptionOn validation failure.

Definition at line 183 of file Handler.php.

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

Member Data Documentation

◆ $authority

Authority MediaWiki\Rest\Handler::$authority
private

Definition at line 35 of file Handler.php.

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

◆ $conditionalHeaderUtil

ConditionalHeaderUtil MediaWiki\Rest\Handler::$conditionalHeaderUtil
private

Definition at line 50 of file Handler.php.

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

◆ $config

◆ $hookContainer

HookContainer MediaWiki\Rest\Handler::$hookContainer
private

◆ $hookRunner

HookRunner MediaWiki\Rest\Handler::$hookRunner
private

Definition at line 56 of file Handler.php.

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

◆ $request

◆ $responseFactory

ResponseFactory MediaWiki\Rest\Handler::$responseFactory
private

◆ $router

Router MediaWiki\Rest\Handler::$router
private

Definition at line 29 of file Handler.php.

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

◆ $validatedBody

mixed MediaWiki\Rest\Handler::$validatedBody
private

◆ $validatedParams

array null MediaWiki\Rest\Handler::$validatedParams
private

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

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


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