MediaWiki  master
Handler.php
Go to the documentation of this file.
1 <?php
2 
3 namespace MediaWiki\Rest;
4 
11 
17 abstract class Handler {
18 
26  public const PARAM_SOURCE = 'rest-param-source';
27 
29  private $router;
30 
32  private $request;
33 
35  private $authority;
36 
38  private $config;
39 
42 
45 
47  private $validatedBody;
48 
51 
53  private $hookContainer;
54 
56  private $hookRunner;
57 
68  final public function init( Router $router, RequestInterface $request, array $config,
70  ) {
71  $this->router = $router;
72  $this->request = $request;
73  $this->authority = $authority;
74  $this->config = $config;
75  $this->responseFactory = $responseFactory;
76  $this->hookContainer = $hookContainer;
77  $this->hookRunner = new HookRunner( $hookContainer );
78  $this->postInitSetup();
79  }
80 
86  protected function getRouter(): Router {
87  return $this->router;
88  }
89 
101  protected function getRouteUrl( $pathParams = [], $queryParams = [] ): string {
102  $path = $this->getConfig()['path'];
103  return $this->router->getRouteUrl( $path, $pathParams, $queryParams );
104  }
105 
120  protected function urlEncodeTitle( $title ) {
121  $title = str_replace( ' ', '_', $title );
122  $title = urlencode( $title );
123 
124  // %3B_a_%40_b_%24_c_%21_d_%2A_e_%28_f_%29_g_%2C_h_~_i_%3A
125  $replace = [ '%3B', '%40', '%24', '%21', '%2A', '%28', '%29', '%2C', '%7E', '%3A' ];
126  $with = [ ';', '@', '$', '!', '*', '(', ')', ',', '~', ':' ];
127 
128  return str_replace( $replace, $with, $title );
129  }
130 
137  public function getRequest(): RequestInterface {
138  return $this->request;
139  }
140 
148  public function getAuthority(): Authority {
149  return $this->authority;
150  }
151 
159  public function getConfig(): array {
160  return $this->config;
161  }
162 
170  public function getResponseFactory(): ResponseFactory {
171  return $this->responseFactory;
172  }
173 
183  public function validate( Validator $restValidator ) {
184  $validatedParams = $restValidator->validateParams( $this->getParamSettings() );
185  $validatedBody = $restValidator->validateBody( $this->request, $this );
186  $this->validatedParams = $validatedParams;
187  $this->validatedBody = $validatedBody;
188  $this->postValidationSetup();
189  }
190 
200  protected function getConditionalHeaderUtil() {
201  if ( $this->conditionalHeaderUtil === null ) {
202  $this->conditionalHeaderUtil = new ConditionalHeaderUtil;
203  $this->conditionalHeaderUtil->setValidators(
204  $this->getETag(),
205  $this->getLastModified(),
206  $this->hasRepresentation()
207  );
208  }
210  }
211 
220  public function checkPreconditions() {
221  $status = $this->getConditionalHeaderUtil()->checkPreconditions( $this->getRequest() );
222  if ( $status ) {
223  $response = $this->getResponseFactory()->create();
224  $response->setStatus( $status );
225  return $response;
226  }
227 
228  return null;
229  }
230 
240  public function applyConditionalResponseHeaders( ResponseInterface $response ) {
241  $this->getConditionalHeaderUtil()->applyResponseHeaders( $response );
242  }
243 
259  public function getParamSettings() {
260  return [];
261  }
262 
271  public function getBodyValidator( $contentType ) {
272  return new NullBodyValidator();
273  }
274 
282  public function getValidatedParams() {
283  if ( $this->validatedParams === null ) {
284  throw new \RuntimeException( 'getValidatedParams() called before validate()' );
285  }
286  return $this->validatedParams;
287  }
288 
294  public function getValidatedBody() {
295  return $this->validatedBody;
296  }
297 
304  protected function getHookContainer() {
305  return $this->hookContainer;
306  }
307 
316  protected function getHookRunner() {
317  return $this->hookRunner;
318  }
319 
332  protected function getLastModified() {
333  return null;
334  }
335 
349  protected function getETag() {
350  return null;
351  }
352 
362  protected function hasRepresentation() {
363  return null;
364  }
365 
377  public function needsReadAccess() {
378  return true;
379  }
380 
395  public function needsWriteAccess() {
396  return true;
397  }
398 
405  protected function postInitSetup() {
406  }
407 
416  protected function postValidationSetup() {
417  }
418 
435  abstract public function execute();
436 }
MediaWiki\Rest\ResponseFactory
Generates standardized response objects.
Definition: ResponseFactory.php:17
MediaWiki\Rest\Handler\$hookContainer
HookContainer $hookContainer
Definition: Handler.php:53
MediaWiki\Rest\Handler\$authority
Authority $authority
Definition: Handler.php:35
MediaWiki\Rest\Validator\Validator
Wrapper for ParamValidator.
Definition: Validator.php:32
MediaWiki\Rest\Handler\getResponseFactory
getResponseFactory()
Get the ResponseFactory which can be used to generate Response objects.
Definition: Handler.php:170
MediaWiki\Rest\Handler\getParamSettings
getParamSettings()
Fetch ParamValidator settings for parameters.
Definition: Handler.php:259
MediaWiki\Rest\Handler\getETag
getETag()
The subclass should override this to provide an ETag for the current request.
Definition: Handler.php:349
MediaWiki\Rest\Handler\$router
Router $router
Definition: Handler.php:29
MediaWiki\Rest\Handler\$request
RequestInterface $request
Definition: Handler.php:32
MediaWiki\Rest\Handler\PARAM_SOURCE
const PARAM_SOURCE
(string) ParamValidator constant to specify the source of the parameter.
Definition: Handler.php:26
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:240
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:405
MediaWiki\Rest\Handler\validate
validate(Validator $restValidator)
Validate the request parameters/attributes and body.
Definition: Handler.php:183
MediaWiki\Rest\Handler\execute
execute()
Execute the handler.
MediaWiki\Rest\Handler
Base class for REST route handlers.
Definition: Handler.php:17
MediaWiki\Rest\Validator\BodyValidator
Interface for validating a request body.
Definition: BodyValidator.php:14
MediaWiki\Rest\Handler\$validatedBody
mixed $validatedBody
Definition: Handler.php:47
MediaWiki\Rest\Router
The REST router is responsible for gathering handler configuration, matching an input path and HTTP m...
Definition: Router.php:20
MediaWiki\Rest\Validator\Validator\validateParams
validateParams(array $paramSettings)
Validate parameters.
Definition: Validator.php:103
MediaWiki\Rest\Handler\getHookContainer
getHookContainer()
Get a HookContainer, for running extension hooks or for hook metadata.
Definition: Handler.php:304
MediaWiki\Rest\Handler\checkPreconditions
checkPreconditions()
Check the conditional request headers and generate a response if appropriate.
Definition: Handler.php:220
MediaWiki\Rest\Handler\getValidatedBody
getValidatedBody()
Fetch the validated body.
Definition: Handler.php:294
MediaWiki\Rest\Handler\getRouteUrl
getRouteUrl( $pathParams=[], $queryParams=[])
Get the URL of this handler's endpoint.
Definition: Handler.php:101
MediaWiki\Rest\Handler\postValidationSetup
postValidationSetup()
The handler can override this to do any necessary setup after validate() has been called.
Definition: Handler.php:416
$title
$title
Definition: testCompression.php:38
MediaWiki\Rest\Handler\getValidatedParams
getValidatedParams()
Fetch the validated parameters.
Definition: Handler.php:282
MediaWiki\Rest
MediaWiki\Permissions\Authority
This interface represents the authority associated the current execution context, such as a web reque...
Definition: Authority.php:37
MediaWiki\Rest\Handler\getConfig
getConfig()
Get the configuration array for the current route.
Definition: Handler.php:159
MediaWiki\Rest\Handler\getHookRunner
getHookRunner()
Get a HookRunner for running core hooks.
Definition: Handler.php:316
MediaWiki\Rest\Handler\$config
array $config
Definition: Handler.php:38
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:50
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:395
MediaWiki\Rest\Handler\$responseFactory
ResponseFactory $responseFactory
Definition: Handler.php:41
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:137
MediaWiki\Rest\Handler\$hookRunner
HookRunner $hookRunner
Definition: Handler.php:56
MediaWiki\Rest\Handler\hasRepresentation
hasRepresentation()
The subclass should override this to indicate whether the resource exists.
Definition: Handler.php:362
MediaWiki\Rest\Validator\Validator\validateBody
validateBody(RequestInterface $request, Handler $handler)
Validate the body of a request.
Definition: Validator.php:135
MediaWiki\Rest\Handler\getLastModified
getLastModified()
The subclass should override this to provide the maximum last modified timestamp for the current requ...
Definition: Handler.php:332
$path
$path
Definition: NoLocalSettings.php:25
MediaWiki\Rest\Handler\urlEncodeTitle
urlEncodeTitle( $title)
URL-encode titles in a "pretty" way.
Definition: Handler.php:120
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:557
MediaWiki\Rest\Handler\getRouter
getRouter()
Get the Router.
Definition: Handler.php:86
MediaWiki\Rest\Handler\getAuthority
getAuthority()
Get the current acting authority.
Definition: Handler.php:148
MediaWiki\Rest\Handler\getConditionalHeaderUtil
getConditionalHeaderUtil()
Get a ConditionalHeaderUtil object.
Definition: Handler.php:200
MediaWiki\Rest\Handler\$validatedParams
array null $validatedParams
Definition: Handler.php:44
MediaWiki\Rest\Handler\needsReadAccess
needsReadAccess()
Indicates whether this route requires read rights.
Definition: Handler.php:377
MediaWiki\Rest\Handler\getBodyValidator
getBodyValidator( $contentType)
Fetch the BodyValidator.
Definition: Handler.php:271
MediaWiki\Rest\ConditionalHeaderUtil\setValidators
setValidators( $eTag, $lastModified, $hasRepresentation)
Initialize the object with information about the requested resource.
Definition: ConditionalHeaderUtil.php:29
MediaWiki\Rest\Handler\init
init(Router $router, RequestInterface $request, array $config, Authority $authority, ResponseFactory $responseFactory, HookContainer $hookContainer)
Initialise with dependencies from the Router.
Definition: Handler.php:68