Merge pull request #4 from lordrhodos/feature/request-validation

Add support to validate HttpFoundation Requests and PSR ServerRequests

Author: osteel

README.md

@@ -5,23 +5,23 @@
 [![Build Status](https://travis-ci.com/osteel/openapi-httpfoundation-testing.svg?token=SDx8eeySnDpzswpLVTU3&branch=main)](https://travis-ci.com/osteel/openapi-httpfoundation-testing)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/osteel/openapi-httpfoundation-testing/badges/quality-score.png?b=main&s=bef9ddbf29dac69612a3092e4761e14ce768bccd)](https://scrutinizer-ci.com/g/osteel/openapi-httpfoundation-testing/?branch=main)
 
-Strengthen your API tests by validating HttpFoundation responses against OpenAPI (3.0.x) definitions.
+Strengthen your API tests by validating HttpFoundation requests and responses against OpenAPI (3.0.x) definitions.
 
 See [this article](https://tech.osteel.me/posts/openapi-backed-api-testing-in-php-projects-a-laravel-example "OpenAPI-backed API testing in PHP projects – a Laravel example") for more details, and [this repository](https://github.com/osteel/openapi-httpfoundation-testing-laravel-example) for an example use in a Laravel project.
 
 ## Why?
 
 [OpenAPI](https://swagger.io/specification/) is a specification intended to describe RESTful APIs in a way that is understood by humans and machines alike.
 
-By validating an API's responses against the OpenAPI definition that describes it, we guarantee that the API's behaviour conforms to the documentation we provide, thus making the OpenAPI definition the single source of truth.
+By validating an API's responses against the OpenAPI definition that describes it, we guarantee that the API's behaviour conforms to the documentation we provide, thus making the OpenAPI definition the single source of truth. The request validation on the other hand supports you in the process of doing the server side validation of the requests payloads. 
 
 The [HttpFoundation component](https://symfony.com/doc/current/components/http_foundation.html) is developed and maintained as part of the [Symfony framework](https://symfony.com/). It is used to handle HTTP requests and responses in projects such as Symfony, Laravel, Drupal, and many other major industry players (see the [extended list](https://symfony.com/components/HttpFoundation)).
 
 ## How does it work?
 
 This package is built upon the [OpenAPI PSR-7 Message Validator](https://github.com/thephpleague/openapi-psr7-validator) package, which validates [PSR-7 messages](https://www.php-fig.org/psr/psr-7/) against OpenAPI definitions.
 
-It essentially converts HttpFoundation response objects to PSR-7 messages using Symfony's [PSR-7 Bridge](https://symfony.com/doc/current/components/psr7.html) and [Tobias Nyholm](https://github.com/Nyholm)'s [PSR-7 implementation](https://github.com/Nyholm/psr7), before passing them on to the OpenAPI PSR-7 Message Validator.
+It essentially converts HttpFoundation response and request objects to PSR-7 messages using Symfony's [PSR-7 Bridge](https://symfony.com/doc/current/components/psr7.html) and [Tobias Nyholm](https://github.com/Nyholm)'s [PSR-7 implementation](https://github.com/Nyholm/psr7), before passing them on to the OpenAPI PSR-7 Message Validators.
 
 ## Install
 
@@ -35,6 +35,7 @@ $ composer require --dev osteel/openapi-httpfoundation-testing
 
 ## Usage
 
+### Response Validation
 First, import the builder in the class that will perform the validation:
 
 ```php
@@ -71,6 +72,35 @@ $validator->post('/users', $response);
 
 The `validate` method returns `true` in case of success, and throws `\Osteel\OpenApi\Testing\Exceptions\ValidationException` exceptions in case of error.
 
+### Request Validation
+The procedure is the same as described in the [Response Validation](https://github.com/osteel/openapi-httpfoundation-testing#response-validation) section. Import the builder first: 
+
+```php
+use Osteel\OpenApi\Testing\RequestValidatorBuilder;
+```
+
+and use it to create a `\Osteel\OpenApi\Testing\RequestValidator` object, feeding it a YAML or JSON OpenAPI definition:
+
+```php
+$validator = RequestValidatorBuilder::fromYaml('my-definition.yaml')->getValidator();
+
+// or
+
+$validator = RequestValidatorBuilder::fromJson('my-definition.json')->getValidator();
+```
+
+💡 _Instead of a file, you can also pass a YAML or JSON string directly._
+
+You can now validate a `\Symfony\Component\HttpFoundation\Request` object:
+
+```php
+$validator->validate($request);
+```
+
+💡 _For convenience, requests implementing `\Psr\Http\Message\ServerRequestInterface` are also accepted._
+
+The `validate` method returns `true` in case of success, and throws `\Osteel\OpenApi\Testing\Exceptions\ValidationException` exceptions in case of error.
+
 ## Change log
 
 Please see the [Releases section](../../releases) for more information on what has changed recently.

src/HttpFoundation/HttpFoundationRequestAdapter.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Osteel\OpenApi\Testing\HttpFoundation;
+
+use InvalidArgumentException;
+use Nyholm\Psr7\Factory\Psr17Factory;
+use Osteel\OpenApi\Testing\RequestAdapter;
+use Psr\Http\Message\ServerRequestInterface;
+use Symfony\Bridge\PsrHttpMessage\Factory\PsrHttpFactory;
+use Symfony\Component\HttpFoundation\Request;
+
+class HttpFoundationRequestAdapter implements RequestAdapter
+{
+    /**
+     * {@inheritDoc}
+     *
+     * @param  Request|ServerRequestInterface $request The request object to convert.
+     * @return ServerRequestInterface
+     * @throws InvalidArgumentException
+     */
+    public function convert(object $request): ServerRequestInterface
+    {
+        if ($request instanceof ServerRequestInterface) {
+            return $request;
+        }
+
+        if ($request instanceof Request) {
+            $psr17Factory   = new Psr17Factory();
+            $psrHttpFactory = new PsrHttpFactory($psr17Factory, $psr17Factory, $psr17Factory, $psr17Factory);
+
+            return $psrHttpFactory->createRequest($request);
+        }
+
+        throw new InvalidArgumentException(sprintf(
+            'Can only validate requests of type %s or %s; %s received',
+            Request::class,
+            ServerRequestInterface::class,
+            get_class($request)
+        ));
+    }
+}

src/RequestAdapter.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Osteel\OpenApi\Testing;
+
+use Psr\Http\Message\ServerRequestInterface;
+
+interface RequestAdapter
+{
+    /**
+     * Convert a request to a PSR-7 HTTP message.
+     *
+     * @param  object $request The request object to convert.
+     * @return ServerRequestInterface
+     */
+    public function convert(object $request): ServerRequestInterface;
+}

src/RequestValidator.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Osteel\OpenApi\Testing;
+
+use League\OpenAPIValidation\PSR7\Exception\ValidationFailed;
+use League\OpenAPIValidation\PSR7\RequestValidator as BaseRequestValidator;
+use Osteel\OpenApi\Testing\Exceptions\ValidationException;
+
+/**
+ * This class is a wrapper for League\OpenAPIValidation\PSR7\RequestValidator objects,
+ * providing an interface to validate HTTP requests against an OpenAPI definition.
+ */
+final class RequestValidator
+{
+    /**
+     * @var \League\OpenAPIValidation\PSR7\RequestValidator
+     */
+    private $validator;
+
+    /**
+     * @var RequestAdapter
+     */
+    private $adapter;
+
+    /**
+     * Constructor.
+     *
+     * @param  \League\OpenAPIValidation\PSR7\RequestValidator $validator
+     * @param  RequestAdapter                                  $adapter
+     * @return void
+     */
+    public function __construct(BaseRequestValidator $validator, RequestAdapter $adapter)
+    {
+        $this->validator = $validator;
+        $this->adapter   = $adapter;
+    }
+
+    /**
+     * Validate a request against the specified OpenAPI definition.
+     *
+     * @param  object $request The request object to validate.
+     *
+     * @return bool
+     * @throws ValidationException
+     */
+    public function validate(object $request): bool
+    {
+        try {
+            $this->validator->validate($this->adapter->convert($request));
+        } catch (ValidationFailed $exception) {
+            throw ValidationException::fromValidationFailed($exception);
+        }
+
+        return true;
+    }
+}

src/RequestValidatorBuilder.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Osteel\OpenApi\Testing;
+
+use InvalidArgumentException;
+use League\OpenAPIValidation\PSR7\ValidatorBuilder;
+use Osteel\OpenApi\Testing\HttpFoundation\HttpFoundationRequestAdapter;
+
+/**
+ * This class creates RequestValidator objects based on OpenAPI definitions.
+ */
+class RequestValidatorBuilder
+{
+    /**
+     * @var ValidatorBuilder
+     */
+    protected $validatorBuilder;
+
+    /**
+     * @var string
+     */
+    protected $adapter = HttpFoundationRequestAdapter::class;
+
+    /**
+     * Constructor.
+     *
+     * @param  ValidatorBuilder $builder
+     * @return void
+     */
+    public function __construct(ValidatorBuilder $builder)
+    {
+        $this->validatorBuilder = $builder;
+    }
+
+    /**
+     * Create a RequestValidator object based on a YAML OpenAPI definition.
+     *
+     * @param  string $definition The OpenAPI definition.
+     * @return RequestValidatorBuilder
+     */
+    public static function fromYaml(string $definition): RequestValidatorBuilder
+    {
+        $method = is_file($definition) ? 'fromYamlFile' : 'fromYaml';
+
+        return self::fromMethod($method, $definition);
+    }
+
+    /**
+     * Create a RequestValidator object based on a JSON OpenAPI definition.
+     *
+     * @param  string $definition The OpenAPI definition.
+     * @return RequestValidatorBuilder
+     */
+    public static function fromJson(string $definition): RequestValidatorBuilder
+    {
+        $method = is_file($definition) ? 'fromJsonFile' : 'fromJson';
+
+        return self::fromMethod($method, $definition);
+    }
+
+    /**
+     * Create a RequestValidator object based on an OpenAPI definition.
+     *
+     * @param  string $method     The ValidatorBuilder object's method to use.
+     * @param  string $definition The OpenAPI definition.
+     * @return RequestValidatorBuilder
+     */
+    private static function fromMethod(string $method, string $definition): RequestValidatorBuilder
+    {
+        $builder = (new ValidatorBuilder())->$method($definition);
+
+        return new RequestValidatorBuilder($builder);
+    }
+
+    /**
+     * Return the RequestValidator object.
+     *
+     * @return RequestValidator
+     */
+    public function getValidator(): RequestValidator
+    {
+        return new RequestValidator($this->validatorBuilder->getRequestValidator(), new $this->adapter());
+    }
+
+    /**
+     * Change the request adapter to be used. The provided class must
+     * implement the \Osteel\OpenApi\Testing\RequestAdapter interface.
+     *
+     * @param  string $class The adapter's class.
+     * @return self
+     * @throws InvalidArgumentException
+     */
+    public function setAdapter(string $class): self
+    {
+        if (! is_subclass_of($class, RequestAdapter::class)) {
+            throw new InvalidArgumentException(sprintf(
+                'Class %s does not implement the %s interface',
+                $class,
+                RequestAdapter::class
+            ));
+        }
+
+        $this->adapter = $class;
+
+        return $this;
+    }
+}

tests/HttpFoundation/HttpFoundationRequestAdapterTest.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Osteel\OpenApi\Testing\Tests\HttpFoundation;
+
+use InvalidArgumentException;
+use Osteel\OpenApi\Testing\HttpFoundation\HttpFoundationRequestAdapter;
+use Osteel\OpenApi\Testing\Tests\TestCase;
+use Psr\Http\Message\ServerRequestInterface;
+use Symfony\Component\HttpFoundation\Request;
+
+class HttpFoundationRequestAdapterTest extends TestCase
+{
+    /**
+     * @var HttpFoundationRequestAdapter
+     */
+    private $sut;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->sut = new HttpFoundationRequestAdapter();
+    }
+
+    public function testItDoesNotConvertTheRequestBecauseItsTypeIsNotSupported()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage(sprintf(
+            'Can only validate requests of type %s or %s; InvalidArgumentException received',
+            Request::class,
+            ServerRequestInterface::class
+        ));
+
+        $this->sut->convert(new InvalidArgumentException());
+    }
+
+    public function testItConvertsTheHttpFoundationRequest()
+    {
+        $result = $this->sut->convert(Request::create('/foo'));
+
+        $this->assertInstanceOf(ServerRequestInterface::class, $result);
+    }
+
+    public function testItLeavesTheRequestInterfaceUntouched()
+    {
+        $request = $this->createMock(ServerRequestInterface::class);
+        $result  = $this->sut->convert($request);
+
+        $this->assertEquals($request, $result);
+    }
+}