includes/Rest/Handler.php

   1 <?php
   2
   3 namespace MediaWiki\Rest;
   4
   5 abstract class Handler {
   6         /** @var Router */
   7         private $router;
   8
   9         /** @var RequestInterface */
  10         private $request;
  11
  12         /** @var array */
  13         private $config;
  14
  15         /** @var ResponseFactory */
  16         private $responseFactory;
  17
  18         /**
  19          * Initialise with dependencies from the Router. This is called after construction.
  20          * @internal
  21          */
  22         public function init( Router $router, RequestInterface $request, array $config,
  23                 ResponseFactory $responseFactory
  24         ) {
  25                 $this->router = $router;
  26                 $this->request = $request;
  27                 $this->config = $config;
  28                 $this->responseFactory = $responseFactory;
  29         }
  30
  31         /**
  32          * Get the Router. The return type declaration causes it to raise
  33          * a fatal error if init() has not yet been called.
  34          */
  35         protected function getRouter(): Router {
  36                 return $this->router;
  37         }
  38
  39         /**
  40          * Get the current request. The return type declaration causes it to raise
  41          * a fatal error if init() has not yet been called.
  42          *
  43          * @return RequestInterface
  44          */
  45         public function getRequest(): RequestInterface {
  46                 return $this->request;
  47         }
  48
  49         /**
  50          * Get the configuration array for the current route. The return type
  51          * declaration causes it to raise a fatal error if init() has not
  52          * been called.
  53          *
  54          * @return array
  55          */
  56         public function getConfig(): array {
  57                 return $this->config;
  58         }
  59
  60         /**
  61          * Get the ResponseFactory which can be used to generate Response objects.
  62          * This will raise a fatal error if init() has not been
  63          * called.
  64          *
  65          * @return ResponseFactory
  66          */
  67         public function getResponseFactory(): ResponseFactory {
  68                 return $this->responseFactory;
  69         }
  70
  71         /**
  72          * The subclass should override this to provide the maximum last modified
  73          * timestamp for the current request. This is called before execute() in
  74          * order to decide whether to send a 304.
  75          *
  76          * The timestamp can be in any format accepted by ConvertibleTimestamp, or
  77          * null to indicate that the timestamp is unknown.
  78          *
  79          * @return bool|string|int|float|\DateTime|null
  80          */
  81         protected function getLastModified() {
  82                 return null;
  83         }
  84
  85         /**
  86          * The subclass should override this to provide an ETag for the current
  87          * request. This is called before execute() in order to decide whether to
  88          * send a 304.
  89          *
  90          * See RFC 7232 § 2.3 for semantics.
  91          *
  92          * @return string|null
  93          */
  94         protected function getETag() {
  95                 return null;
  96         }
  97
  98         /**
  99          * Execute the handler. This is called after parameter validation. The
 100          * return value can either be a Response or any type accepted by
 101          * ResponseFactory::createFromReturnValue().
 102          *
 103          * To automatically construct an error response, execute() should throw a
 104          * RestException. Such exceptions will not be logged like a normal exception.
 105          *
 106          * If execute() throws any other kind of exception, the exception will be
 107          * logged and a generic 500 error page will be shown.
 108          *
 109          * @return mixed
 110          */
 111         abstract public function execute();
 112 }