Nested property filters fail to generate JOINs when relation target entity is not directly declared as ApiResource

[or-benjamin]

@ -0,0 +1,118 @@
API Platform version(s) affected: 4.3.3

Description

When using stateOptions with entityClass to map an API Resource to a Doctrine entity, nested property filters (PartialSearchFilter, OrFilter, FreeTextQueryFilter) fail to generate JOINs for relations that point to an entity which is not directly declared as an #[ApiResource].

The root cause is in ParameterResourceMetadataCollectionFactory::getProperties(). When traversing a dotted property path (e.g. user.name), the method calls getClassNameFromProperty() which internally calls isResourceClass() on the relation's target class. If the target entity class is not registered as an API resource (even if another API Resource references it via stateOptions), isResourceClass() returns false, getClassNameFromProperty() returns null, and the traversal stops — meaning nested_properties_info is never populated.

Without nested_properties_info, the NestedPropertyHelperTrait::addNestedParameterJoins() returns early without adding any JOIN, producing invalid DQL like WHERE LOWER(o.user.name) LIKE ... instead of JOIN o.user u WHERE LOWER(u.name) LIKE ....

How to reproduce

// Entity (not declared as ApiResource)
#[ORM\Entity]
class User implements UserInterface
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private ?string $name = null;

    #[ORM\Column(length: 180, unique: true)]
    private ?string $email = null;

    // getters/setters...
}

// Entity with relation to User
#[ORM\Entity]
class UserAction
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 50)]
    private string $action;

    #[ORM\ManyToOne(targetEntity: User::class)]
    #[ORM\JoinColumn(nullable: false)]
    private User $user;

    // getters/setters...
}

// API Resource using stateOptions
#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/user-actions',
            parameters: [
                'user' => new QueryParameter(
                    filter: new OrFilter(new PartialSearchFilter()),
                    properties: ['user.name', 'user.email'],
                ),
            ],
        ),
    ],
    stateOptions: new Options(entityClass: UserAction::class),
)]
class UserActionResource
{
    public ?int $id = null;
    public ?string $action = null;
    // ...
}

// Separate API Resource for User exists with stateOptions
#[ApiResource(
    stateOptions: new Options(entityClass: User::class),
)]
class UserResource
{
    public ?int $id = null;
    public ?string $name = null;
    // ...
}

Requesting GET /user-actions?user=john produces:

[Semantical Error] Class UserAction has no field or association named user.name

Generated DQL:

SELECT o FROM UserAction o WHERE LOWER(o.user.name) LIKE LOWER(:p1)

Expected DQL:

SELECT o FROM UserAction o JOIN o.user u WHERE LOWER(u.name) LIKE LOWER(:p1)

Workaround

Add #[ApiResource(operations: [])] on the target entity to register it as a resource class without exposing any routes:

#[ApiResource(operations: [])]
#[ORM\Entity]
class User implements UserInterface
{
    // ...
}

Additional Context

• The filterClass parameter on QueryParameter does not help because it only affects the starting class of the traversal, not the isResourceClass check on the relation target.
• This issue affects all nested property filters: PartialSearchFilter, ExactFilter, OrFilter, FreeTextQueryFilter.
• Discovered while using the ObjectMapper pattern (separate API Resource class + stateOptions(entityClass: ...)) which is the recommended approach in API Platform 4.x.

[JasminR2]

I've also just noticed this, but there's another issue with workaround you specified. If you use stateOptions on route config with handleLinks, it breaks DQL generation even further.

Role class

#[ApiResource(
    operations: [
        // ...
    ]
)]
class Role
{
    // ...

    /**
     * @var Collection<int, Permission>
     */
    #[ManyToMany(targetEntity: Permission::class, inversedBy: 'roles')]
    private Collection $permissions;

    // ...
}

Permission class

#[ApiResource(
    uriTemplate: '/admin/role/{id}/permissions',
    uriVariables: ['id' => new Link(fromClass: Role::class, fromProperty: 'permissions')],
    stateOptions: new Options(handleLinks: RolePermissionsLink::class),
    operations: [
        new GetCollection(
            parameters: [
                'active' => new QueryParameter(
                    filter: ExactFilter::class,
                    schema: ['type' => 'boolean'],
                    castToNativeType: true,
                    required: true
                ),
                'search' => new QueryParameter(
                    filter: new FreeTextQueryFilter(new OrFilter(new PartialSearchFilter(caseSensitive: false))),
                    properties: ['permissionLocalizations.description']
                )
            ]
        )
    ]
)]
class Permission
{
    // ...

    /**
     * @var Collection<int, PermissionLocalization>
     */
    #[OneToMany(targetEntity: PermissionLocalization::class, mappedBy: 'permission')]
    private Collection $permissionLocalizations;

    // ...
}

PermissionLocalization class

#[ApiResource(operations: [])]
#[ORM\Entity(repositoryClass: PermissionLocalizationRepository::class)]
class PermissionLocalization
{
    // ...

    #[ORM\ManyToOne(inversedBy: 'permissionLocalizations')]
    #[ORM\JoinColumn(nullable: false)]
    private ?Permission $permission = null;

    #[ORM\Column(length: 150)]
    private ?string $description = null;

    // ...
}

RolePermissionsLink class

final class RolePermissionsLink implements LinksHandlerInterface
{
    public function handleLinks(QueryBuilder $queryBuilder, array $uriVariables, QueryNameGeneratorInterface $queryNameGeneratorInterface, array $context): void
    {
        $active = $context['operation']->getParameters()->get('active')->getValue();
        $rootAlias = $queryBuilder->getRootAliases()[0];
        
        $entityManager = $queryBuilder->getEntityManager();
        $subQuery = $entityManager->createQueryBuilder()
                               ->select('1')
                               ->from(Role::class, 'r')
                               ->innerJoin('r.permissions', 'rp')
                               ->where('r.id = :role')
                               ->andWhere(sprintf('rp = %s', $rootAlias))
                               ->getDQL();
                               
        $queryBuilder->where(
            $active === true
                ? $queryBuilder->expr()->exists($subQuery)
                : $queryBuilder->expr()->not($queryBuilder->expr()->exists($subQuery))
        )->setParameter('role', $uriVariables['id'], UuidType::NAME);
    }
}

Expected DQL

SELECT o FROM App\Domain\AccessControl\Entity\Permission o
LEFT JOIN o.permissionLocalizations permissionLocalizations_a1
WHERE
(
    EXISTS
    (
        SELECT 1 FROM App\Domain\AccessControl\Entity\Role r
        INNER JOIN r.permissions rp
        WHERE r.id = :role
        AND rp = o
    )
    AND LOWER(permissionLocalizations_a1.description) LIKE LOWER(:description_p1) ESCAPE '\'
) ORDER BY o.id ASC

Generated DQL

SELECT o FROM App\Domain\AccessControl\Entity\Permission o
INNER JOIN o.permissionLocalizations permissionLocalizations_a1
WHERE o IN
(
    SELECT o_a2 FROM App\Domain\AccessControl\Entity\Permission o_a2
    INNER JOIN o_a2.permissionLocalizations permissionLocalizations_a3
    WHERE
    (
        EXISTS
        (
            SELECT 1 FROM App\Domain\AccessControl\Entity\Role r
            INNER JOIN r.permissions rp
            WHERE r.id = :role
            AND rp = o
        )
    )
    AND LOWER(permissionLocalizations_a3.description) LIKE LOWER(:description_p1) ESCAPE '\'
) ORDER BY o.id ASC

[Maxcastel]

Does #7926 resolve your issue? @or-benjamin

1. composer.json:

"repositories": [
   {
       "type": "vcs",
       "url": "https://github.com/Maxcastel/api-platform-core.git"
   }
],
"require": {
     "api-platform/core": "dev-fix-nested-property-join-relation-not-ApiResource",
}

2. composer update api-platform/core