[#4] Improve validation tooling in http-kernel-extension

Author: arjanfrans

.gitignore

@@ -3,3 +3,4 @@
 .php_cs.cache
 composer.lock
 /coverage
+.php-cs-fixer.cache

README.md

@@ -62,6 +62,9 @@ also validate the resulting object with Symfony Validation if you set validation
 - A `BadRequestHttpException` will be thrown when the request or rather the resulting object is invalid according to the
   Symfony Validation, the request body can't be deserialized, it contains invalid JSON or the hierarchy levels of the
   request body of exceed 512.
+- If you are using the [ConstraintViolationErrorHandler](src/ErrorHandler/ConstraintViolationErrorHandler.php) error handler, a
+  [ConstraintViolationException](src/Exception/ConstraintViolationException.php) will be thrown if the validation of your object
+  fails. You can also implement your own handler by implementing the [ErrorHandlerInterface](src/ErrorHandler/ErrorHandlerInterface.php).
 - Currently, only JSON is supported as payload format and the payload is only taken from the requests body.
 
 ### How to use?
@@ -84,20 +87,14 @@ needed by the serializer.
 
 final class UpdateFooDto
 {
-    /**
-     * @Assert\NotNull(message="Id should not be null.")
-     * @Assert\Positive(message="Id should be a positive integer.")
-     */
+    #[Assert\NotNull]
+    #[Assert\Positive]
     private int $id;
 
-    /**
-     * @Assert\NotBlank(message="Client version should not be be blank.")
-     */
+    #[Assert\NotBlank]
     private string $clientVersion;
 
-    /**
-     * @Assert\NotNull(message="Browser info should not be null.")
-     */
+    #[Assert\NotNull]
     private array $browserInfo;
 
     public function getClientVersion(): string
@@ -187,12 +184,64 @@ final class FooController extends AbstractController
 }
 ```
 
-#### Error handler
+#### Error handling
+
+The extension provides a default error handler (`http-kernel-extensions/src/ErrorHandler/ConstraintViolationErrorHandler.php`) which
+handles common de-normalization errors that should be considered type errors. It will create a
+`Fusonic\HttpKernelExtensions\Exception\ConstraintViolationException` [ConstraintViolationException](src/Exception/ConstraintViolationException.php)
+which can be used with the provided `Fusonic\HttpKernelExtensions\Normalizer\ConstraintViolationExceptionNormalizer` [ConstraintViolationExceptionNormalizer](src/Normalizer/ConstraintViolationExceptionNormalizer.php).
+This normalizer is uses on Symfony's built-in `Symfony\Component\Serializer\Normalizer\ConstraintViolationListNormalizer` and enhances it
+with some extra information: an `errorCode` and `messageTemplate`. Both useful for parsing validation errors on the client side.
+If that does not match your needs you can simply provide your own error handler by implementing
+the `Fusonic\HttpKernelExtensions\ErrorHandler\ErrorHandlerInterface` and passing it to the `RequestDtoResolver`.
+
+You have to register the normalizer as a service like this:
+
+```yaml
+  Fusonic\HttpKernelExtensions\Normalizer\ConstraintViolationExceptionNormalizer:
+        arguments:
+            - "@serializer.normalizer.constraint_violation_list"
+        tags:
+          - { name: serializer.normalizer }
+```
+
+##### Using an exception listener/subscriber
+In Symfony you can use an exception listener or subscriber to eventually convert the `ConstraintViolationException` into an actual response using
+the `Fusonic\HttpKernelExtensions\Normalizer\ConstraintViolationExceptionNormalizer`. For example:
+
+```php
+
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Fusonic\HttpKernelExtensions\Exception\ConstraintViolationException;
+use Symfony\Component\HttpKernel\Event\ExceptionEvent;
+
+final class ExceptionSubscriber implements EventSubscriberInterface {
+
+    public function __construct(private NormalizerInterface $normalizer) 
+    {
+    }
+
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            KernelEvents::EXCEPTION => 'onKernelException',
+        ];
+    }
+
+    public function onKernelException(ExceptionEvent $event): void
+    {
+        $throwable = $event->getThrowable();
+        
+        if ($throwable instanceof ConstraintViolationException) {
+            $data = $this->normalizer->normalize($throwable);
+            $event->setResponse(new JsonResponse($data, 422));
+        }
+    }
+}
+```
 
-The extension provides a default error handler in here `http-kernel-extensions/src/ErrorHandler/ErrorHandler.php` which
-throws `BadRequestHttpExceptions` in case the request can't be deserialized onto the given class or Symfony Validation
-deems it invalid. If that does not match your needs you can simply provide your own error handler by implementing
-the `ErrorHandlerInterface` and passing it to the `RequestDtoResolver`.
+Check the [Events and Event Listeners](https://symfony.com/doc/current/event_dispatcher.html) for details.
 
 #### ContextAwareProvider
 

UPGRADE-3.0.md

@@ -0,0 +1,6 @@
+# Upgrade 2.x to 3.0
+
+## Changes
+A new error handler has been added for handling Symfony validation errors. The default error handler is now set to
+`Fusonic\HttpKernelExtensions\ErrorHandler\ConstraintViolationErrorHandler`. If you do not need this behaviour, you should use
+your own implementation and inject that into the `Fusonic\HttpKernelExtensions\Controller\RequestDtoResolver`.

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "fusonic/http-kernel-extensions",
     "license": "MIT",
-    "version": "2.1.0",
+    "version": "3.0.0",
     "description": "Symfony HttpKernel Component Extensions.",
     "type": "library",
     "authors": [
@@ -30,13 +30,14 @@
     },
     "require-dev": {
         "phpunit/phpunit": "^9.3",
-        "phpstan/phpstan": "^0.12.42",
-        "friendsofphp/php-cs-fixer": "^2.16.1",
+        "phpstan/phpstan": "^1.4",
+        "friendsofphp/php-cs-fixer": "^3.5",
         "doctrine/cache": "^1.10",
-        "doctrine/annotations": "^1.11"
+        "doctrine/annotations": "^1.11",
+        "phpstan/phpstan-phpunit": "^1.0"
     },
     "scripts": {
-        "phpstan": "vendor/bin/phpstan analyse",
+        "phpstan": "php -d memory_limit=2048M vendor/bin/phpstan analyse",
         "phpcs-check": "vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php -v --dry-run --diff --using-cache=yes",
         "phpcs-fix": "vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php -v --using-cache=yes",
         "test": "vendor/bin/phpunit --testdox",

phpstan.neon

@@ -4,3 +4,6 @@ parameters:
         - src
         - tests
     checkMissingIterableValueType: false
+
+includes:
+    - vendor/phpstan/phpstan-phpunit/extension.neon

src/ConstraintViolation/ArgumentCountConstraintViolation.php

@@ -0,0 +1,75 @@
+<?php
+
+// Copyright (c) Fusonic GmbH. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for license information.
+
+declare(strict_types=1);
+
+namespace Fusonic\HttpKernelExtensions\ConstraintViolation;
+
+use ArgumentCountError;
+use ReflectionClass;
+use Symfony\Component\Validator\Constraints\NotNull;
+use Symfony\Component\Validator\ConstraintViolation;
+
+/**
+ * Wraps a {@see ArgumentCountError} into a {@see ConstraintViolation}.
+ */
+class ArgumentCountConstraintViolation extends ConstraintViolation
+{
+    private const EXPECTED_MATCHES = 6;
+
+    public function __construct(ArgumentCountError $error)
+    {
+        $message = $error->getMessage();
+
+        if (!str_starts_with($message, 'Too few arguments to function')) {
+            throw $error;
+        }
+
+        $matches = null;
+        $pattern = '/Too few arguments to function (.+)::__construct\(\), (\d+) passed in (.+) on line (\d+) and (?:at least|exactly) (\d+) expected/';
+
+        preg_match($pattern, $message, $matches);
+
+        if (count($matches) < self::EXPECTED_MATCHES) {
+            throw $error;
+        }
+
+        // Get the first missing constructor argument
+        if (!class_exists($matches[1])) {
+            throw $error;
+        }
+
+        $class = new ReflectionClass($matches[1]);
+
+        $constructor = $class->getConstructor();
+        $parameters = $constructor?->getParameters() ?: [];
+
+        $propertyPath = null;
+
+        foreach ($parameters as $parameter) {
+            if (!$parameter->isOptional()) {
+                $propertyPath = $parameter->getName();
+            }
+        }
+
+        // If no propertyPath is found throw the exception up
+        if (null === $propertyPath) {
+            throw $error;
+        }
+
+        $constraint = new NotNull();
+
+        parent::__construct(
+            message: $constraint->message,
+            messageTemplate: $constraint->message,
+            parameters: [],
+            root: null,
+            propertyPath: $propertyPath,
+            invalidValue: null,
+            code: NotNull::IS_NULL_ERROR,
+            constraint: $constraint
+        );
+    }
+}

src/ConstraintViolation/MissingConstructorArgumentsConstraintViolation.php

@@ -0,0 +1,51 @@
+<?php
+
+// Copyright (c) Fusonic GmbH. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for license information.
+
+declare(strict_types=1);
+
+namespace Fusonic\HttpKernelExtensions\ConstraintViolation;
+
+use Symfony\Component\Serializer\Exception\MissingConstructorArgumentsException;
+use Symfony\Component\Validator\Constraints\NotNull;
+use Symfony\Component\Validator\ConstraintViolation;
+
+/**
+ * Wraps a {@see MissingConstructorArgumentsException} into a {@see ConstraintViolation}.
+ */
+class MissingConstructorArgumentsConstraintViolation extends ConstraintViolation
+{
+    private const EXPECTED_MATCHES = 3;
+
+    public function __construct(MissingConstructorArgumentsException $exception)
+    {
+        $message = $exception->getMessage();
+
+        if (!str_starts_with($message, 'Cannot create an instance of')) {
+            throw $exception;
+        }
+
+        $matches = null;
+        $pattern = '/Cannot create an instance of "(.+)" from serialized data because its constructor requires parameter "(.+)" to be present\./';
+
+        preg_match($pattern, $message, $matches);
+
+        if (count($matches) < self::EXPECTED_MATCHES) {
+            throw $exception;
+        }
+
+        $constraint = new NotNull();
+
+        parent::__construct(
+            message: $constraint->message,
+            messageTemplate: $constraint->message,
+            parameters: [],
+            root: null,
+            propertyPath: $matches[2],
+            invalidValue: null,
+            code: NotNull::IS_NULL_ERROR,
+            constraint: $constraint
+        );
+    }
+}

src/ConstraintViolation/NotNormalizableValueConstraintViolation.php

@@ -0,0 +1,53 @@
+<?php
+
+// Copyright (c) Fusonic GmbH. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for license information.
+
+declare(strict_types=1);
+
+namespace Fusonic\HttpKernelExtensions\ConstraintViolation;
+
+use Symfony\Component\Serializer\Exception\NotNormalizableValueException;
+use Symfony\Component\Validator\Constraints\Type;
+use Symfony\Component\Validator\ConstraintViolation;
+
+/**
+ * Wraps a {@see NotNormalizableValueException} into a {@see ConstraintViolation}.
+ */
+class NotNormalizableValueConstraintViolation extends ConstraintViolation
+{
+    private const EXPECTED_MATCHES = 5;
+
+    public function __construct(NotNormalizableValueException $exception)
+    {
+        $message = $exception->getMessage();
+
+        if (str_starts_with($message, 'The type of the')) {
+            $pattern = '/The type of the "(\w+)" attribute for class "(.+)" must be one of "(.+)" \("(.+)" given\)\./';
+        } elseif (str_starts_with($message, 'Failed to denormalize attribute')) {
+            $pattern = '/Failed to denormalize attribute "(\w+)" value for class "(.+)": Expected argument of type "(.+)", "(.+)" given/';
+        } else {
+            throw $exception;
+        }
+
+        $matches = null;
+        preg_match($pattern, $message, $matches);
+
+        if (count($matches) < self::EXPECTED_MATCHES) {
+            throw $exception;
+        }
+
+        $constraint = new Type($matches[1]);
+
+        parent::__construct(
+            message: str_replace('{{ type }}', $matches[3], $constraint->message),
+            messageTemplate: $constraint->message,
+            parameters: ['{{ type }}' => $matches[3]],
+            root: null,
+            propertyPath: $matches[1],
+            invalidValue: $matches[4],
+            code: Type::INVALID_TYPE_ERROR,
+            constraint: $constraint
+        );
+    }
+}

src/ConstraintViolation/TypeConstraintViolation.php

@@ -0,0 +1,51 @@
+<?php
+
+// Copyright (c) Fusonic GmbH. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for license information.
+
+declare(strict_types=1);
+
+namespace Fusonic\HttpKernelExtensions\ConstraintViolation;
+
+use Symfony\Component\Validator\Constraints\Type;
+use Symfony\Component\Validator\ConstraintViolation;
+use TypeError;
+
+/**
+ * Wraps a {@see TypeError} into a {@see ConstraintViolation}.
+ */
+class TypeConstraintViolation extends ConstraintViolation
+{
+    private const EXPECTED_MATCHES = 4;
+
+    public function __construct(TypeError $error)
+    {
+        $message = $error->getMessage();
+
+        if (!str_contains($message, 'must be of type')) {
+            throw $error;
+        }
+
+        $matches = null;
+        $pattern = '/.+: Argument #\d+ \(\$(.+)\) must be of type \??(.+), (.+) given/';
+
+        preg_match($pattern, $message, $matches);
+
+        if (count($matches) < self::EXPECTED_MATCHES) {
+            throw $error;
+        }
+
+        $constraint = new Type($matches[2]);
+
+        parent::__construct(
+            message: str_replace('{{ type }}', $matches[2], $constraint->message),
+            messageTemplate: $constraint->message,
+            parameters: ['{{ type }}' => $matches[2]],
+            root: null,
+            propertyPath: $matches[1],
+            invalidValue: $matches[3],
+            code: Type::INVALID_TYPE_ERROR,
+            constraint: $constraint
+        );
+    }
+}