API Platform非实体资源添加过滤器与分页问题求助

一、解决SearchFilter触发的Call to a member function getClassMetadata() on null错误 #

这个错误的核心原因是：ApiPlatform默认的SearchFilter依赖Doctrine实体的元数据（ClassMetadata），而非实体资源本身没有对应元数据，导致过滤器无法正常初始化。可通过以下两种方式解决：

方式1：为非实体资源关联实体元数据 #

在非实体资源类上，通过#[ApiResource]配置过滤器时明确关联Treasure实体的属性，同时在Provider中手动提取过滤参数并应用到实体查询：

// 非实体资源类
#[ApiResource(
    providers: [TreasureOutputProvider::class],
    filters: [
        #[ApiFilter(SearchFilter::class, properties: [
            'name' => 'partial', // 对应Treasure实体的name属性
            'price' => 'exact'
        ])]
    ]
)]
class TreasureOutput
{
    public string $name;
    public int $price;
    // 其他输出字段
}

Provider中处理过滤逻辑：

class TreasureOutputProvider implements CollectionDataProviderInterface
{
    public function __construct(private EntityManagerInterface $em) {}

    public function getCollection(string $resourceClass, string $operationName = null, array $context = []): iterable
    {
        // 从请求上下文提取过滤参数
        $request = $context['request'] ?? null;
        $nameFilter = $request?->query->get('name');
        
        // 构建Treasure实体查询
        $queryBuilder = $this->em->createQueryBuilder()
            ->select('t')
            ->from(Treasure::class, 't');
        
        // 应用过滤条件
        if ($nameFilter) {
            $queryBuilder->andWhere('t.name LIKE :name')
                ->setParameter('name', "%$nameFilter%");
        }
        
        // 后续处理分页与实体转输出对象逻辑
        // ...
    }
}

方式2：自定义适配非实体资源的过滤器 #

如果需要更灵活的过滤逻辑，可自定义过滤器绕过Doctrine元数据依赖：

#[ApiFilter(NonEntityTreasureSearchFilter::class)]
class TreasureOutput { /* ... */ }

class NonEntityTreasureSearchFilter extends AbstractFilter
{
    protected function filterProperty(string $property, $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, Operation $operation = null, array $context = []): void
    {
        // 直接针对Treasure实体构建过滤规则
        if ($property === 'name' && $value) {
            $paramName = $queryNameGenerator->generateParameterName('name');
            $queryBuilder->andWhere('t.name LIKE :'.$paramName)
                ->setParameter($paramName, "%$value%");
        }
    }

    public function getDescription(string $resourceClass): array
    {
        return [
            'name' => [
                'property' => 'name',
                'type' => 'string',
                'required' => false,
                'swagger' => [
                    'description' => '按名称模糊搜索',
                    'name' => 'name',
                    'type' => 'string',
                ],
            ],
        ];
    }
}

二、解决分页元数据缺失问题（hydra:totalItems、上下页链接等） #

要让ApiPlatform自动生成完整的hydra分页元数据，Provider必须返回实现PaginatorInterface的实例，而非普通数组。可使用ApiPlatform自带的ArrayPaginator实现：

步骤1：在非实体资源启用原生分页配置 #

#[ApiResource(
    providers: [TreasureOutputProvider::class],
    paginationEnabled: true,
    paginationItemsPerPage: 20,
    paginationClientEnabled: true, // 允许客户端指定页码
    paginationClientItemsPerPage: true // 允许客户端指定每页条数
)]
class TreasureOutput { /* ... */ }

步骤2：在Provider中返回Paginator实例 #

class TreasureOutputProvider implements CollectionDataProviderInterface
{
    public function __construct(private EntityManagerInterface $em) {}

    public function getCollection(string $resourceClass, string $operationName = null, array $context = []): iterable
    {
        // 从上下文提取分页参数
        $page = $context['pagination']['page'] ?? 1;
        $itemsPerPage = $context['pagination']['items_per_page'] ?? 20;
        
        // 1. 查询总数据条数（用于hydra:totalItems）
        $totalQuery = $this->em->createQueryBuilder()
            ->select('COUNT(t.id)')
            ->from(Treasure::class, 't');
        // 同步应用之前的过滤条件
        // ...
        $totalItems = (int)$totalQuery->getQuery()->getSingleScalarResult();
        
        // 2. 查询当前页的Treasure数据
        $dataQuery = $this->em->createQueryBuilder()
            ->select('t')
            ->from(Treasure::class, 't')
            ->setFirstResult(($page - 1) * $itemsPerPage)
            ->setMaxResults($itemsPerPage);
        // 同步应用过滤条件
        // ...
        $treasures = $dataQuery->getQuery()->getResult();
        
        // 3. 将实体转换为非实体资源对象
        $outputItems = array_map(function(Treasure $treasure) {
            $output = new TreasureOutput();
            $output->name = $treasure->getName();
            $output->price = $treasure->getPrice();
            // 其他字段赋值
            return $output;
        }, $treasures);
        
        // 4. 用ArrayPaginator包装结果，自动生成分页元数据
        return new ArrayPaginator(
            $outputItems,
            ($page - 1) * $itemsPerPage,
            $itemsPerPage,
            $totalItems
        );
    }
}

返回ArrayPaginator实例后，ApiPlatform会自动生成hydra:totalItems、hydra:view（包含上下页链接）、hydra:first、hydra:last等完整分页元数据。

内容的提问来源于stack exchange，提问作者Emmanuel Michaud