Allow injecting query parameters in controllers

ruudk · ruudk · commit 161d2832aaad · 2023-02-22T15:16:38.000+01:00
We increased the PHPStan level from 8 to 9. This lead to some problems when working with query or request parameters. For example: ```php $firstName = $request->get('firstName'); ``` Because Symfony types `Request::get()` as `mixed` there is no type safety and you have to assert everything manually. We then learned that we shouldn't use `Request::get()` but use the explicit parameter bag like: ```php $request->query->get('firstName'); ``` This `ParameterBag` is used for `request` and `query`. It contains interesting methods like: ```php $request->query->getAlpha('firstName') : string; $request->query->getInt('age') : int; ``` This has the benefit that now the returned value is of a correct type. Why aren't we being explicit by requiring the parameters and their types in the controller action instead? Luckily Symfony has a concept called [ValueResolver](https://symfony.com/doc/current/controller/value_resolver.html). It allows you to do dynamically alter what is injected into a controller action. So in this PR, we introduces a new attribute: `#[MapQueryParameter]` that can be used in controller arguments. It allows you to define which parameters your controller is using and which type they should be. For example: ```php public function indexAction( #[MapQueryParameter] array $ids, #[MapQueryParameter] string $firstName, #[MapQueryParameter] bool $required, #[MapQueryParameter] int $age, #[MapQueryParameter] string $category = '', #[MapQueryParameter] ?string $theme = null, ) ``` When requesting `/?ids[]=1&ids[]=2&firstName=Ruud&required=3&age=123` you'll get: ``` $ids = ['1', '2'] $firstName = "Ruud" $required = false $age = 123 $category = '' $theme = null ``` It even supports variadic arguments like this: ```php public function indexAction( #[MapQueryParameter] string ...$ids, ) ``` When requesting `/?ids[]=111&ids[]=222` the `$ids` argument will have an array with values ['111','222']. Unit testing the controller now also becomes a bit easier, as you only have to pass the required parameters instead of constructing the `Request` object.
diff --git a/src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php b/src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php
@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Attribute;
+
+/**
+ * Can be used in a controller action to mark a parameter as a query parameter.
+ *
+ * public function homeAction(
+ *   #[MapQueryParameter] ?string $name
+ * );
+ *
+ * When opening this URL: /home?name=John
+ * It will fill the $name parameter with the value of the query parameter "name".
+ *
+ * When opening this URL: /home
+ * It will set $name to null.
+ *
+ * When the parameter is non-nullable / not optional:
+ * public function homeAction(
+ *   #[MapQueryParameter] string $name
+ * );
+ *
+ * Opening /home without passing ?name=John will throw a Bad Request exception.
+ */
+#[\Attribute(\Attribute::TARGET_PARAMETER)]
+final class MapQueryParameter
+{
+    /**
+     * @param string|null $name The name of the query parameter. If null, the name of the parameter in the action will be used.
+     */
+    public function __construct(
+        public ?string $name = null,
+    ) {
+    }
+}
diff --git a/src/Symfony/Component/HttpKernel/CHANGELOG.md b/src/Symfony/Component/HttpKernel/CHANGELOG.md
@@ -10,6 +10,7 @@ CHANGELOG
  * Use an instance of `Psr\Clock\ClockInterface` to generate the current date time in `DateTimeValueResolver`
  * Add `#[WithLogLevel]` for defining log levels for exceptions
  * Add `skip_response_headers` to the `HttpCache` options
+ * Add QueryParameterValueResolver that handles `#[MapQueryParameter]`
 
 6.2
 ---
diff --git a/src/Symfony/Component/HttpKernel/Controller/ArgumentResolver/MapQueryParameterValueResolver.php b/src/Symfony/Component/HttpKernel/Controller/ArgumentResolver/MapQueryParameterValueResolver.php
@@ -0,0 +1,77 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Controller\ArgumentResolver;
+
+use Symfony\Component\HttpFoundation\Exception\BadRequestException;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
+use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
+use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
+
+final class MapQueryParameterValueResolver implements ValueResolverInterface
+{
+    /**
+     * @return array<mixed>
+     */
+    public function resolve(Request $request, ArgumentMetadata $argument): array
+    {
+        $attribute = $argument->getAttributesOfType(MapQueryParameter::class)[0] ?? null;
+        if (null === $attribute) {
+            return [];
+        }
+
+        $name = $attribute->name ?? $argument->getName();
+        if (false === $request->query->has($name)) {
+            if ($argument->isNullable() || $argument->hasDefaultValue()) {
+                return [];
+            }
+
+            throw new BadRequestException(sprintf('Missing query parameter "%s".', $name));
+        }
+
+        if ($argument->isVariadic()) {
+            return $request->query->all($name);
+        }
+
+        if ('array' === $argument->getType()) {
+            return [$request->query->all($name)];
+        }
+
+        $value = $request->query->get($name);
+
+        if ('string' === $argument->getType()) {
+            return [$value];
+        }
+
+        if ('int' === $argument->getType()) {
+            if (!is_numeric($value)) {
+                throw new BadRequestException(sprintf('Query parameter "%s" must be an integer.', $name));
+            }
+
+            return [(int) $value];
+        }
+
+        if ('float' === $argument->getType()) {
+            if (!is_numeric($value)) {
+                throw new BadRequestException(sprintf('Query parameter "%s" must be a float.', $name));
+            }
+
+            return [(float) $value];
+        }
+
+        if ('bool' === $argument->getType()) {
+            return [filter_var($value, \FILTER_VALIDATE_BOOLEAN)];
+        }
+
+        return [];
+    }
+}
diff --git a/src/Symfony/Component/HttpKernel/Tests/Controller/ArgumentResolver/MapQueryParameterValueResolverTest.php b/src/Symfony/Component/HttpKernel/Tests/Controller/ArgumentResolver/MapQueryParameterValueResolverTest.php
