Merge "Provide command to adjust phpunit.xml for code coverage"

[lhc/web/wiklou.git] / includes / Rest / Handler.php

diff --git a/includes/Rest/Handler.php b/includes/Rest/Handler.php
index cee403f..efe2b7e 100644 (file)
--- a/includes/Rest/Handler.php
+++ b/includes/Rest/Handler.php
@@ -2,7 +2,18 @@
 
 namespace MediaWiki\Rest;
 
+use MediaWiki\Rest\Validator\BodyValidator;
+use MediaWiki\Rest\Validator\NullBodyValidator;
+use MediaWiki\Rest\Validator\Validator;
+
 abstract class Handler {
+
+       /**
+        * (string) ParamValidator constant to specify the source of the parameter.
+        * Value must be 'path', 'query', or 'post'.
+        */
+       const PARAM_SOURCE = 'rest-param-source';
+
        /** @var Router */
        private $router;
 
@@ -15,6 +26,12 @@ abstract class Handler {
        /** @var ResponseFactory */
        private $responseFactory;
 
+       /** @var array|null */
+       private $validatedParams;
+
+       /** @var mixed */
+       private $validatedBody;
+
        /**
         * Initialise with dependencies from the Router. This is called after construction.
         * @internal
@@ -68,6 +85,62 @@ abstract class Handler {
                return $this->responseFactory;
        }
 
+       /**
+        * Validate the request parameters/attributes and body. If there is a validation
+        * failure, a response with an error message should be returned or an
+        * HttpException should be thrown.
+        *
+        * @param Validator $restValidator
+        * @throws HttpException On validation failure.
+        */
+       public function validate( Validator $restValidator ) {
+               $validatedParams = $restValidator->validateParams( $this->getParamSettings() );
+               $validatedBody = $restValidator->validateBody( $this->request, $this );
+               $this->validatedParams = $validatedParams;
+               $this->validatedBody = $validatedBody;
+       }
+
+       /**
+        * Fetch ParamValidator settings for parameters
+        *
+        * Every setting must include self::PARAM_SOURCE to specify which part of
+        * the request is to contain the parameter.
+        *
+        * @return array[] Associative array mapping parameter names to
+        *  ParamValidator settings arrays
+        */
+       public function getParamSettings() {
+               return [];
+       }
+
+       /**
+        * Fetch the BodyValidator
+        * @param string $contentType Content type of the request.
+        * @return BodyValidator
+        */
+       public function getBodyValidator( $contentType ) {
+               return new NullBodyValidator();
+       }
+
+       /**
+        * Fetch the validated parameters
+        *
+        * @return array|null Array mapping parameter names to validated values,
+        *  or null if validateParams() was not called yet or validation failed.
+        */
+       public function getValidatedParams() {
+               return $this->validatedParams;
+       }
+
+       /**
+        * Fetch the validated body
+        * @return mixed Value returned by the body validator, or null if validateParams() was
+        *  not called yet, validation failed, there was no body, or the body was form data.
+        */
+       public function getValidatedBody() {
+               return $this->validatedBody;
+       }
+
        /**
         * The subclass should override this to provide the maximum last modified
         * timestamp for the current request. This is called before execute() in
@@ -95,6 +168,35 @@ abstract class Handler {
                return null;
        }
 
+       /**
+        * Indicates whether this route requires read rights.
+        *
+        * The handler should override this if it does not need to read from the
+        * wiki. This is uncommon, but may be useful for login and other account
+        * management APIs.
+        *
+        * @return bool
+        */
+       public function needsReadAccess() {
+               return true;
+       }
+
+       /**
+        * Indicates whether this route requires write access.
+        *
+        * The handler should override this if the route does not need to write to
+        * the database.
+        *
+        * This should return true for routes that may require synchronous database writes.
+        * Modules that do not need such writes should also not rely on master database access,
+        * since only read queries are needed and each master DB is a single point of failure.
+        *
+        * @return bool
+        */
+       public function needsWriteAccess() {
+               return true;
+       }
+
        /**
         * Execute the handler. This is called after parameter validation. The
         * return value can either be a Response or any type accepted by