feat(doctrine): allow property aliasing on doctrine filters

src/Doctrine/Common/Filter/PropertyAliasesFilterTrait.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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\Doctrine\Common\Filter;
+
+use ApiPlatform\Metadata\Exception\UnMappedPropertyAliasException;
+
+/**
+ * Interface for filtering the collection by given properties.
+ *
+ * @author Christophe Zarebski <[email protected]>
+ */
+trait PropertyAliasesFilterTrait
+{
+    protected array $propertyAliases = [];
+
+    protected function getPropertyAliases(): array
+    {
+        return $this->propertyAliases;
+    }
+
+    protected function isAlias(int|string $alias): bool
+    {
+        return !empty($this->getPropertyAliases()) && \in_array($alias, $this->getPropertyAliases(), true);
+    }
+
+    protected function getAliasForPropertyOrProperty(int|string $property): int|string
+    {
+        return $this->propertyAliases[$property] ?? $property;
+    }
+
+    protected function getPropertyFromAlias(int|string $alias): int|string
+    {
+        return array_flip($this->propertyAliases)[$alias] ?? throw new UnMappedPropertyAliasException($alias);
+    }
+}

src/Doctrine/Odm/Filter/AbstractFilter.php

@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Doctrine\Odm\Filter;
 
+use ApiPlatform\Doctrine\Common\Filter\PropertyAliasesFilterTrait;
 use ApiPlatform\Doctrine\Common\Filter\PropertyAwareFilterInterface;
 use ApiPlatform\Doctrine\Common\PropertyHelperTrait;
 use ApiPlatform\Doctrine\Odm\PropertyHelperTrait as MongoDbOdmPropertyHelperTrait;
@@ -33,12 +34,15 @@
 abstract class AbstractFilter implements FilterInterface, PropertyAwareFilterInterface
 {
     use MongoDbOdmPropertyHelperTrait;
+    use PropertyAliasesFilterTrait;
     use PropertyHelperTrait;
+
     protected LoggerInterface $logger;
 
-    public function __construct(protected ManagerRegistry $managerRegistry, ?LoggerInterface $logger = null, protected ?array $properties = null, protected ?NameConverterInterface $nameConverter = null)
+    public function __construct(protected ManagerRegistry $managerRegistry, ?LoggerInterface $logger = null, protected ?array $properties = null, protected ?NameConverterInterface $nameConverter = null, array $propertyAliases = [])
     {
         $this->logger = $logger ?? new NullLogger();
+        $this->propertyAliases = $propertyAliases;
     }
 
     /**
@@ -94,6 +98,10 @@ protected function isPropertyEnabled(string $property, string $resourceClass): b
 
     protected function denormalizePropertyName(string|int $property): string
     {
+        if ($this->isAlias($property)) {
+            $property = $this->getPropertyFromAlias($property);
+        }
+
         if (!$this->nameConverter instanceof NameConverterInterface) {
             return (string) $property;
         }
@@ -103,6 +111,8 @@ protected function denormalizePropertyName(string|int $property): string
 
     protected function normalizePropertyName(string $property): string
     {
+        $property = $this->getAliasForPropertyOrProperty($property);
+
         if (!$this->nameConverter instanceof NameConverterInterface) {
             return $property;
         }

src/Doctrine/Odm/Filter/BooleanFilter.php

@@ -46,6 +46,10 @@
  *     book.boolean_filter:
  *         parent: 'api_platform.doctrine.odm.boolean_filter'
  *         arguments: [ { published: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { published: ~ }
+ *         #   $propertyAliases: { published: 'issuedOn' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)

src/Doctrine/Odm/Filter/DateFilter.php

@@ -59,6 +59,10 @@
  *     book.date_filter:
  *         parent: 'api_platform.doctrine.odm.date_filter'
  *         arguments: [ { createdAt: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { createdAt: ~ }
+ *         #   $propertyAliases: { createdAt: 'created' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)

src/Doctrine/Odm/Filter/ExistsFilter.php

@@ -50,6 +50,10 @@
  *     book.exist_filter:
  *         parent: 'api_platform.doctrine.odm.exist_filter'
  *         arguments: [ { comment: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { comment: ~ }
+ *         #   $propertyAliases: { comment: 'opinion' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
@@ -111,9 +115,9 @@ final class ExistsFilter extends AbstractFilter implements ExistsFilterInterface
 {
     use ExistsFilterTrait;
 
-    public function __construct(ManagerRegistry $managerRegistry, ?LoggerInterface $logger = null, ?array $properties = null, string $existsParameterName = self::QUERY_PARAMETER_KEY, ?NameConverterInterface $nameConverter = null)
+    public function __construct(ManagerRegistry $managerRegistry, ?LoggerInterface $logger = null, ?array $properties = null, string $existsParameterName = self::QUERY_PARAMETER_KEY, ?NameConverterInterface $nameConverter = null, array $propertyAliases = [])
     {
-        parent::__construct($managerRegistry, $logger, $properties, $nameConverter);
+        parent::__construct($managerRegistry, $logger, $properties, $nameConverter, $propertyAliases);
 
         $this->existsParameterName = $existsParameterName;
     }

src/Doctrine/Odm/Filter/NumericFilter.php

@@ -46,6 +46,10 @@
  *     book.numeric_filter:
  *         parent: 'api_platform.doctrine.odm.numeric_filter'
  *         arguments: [ { price: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { price: ~ }
+ *         #   $propertyAliases: { price: 'priceInclVat' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)

src/Doctrine/Odm/Filter/OrderFilter.php

@@ -49,6 +49,11 @@
  *     book.order_filter:
  *         parent: 'api_platform.doctrine.odm.order_filter'
  *         arguments: [ $properties: { id: ~, title: ~ }, $orderParameterName: order ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { id: ASC, title: DESC }
+ *         #   $orderParameterName: order
+ *         #   $propertyAliases: { id: 'identifier', title: 'aliasedFieldName' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
@@ -131,6 +136,10 @@
  *     book.order_filter:
  *         parent: 'api_platform.doctrine.odm.order_filter'
  *         arguments: [ { id: ASC, title: DESC } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { id: ASC, title: DESC }
+ *         #   $propertyAliases: { id: 'identifier', title: 'aliasedFieldName' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
@@ -200,7 +209,7 @@ final class OrderFilter extends AbstractFilter implements OrderFilterInterface
 {
     use OrderFilterTrait;
 
-    public function __construct(ManagerRegistry $managerRegistry, string $orderParameterName = 'order', ?LoggerInterface $logger = null, ?array $properties = null, ?NameConverterInterface $nameConverter = null)
+    public function __construct(ManagerRegistry $managerRegistry, string $orderParameterName = 'order', ?LoggerInterface $logger = null, ?array $properties = null, ?NameConverterInterface $nameConverter = null, array $propertyAliases = [])
     {
         if (null !== $properties) {
             $properties = array_map(static function ($propertyOptions) {
@@ -215,7 +224,7 @@ public function __construct(ManagerRegistry $managerRegistry, string $orderParam
             }, $properties);
         }
 
-        parent::__construct($managerRegistry, $logger, $properties, $nameConverter);
+        parent::__construct($managerRegistry, $logger, $properties, $nameConverter, $propertyAliases);
 
         $this->orderParameterName = $orderParameterName;
     }

src/Doctrine/Odm/Filter/RangeFilter.php

@@ -46,6 +46,10 @@
  *     book.range_filter:
  *         parent: 'api_platform.doctrine.odm.range_filter'
  *         arguments: [ { price: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { price: ~ }
+ *         #   $propertyAliases: { price: 'priceInclVat' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)

src/Doctrine/Odm/Filter/SearchFilter.php

@@ -77,6 +77,10 @@
  *     book.search_filter:
  *         parent: 'api_platform.doctrine.odm.search_filter'
  *         arguments: [ { isbn: 'exact', description: 'partial' } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { isbn: 'exact', description: 'partial' }
+ *         #   $propertyAliases: { isbn: 'identifier', description: 'aliasedDescription' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
@@ -140,9 +144,9 @@ final class SearchFilter extends AbstractFilter implements SearchFilterInterface
 
     public const DOCTRINE_INTEGER_TYPE = [MongoDbType::INTEGER, MongoDbType::INT];
 
-    public function __construct(ManagerRegistry $managerRegistry, IriConverterInterface $iriConverter, ?IdentifiersExtractorInterface $identifiersExtractor, ?PropertyAccessorInterface $propertyAccessor = null, ?LoggerInterface $logger = null, ?array $properties = null, ?NameConverterInterface $nameConverter = null)
+    public function __construct(ManagerRegistry $managerRegistry, IriConverterInterface $iriConverter, ?IdentifiersExtractorInterface $identifiersExtractor, ?PropertyAccessorInterface $propertyAccessor = null, ?LoggerInterface $logger = null, ?array $properties = null, ?NameConverterInterface $nameConverter = null, array $propertyAliases = [])
     {
-        parent::__construct($managerRegistry, $logger, $properties, $nameConverter);
+        parent::__construct($managerRegistry, $logger, $properties, $nameConverter, $propertyAliases);
 
         $this->iriConverter = $iriConverter;
         $this->identifiersExtractor = $identifiersExtractor;

src/Doctrine/Odm/Tests/Filter/AliasedFieldFilterTest.php

@@ -0,0 +1,107 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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\Doctrine\Odm\Tests\Filter;
+
+use ApiPlatform\Doctrine\Odm\Filter\AbstractFilter as OdmAbstractFilter;
+use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\Operation;
+use Doctrine\ODM\MongoDB\Aggregation\Builder;
+use Doctrine\Persistence\ManagerRegistry;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+
+class AliasedFieldFilterTest extends TestCase
+{
+    private function getFakeFilter(): object
+    {
+        return new class(managerRegistry: $this->createMock(ManagerRegistry::class), logger: $this->createMock(LoggerInterface::class), properties: ['name' => 'exact', 'some.relation.field' => 'partial'], propertyAliases: ['some.relation.field' => 'aliasedField']) extends OdmAbstractFilter {
+            protected function filterProperty(string $property, $value, Builder $aggregationBuilder, string $resourceClass, ?Operation $operation = null, array &$context = []): void
+            {
+            }
+
+            public function getDescription(string $resourceClass): array
+            {
+                return [];
+            }
+        };
+    }
+
+    #[Group('filter-test')]
+    public function testOdmFilterWithAliasedFieldsDenormalizes(): void
+    {
+        $fakeFilter = $this->getFakeFilter();
+
+        $denormalizePropertyNameClosure = function () {
+            $that = $this;
+
+            /* @var FilterInterface $that */
+            /* @phpstan-ignore method.notFound */
+            return $that->denormalizePropertyName('aliasedField');
+        };
+
+        $this->assertEquals('some.relation.field', $denormalizePropertyNameClosure->call($fakeFilter));
+
+        $normalizePropertyNameClosure = function () {
+            $that = $this;
+
+            /* @var FilterInterface $that */
+            /* @phpstan-ignore method.notFound */
+            return $that->normalizePropertyName('some.relation.field');
+        };
+
+        $this->assertEquals('aliasedField', $normalizePropertyNameClosure->call($fakeFilter));
+    }
+
+    #[Group('filter-test')]
+    public function testOdmFilterWithAliasedFieldsNormalizes(): void
+    {
+        $fakeFilter = $this->getFakeFilter();
+
+        $normalizePropertyNameClosure = function () {
+            $that = $this;
+
+            /* @var FilterInterface $that */
+            /* @phpstan-ignore method.notFound */
+            return $that->normalizePropertyName('some.relation.field');
+        };
+
+        $this->assertEquals('aliasedField', $normalizePropertyNameClosure->call($fakeFilter));
+    }
+
+    #[Group('filter-test')]
+    public function testOdmFilterWithAliasedFieldsDefaultsOnUnaliasedProperty(): void
+    {
+        $fakeFilter = $this->getFakeFilter();
+
+        $denormalizePropertyNameClosure = function () {
+            $that = $this;
+
+            /* @var FilterInterface $that */
+            /* @phpstan-ignore method.notFound */
+            return $that->denormalizePropertyName('name');
+        };
+
+        $normalizePropertyNameClosure = function () {
+            $that = $this;
+
+            /* @var FilterInterface $that */
+            /* @phpstan-ignore method.notFound */
+            return $that->normalizePropertyName('name');
+        };
+
+        $this->assertEquals('name', $denormalizePropertyNameClosure->call($fakeFilter));
+        $this->assertEquals('name', $normalizePropertyNameClosure->call($fakeFilter));
+    }
+}

src/Doctrine/Orm/Filter/AbstractFilter.php

@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Doctrine\Orm\Filter;
 
+use ApiPlatform\Doctrine\Common\Filter\PropertyAliasesFilterTrait;
 use ApiPlatform\Doctrine\Common\Filter\PropertyAwareFilterInterface;
 use ApiPlatform\Doctrine\Common\PropertyHelperTrait;
 use ApiPlatform\Doctrine\Orm\PropertyHelperTrait as OrmPropertyHelperTrait;
@@ -27,12 +28,15 @@
 abstract class AbstractFilter implements FilterInterface, PropertyAwareFilterInterface
 {
     use OrmPropertyHelperTrait;
+    use PropertyAliasesFilterTrait;
     use PropertyHelperTrait;
+
     protected LoggerInterface $logger;
 
-    public function __construct(protected ManagerRegistry $managerRegistry, ?LoggerInterface $logger = null, protected ?array $properties = null, protected ?NameConverterInterface $nameConverter = null)
+    public function __construct(protected ManagerRegistry $managerRegistry, ?LoggerInterface $logger = null, protected ?array $properties = null, protected ?NameConverterInterface $nameConverter = null, array $propertyAliases = [])
     {
         $this->logger = $logger ?? new NullLogger();
+        $this->propertyAliases = $propertyAliases;
     }
 
     /**
@@ -91,6 +95,10 @@ protected function isPropertyEnabled(string $property, string $resourceClass): b
 
     protected function denormalizePropertyName(string|int $property): string
     {
+        if ($this->isAlias($property)) {
+            $property = $this->getPropertyFromAlias($property);
+        }
+
         if (!$this->nameConverter instanceof NameConverterInterface) {
             return (string) $property;
         }
@@ -100,6 +108,8 @@ protected function denormalizePropertyName(string|int $property): string
 
     protected function normalizePropertyName(string $property): string
     {
+        $property = $this->getAliasForPropertyOrProperty($property);
+
         if (!$this->nameConverter instanceof NameConverterInterface) {
             return $property;
         }

src/Doctrine/Orm/Filter/BackedEnumFilter.php

@@ -51,6 +51,10 @@
  *     book.backed_enum_filter:
  *         parent: 'api_platform.doctrine.orm.backed_enum_filter'
  *         arguments: [ { status: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { status: ~ }
+ *         #   $propertyAliases: { status: 'statusLabel' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)

src/Doctrine/Orm/Filter/BooleanFilter.php

@@ -48,6 +48,10 @@
  *     book.boolean_filter:
  *         parent: 'api_platform.doctrine.orm.boolean_filter'
  *         arguments: [ { published: ~ } ]
+ *         # you can also alias the properties you are filtering on to expose search under different names
+ *         # arguments:
+ *         #   $properties: { published: ~ }
+ *         #   $propertyAliases: { published: 'issuedOn' }
  *         tags:  [ 'api_platform.filter' ]
  *         # The following are mandatory only if a _defaults section is defined with inverted values.
  *         # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)