feat(doctrine): add nested relation support to IriFilter and UuidFilter

src/Doctrine/Orm/Filter/AbstractUuidFilter.php

@@ -18,7 +18,7 @@
 use ApiPlatform\Doctrine\Common\Filter\ManagerRegistryAwareInterface;
 use ApiPlatform\Doctrine\Common\Filter\ManagerRegistryAwareTrait;
 use ApiPlatform\Doctrine\Common\PropertyHelperTrait;
-use ApiPlatform\Doctrine\Orm\PropertyHelperTrait as OrmPropertyHelperTrait;
+use ApiPlatform\Doctrine\Orm\NestedPropertyHelperTrait;
 use ApiPlatform\Doctrine\Orm\Util\QueryBuilderHelper;
 use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
 use ApiPlatform\Metadata\BackwardCompatibleFilterDescriptionTrait;
@@ -33,7 +33,7 @@
 use Doctrine\DBAL\ParameterType;
 use Doctrine\DBAL\Types\ConversionException;
 use Doctrine\DBAL\Types\Type;
-use Doctrine\ORM\Query\Expr\Join;
+use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\QueryBuilder;
 
 /**
@@ -44,14 +44,30 @@ class AbstractUuidFilter implements FilterInterface, ManagerRegistryAwareInterfa
     use BackwardCompatibleFilterDescriptionTrait;
     use LoggerAwareTrait;
     use ManagerRegistryAwareTrait;
-    use OrmPropertyHelperTrait;
+    use NestedPropertyHelperTrait;
     use PropertyHelperTrait;
 
     private const UUID_SCHEMA = [
         'type' => 'string',
         'format' => 'uuid',
     ];
 
+    /**
+     * Gets class metadata for the given resource.
+     */
+    protected function getClassMetadata(string $resourceClass): \Doctrine\Persistence\Mapping\ClassMetadata
+    {
+        $manager = $this
+            ->getManagerRegistry()
+            ->getManagerForClass($resourceClass);
+
+        if ($manager) {
+            return $manager->getClassMetadata($resourceClass);
+        }
+
+        return new ClassMetadata($resourceClass);
+    }
+
     public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
     {
         $parameter = $context['parameter'] ?? null;
@@ -60,26 +76,28 @@ public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $q
         }
 
         if (null === $parameter->getProperty()) {
-            throw new InvalidArgumentException(\sprintf('The filter parameter with key "%s" must specify a property. Nested properties are not automatically resolved. Please provide the property explicitly.', $parameter->getKey()));
+            throw new InvalidArgumentException(\sprintf('The filter parameter with key "%s" must specify a property. Please provide the property explicitly.', $parameter->getKey()));
         }
 
-        $this->filterProperty($parameter->getProperty(), $parameter->getValue(), $queryBuilder, $queryNameGenerator, $resourceClass, $operation, $context);
+        $this->filterProperty($parameter, $queryBuilder, $queryNameGenerator, $resourceClass, $operation, $context);
     }
 
-    private function filterProperty(string $property, mixed $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
+    private function filterProperty(Parameter $parameter, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
     {
+        $property = $parameter->getProperty();
+        $value = $parameter->getValue();
         $alias = $queryBuilder->getRootAliases()[0];
-        $field = $property;
 
-        $associations = [];
-        if ($this->isPropertyNested($property, $resourceClass)) {
-            [$alias, $field, $associations] = $this->addJoinsForNestedProperty($property, $alias, $queryBuilder, $queryNameGenerator, $resourceClass, Join::INNER_JOIN);
-        }
+        [$alias, $field] = $this->addNestedParameterJoins($property, $alias, $queryBuilder, $queryNameGenerator, $parameter);
+
+        // Get the target resource class for nested properties
+        $nestedInfo = $parameter->getExtraProperties()['nested_property_info'] ?? null;
+        $targetResourceClass = $nestedInfo['leaf_class'] ?? $resourceClass;
 
-        $metadata = $this->getNestedMetadata($resourceClass, $associations);
+        $metadata = $this->getClassMetadata($targetResourceClass);
 
         if ($metadata->hasField($field)) {
-            $value = $this->convertValuesToTheDatabaseRepresentation($queryBuilder, $this->getDoctrineFieldType($property, $resourceClass), $value);
+            $value = $this->convertValuesToTheDatabaseRepresentation($queryBuilder, $this->getDoctrineFieldType($field, $targetResourceClass), $value);
             $this->addWhere($queryBuilder, $queryNameGenerator, $alias, $field, $value);
 
             return;
@@ -89,8 +107,8 @@ private function filterProperty(string $property, mixed $value, QueryBuilder $qu
         if (!$metadata->hasAssociation($field)) {
             $this->logger->notice('Tried to filter on a non-existent field or association', [
                 'field' => $field,
-                'resource_class' => $resourceClass,
-                'exception' => new InvalidArgumentException(\sprintf('Property "%s" does not exist in resource "%s".', $field, $resourceClass)),
+                'resource_class' => $targetResourceClass,
+                'exception' => new InvalidArgumentException(\sprintf('Property "%s" does not exist in resource "%s".', $field, $targetResourceClass)),
             ]);
 
             return;

src/Doctrine/Orm/Filter/ExactFilter.php

@@ -44,7 +44,7 @@ public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $q
         $alias = $queryBuilder->getRootAliases()[0];
         $parameterName = $queryNameGenerator->generateParameterName($property);
 
-        [$alias, $property] = $this->addJoinsForNestedProperty($property, $alias, $queryBuilder, $queryNameGenerator, $parameter);
+        [$alias, $property] = $this->addNestedParameterJoins($property, $alias, $queryBuilder, $queryNameGenerator, $parameter);
 
         if (\is_array($value)) {
             $queryBuilder

src/Doctrine/Orm/Filter/IriFilter.php

@@ -14,6 +14,7 @@
 namespace ApiPlatform\Doctrine\Orm\Filter;
 
 use ApiPlatform\Doctrine\Common\Filter\OpenApiFilterTrait;
+use ApiPlatform\Doctrine\Orm\NestedPropertyHelperTrait;
 use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
 use ApiPlatform\Metadata\BackwardCompatibleFilterDescriptionTrait;
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
@@ -29,6 +30,7 @@
 final class IriFilter implements FilterInterface, OpenApiParameterFilterInterface, ParameterProviderFilterInterface
 {
     use BackwardCompatibleFilterDescriptionTrait;
+    use NestedPropertyHelperTrait;
     use OpenApiFilterTrait;
 
     public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
@@ -42,19 +44,66 @@ public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $q
 
         $property = $parameter->getProperty();
         $alias = $queryBuilder->getRootAliases()[0];
+
+        [$alias, $property] = $this->addNestedParameterJoins($property, $alias, $queryBuilder, $queryNameGenerator, $parameter);
+
         $parameterName = $queryNameGenerator->generateParameterName($property);
 
-        $queryBuilder->join(\sprintf('%s.%s', $alias, $property), $parameterName);
+        // Resolve the metadata for the entity that owns the leaf property.
+        // For nested properties like "department.company", we need to walk the association chain
+        // to get the metadata of the entity that owns "company" (i.e. FilterDepartment).
+        $em = $queryBuilder->getEntityManager();
+        $metadata = $em->getClassMetadata($resourceClass);
+        $originalProperty = $parameter->getProperty();
+        $segments = explode('.', $originalProperty);
+        // Walk all segments except the last (which is the leaf property)
+        for ($i = 0, $count = \count($segments) - 1; $i < $count; ++$i) {
+            $associationMapping = $metadata->getAssociationMapping($segments[$i]);
+            $metadata = $em->getClassMetadata($associationMapping['targetEntity']);
+        }
+
+        // Determine if the association is a collection (OneToMany/ManyToMany) or single-valued (ManyToOne/OneToOne).
+        // Collection associations require a JOIN to compare individual elements.
+        // Single-valued associations can be compared directly, which avoids issues with custom ID types (e.g. UUID).
+        $isCollectionAssociation = $metadata->isCollectionValuedAssociation($property);
+
+        if ($isCollectionAssociation) {
+            $queryBuilder->join(\sprintf('%s.%s', $alias, $property), $parameterName);
+
+            if (is_iterable($value)) {
+                $queryBuilder
+                    ->{$context['whereClause'] ?? 'andWhere'}(\sprintf('%s IN (:%s)', $parameterName, $parameterName));
+            } else {
+                $queryBuilder
+                    ->{$context['whereClause'] ?? 'andWhere'}(\sprintf('%s = :%s', $parameterName, $parameterName));
+            }
 
-        if (is_iterable($value)) {
-            $queryBuilder
-                ->{$context['whereClause'] ?? 'andWhere'}(\sprintf('%s IN (:%s)', $parameterName, $parameterName));
             $queryBuilder->setParameter($parameterName, $value);
-        } else {
+
+            return;
+        }
+
+        $propertyExpr = \sprintf('%s.%s', $alias, $property);
+
+        if (is_iterable($value)) {
             $queryBuilder
-                ->{$context['whereClause'] ?? 'andWhere'}(\sprintf('%s = :%s', $parameterName, $parameterName));
+                ->{$context['whereClause'] ?? 'andWhere'}(\sprintf('%s IN (:%s)', $propertyExpr, $parameterName));
             $queryBuilder->setParameter($parameterName, $value);
+
+            return;
         }
+
+        $queryBuilder
+            ->{$context['whereClause'] ?? 'andWhere'}(\sprintf('%s = :%s', $propertyExpr, $parameterName));
+
+        // Extract the identifier value and its type from the target entity metadata
+        // to properly handle custom ID types (e.g. UUID).
+        $associationMapping = $metadata->getAssociationMapping($property);
+        $targetMetadata = $em->getClassMetadata($associationMapping['targetEntity']);
+        $idFieldNames = $targetMetadata->getIdentifierFieldNames();
+        $idType = $targetMetadata->getTypeOfField($idFieldNames[0]);
+        $identifierValues = $targetMetadata->getIdentifierValues($value);
+        $queryBuilder->setParameter($parameterName, reset($identifierValues), $idType);
     }
 
     public static function getParameterProvider(): string

src/Doctrine/Orm/Filter/PartialSearchFilter.php

@@ -45,7 +45,7 @@ public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $q
 
         $property = $parameter->getProperty();
         $alias = $queryBuilder->getRootAliases()[0];
-        [$alias, $property] = $this->addJoinsForNestedProperty($property, $alias, $queryBuilder, $queryNameGenerator, $parameter);
+        [$alias, $property] = $this->addNestedParameterJoins($property, $alias, $queryBuilder, $queryNameGenerator, $parameter);
         $field = $alias.'.'.$property;
         $values = $parameter->getValue();
 

src/Doctrine/Orm/Filter/SortFilter.php

@@ -0,0 +1,88 @@
+<?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\Doctrine\Orm\Filter;
+
+use ApiPlatform\Doctrine\Common\Filter\OpenApiFilterTrait;
+use ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface;
+use ApiPlatform\Doctrine\Orm\NestedPropertyHelperTrait;
+use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
+use ApiPlatform\Metadata\BackwardCompatibleFilterDescriptionTrait;
+use ApiPlatform\Metadata\JsonSchemaFilterInterface;
+use ApiPlatform\Metadata\OpenApiParameterFilterInterface;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\Parameter;
+use Doctrine\ORM\Query\Expr\Join;
+use Doctrine\ORM\QueryBuilder;
+
+/**
+ * Parameter-based order filter for sorting a collection by a property.
+ *
+ * Unlike {@see OrderFilter}, this filter does not extend AbstractFilter and is designed
+ * exclusively for use with Parameters (QueryParameter).
+ *
+ * Usage: `new QueryParameter(filter: new SortFilter(), property: 'department.name')`.
+ *
+ * @author Antoine Bluchet <soyuka@gmail.com>
+ */
+final class SortFilter implements FilterInterface, JsonSchemaFilterInterface, OpenApiParameterFilterInterface
+{
+    use BackwardCompatibleFilterDescriptionTrait;
+    use NestedPropertyHelperTrait;
+    use OpenApiFilterTrait;
+
+    public function __construct(
+        private readonly ?string $nullsComparison = null,
+    ) {
+    }
+
+    public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
+    {
+        $parameter = $context['parameter'] ?? null;
+        if (null === $parameter) {
+            return;
+        }
+
+        $value = $context['filters'][$parameter->getProperty() ?? ''] ?? null;
+        if (null === $value) {
+            return;
+        }
+
+        $direction = strtoupper($value);
+        if (!\in_array($direction, ['ASC', 'DESC'], true)) {
+            return;
+        }
+
+        $property = $parameter->getProperty();
+        $alias = $queryBuilder->getRootAliases()[0];
+
+        [$alias, $field] = $this->addNestedParameterJoins($property, $alias, $queryBuilder, $queryNameGenerator, $parameter, Join::LEFT_JOIN);
+
+        if (null !== $nullsComparison = $this->nullsComparison) {
+            $nullsDirection = OrderFilterInterface::NULLS_DIRECTION_MAP[$nullsComparison][$direction];
+            $nullRankHiddenField = \sprintf('_%s_%s_null_rank', $alias, str_replace('.', '_', $field));
+            $queryBuilder->addSelect(\sprintf('CASE WHEN %s.%s IS NULL THEN 0 ELSE 1 END AS HIDDEN %s', $alias, $field, $nullRankHiddenField));
+            $queryBuilder->addOrderBy($nullRankHiddenField, $nullsDirection);
+        }
+
+        $queryBuilder->addOrderBy(\sprintf('%s.%s', $alias, $field), $direction);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function getSchema(Parameter $parameter): array
+    {
+        return ['type' => 'string', 'enum' => ['asc', 'desc', 'ASC', 'DESC']];
+    }
+}

src/Doctrine/Orm/NestedPropertyHelperTrait.php

@@ -31,12 +31,13 @@ trait NestedPropertyHelperTrait
      * @return array An array where the first element is the join $alias of the leaf entity,
      *               the second element is the leaf property
      */
-    protected function addJoinsForNestedProperty(
+    protected function addNestedParameterJoins(
         string $property,
         string $alias,
         QueryBuilder $queryBuilder,
         QueryNameGeneratorInterface $queryNameGenerator,
         Parameter $parameter,
+        ?string $joinType = null,
     ): array {
         $extraProperties = $parameter->getExtraProperties();
         $nestedInfo = $extraProperties['nested_property_info'] ?? null;
@@ -50,7 +51,8 @@ protected function addJoinsForNestedProperty(
                 $queryBuilder,
                 $queryNameGenerator,
                 $alias,
-                $association
+                $association,
+                $joinType
             );
         }
 

src/Laravel/Eloquent/Filter/EqualsFilter.php

@@ -28,7 +28,7 @@ final class EqualsFilter implements FilterInterface
      */
     public function apply(Builder $builder, mixed $values, Parameter $parameter, array $context = []): Builder
     {
-        return $this->applyWithNestedProperty(
+        return $this->addNestedParameterJoins(
             $builder,
             $parameter,
             static fn (Builder $query, string $property, string $whereClause) => $query->{$whereClause}($property, $values),

src/Laravel/Eloquent/Filter/NestedPropertyTrait.php

@@ -29,7 +29,7 @@ trait NestedPropertyTrait
      *
      * @return Builder<\Illuminate\Database\Eloquent\Model>
      */
-    private function applyWithNestedProperty(
+    private function addNestedParameterJoins(
         Builder $builder,
         Parameter $parameter,
         callable $condition,