feat(symfony): upgrade-filter handles relations, dates, case, arguments

Close five gaps in the api:upgrade-filter codemod so it migrates the
real-world filter shapes faithfully or skips what it cannot:

- Search-on-relation -> IriFilter (native type resolves to a resource)
- DateFilter null-management -> filterContext: DateFilter::INCLUDE_NULL_*
- i-variant search strategies -> caseSensitive flag (iexact->ExactFilter)
- custom filter arguments preserved; filters keyed by service id so two
  instances of one class survive; nested keys emit an explicit property
- detect & skip resources the target filters cannot express: an in-place
  filters: service filter sharing a key (F5/F6 overlap), or a property
  renamed by a name converter (the overlay filters do not denormalize)

Author: soyuka

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterCollisionException.php

@@ -20,7 +20,7 @@
  *
  * @internal
  */
-final class UpgradeApiFilterCollisionException extends \RuntimeException
+final class UpgradeApiFilterCollisionException extends UpgradeApiFilterSkipException
 {
     public function __construct(public readonly string $parameterKey)
     {

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterMapper.php

@@ -43,24 +43,37 @@ public function map(string $filterClass, ?string $strategy = null, ?string $prop
             'NumericFilter' => new UpgradeApiFilterMapping($canonical('ExactFilter'), castToNativeType: true, nativeType: $propertyNativeType ?? 'int'),
             'BackedEnumFilter' => new UpgradeApiFilterMapping($canonical('ExactFilter'), castToNativeType: true, nativeType: $propertyNativeType),
             'OrderFilter' => new UpgradeApiFilterMapping($canonical('SortFilter')),
-            'SearchFilter' => new UpgradeApiFilterMapping($canonical($this->searchReplacement($strategy, $isRelation))),
+            'SearchFilter' => $this->searchReplacement($canonical, $strategy, $isRelation),
             default => new UpgradeApiFilterMapping($filterClass),
         };
     }
 
-    private function searchReplacement(?string $strategy, bool $isRelation): string
+    /**
+     * @param callable(string): string $canonical
+     */
+    private function searchReplacement(callable $canonical, ?string $strategy, bool $isRelation): UpgradeApiFilterMapping
     {
         if ($isRelation) {
-            return 'IriFilter';
+            return new UpgradeApiFilterMapping($canonical('IriFilter'));
         }
 
-        return match ($strategy) {
+        // A leading "i" makes the legacy strategy case-insensitive; the new search filters are
+        // case-insensitive by default, so a case-sensitive (non-"i") strategy opts back in.
+        $caseInsensitive = null !== $strategy && str_starts_with($strategy, 'i');
+        $base = $caseInsensitive ? substr($strategy, 1) : $strategy;
+
+        $shortName = match ($base) {
             'exact' => 'ExactFilter',
             'start' => 'StartSearchFilter',
             'end' => 'EndSearchFilter',
             'word_start' => 'WordStartSearchFilter',
             default => 'PartialSearchFilter',
         };
+
+        // ExactFilter has no case-sensitivity option.
+        $caseSensitive = 'ExactFilter' !== $shortName && !$caseInsensitive;
+
+        return new UpgradeApiFilterMapping($canonical($shortName), caseSensitive: $caseSensitive);
     }
 
     private function driverNamespace(string $filterClass): ?string

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterMapping.php

@@ -24,6 +24,7 @@ public function __construct(
         public string $filterClass,
         public bool $castToNativeType = false,
         public ?string $nativeType = null,
+        public bool $caseSensitive = false,
     ) {
     }
 }

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterNameConversionException.php

@@ -0,0 +1,29 @@
+<?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\Symfony\Bundle\Command\Upgrade;
+
+/**
+ * Thrown when a filtered property is renamed by a configured name converter. The new overlay filters
+ * do not denormalize the property (the parameter factory normalizes it), so such a resource cannot be
+ * auto-migrated faithfully and is reported and skipped.
+ *
+ * @internal
+ */
+final class UpgradeApiFilterNameConversionException extends UpgradeApiFilterSkipException
+{
+    public function __construct(public readonly string $property)
+    {
+        parent::__construct(\sprintf('Cannot auto-migrate: property "%s" is renamed by a name converter, which the target filters do not support. Migrate this resource manually.', $property));
+    }
+}

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterParameter.php

@@ -26,13 +26,21 @@
      * @param string|null $property         explicit property when it differs from $key
      * @param string|null $nativeType       scalar native type hint (bool|int|float|string), null to omit
      * @param bool        $castToNativeType whether the QueryParameter should coerce the raw value
+     * @param string|null $filterContext    filter-specific config carried by the QueryParameter (e.g. the
+     *                                       DateFilter null-management mode), null to omit
+     * @param bool                 $caseSensitive emit `caseSensitive: true` on the search filter (case-sensitive
+     *                                            strategy); the new search filters are case-insensitive by default
+     * @param array<string, mixed> $arguments     constructor arguments to pass to the (kept) filter, named
      */
     public function __construct(
         public string $key,
         public string $filterClass,
         public ?string $property = null,
         public ?string $nativeType = null,
         public bool $castToNativeType = false,
+        public ?string $filterContext = null,
+        public bool $caseSensitive = false,
+        public array $arguments = [],
     ) {
     }
 }

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterResolver.php

@@ -13,52 +13,104 @@
 
 namespace ApiPlatform\Symfony\Bundle\Command\Upgrade;
 
+use ApiPlatform\Doctrine\Common\Filter\DateFilterInterface;
+use ApiPlatform\Metadata\Exception\PropertyNotFoundException;
 use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
+use ApiPlatform\Metadata\ResourceClassResolverInterface;
+use ApiPlatform\Metadata\Util\TypeHelper;
+use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
 
 /**
  * Turns the legacy filters declared on a resource into the canonical {@see UpgradeApiFilterParameter}
  * list that the visitor injects as QueryParameters.
  *
  * Properties and strategies are read from each filter's runtime `getDescription()` (the only place
  * that knows what a class-level auto-detecting filter actually targets), then mapped to the canonical
- * filter by {@see UpgradeApiFilterMapper}.
+ * filter by {@see UpgradeApiFilterMapper}. A SearchFilter targeting an association cannot be told apart
+ * from one targeting a scalar field through the description alone, so the property's native type is
+ * resolved to decide whether it maps to an IriFilter.
  *
  * @internal
  */
 final class UpgradeApiFilterResolver
 {
-    public function __construct(private readonly UpgradeApiFilterMapper $mapper)
-    {
+    /** DateFilter null-management modes carried verbatim into the QueryParameter `filterContext`. */
+    private const DATE_NULL_MANAGEMENT = [
+        DateFilterInterface::EXCLUDE_NULL,
+        DateFilterInterface::INCLUDE_NULL_BEFORE,
+        DateFilterInterface::INCLUDE_NULL_AFTER,
+        DateFilterInterface::INCLUDE_NULL_BEFORE_AND_AFTER,
+    ];
+
+    public function __construct(
+        private readonly UpgradeApiFilterMapper $mapper,
+        private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory,
+        private readonly ResourceClassResolverInterface $resourceClassResolver,
+    ) {
     }
 
     /**
-     * @param array<class-string, FilterInterface> $filtersByClass
+     * @param list<array{filter: FilterInterface, filterClass: class-string, arguments: array<string, mixed>}> $filters
+     *                                                                                                          one entry per `#[ApiFilter]` declaration (keyed by service id upstream so that two
+     *                                                                                                          instances of the same filter class are kept distinct)
+     * @param list<FilterInterface>                                                                            $reservedFilters in-place service filters (the resource `filters:` array) whose query keys must
+     *                                                                                                          not be re-migrated: an #[ApiFilter] mapping onto one of these keys would shadow it
      *
      * @return list<UpgradeApiFilterParameter>
      *
-     * @throws UpgradeApiFilterCollisionException when two filters map to the same parameter key
+     * @throws UpgradeApiFilterCollisionException when two filters map to the same parameter key, or an
+     *                                            #[ApiFilter] key collides with an in-place service filter
      */
-    public function resolve(string $resourceClass, array $filtersByClass): array
+    public function resolve(string $resourceClass, array $filters, array $reservedFilters = []): array
     {
         $params = [];
         $seenKeys = [];
 
-        foreach ($filtersByClass as $filterClass => $filter) {
-            foreach ($this->group($filter->getDescription($resourceClass)) as $key => $info) {
+        foreach ($reservedFilters as $reservedFilter) {
+            foreach (array_keys($this->group($reservedFilter->getDescription($resourceClass))) as $reservedKey) {
+                $seenKeys[$reservedKey] = true;
+            }
+        }
+
+        foreach ($filters as ['filter' => $filter, 'filterClass' => $filterClass, 'arguments' => $arguments]) {
+            $description = $filter->getDescription($resourceClass);
+            // The new overlay filters do not denormalize property names, so a resource whose filtered
+            // properties are renamed by a name converter cannot be migrated faithfully — skip it.
+            $this->assertNoNameConversion($filter, $description);
+
+            // The mode of a DateFilter (include/exclude null) lives in the constructor `properties` map
+            // as the value, never in getDescription(); read it straight from the filter instance.
+            $rawProperties = is_callable([$filter, 'getProperties']) ? ($filter->getProperties() ?? []) : [];
+
+            foreach ($this->group($description) as $key => $info) {
                 if (isset($seenKeys[$key])) {
                     throw new UpgradeApiFilterCollisionException($key);
                 }
                 $seenKeys[$key] = true;
 
-                $mapping = $this->mapper->map($filterClass, $info['strategy'], $info['type'], $info['isRelation']);
-                $property = (null !== $info['property'] && $info['property'] !== $key) ? $info['property'] : null;
+                $isRelation = null !== $info['property'] && $this->isRelation($resourceClass, $info['property']);
+                $mapping = $this->mapper->map($filterClass, $info['strategy'], $info['type'], $isRelation);
+                // The new filter system infers the property from a plain key, but cannot for a nested
+                // (dotted) key, so it must be stated explicitly even when it equals the key.
+                $property = $this->explicitProperty($info['property'], $key);
+
+                $mode = null !== $info['property'] ? ($rawProperties[$info['property']] ?? null) : null;
+                $filterContext = \is_string($mode) && \in_array($mode, self::DATE_NULL_MANAGEMENT, true) ? $mode : null;
+
+                // Constructor arguments only carry over when the filter is kept as-is (custom or a
+                // surviving filter); a remapped filter has a different constructor.
+                $filterArguments = $mapping->filterClass === $filterClass ? $arguments : [];
 
                 $params[] = new UpgradeApiFilterParameter(
                     key: $key,
                     filterClass: $mapping->filterClass,
                     property: $property,
                     nativeType: $mapping->nativeType,
                     castToNativeType: $mapping->castToNativeType,
+                    filterContext: $filterContext,
+                    caseSensitive: $mapping->caseSensitive,
+                    arguments: $filterArguments,
                 );
             }
         }
@@ -73,15 +125,22 @@ public function resolve(string $resourceClass, array $filtersByClass): array
      *
      * @param array<string, array<string, mixed>> $description
      *
-     * @return array<string, array{property: ?string, strategy: ?string, type: ?string, isRelation: bool}>
+     * @return array<string, array{property: ?string, strategy: ?string, type: ?string}>
      */
     private function group(array $description): array
     {
         $grouped = [];
 
         foreach ($description as $descKey => $meta) {
             if (str_starts_with($descKey, 'order[')) {
-                $grouped['order[:property]'] = ['property' => null, 'strategy' => null, 'type' => null, 'isRelation' => false];
+                $grouped['order[:property]'] = ['property' => null, 'strategy' => null, 'type' => null];
+                continue;
+            }
+
+            // ExistsFilter uses the `exists[property]` query syntax; collapse it to the catch-all template
+            // (the bracketed property, name-converted or not, is resolved by the filter at query time).
+            if (str_starts_with($descKey, 'exists[')) {
+                $grouped['exists[:property]'] = ['property' => null, 'strategy' => null, 'type' => null];
                 continue;
             }
 
@@ -91,10 +150,69 @@ private function group(array $description): array
                 'property' => $meta['property'] ?? $key,
                 'strategy' => $meta['strategy'] ?? null,
                 'type' => $meta['type'] ?? null,
-                'isRelation' => (bool) ($meta['is_collection'] ?? false) || isset($meta['association']),
             ];
         }
 
         return $grouped;
     }
+
+    /**
+     * The new overlay filters read the property as-is (no name-converter denormalization the legacy
+     * filters did), while the parameter factory normalizes it — so a filtered property renamed by a
+     * configured name converter would target the wrong field. Detect it and skip the resource.
+     *
+     * @param array<string, array<string, mixed>> $description
+     *
+     * @throws UpgradeApiFilterNameConversionException
+     */
+    private function assertNoNameConversion(FilterInterface $filter, array $description): void
+    {
+        $nameConverter = is_callable([$filter, 'getNameConverter']) ? $filter->getNameConverter() : null;
+        if (!$nameConverter instanceof NameConverterInterface) {
+            return;
+        }
+
+        foreach ($description as $meta) {
+            $property = $meta['property'] ?? null;
+            if (null === $property) {
+                continue;
+            }
+
+            $real = implode('.', array_map($nameConverter->denormalize(...), explode('.', (string) $property)));
+            if ($real !== $property) {
+                throw new UpgradeApiFilterNameConversionException($property);
+            }
+        }
+    }
+
+    private function explicitProperty(?string $property, string $key): ?string
+    {
+        if (null === $property) {
+            return null;
+        }
+
+        return ($property !== $key || str_contains($property, '.')) ? $property : null;
+    }
+
+    /**
+     * A SearchFilter property is a relation when its native type resolves to an API resource class (an
+     * object, or a collection of objects). Gating on the resource resolver keeps value objects such as
+     * \DateTime — which also resolve to a class — out of the IriFilter mapping.
+     */
+    private function isRelation(string $resourceClass, string $property): bool
+    {
+        try {
+            $type = $this->propertyMetadataFactory->create($resourceClass, $property)->getNativeType();
+        } catch (PropertyNotFoundException) {
+            return false;
+        }
+
+        if (null === $type) {
+            return false;
+        }
+
+        $className = TypeHelper::getClassName(TypeHelper::getCollectionValueType($type) ?? $type);
+
+        return null !== $className && $this->resourceClassResolver->isResourceClass($className);
+    }
 }

src/Symfony/Bundle/Command/Upgrade/UpgradeApiFilterSkipException.php

@@ -0,0 +1,23 @@
+<?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\Symfony\Bundle\Command\Upgrade;
+
+/**
+ * Base class for the reasons a resource cannot be auto-migrated and is reported and skipped by the command.
+ *
+ * @internal
+ */
+abstract class UpgradeApiFilterSkipException extends \RuntimeException
+{
+}