MediaWiki
master
|
Base class for REST route handlers. More...
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... | |
checkSession () | |
Check the session (and session provider) 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... | |
getSession () | |
Get the Session. 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, Session $session) | |
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... | |
requireSafeAgainstCsrf () | |
Indicates whether this route can be accessed only by session providers safe vs csrf. 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 |
Session | $session |
mixed | $validatedBody |
array null | $validatedParams |
Base class for REST route handlers.
Definition at line 19 of file Handler.php.
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.
ResponseInterface | $response |
Definition at line 280 of file Handler.php.
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.
Definition at line 260 of file Handler.php.
MediaWiki\Rest\Handler::checkSession | ( | ) |
Check the session (and session provider)
HttpException | on failed check |
Definition at line 215 of file Handler.php.
|
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.
Reimplemented in MediaWiki\Rest\SimpleHandler, MediaWiki\Rest\Handler\UserContributionsHandler, MediaWiki\Rest\Handler\TransformHandler, MediaWiki\Rest\Handler\SearchHandler, MediaWiki\Rest\Handler\ParsoidHandler, MediaWiki\Rest\Handler\ContributionsCountHandler, MediaWiki\Rest\Handler\CompareHandler, and MediaWiki\Rest\Handler\ActionModuleBasedHandler.
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.
Definition at line 156 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\SearchHandler\buildSinglePage(), 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\MediaFileHandler\getFile(), 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\MediaLinksHandler\run(), MediaWiki\Rest\Handler\PageHistoryHandler\run(), and MediaWiki\Rest\Handler\PageHistoryCountHandler\run().
MediaWiki\Rest\Handler::getBodyValidator | ( | $contentType | ) |
Fetch the BodyValidator.
string | $contentType | Content type of the request. |
Reimplemented in MediaWiki\Rest\Handler\UpdateHandler, and MediaWiki\Rest\Handler\CreationHandler.
Definition at line 311 of file Handler.php.
Referenced by MediaWiki\Rest\Validator\Validator\validateBody().
|
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().
Definition at line 240 of file Handler.php.
References MediaWiki\Rest\ConditionalHeaderUtil\setValidators().
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.
Definition at line 167 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\AbstractContributionHandler\postInitSetup(), and MediaWiki\Rest\Handler\SearchHandler\postInitSetup().
|
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.
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 389 of file Handler.php.
|
protected |
Get a HookContainer, for running extension hooks or for hook metadata.
Definition at line 344 of file Handler.php.
|
protected |
Get a HookRunner for running core hooks.
Definition at line 356 of file Handler.php.
|
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.
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 372 of file Handler.php.
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().
Reimplemented in MediaWiki\Rest\Handler\UserContributionsHandler, MediaWiki\Rest\Handler\UpdateHandler, MediaWiki\Rest\Handler\TransformHandler, 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 299 of file Handler.php.
Referenced by MediaWiki\Rest\SimpleHandler\execute().
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.
Definition at line 145 of file Handler.php.
Referenced by MediaWiki\Rest\SimpleHandler\execute().
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.
Definition at line 178 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\ActionModuleBasedHandler\execute(), MediaWiki\Rest\Handler\CompareHandler\execute(), MediaWiki\Rest\Handler\LanguageLinksHandler\run(), MediaWiki\Rest\Handler\MediaLinksHandler\run(), MediaWiki\Rest\Handler\PageHistoryHandler\run(), MediaWiki\Rest\Handler\PageHistoryCountHandler\run(), and MediaWiki\Rest\Handler\RevisionSourceHandler\run().
|
protected |
Get the Router.
The return type declaration causes it to raise a fatal error if init() has not yet been called.
Definition at line 94 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\CreationHandler\mapActionModuleResponse().
|
protected |
Get the URL of this handler's endpoint.
Supports the substitution of path parameters, and additions of query parameters.
string[] | $pathParams | Path parameters to be injected into the path |
string[] | $queryParams | Query parameters to be attached to the URL |
Definition at line 109 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\PageHistoryHandler\processDbResults().
MediaWiki\Rest\Handler::getSession | ( | ) |
Get the Session.
This will raise a fatal error if init() has not been called.
Definition at line 189 of file Handler.php.
MediaWiki\Rest\Handler::getValidatedBody | ( | ) |
Fetch the validated body.
Definition at line 334 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\CreationHandler\getActionModuleParameters(), MediaWiki\Rest\Handler\UpdateHandler\getActionModuleParameters(), MediaWiki\Rest\Handler\UpdateHandler\getConflictData(), and MediaWiki\Rest\Handler\CreationHandler\getTitleParameter().
MediaWiki\Rest\Handler::getValidatedParams | ( | ) |
Fetch the validated parameters.
This must be called after validate() is called. During execute() is fine.
Definition at line 322 of file Handler.php.
Referenced by 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().
|
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.
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 402 of file Handler.php.
|
final |
Initialise with dependencies from the Router.
This is called after construction.
Router | $router | |
RequestInterface | $request | |
array | $config | |
Authority | $authority | |
ResponseFactory | $responseFactory | |
HookContainer | $hookContainer | |
Session | $session |
Definition at line 74 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, MediaWiki\Rest\Handler\$session, and MediaWiki\Rest\Handler\postInitSetup().
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.
Definition at line 417 of file Handler.php.
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.
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 435 of file Handler.php.
Referenced by MediaWiki\Rest\CorsUtils\authorize().
|
protected |
The handler can override this to do any necessary setup after init() is called to inject the dependencies.
Reimplemented in MediaWiki\Rest\Handler\SearchHandler, and MediaWiki\Rest\Handler\AbstractContributionHandler.
Definition at line 463 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\init().
|
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().
Reimplemented in MediaWiki\Rest\Handler\RevisionSourceHandler, MediaWiki\Rest\Handler\RevisionHTMLHandler, MediaWiki\Rest\Handler\PageSourceHandler, and MediaWiki\Rest\Handler\PageHTMLHandler.
Definition at line 474 of file Handler.php.
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.
Definition at line 453 of file Handler.php.
|
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).
string | $title |
Definition at line 128 of file Handler.php.
References $title.
Referenced by MediaWiki\Rest\Handler\CreationHandler\mapActionModuleResponse().
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.
Validator | $restValidator |
HttpException | On validation failure. |
Definition at line 202 of file Handler.php.
References MediaWiki\Rest\Validator\Validator\validateBody(), and MediaWiki\Rest\Validator\Validator\validateParams().
|
private |
Definition at line 37 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\init().
|
private |
Definition at line 52 of file Handler.php.
|
private |
Definition at line 40 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\PageSourceHandler\__construct(), MediaWiki\Rest\Handler\RevisionSourceHandler\__construct(), MediaWiki\Rest\Handler\PageHTMLHandler\__construct(), MediaWiki\Rest\Handler\RevisionHTMLHandler\__construct(), MediaWiki\Rest\Handler\SearchHandler\__construct(), and MediaWiki\Rest\Handler\init().
|
private |
Definition at line 55 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\init().
|
private |
Definition at line 61 of file Handler.php.
|
private |
Definition at line 34 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\ActionModuleBasedHandler\execute(), and MediaWiki\Rest\Handler\init().
|
private |
Definition at line 43 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\init().
|
private |
Definition at line 31 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\init().
|
private |
Definition at line 58 of file Handler.php.
Referenced by MediaWiki\Rest\Handler\ActionModuleBasedHandler\getApiMain(), and MediaWiki\Rest\Handler\init().
|
private |
Definition at line 49 of file Handler.php.
|
private |
Definition at line 46 of file Handler.php.
Referenced by MediaWiki\Rest\SimpleHandler\execute().
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 28 of file Handler.php.
Referenced by MediaWiki\Rest\SimpleHandler\execute(), MediaWiki\Rest\Handler\CompareHandler\getParamSettings(), and MediaWiki\Rest\Validator\Validator\validateParams().