feat(state): skip the filter for empty parameter values

Add a skipFilterOnEmpty option on Parameter, defaulting to true. An empty
string value is kept, so validation still runs and can return a 422, but
the Doctrine ORM/ODM ParameterExtension does not call the filter for it,
avoiding driver-specific errors (e.g. PostgreSQL rejecting '' for an
integer column). Set it to false to call the filter with the raw value.

ValueCaster no longer casts empty strings (reverted): an empty value is a
present-but-valueless parameter, distinct from a typed zero/false and from
an absent parameter.

Author: soyuka

src/Doctrine/Odm/Extension/ParameterExtension.php

@@ -55,6 +55,12 @@ private function applyFilter(Builder $aggregationBuilder, ?string $resourceClass
                 continue;
             }
 
+            // An empty value is left for validation to handle (e.g. a 422); by default the filter
+            // itself is not called for it. Set skipFilterOnEmpty to false to call it anyway.
+            if ('' === $v && false !== $parameter->getSkipFilterOnEmpty()) {
+                continue;
+            }
+
             $values = $this->extractParameterValue($parameter, $v);
             if (null === ($filterId = $parameter->getFilter())) {
                 continue;

src/Doctrine/Orm/Extension/ParameterExtension.php

@@ -55,6 +55,12 @@ private function applyFilter(QueryBuilder $queryBuilder, QueryNameGeneratorInter
                 continue;
             }
 
+            // An empty value is left for validation to handle (e.g. a 422); by default the filter
+            // itself is not called for it. Set skipFilterOnEmpty to false to call it anyway.
+            if ('' === $v && false !== $parameter->getSkipFilterOnEmpty()) {
+                continue;
+            }
+
             $values = $this->extractParameterValue($parameter, $v);
             if (null === ($filterId = $parameter->getFilter())) {
                 continue;

src/Metadata/Parameter.php

@@ -42,6 +42,7 @@ abstract class Parameter
      * @param ?bool                                           $castToNativeType whether API Platform should cast your parameter to the nativeType declared
      * @param ?callable(mixed): mixed                         $castFn           the closure used to cast your parameter, this gets called only when $castToNativeType is set
      * @param ?string                                         $filterClass      the class to use when resolving filter properties (from stateOptions)
+     * @param ?bool                                           $skipFilterOnEmpty when true (the default), the filter is not called for an empty string value (validation still runs); set to false to call the filter with the raw empty value (the filter must then handle it)
      *
      * @phpstan-param array<string, mixed>|null $schema
      *
@@ -70,6 +71,7 @@ public function __construct(
         protected mixed $castFn = null,
         protected mixed $default = null,
         protected ?string $filterClass = null,
+        protected ?bool $skipFilterOnEmpty = null,
     ) {
     }
 
@@ -369,6 +371,19 @@ public function withCastToNativeType(bool $castToNativeType): self
         return $self;
     }
 
+    public function getSkipFilterOnEmpty(): ?bool
+    {
+        return $this->skipFilterOnEmpty;
+    }
+
+    public function withSkipFilterOnEmpty(bool $skipFilterOnEmpty): self
+    {
+        $self = clone $this;
+        $self->skipFilterOnEmpty = $skipFilterOnEmpty;
+
+        return $self;
+    }
+
     public function getCastFn(): ?callable
     {
         return $this->castFn;

src/State/Parameter/ValueCaster.php

@@ -30,7 +30,7 @@ public static function toBool(mixed $v): mixed
 
         return match (strtolower($v)) {
             '1', 'true' => true,
-            '0', 'false', '' => false,
+            '0', 'false' => false,
             default => $v,
         };
     }
@@ -41,10 +41,6 @@ public static function toInt(mixed $v): mixed
             return $v;
         }
 
-        if ('' === $v) {
-            return 0;
-        }
-
         $value = filter_var($v, \FILTER_VALIDATE_INT);
 
         return false === $value ? $v : $value;
@@ -56,10 +52,6 @@ public static function toFloat(mixed $v): mixed
             return $v;
         }
 
-        if ('' === $v) {
-            return 0.0;
-        }
-
         $value = filter_var($v, \FILTER_VALIDATE_FLOAT);
 
         return false === $value ? $v : $value;

src/State/Tests/Parameter/ValueCasterTest.php

@@ -34,8 +34,8 @@ public function testToInt(mixed $value, mixed $expected): void
     public static function intProvider(): \Generator
     {
         yield 'integer string' => ['10', 10];
-        yield 'empty string' => ['', 0];
         yield 'invalid string' => ['string', 'string'];
+        yield 'empty string is not cast' => ['', ''];
         yield 'null string is not cast' => ['null', 'null'];
         yield 'int passthrough' => [10, 10];
     }
@@ -49,8 +49,8 @@ public function testToFloat(mixed $value, mixed $expected): void
     public static function floatProvider(): \Generator
     {
         yield 'float string' => ['1.5', 1.5];
-        yield 'empty string' => ['', 0.0];
         yield 'invalid string' => ['string', 'string'];
+        yield 'empty string is not cast' => ['', ''];
         yield 'null string is not cast' => ['null', 'null'];
         yield 'float passthrough' => [1.5, 1.5];
     }
@@ -61,12 +61,10 @@ public static function boolProvider(): \Generator
         yield 'numeric 1' => ['1', true];
         yield 'false string' => ['false', false];
         yield 'numeric 0' => ['0', false];
-        // An empty value casts to false deterministically across drivers, instead of
-        // reaching the database as a raw string that each driver coerces differently.
-        yield 'empty string' => ['', false];
-        // Genuinely invalid values (including "null") are returned untouched so constraint
-        // validation rejects them; "null" is not a supported boolean input.
+        // Unrecognized values (including empty and "null" strings) are returned untouched;
+        // emptiness is handled at the filter layer via skipFilterOnEmpty, not by the caster.
         yield 'invalid string' => ['string', 'string'];
+        yield 'empty string is not cast' => ['', ''];
         yield 'null string is not cast' => ['null', 'null'];
         yield 'non-string passthrough' => [true, true];
     }

tests/Functional/Parameters/BooleanFilterTest.php

@@ -77,24 +77,19 @@ public static function booleanFilterScenariosProvider(): \Generator
     }
 
     /**
-     * With the canonical ExactFilter, an empty boolean value casts to false (deterministically
-     * across drivers), so it matches the inactive rows — unlike the deprecated BooleanFilter
-     * which skipped filtering (returning all rows, covered by the legacy regression suite).
+     * An empty value does not call the filter (skipFilterOnEmpty defaults to true) while the value
+     * is still validated, so the result matches the unfiltered collection.
      */
     #[DataProvider('booleanFilterEmptyScenariosProvider')]
     public function testBooleanFilterWithEmptyValues(string $url): void
     {
-        $response = self::createClient()->request('GET', $url);
-        $this->assertResponseIsSuccessful();
-
-        $responseData = $response->toArray();
-        $filteredItems = $responseData['hydra:member'];
+        $client = self::createClient();
+        $unfilteredCount = \count($client->request('GET', '/filtered_boolean_parameters')->toArray()['hydra:member']);
 
-        $this->assertCount(1, $filteredItems, \sprintf('Expected one inactive item for URL %s', $url));
+        $response = $client->request('GET', $url);
+        $this->assertResponseIsSuccessful();
 
-        foreach ($filteredItems as $item) {
-            $this->assertFalse($item['active'], 'Expected an empty boolean value to cast to false');
-        }
+        $this->assertCount($unfilteredCount, $response->toArray()['hydra:member'], \sprintf('Expected the filter to be skipped for URL %s', $url));
     }
 
     public static function booleanFilterEmptyScenariosProvider(): \Generator

tests/Functional/Parameters/NumericFilterTest.php

@@ -67,20 +67,19 @@ public static function rangeFilterScenariosProvider(): \Generator
     }
 
     /**
-     * With the canonical ExactFilter, an empty value casts to 0/0.0 (deterministically across
-     * drivers) and matches no row in this fixture — unlike the deprecated NumericFilter which
-     * skipped filtering (returning all rows, covered by the legacy regression suite).
+     * An empty value does not call the filter (skipFilterOnEmpty defaults to true) while the value
+     * is still validated, so the result matches the unfiltered collection.
      */
     #[DataProvider('emptyScenariosProvider')]
     public function testRangeFilterWithEmptyValues(string $url): void
     {
-        $response = self::createClient()->request('GET', $url);
-        $this->assertResponseIsSuccessful();
+        $client = self::createClient();
+        $unfilteredCount = \count($client->request('GET', '/filtered_numeric_parameters')->toArray()['hydra:member']);
 
-        $responseData = $response->toArray();
-        $filteredItems = $responseData['hydra:member'];
+        $response = $client->request('GET', $url);
+        $this->assertResponseIsSuccessful();
 
-        $this->assertCount(0, $filteredItems, \sprintf('Expected no item for URL %s', $url));
+        $this->assertCount($unfilteredCount, $response->toArray()['hydra:member'], \sprintf('Expected the filter to be skipped for URL %s', $url));
     }
 
     public static function emptyScenariosProvider(): \Generator