MediaWiki  master
Handler.php
Go to the documentation of this file.
1 <?php
2 
3 namespace MediaWiki\Rest;
4 
10 
16 abstract class Handler {
17 
22  public const PARAM_SOURCE = 'rest-param-source';
23 
25  private $router;
26 
28  private $request;
29 
31  private $config;
32 
35 
38 
40  private $validatedBody;
41 
44 
46  private $hookContainer;
47 
49  private $hookRunner;
50 
60  final public function init( Router $router, RequestInterface $request, array $config,
62  ) {
63  $this->router = $router;
64  $this->request = $request;
65  $this->config = $config;
66  $this->responseFactory = $responseFactory;
67  $this->hookContainer = $hookContainer;
68  $this->hookRunner = new HookRunner( $hookContainer );
69  $this->postInitSetup();
70  }
71 
77  protected function getRouter(): Router {
78  return $this->router;
79  }
80 
92  protected function getRouteUrl( $pathParams = [], $queryParams = [] ): string {
93  $path = $this->getConfig()['path'];
94  return $this->router->getRouteUrl( $path, $pathParams, $queryParams );
95  }
96 
111  protected function urlEncodeTitle( $title ) {
112  $title = str_replace( ' ', '_', $title );
113  $title = urlencode( $title );
114 
115  // %3B_a_%40_b_%24_c_%21_d_%2A_e_%28_f_%29_g_%2C_h_~_i_%3A
116  $replace = [ '%3B', '%40', '%24', '%21', '%2A', '%28', '%29', '%2C', '%7E', '%3A' ];
117  $with = [ ';', '@', '$', '!', '*', '(', ')', ',', '~', ':' ];
118  $title = str_replace( $replace, $with, $title );
119 
120  return $title;
121  }
122 
129  public function getRequest(): RequestInterface {
130  return $this->request;
131  }
132 
140  public function getConfig(): array {
141  return $this->config;
142  }
143 
151  public function getResponseFactory(): ResponseFactory {
152  return $this->responseFactory;
153  }
154 
164  public function validate( Validator $restValidator ) {
165  $validatedParams = $restValidator->validateParams( $this->getParamSettings() );
166  $validatedBody = $restValidator->validateBody( $this->request, $this );
167  $this->validatedParams = $validatedParams;
168  $this->validatedBody = $validatedBody;
169  }
170 
180  protected function getConditionalHeaderUtil() {
181  if ( $this->conditionalHeaderUtil === null ) {
182  $this->conditionalHeaderUtil = new ConditionalHeaderUtil;
183  $this->conditionalHeaderUtil->setValidators(
184  $this->getETag(),
185  $this->getLastModified(),
186  $this->hasRepresentation() );
187  }
189  }
190 
199  public function checkPreconditions() {
200  $status = $this->getConditionalHeaderUtil()->checkPreconditions( $this->getRequest() );
201  if ( $status ) {
202  $response = $this->getResponseFactory()->create();
203  $response->setStatus( $status );
204  return $response;
205  } else {
206  return null;
207  }
208  }
209 
219  public function applyConditionalResponseHeaders( ResponseInterface $response ) {
220  $this->getConditionalHeaderUtil()->applyResponseHeaders( $response );
221  }
222 
234  public function getParamSettings() {
235  return [];
236  }
237 
246  public function getBodyValidator( $contentType ) {
247  return new NullBodyValidator();
248  }
249 
257  public function getValidatedParams() {
258  if ( $this->validatedParams === null ) {
259  throw new \RuntimeException( 'getValidatedParams() called before validate()' );
260  }
261  return $this->validatedParams;
262  }
263 
269  public function getValidatedBody() {
270  return $this->validatedBody;
271  }
272 
279  protected function getHookContainer() {
280  return $this->hookContainer;
281  }
282 
291  protected function getHookRunner() {
292  return $this->hookRunner;
293  }
294 
307  protected function getLastModified() {
308  return null;
309  }
310 
324  protected function getETag() {
325  return null;
326  }
327 
337  protected function hasRepresentation() {
338  return null;
339  }
340 
352  public function needsReadAccess() {
353  return true;
354  }
355 
370  public function needsWriteAccess() {
371  return true;
372  }
373 
380  protected function postInitSetup() {
381  }
382 
398  abstract public function execute();
399 }
MediaWiki\Rest\Handler\init
init(Router $router, RequestInterface $request, array $config, ResponseFactory $responseFactory, HookContainer $hookContainer)
Initialise with dependencies from the Router.
Definition: Handler.php:60
MediaWiki\Rest\ResponseFactory
Generates standardized response objects.
Definition: ResponseFactory.php:17
MediaWiki\Rest\Handler\$hookContainer
HookContainer $hookContainer
Definition: Handler.php:46
MediaWiki\Rest\Validator\Validator
Wrapper for ParamValidator.
Definition: Validator.php:33
MediaWiki\Rest\Handler\getResponseFactory
getResponseFactory()
Get the ResponseFactory which can be used to generate Response objects.
Definition: Handler.php:151
MediaWiki\Rest\Handler\getParamSettings
getParamSettings()
Fetch ParamValidator settings for parameters.
Definition: Handler.php:234
MediaWiki\Rest\Handler\getETag
getETag()
The subclass should override this to provide an ETag for the current request.
Definition: Handler.php:324
MediaWiki\Rest\Handler\$router
Router $router
Definition: Handler.php:25
MediaWiki\Rest\Handler\$request
RequestInterface $request
Definition: Handler.php:28
MediaWiki\Rest\Handler\PARAM_SOURCE
const PARAM_SOURCE
(string) ParamValidator constant to specify the source of the parameter.
Definition: Handler.php:22
MediaWiki\Rest\Handler\applyConditionalResponseHeaders
applyConditionalResponseHeaders(ResponseInterface $response)
Modify the response, adding Last-Modified and ETag headers as indicated the values previously returne...
Definition: Handler.php:219
MediaWiki\Rest\Handler\postInitSetup
postInitSetup()
The handler can override this to do any necessary setup after init() is called to inject the dependen...
Definition: Handler.php:380
MediaWiki\Rest\Handler\validate
validate(Validator $restValidator)
Validate the request parameters/attributes and body.
Definition: Handler.php:164
MediaWiki\Rest\Handler\execute
execute()
Execute the handler.
MediaWiki\Rest\Handler
Base class for REST route handlers.
Definition: Handler.php:16
MediaWiki\Rest\Validator\BodyValidator
Interface for validating a request body.
Definition: BodyValidator.php:13
MediaWiki\Rest\Handler\$validatedBody
mixed $validatedBody
Definition: Handler.php:40
MediaWiki\Rest\Router
The REST router is responsible for gathering handler configuration, matching an input path and HTTP m...
Definition: Router.php:19
MediaWiki\Rest\Validator\Validator\validateParams
validateParams(array $paramSettings)
Validate parameters.
Definition: Validator.php:106
MediaWiki\Rest\Handler\getHookContainer
getHookContainer()
Get a HookContainer, for running extension hooks or for hook metadata.
Definition: Handler.php:279
MediaWiki\Rest\Handler\checkPreconditions
checkPreconditions()
Check the conditional request headers and generate a response if appropriate.
Definition: Handler.php:199
MediaWiki\Rest\Handler\getValidatedBody
getValidatedBody()
Fetch the validated body.
Definition: Handler.php:269
MediaWiki\Rest\Handler\getRouteUrl
getRouteUrl( $pathParams=[], $queryParams=[])
Get the URL of this handler's endpoint.
Definition: Handler.php:92
$title
$title
Definition: testCompression.php:38
MediaWiki\Rest\Handler\getValidatedParams
getValidatedParams()
Fetch the validated parameters.
Definition: Handler.php:257
MediaWiki\Rest
MediaWiki\Rest\Handler\getConfig
getConfig()
Get the configuration array for the current route.
Definition: Handler.php:140
MediaWiki\Rest\Handler\getHookRunner
getHookRunner()
Get a HookRunner for running core hooks.
Definition: Handler.php:291
MediaWiki\Rest\Handler\$config
array $config
Definition: Handler.php:31
MediaWiki\Rest\ResponseInterface
An interface similar to PSR-7's ResponseInterface, the primary difference being that it is mutable.
Definition: ResponseInterface.php:41
MediaWiki\Rest\Handler\$conditionalHeaderUtil
ConditionalHeaderUtil $conditionalHeaderUtil
Definition: Handler.php:43
MediaWiki\Rest\Validator\NullBodyValidator
Do-nothing body validator.
Definition: NullBodyValidator.php:10
MediaWiki\Rest\Handler\needsWriteAccess
needsWriteAccess()
Indicates whether this route requires write access.
Definition: Handler.php:370
MediaWiki\Rest\Handler\$responseFactory
ResponseFactory $responseFactory
Definition: Handler.php:34
MediaWiki\Rest\ConditionalHeaderUtil
Definition: ConditionalHeaderUtil.php:9
MediaWiki\Rest\RequestInterface
A request interface similar to PSR-7's ServerRequestInterface.
Definition: RequestInterface.php:39
MediaWiki\Rest\Handler\getRequest
getRequest()
Get the current request.
Definition: Handler.php:129
MediaWiki\Rest\Handler\$hookRunner
HookRunner $hookRunner
Definition: Handler.php:49
MediaWiki\Rest\Handler\hasRepresentation
hasRepresentation()
The subclass should override this to indicate whether the resource exists.
Definition: Handler.php:337
MediaWiki\Rest\Validator\Validator\validateBody
validateBody(RequestInterface $request, Handler $handler)
Validate the body of a request.
Definition: Validator.php:138
MediaWiki\Rest\Handler\getLastModified
getLastModified()
The subclass should override this to provide the maximum last modified timestamp for the current requ...
Definition: Handler.php:307
$path
$path
Definition: NoLocalSettings.php:25
MediaWiki\Rest\Handler\urlEncodeTitle
urlEncodeTitle( $title)
URL-encode titles in a "pretty" way.
Definition: Handler.php:111
MediaWiki\HookContainer\HookContainer
HookContainer class.
Definition: HookContainer.php:45
MediaWiki\HookContainer\HookRunner
This class provides an implementation of the core hook interfaces, forwarding hook calls to HookConta...
Definition: HookRunner.php:567
MediaWiki\Rest\Handler\getRouter
getRouter()
Get the Router.
Definition: Handler.php:77
MediaWiki\Rest\Handler\getConditionalHeaderUtil
getConditionalHeaderUtil()
Get a ConditionalHeaderUtil object.
Definition: Handler.php:180
MediaWiki\Rest\Handler\$validatedParams
array null $validatedParams
Definition: Handler.php:37
MediaWiki\Rest\Handler\needsReadAccess
needsReadAccess()
Indicates whether this route requires read rights.
Definition: Handler.php:352
MediaWiki\Rest\Handler\getBodyValidator
getBodyValidator( $contentType)
Fetch the BodyValidator.
Definition: Handler.php:246
MediaWiki\Rest\ConditionalHeaderUtil\setValidators
setValidators( $eTag, $lastModified, $hasRepresentation)
Initialize the object with information about the requested resource.
Definition: ConditionalHeaderUtil.php:29