Base class for REST route handlers. More...

Inherited by MediaWiki\Rest\Handler\ActionModuleBasedHandler, MediaWiki\Rest\Handler\CompareHandler, MediaWiki\Rest\Handler\DiscoveryHandler, MediaWiki\Rest\Handler\OpenSearchDescriptionHandler, MediaWiki\Rest\Handler\ParsoidHandler, MediaWiki\Rest\Handler\RedirectHandler, 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.

	getBodyParamSettings ()
	Fetch ParamValidator settings for body fields.

	getBodyValidator ( $contentType)
	Fetch the BodyValidator.

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

	getOpenApiSpec (string $method)
	Returns an OpenAPI Operation Object specification structure as an associative array.

	getParamSettings ()
	Fetch ParamValidator settings for parameters.

	getPath ()
	Returns the path this handler is bound to relative to the module prefix.

	getRequest ()
	Get the current request.

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

	getSession ()
	Get the Session.

	getSupportedPathParams ()
	Get a list of parameter placeholders present in the route's path as returned by getPath().

	getSupportedRequestTypes ()
	Returns the content types that should be accepted by parseBodyData().

	getValidatedBody ()
	Fetch the validated body.

	getValidatedParams ()
	Fetch the validated parameters.

	initContext (Module $module, string $path, array $routeConfig, array $openApiSpec=[])
	Injects information about the handler's context in the Module.

	initForExecute (RequestInterface $request)
	Initialise for execution based on the given request.

	initServices (Authority $authority, ResponseFactory $responseFactory, HookContainer $hookContainer)
	Inject service objects.

	initSession (Session $session)
	Inject session information.

	needsReadAccess ()
	Indicates whether this route requires read rights.

	needsWriteAccess ()
	Indicates whether this route requires write access to the wiki.

	parseBodyData (RequestInterface $request)
	Returns the parsed body of the request.

	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	KNOWN_PARAM_SOURCES = Validator::KNOWN_PARAM_SOURCES

const	OPENAPI_DESCRIPTION_KEY = 'description'

const	PARAM_DESCRIPTION = Validator::PARAM_DESCRIPTION

const	PARAM_SOURCE = Validator::PARAM_SOURCE

Protected Member Functions
	detectExtraneousBodyFields (Validator $restValidator)
	Subclasses may override this to disable or modify checks for extraneous body fields.

	generateResponseSpec (string $method)
	Returns an OpenAPI Responses Object specification structure as an associative array.

	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.

	getJsonLocalizer ()
	Get a JsonLocalizer object.

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

	getModule ()
	Get the Module this handler belongs to.

	getRequestBodySchema (string $mediaType)
	Returns a content schema per the OpenAPI spec.

	getRequestSpec (string $method)
	Returns an OpenAPI Request Body Object specification structure as an associative array.

	getResponseBodySchema (string $method)
	Returns an OpenAPI Schema Object specification structure as an associative array.

	getResponseBodySchemaFileName (string $method)
	Returns the path and name of a JSON file containing an OpenAPI Schema Object specification structure.

	getRouter ()

	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 the init functions are called to inject 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 25 of file Handler.php.

Member Function Documentation

◆ applyCacheControl()

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

Apply cache control to enforce privacy.

Definition at line 559 of file Handler.php.

References MediaWiki\Rest\ResponseInterface\getHeaderLine(), 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 by 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 549 of file Handler.php.

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

◆ checkSession()

MediaWiki\Rest\Handler::checkSession ( )

Check the session (and session provider)

Exceptions

HttpException on failed check

Access: internal

Definition at line 448 of file Handler.php.

◆ detectExtraneousBodyFields()

MediaWiki\Rest\Handler::detectExtraneousBodyFields ( Validator $restValidator )

protected

Subclasses may override this to disable or modify checks for extraneous body fields.

Since: 1.42

Stability: stable: to override

Parameters

Validator $restValidator

Exceptions

HttpException On validation failure.

Definition at line 429 of file Handler.php.

References MediaWiki\Rest\Validator\Validator\detectExtraneousBodyFields().

◆ 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\DiscoveryHandler, MediaWiki\Rest\Handler\OpenSearchDescriptionHandler, MediaWiki\Rest\Handler\ParsoidHandler, MediaWiki\Rest\Handler\RedirectHandler, MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\TransformHandler, and MediaWiki\Rest\SimpleHandler.

◆ generateResponseSpec()

MediaWiki\Rest\Handler::generateResponseSpec ( string $method )

protected

Returns an OpenAPI Responses Object specification structure as an associative array.

See also: https://swagger.io/specification/#responses-object

By default, this will contain basic information response for status 200, 400, and 500. The getResponseBodySchema() method is used to determine the structure of the response for status 200.

Subclasses may override this to provide additional information about the structure of responses.

Parameters

string $method The HTTP method to produce a spec for ("get", "post", etc).

Stability: stable: to override

Returns: array

Reimplemented in MediaWiki\Rest\Handler\EditHandler, MediaWiki\Rest\Handler\OpenSearchDescriptionHandler, MediaWiki\Rest\Handler\PageHTMLHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, and MediaWiki\Rest\Handler\TransformHandler.

Definition at line 839 of file Handler.php.

◆ getAuthority()

MediaWiki\Rest\Handler::getAuthority ( )

Get the current acting authority.

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

Since: 1.36

Returns: Authority

Definition at line 347 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\CompareHandler\execute(), MediaWiki\Rest\Handler\PageHTMLHandler\postValidationSetup(), MediaWiki\Rest\Handler\PageSourceHandler\postValidationSetup(), MediaWiki\Rest\Handler\RevisionHTMLHandler\postValidationSetup(), MediaWiki\Rest\Handler\RevisionSourceHandler\postValidationSetup(), and MediaWiki\Rest\Handler\MediaLinksHandler\run().

◆ getBodyParamSettings()

MediaWiki\Rest\Handler::getBodyParamSettings ( )

Fetch ParamValidator settings for body fields.

Parameters defined by this method are used to validate the request body. The parameter values will become available through getValidatedBody().

Subclasses may override this method to specify what fields they support in the request body. All parameter settings returned by this method must have self::PARAM_SOURCE set to 'body'.

Returns: array[]

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

Definition at line 618 of file Handler.php.

◆ getBodyValidator()

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

Fetch the BodyValidator.

Deprecated: since 1.43, return body properties from getBodyParamSettings(). Subclasses that need full control over body data parsing should override parseBodyData() or implement validation in the execute() method based on the unparsed body data returned by getRequest()->getBody().

Parameters

string $contentType Content type of the request.

Returns: BodyValidator A {

See also: NullBodyValidator} in this default implementation

Exceptions

HttpException It's possible to fail early here when e.g. $contentType is unsupported, or later when {

See also: BodyValidator::validateBody} is called

Definition at line 869 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 491 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 initContext() has not been called.

Definition at line 356 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\RedirectHandler\execute(), 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.

This method should return null if the resource doesn't exist. It may also return null if ETag semantics is not supported by the Handler.

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

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

◆ getJsonLocalizer()

MediaWiki\Rest\Handler::getJsonLocalizer ( )

protected

Get a JsonLocalizer object.

Returns: JsonLocalizer

Definition at line 469 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: 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 1085 of file Handler.php.

◆ getModule()

MediaWiki\Rest\Handler::getModule ( )

protected

Get the Module this handler belongs to.

Will fail hard if called before initContext().

Definition at line 287 of file Handler.php.

◆ getOpenApiSpec()

MediaWiki\Rest\Handler::getOpenApiSpec ( string $method )

Returns an OpenAPI Operation Object specification structure as an associative array.

See also: https://swagger.io/specification/#operation-object

By default, this will contain information about the supported parameters, as well as the response for status 200.

Subclasses may override this to provide additional information.

Since: 1.42

Stability: stable: to override

Parameters

string $method The HTTP method to produce a spec for ("get", "post", etc). Useful for handlers that behave differently depending on the request method.

Returns: array

Definition at line 641 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 the request body as well, by setting self::PARAM_SOURCE to "post". Note that the values of "post" parameters will be accessible through getValidatedParams(). "post" parameters are used with form data (application/x-www-form-urlencoded or multipart/form-data).

For "query" parameters, a PARAM_REQUIRED setting of "false" means the caller does not have to supply the parameter. For "path" parameters, the path matcher will always require the caller to supply all path parameters for a route, regardless of the PARAM_REQUIRED setting. However, "path" parameters may be specified in getParamSettings() as non-required to indicate that the handler services multiple routes, some of which may not supply the parameter.

Stability: stable: to override

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

Definition at line 603 of file Handler.php.

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

◆ getPath()

MediaWiki\Rest\Handler::getPath ( )

Returns the path this handler is bound to relative to the module prefix.

Includes path variables.

Definition at line 258 of file Handler.php.

◆ getRequest()

MediaWiki\Rest\Handler::getRequest ( )

Get the current request.

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

Definition at line 336 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\RedirectHandler\execute(), MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Handler\TransformHandler\getRequestAttributes(), MediaWiki\Rest\Handler\PageHTMLHandler\postValidationSetup(), and MediaWiki\Rest\Handler\RevisionHTMLHandler\postValidationSetup().

◆ getRequestBodySchema()

MediaWiki\Rest\Handler::getRequestBodySchema ( string $mediaType )

protected

Returns a content schema per the OpenAPI spec.

See also: https://swagger.io/specification/#schema-object

Per default, this provides schemas for JSON requests and form data, based on the parameter declarations returned by getParamSettings().

Subclasses may override this to provide additional information about the structure of responses, or to add support for additional mediaTypes.

Stability: stable: to override

Returns: array

Definition at line 739 of file Handler.php.

◆ getRequestSpec()

MediaWiki\Rest\Handler::getRequestSpec ( string $method )

protected

Returns an OpenAPI Request Body Object specification structure as an associative array.

See also: https://swagger.io/specification/#request-body-object

This is based on the getBodyParamSettings() and getSupportedRequestTypes().

Subclasses may override this to provide additional information about the structure of responses, or to add support for additional mediaTypes.

Stability: stable: to override getBodySchema() to generate a schema for each supported media type as returned by getSupportedBodyTypes().

Parameters

string $method

Returns: ?array

Definition at line 703 of file Handler.php.

◆ getResponseBodySchema()

MediaWiki\Rest\Handler::getResponseBodySchema ( string $method )

protected

Returns an OpenAPI Schema Object specification structure as an associative array.

See also: https://swagger.io/specification/#schema-object

Returns null by default. Subclasses that return a JSON response should implement this method to return a schema of the response body.

Parameters

string $method The HTTP method to produce a spec for ("get", "post", etc).

Stability: stable: to override

Returns: ?array

Definition at line 801 of file Handler.php.

◆ getResponseBodySchemaFileName()

MediaWiki\Rest\Handler::getResponseBodySchemaFileName ( string $method )

protected

Returns the path and name of a JSON file containing an OpenAPI Schema Object specification structure.

See also: https://swagger.io/specification/#schema-object

Returns null by default. Subclasses with a suitable JSON file should implement this method.

Parameters

string $method The HTTP method to produce a spec for ("get", "post", etc).

Stability: stable: to override

Since: 1.43

Returns: ?string

Definition at line 820 of file Handler.php.

◆ getResponseFactory()

MediaWiki\Rest\Handler::getResponseFactory ( )

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

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

Definition at line 365 of file Handler.php.

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

◆ getRouter()

MediaWiki\Rest\Handler::getRouter ( )

protected

Definition at line 279 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\RedirectHandler\execute(), 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[]	$pathParams	Path parameters to be injected into the path
string[]	$queryParams	Query parameters to be attached to the URL

Returns: string

Definition at line 302 of file Handler.php.

◆ getSession()

MediaWiki\Rest\Handler::getSession ( )

Get the Session.

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

Definition at line 374 of file Handler.php.

◆ getSupportedPathParams()

MediaWiki\Rest\Handler::getSupportedPathParams ( )

Get a list of parameter placeholders present in the route's path as returned by getPath().

Note that this is independent of the parameters defined by getParamSettings(): required path parameters defined in getParamSettings() should be present in the path, but there is no mechanism to ensure that they are.

Returns: string[]

Definition at line 271 of file Handler.php.

◆ getSupportedRequestTypes()

MediaWiki\Rest\Handler::getSupportedRequestTypes ( )

Returns the content types that should be accepted by parseBodyData().

Subclasses that support request types other than application/json should override this method.

If "application/x-www-form-urlencoded" or "multipart/form-data" are returned, parseBodyData() will use $request->getPostParams() to determine the body data.

Note: The return value of this method is ignored for requests using a method listed in Validator::NO_BODY_METHODS, in particular for the GET method.; for backwards compatibility, the default implementation of this method will examine the parameter definitions returned by getParamSettings() to see if any of the parameters are declared as "post" parameters. If this is the case, support for "application/x-www-form-urlencoded" and "multipart/form-data" is added. This may change in future releases. It is preferred to use "body" parameters and override this method explicitly when support for form data is desired.

Stability: stable: to override

Returns: string[] A list of content-types

Reimplemented in MediaWiki\Rest\Handler\ParsoidHandler.

Definition at line 1024 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\ParsoidHandler\getSupportedRequestTypes().

◆ getValidatedBody()

MediaWiki\Rest\Handler::getValidatedBody ( )

Fetch the validated body.

Returns: mixed|null 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 894 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 882 of file Handler.php.

Referenced by MediaWiki\Rest\SimpleHandler\execute(), 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(), and MediaWiki\Rest\Handler\RevisionSourceHandler\postValidationSetup().

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

If this method returns null, the value returned by getETag() will be used to determine whether the resource exists.

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

◆ initContext()

MediaWiki\Rest\Handler::initContext	(	Module	$module,
		string	$path,
		array	$routeConfig,
		array	$openApiSpec = [] )

final

Injects information about the handler's context in the Module.

The framework should call this right after the object was constructed.

First function of the initialization function, must be called before initServices().

Parameters

Module	$module
string	$path
array	$routeConfig	information about the route declaration.
array	$openApiSpec	OpenAPI meta-data, such as the description.

Access: internal

Definition at line 100 of file Handler.php.

References $path.

◆ initForExecute()

MediaWiki\Rest\Handler::initForExecute ( RequestInterface $request )

final

Initialise for execution based on the given request.

Last function of the initialization function, must be called after initSession() and before validate() and checkPreconditions().

This function will call postInitSetup() to allow subclasses to perform their own initialization.

The request object is updated with parsed body data if needed.

Access: internal

Parameters

RequestInterface $request

Exceptions

HttpException if the handler does not accept the request for some reason.

Definition at line 196 of file Handler.php.

References MediaWiki\Rest\RequestInterface\getParsedBody(), and MediaWiki\Rest\Handler\postInitSetup().

◆ initServices()

MediaWiki\Rest\Handler::initServices	(	Authority	$authority,
		ResponseFactory	$responseFactory,
		HookContainer	$hookContainer )

final

Inject service objects.

Second function of the initialization function, must be called after initContext() and before initSession().

Parameters

Authority	$authority
ResponseFactory	$responseFactory
HookContainer	$hookContainer

Access: internal

Definition at line 129 of file Handler.php.

Referenced by MediaWiki\Rest\Router\prepareHandler().

◆ initSession()

MediaWiki\Rest\Handler::initSession ( Session $session )

final

Inject session information.

Third function of the initialization function, must be called after initServices() and before initForExecute().

Parameters

Session $session

Access: internal

Definition at line 165 of file Handler.php.

Referenced by MediaWiki\Rest\Router\prepareHandler().

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

◆ needsWriteAccess()

MediaWiki\Rest\Handler::needsWriteAccess ( )

Indicates whether this route requires write access to the wiki.

Handlers may override this method to return false if and only if the operation they implement is "safe" per RFC 7231 section 4.2.1. A handler's operation is "safe" if it is essentially read-only, i.e. the client does not request nor expect any state change that would be observable in the responses to future requests.

Implementations of this method must always return the same value, regardless of the parameters passed to the constructor or system state.

Handlers for GET, HEAD, OPTIONS, and TRACE requests should each implement a "safe" operation. Handlers of PUT and DELETE requests should each implement a non-"safe" operation. Note that handlers of POST requests can implement a "safe" operation, particularly in the case where large input parameters are required.

The information provided by this method is used to perform basic authorization checks and to determine whether cross-origin requests are safe.

Stability: stable: to override

Returns: bool

Definition at line 1177 of file Handler.php.

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

◆ parseBodyData()

MediaWiki\Rest\Handler::parseBodyData ( RequestInterface $request )

Returns the parsed body of the request.

Should only be called if $request->hasBody() returns true.

The default implementation handles application/x-www-form-urlencoded and multipart/form-data by calling $request->getPostParams(), if the list returned by getSupportedRequestTypes() includes these types.

The default implementation handles application/json by parsing the body content as JSON. Only object structures (maps) are supported, other types will trigger an HttpException with status 400.

Other content types will trigger a HttpException with status 415 per default.

Subclasses may override this method to support parsing additional content types or to disallow content types by throwing an HttpException with status 415. Subclasses may also return null to indicate that they support reading the content, but intend to handle it as an unparsed stream in their implementation of the execute() method.

Subclasses that override this method to support additional request types should also override getSupportedRequestTypes() to allow that support to be documented in the OpenAPI spec.

Since: 1.42

Exceptions

HttpException If the content type is not supported or the content is malformed.

Returns: array|null The body content represented as an associative array, or null if the request body is accepted unparsed.

Definition at line 931 of file Handler.php.

◆ postInitSetup()

MediaWiki\Rest\Handler::postInitSetup ( )

protected

The handler can override this to do any necessary setup after the init functions are called to inject dependencies.

Stability: stable: to override

Exceptions

HttpException if the handler does not accept the request for some reason.

Reimplemented in MediaWiki\Rest\Handler\SearchHandler.

Definition at line 1207 of file Handler.php.

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

◆ 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 1218 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 1195 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 321 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.

Reimplemented in MediaWiki\Rest\Handler\EditHandler.

Definition at line 387 of file Handler.php.

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

Member Data Documentation

◆ KNOWN_PARAM_SOURCES

const MediaWiki\Rest\Handler::KNOWN_PARAM_SOURCES = Validator::KNOWN_PARAM_SOURCES

See also: Validator::KNOWN_PARAM_SOURCES

Definition at line 30 of file Handler.php.

◆ OPENAPI_DESCRIPTION_KEY

const MediaWiki\Rest\Handler::OPENAPI_DESCRIPTION_KEY = 'description'

Definition at line 42 of file Handler.php.

◆ PARAM_DESCRIPTION

const MediaWiki\Rest\Handler::PARAM_DESCRIPTION = Validator::PARAM_DESCRIPTION

See also: Validator::PARAM_DESCRIPTION

Definition at line 40 of file Handler.php.

Referenced by MediaWiki\Rest\Handler\MediaLinksHandler\getParamSettings(), and MediaWiki\Rest\Handler\TransformHandler\getParamSettings().

◆ PARAM_SOURCE

const MediaWiki\Rest\Handler::PARAM_SOURCE = Validator::PARAM_SOURCE

See also: Validator::PARAM_SOURCE

Definition at line 35 of file Handler.php.

Referenced by MediaWiki\Rest\Validator\Validator\detectExtraneousBodyFields(), MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Validator\Validator\validateBodyParams(), 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

Detailed Description

Member Function Documentation

◆ applyCacheControl()

◆ applyConditionalResponseHeaders()

◆ checkPreconditions()

◆ checkSession()

◆ detectExtraneousBodyFields()

◆ execute()

◆ generateResponseSpec()

◆ getAuthority()

◆ getBodyParamSettings()

◆ getBodyValidator()

◆ getConditionalHeaderUtil()

◆ getConfig()

◆ getETag()

◆ getHookContainer()

◆ getHookRunner()

◆ getJsonLocalizer()

◆ getLastModified()

◆ getModule()

◆ getOpenApiSpec()

◆ getParamSettings()

◆ getPath()

◆ getRequest()

◆ getRequestBodySchema()

◆ getRequestSpec()

◆ getResponseBodySchema()

◆ getResponseBodySchemaFileName()

◆ getResponseFactory()

◆ getRouter()

◆ getRouteUrl()

◆ getSession()

◆ getSupportedPathParams()

◆ getSupportedRequestTypes()

◆ getValidatedBody()

◆ getValidatedParams()

◆ hasRepresentation()

◆ initContext()

◆ initForExecute()

◆ initServices()

◆ initSession()

◆ needsReadAccess()

◆ needsWriteAccess()

◆ parseBodyData()

◆ postInitSetup()

◆ postValidationSetup()

◆ requireSafeAgainstCsrf()

◆ urlEncodeTitle()

◆ validate()

Member Data Documentation

◆ KNOWN_PARAM_SOURCES

◆ OPENAPI_DESCRIPTION_KEY

◆ PARAM_DESCRIPTION

◆ PARAM_SOURCE