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          * Indicates whether this route requires read rights.
 100          *
 101          * The handler should override this if it does not need to read from the
 102          * wiki. This is uncommon, but may be useful for login and other account
 103          * management APIs.
 104          *
 105          * @return bool
 106          */
 107         public function needsReadAccess() {
 108                 return true;
 109         }
 110
 111         /**
 112          * Indicates whether this route requires write access.
 113          *
 114          * The handler should override this if the route does not need to write to
 115          * the database.
 116          *
 117          * This should return true for routes that may require synchronous database writes.
 118          * Modules that do not need such writes should also not rely on master database access,
 119          * since only read queries are needed and each master DB is a single point of failure.
 120          *
 121          * @return bool
 122          */
 123         public function needsWriteAccess() {
 124                 return true;
 125         }
 126
 127         /**
 128          * Execute the handler. This is called after parameter validation. The
 129          * return value can either be a Response or any type accepted by
 130          * ResponseFactory::createFromReturnValue().
 131          *
 132          * To automatically construct an error response, execute() should throw a
 133          * RestException. Such exceptions will not be logged like a normal exception.
 134          *
 135          * If execute() throws any other kind of exception, the exception will be
 136          * logged and a generic 500 error page will be shown.
 137          *
 138          * @return mixed
 139          */
 140         abstract public function execute();
 141 }