feat(symfony): api:upgrade-filter codemod + filter fixture migration (#8344)

* feat(symfony): add api:upgrade-filter codemod

Add an `api:upgrade-filter` command that rewrites legacy `#[ApiFilter]`
attributes into parameter-based filters via a php-parser visitor. Includes
the mapper/resolver/visitor pipeline, collision/skip/name-conversion
handling, DI wiring, service config and unit tests. CI runs the codemod
with --force before the functional suite.

* test: migrate #[ApiFilter] fixtures to parameter filters + legacy suite

Run api:upgrade-filter over the test fixtures to move them onto parameter
filters, and relocate the un-migrated #[ApiFilter] fixtures (Boolean,
Numeric, Enum, Order, Search, Date/Range/Exists, ExceptionToStatus) into a
Legacy/ suite that keeps covering the deprecated path.

* feat(metadata): deprecate #[ApiFilter] and Operation::$filters

Emit a deprecation for the #[ApiFilter] attribute and for Operation::$filters
consumption, surfaced through the metadata factory and OpenAPI factory with
de-duplication. Baseline the resulting deprecations.

* fix(state): cast empty/null scalar params, reject bad scalars with 400

ValueCaster now casts empty/null boolean params to false and empty/null
numeric params consistently, and rejects empty values cast to a scalar
native type with a 400 via BadRequestException (wired through the Laravel
error renderer).

* Apply suggestions from code review

Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>

Author: soyuka

.github/workflows/ci.yml

@@ -122,6 +122,50 @@ jobs:
       - name: Run container lint
         run: tests/Fixtures/app/console lint:container
 
+  upgrade-filter:
+    name: Upgrade Filter Codemod
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      matrix:
+        php:
+          - '8.5'
+      fail-fast: false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: intl, bcmath, curl, openssl, mbstring
+          ini-values: memory_limit=-1
+          tools: composer
+          coverage: none
+      - name: Get composer cache directory
+        id: composercache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+      - name: Cache dependencies
+        uses: actions/cache@v5
+        with:
+          path: ${{ steps.composercache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: ${{ runner.os }}-composer-
+      - name: Update project dependencies
+        run: |
+          composer global require soyuka/pmu
+          composer global config allow-plugins.soyuka/pmu true --no-interaction
+          composer global link .
+      - name: Codemod unit tests
+        run: vendor/bin/phpunit src/Symfony/Tests/Bundle/Command
+      # The #[ApiFilter] fixtures are already migrated in the tree, so --force only re-skips the
+      # special cases (name conversion, service/#[ApiFilter] key overlap); it must not error.
+      - name: Codemod force run
+        run: tests/Fixtures/app/console api:upgrade-filter --force
+      # Guard both paths: the migrated QueryParameter fixtures and the Legacy/ #[ApiFilter] fixtures.
+      - name: Functional suite
+        run: vendor/bin/phpunit tests/Functional
+
   phpstan:
     name: PHPStan (PHP ${{ matrix.php }})
     runs-on: ubuntu-latest

phpunit.baseline.xml

@@ -48,4 +48,68 @@
    <issue><![CDATA[Since api-platform/core 4.2: Having multiple "#[ApiResource]" attributes with the same "shortName" "OneToOneSubresourceAnswer" on class "ApiPlatform\Tests\Fixtures\TestBundle\Entity\OneToOneSubresourceAnswer" is deprecated and will result in automatic short name deduplication in API Platform 5.x. Set "defaults.extra_properties.deduplicate_resource_short_names" to "true" in the API Platform configuration to enable it now.]]></issue>
   </line>
  </file>
+ <file path="src/Metadata/Resource/Factory/FiltersResourceMetadataCollectionFactory.php">
+  <line number="63" hash="3f3dc5ed5b98671df2409a336d87db4f629303d2">
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "AbstractDummy" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ArrayFilterValidator" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ContainNonResource" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ConvertedBoolean" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ConvertedDate" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ConvertedInteger" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ConvertedOwner" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "ConvertedString" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "Dummy2" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "Dummy3" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyDate" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyExceptionToStatus" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyForBackedEnumFilter" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyGroup" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyImmutableDate" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "Dummy" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyProperty" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyResource" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyTravel" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "DummyWithArrayOfNotResourceObjects" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "EmbeddedDummy" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "FilteredAttributeParameter" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "FilterValidator" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "JsonApiFilteringProperty" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "MainResource" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy2" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy3" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy4" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy5" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy6" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy7" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy8" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedDummy" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedToDummyFriend2" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedToDummyFriend3" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedToDummyFriend4" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedToDummyFriend5" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedToDummyFriend6" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "RelatedToDummyFriend" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "SeparatedDocument" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on the "SeparatedEntity" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.]]></issue>
+  </line>
+ </file>
+ <file path="src/Symfony/Bundle/DependencyInjection/Compiler/AttributeFilterPass.php">
+  <line number="60" hash="8001ad8a808628ce0a018b7798041837c9d07aa1">
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\AgentApi" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\FilterWithStateOptions" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\Issue5605\MainResource" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\Issue5648\DummyResource" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\ResourceWithSeparatedEntity" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\ConvertedBoolean" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\ConvertedDate" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\ConvertedInteger" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\ConvertedOwner" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\ConvertedString" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\DummyDate" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\Legacy\DummyExceptionToStatus" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\Legacy\DummyForBackedEnumFilter" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\Legacy\FilteredAttributeParameter" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+   <issue><![CDATA[Since api-platform/core 4.4: Declaring filters on "ApiPlatform\Tests\Fixtures\TestBundle\Entity\Legacy\SearchFilterParameter" with the "#[ApiFilter]" attribute is deprecated, use the "#[QueryParameter]" attribute instead. The "#[ApiFilter]" attribute will be removed in 6.0.]]></issue>
+  </line>
+ </file>
 </files>

src/Laravel/Exception/ErrorRenderer.php

@@ -15,6 +15,7 @@
 
 use ApiPlatform\Laravel\ApiResource\Error;
 use ApiPlatform\Laravel\Controller\ApiPlatformController;
+use ApiPlatform\Metadata\Exception\HttpExceptionInterface;
 use ApiPlatform\Metadata\Exception\InvalidUriVariableException;
 use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;
 use ApiPlatform\Metadata\Exception\StatusAwareExceptionInterface;
@@ -186,7 +187,7 @@ private function getStatusCode(?HttpOperation $apiOperation, ?HttpOperation $err
             return 403;
         }
 
-        if ($exception instanceof SymfonyHttpExceptionInterface) {
+        if ($exception instanceof SymfonyHttpExceptionInterface || $exception instanceof HttpExceptionInterface) {
             return $exception->getStatusCode();
         }
 

src/Metadata/ApiFilter.php

@@ -19,6 +19,8 @@
  * Filter attribute.
  *
  * @author Antoine Bluchet <soyuka@gmail.com>
+ *
+ * @deprecated since API Platform 4.4, use the {@see QueryParameter} attribute instead. Will be removed in 6.0.
  */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
 final class ApiFilter

src/Metadata/Exception/BadRequestException.php

@@ -0,0 +1,33 @@
+<?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\Metadata\Exception;
+
+/**
+ * Framework-agnostic 400 Bad Request, mapped by both the Symfony and Laravel error handlers.
+ */
+class BadRequestException extends \RuntimeException implements ExceptionInterface, HttpExceptionInterface
+{
+    public function getStatusCode(): int
+    {
+        return 400;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function getHeaders(): array
+    {
+        return [];
+    }
+}

src/Metadata/Resource/Factory/FiltersResourceMetadataCollectionFactory.php

@@ -58,7 +58,12 @@ public function create(string $resourceClass): ResourceMetadataCollection
 
         foreach ($resourceMetadataCollection as $i => $resource) {
             foreach ($operations = $resource->getOperations() ?? [] as $operationName => $operation) {
-                $operations->add($operationName, $operation->withFilters(array_unique(array_merge($resource->getFilters() ?? [], $operation->getFilters() ?? [], $filters))));
+                $operationFilters = array_unique(array_merge($resource->getFilters() ?? [], $operation->getFilters() ?? [], $filters));
+                if ($operationFilters) {
+                    trigger_deprecation('api-platform/core', '4.4', \sprintf('Declaring filters on the "%s" operation through "Operation::$filters" is deprecated, use the "parameters" argument instead. It will be removed in 6.0.', $operation->getShortName()));
+                }
+
+                $operations->add($operationName, $operation->withFilters($operationFilters));
             }
 
             if ($operations) {

src/Serializer/Filter/PropertyFilter.php

@@ -280,7 +280,7 @@ public function getSchema(MetadataParameter $parameter): array
     public function getOpenApiParameters(MetadataParameter $parameter): Parameter
     {
         $example = \sprintf(
-            '%1$s[]={propertyName}&%1$s[]={anotherPropertyName}',
+            '%1$s[]={propertyName}&%1$s[]={anotherPropertyName}&%1$s[{nestedPropertyParent}][]={nestedProperty}',
             $parameter->getKey()
         );