includes/Rest/Handler.php

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