feat(state): cast parameter values to validate with the Type constraint

vincentchalamon · soyuka · commit b41ed3f99e39 · 2025-07-02T18:35:06.000+02:00
diff --git a/src/Laravel/workbench/app/Models/Book.php b/src/Laravel/workbench/app/Models/Book.php
@@ -37,6 +37,8 @@
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Symfony\Component\TypeInfo\Type\BuiltinType;
+use Symfony\Component\TypeInfo\TypeIdentifier;
 use Workbench\App\Http\Requests\BookFormRequest;
 
 #[ApiResource(
@@ -79,7 +81,7 @@
     property: 'name'
 )]
 #[QueryParameter(key: 'properties', filter: PropertyFilter::class)]
-#[QueryParameter(key: 'published', filter: BooleanFilter::class)]
+#[QueryParameter(key: 'published', filter: BooleanFilter::class, nativeType: new BuiltinType(TypeIdentifier::BOOL))]
 class Book extends Model
 {
     use HasFactory;
diff --git a/src/Metadata/Parameter.php b/src/Metadata/Parameter.php
@@ -27,10 +27,12 @@ abstract class Parameter
      * @param (array<string, mixed>&array{type?: string, default?: string})|null $schema
      * @param array<string, mixed>                                               $extraProperties
      * @param ParameterProviderInterface|callable|string|null                    $provider
-     * @param list<string>                                                       $properties      a list of properties this parameter applies to (works with the :property placeholder)
+     * @param list<string>                                                       $properties       a list of properties this parameter applies to (works with the :property placeholder)
      * @param FilterInterface|string|null                                        $filter
-     * @param mixed                                                              $constraints     an array of Symfony constraints, or an array of Laravel rules
-     * @param Type                                                               $nativeType      the PHP native type, we cast values to an array if its a CollectionType, if not and it's an array with a single value we use it (eg: HTTP Header)
+     * @param mixed                                                              $constraints      an array of Symfony constraints, or an array of Laravel rules
+     * @param Type                                                               $nativeType       the PHP native type, we cast values to an array if its a CollectionType, if not and it's an array with a single value we use it (eg: HTTP Header)
+     * @param ?bool                                                              $castToNativeType whether API Platform should cast your parameter to the nativeType declared
+     * @param ?callable                                                          $castFn           the closure used to cast your parameter, this gets called only when $castToNativeType is set
      */
     public function __construct(
         protected ?string $key = null,
@@ -51,6 +53,8 @@ public function __construct(
         protected array|string|null $filterContext = null,
         protected ?Type $nativeType = null,
         protected ?bool $castToArray = null,
+        protected ?bool $castToNativeType = null,
+        protected ?callable $castFn = null,
     ) {
     }
 
@@ -332,4 +336,30 @@ public function withCastToArray(bool $castToArray): self
 
         return $self;
     }
+
+    public function getCastToNativeType(): ?bool
+    {
+        return $this->castToNativeType;
+    }
+
+    public function withCastToNativeType(bool $castToNativeType): self
+    {
+        $self = clone $this;
+        $self->castToNativeType = $castToNativeType;
+
+        return $self;
+    }
+
+    public function getCastFn(): ?callable
+    {
+        return $this->castFn;
+    }
+
+    public function withCastFn(callable $castFn): self
+    {
+        $self = clone $this;
+        $self->castFn = $castFn;
+
+        return $self;
+    }
 }
diff --git a/src/Metadata/Resource/Factory/ParameterResourceMetadataCollectionFactory.php b/src/Metadata/Resource/Factory/ParameterResourceMetadataCollectionFactory.php
@@ -28,11 +28,13 @@
 use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
 use ApiPlatform\OpenApi\Model\Parameter as OpenApiParameter;
 use ApiPlatform\Serializer\Filter\FilterInterface as SerializerFilterInterface;
+use ApiPlatform\State\Parameter\ValueCaster;
 use ApiPlatform\State\Util\StateOptionsTrait;
 use Psr\Container\ContainerInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
 use Symfony\Component\TypeInfo\Type;
+use Symfony\Component\TypeInfo\TypeIdentifier;
 
 /**
  * Prepares Parameters documentation by reading its filter details and declaring an OpenApi parameter.
@@ -158,11 +160,27 @@ private function getDefaultParameters(Operation $operation, string $resourceClas
                     $parameter = $parameter->withNativeType(Type::string());
                 } elseif ('boolean' === ($parameter->getSchema()['type'] ?? null)) {
                     $parameter = $parameter->withNativeType(Type::bool());
+                } elseif ('integer' === ($parameter->getSchema()['type'] ?? null)) {
+                    $parameter = $parameter->withNativeType(Type::int());
+                } elseif ('number' === ($parameter->getSchema()['type'] ?? null)) {
+                    $parameter = $parameter->withNativeType(Type::float());
                 } else {
                     $parameter = $parameter->withNativeType(Type::union(Type::string(), Type::list(Type::string())));
                 }
             }
 
+            if ($parameter->getCastToNativeType() && null === $parameter->getCastFn() && ($nativeType = $parameter->getNativeType())) {
+                if ($nativeType->isIdentifiedBy(TypeIdentifier::BOOL)) {
+                    $parameter = $parameter->withCastFn([ValueCaster::class, 'toBool']);
+                }
+                if ($nativeType->isIdentifiedBy(TypeIdentifier::INT)) {
+                    $parameter = $parameter->withCastFn([ValueCaster::class, 'toInt']);
+                }
+                if ($nativeType->isIdentifiedBy(TypeIdentifier::FLOAT)) {
+                    $parameter = $parameter->withCastFn([ValueCaster::class, 'toFloat']);
+                }
+            }
+
             $priority = $parameter->getPriority() ?? $internalPriority--;
             $parameters->add($key, $parameter->withPriority($priority));
         }
diff --git a/src/State/Parameter/ValueCaster.php b/src/State/Parameter/ValueCaster.php
@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\State\Parameter;
+
+/**
+ * Caster returns the default value when a value can not be casted
+ * This is used by parameters before they get validated by constraints
+ * Therefore we do not need to throw exceptions, validation will just fail.
+ *
+ * @internal
+ */
+final class ValueCaster
+{
+    public static function toBool(mixed $v): mixed
+    {
+        if (!\is_string($v)) {
+            return $v;
+        }
+
+        return match (strtolower($v)) {
+            '1', 'true' => true,
+            '0', 'false' => false,
+            default => $v,
+        };
+    }
+
+    public static function toInt(mixed $v): mixed
+    {
+        if (\is_int($v)) {
+            return $v;
+        }
+
+        $value = filter_var($v, \FILTER_VALIDATE_INT);
+
+        return false === $value ? $v : $value;
+    }
+
+    public static function toFloat(mixed $v): mixed
+    {
+        if (\is_float($v)) {
+            return $v;
+        }
+
+        $value = filter_var($v, \FILTER_VALIDATE_FLOAT);
+
+        return false === $value ? $v : $value;
+    }
+}
diff --git a/src/State/Util/ParameterParserTrait.php b/src/State/Util/ParameterParserTrait.php
@@ -45,7 +45,7 @@ private function getParameterValues(Parameter $parameter, ?Request $request, arr
      *
      * @return array<mixed, mixed>|ParameterNotFound|array
      */
-    private function extractParameterValues(Parameter $parameter, array $values): string|ParameterNotFound|array
+    private function extractParameterValues(Parameter $parameter, array $values): string|ParameterNotFound|array|bool
     {
         $accessors = null;
         $key = $parameter->getKey();
@@ -72,7 +72,6 @@ private function extractParameterValues(Parameter $parameter, array $values): st
                 $value = $value[$accessor];
             } else {
                 $value = new ParameterNotFound();
-                continue;
             }
         }
 
@@ -100,6 +99,14 @@ private function extractParameterValues(Parameter $parameter, array $values): st
             $value = $value[0];
         }
 
+        if (true === $parameter->getCastToNativeType() && ($castFn = $parameter->getCastFn())) {
+            if (\is_array($value)) {
+                $value = array_map(fn ($v) => $castFn($v, $parameter), $value);
+            } else {
+                $value = $castFn($value, $parameter);
+            }
+        }
+
         return $value;
     }
 }
diff --git a/src/Validator/Util/ParameterValidationConstraints.php b/src/Validator/Util/ParameterValidationConstraints.php
@@ -144,8 +144,16 @@ public static function getParameterValidationConstraints(Parameter $parameter, ?
             $assertions[] = new Unique();
         }
 
-        if (isset($schema['type']) && 'array' === $schema['type']) {
-            $assertions[] = new Type(type: 'array');
+        if (isset($schema['type'])) {
+            $assertion = match ($schema['type']) {
+                'array', 'boolean', 'integer' => new Type(type: $schema['type']),
+                'number' => new Type(type: 'float'),
+                default => null,
+            };
+
+            if ($assertion) {
+                $assertions[] = $assertion;
+            }
         }
 
         return $assertions;
diff --git a/tests/Fixtures/TestBundle/ApiResource/WithParameter.php b/tests/Fixtures/TestBundle/ApiResource/WithParameter.php
@@ -171,7 +171,77 @@
                 'minimum' => 1,
                 'maximum' => 5,
             ],
-            required: true,
+        ),
+    ],
+    provider: [self::class, 'noopProvider']
+)]
+#[GetCollection(
+    uriTemplate: 'header_float',
+    parameters: [
+        'Bar' => new HeaderParameter(
+            schema: [
+                'type' => 'number',
+                'example' => 42.0,
+                'minimum' => 1.0,
+                'maximum' => 100.0,
+                'multipleOf' => 0.01,
+            ],
+            castToNativeType: true
+        ),
+    ],
+    provider: [self::class, 'noopProvider']
+)]
+#[GetCollection(
+    uriTemplate: 'header_boolean',
+    parameters: [
+        'Lorem' => new HeaderParameter(
+            schema: [
+                'type' => 'boolean',
+            ],
+            castToNativeType: true,
+        ),
+    ],
+    provider: [self::class, 'noopProvider']
+)]
+#[GetCollection(
+    uriTemplate: 'query_integer',
+    parameters: [
+        'Foo' => new QueryParameter(
+            schema: [
+                'type' => 'integer',
+                'example' => 3,
+                'minimum' => 1,
+                'maximum' => 5,
+            ],
+            castToNativeType: true
+        ),
+    ],
+    provider: [self::class, 'noopProvider']
+)]
+#[GetCollection(
+    uriTemplate: 'query_float',
+    parameters: [
+        'Bar' => new QueryParameter(
+            schema: [
+                'type' => 'number',
+                'example' => 42.0,
+                'minimum' => 1.0,
+                'maximum' => 100.0,
+                'multipleOf' => 0.01,
+            ],
+            castToNativeType: true
+        ),
+    ],
+    provider: [self::class, 'noopProvider']
+)]
+#[GetCollection(
+    uriTemplate: 'query_boolean',
+    parameters: [
+        'Lorem' => new QueryParameter(
+            schema: [
+                'type' => 'boolean',
+            ],
+            castToNativeType: true,
         ),
     ],
     provider: [self::class, 'noopProvider']
diff --git a/tests/Functional/Parameters/BooleanFilterTest.php b/tests/Functional/Parameters/BooleanFilterTest.php
@@ -98,14 +98,8 @@ public static function booleanFilterScenariosProvider(): \Generator
     #[DataProvider('booleanFilterNullAndEmptyScenariosProvider')]
     public function testBooleanFilterWithNullAndEmptyValues(string $url): void
     {
-        $response = self::createClient()->request('GET', $url);
-        $this->assertResponseIsSuccessful();
-
-        $responseData = $response->toArray();
-        $filteredItems = $responseData['hydra:member'];
-
-        $expectedItemCount = 3;
-        $this->assertCount($expectedItemCount, $filteredItems, \sprintf('Expected %d items for URL %s', $expectedItemCount, $url));
+        self::createClient()->request('GET', $url);
+        $this->assertResponseStatusCodeSame(422);
     }
 
     public static function booleanFilterNullAndEmptyScenariosProvider(): \Generator
diff --git a/tests/Functional/Parameters/ParameterTest.php b/tests/Functional/Parameters/ParameterTest.php

Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@ private function getParameterValues(Parameter $parameter, ?Request $request, arr`
`45`	`45`	`*`
`46`	`46`	`* @return array<mixed, mixed>\|ParameterNotFound\|array`
`47`	`47`	`*/`
`48`		`- private function extractParameterValues(Parameter $parameter, array $values): string\|ParameterNotFound\|array`
	`48`	`+ private function extractParameterValues(Parameter $parameter, array $values): string\|ParameterNotFound\|array\|bool`
`49`	`49`	`{`
`50`	`50`	`$accessors = null;`
`51`	`51`	`$key = $parameter->getKey();`
`@@ -72,7 +72,6 @@ private function extractParameterValues(Parameter $parameter, array $values): st`
`72`	`72`	`$value = $value[$accessor];`
`73`	`73`	`} else {`
`74`	`74`	`$value = new ParameterNotFound();`
`75`		`- continue;`
`76`	`75`	`}`
`77`	`76`	`}`
`78`	`77`
`@@ -100,6 +99,14 @@ private function extractParameterValues(Parameter $parameter, array $values): st`
`100`	`99`	`$value = $value[0];`
`101`	`100`	`}`
`102`	`101`
	`102`	`+ if (true === $parameter->getCastToNativeType() && ($castFn = $parameter->getCastFn())) {`
	`103`	`+ if (\is_array($value)) {`
	`104`	`+ $value = array_map(fn ($v) => $castFn($v, $parameter), $value);`
	`105`	`+ } else {`
	`106`	`+ $value = $castFn($value, $parameter);`
	`107`	`+ }`
	`108`	`+ }`
	`109`	`+`
`103`	`110`	`return $value;`
`104`	`111`	`}`
`105`	`112`	`}`