---
title: 'API Platform : filtrer les lectures avec une extension Doctrine ORM'
description: 'Ajoute une condition Doctrine aux collections et aux éléments API Platform, enregistre ton extension et vérifie que les brouillons restent hors du catalogue.'
pubDate: 2023-10-16
updatedDate: 2026-10-19
family: 'php-symfony'
tags: []
heroImage: /images/les-extensions-avec-symfony-6-et-api-platform-3.webp
videoUrl: 'https://youtu.be/IqcPzkvgBqw'
---

Tu veux que ton catalogue ne renvoie que les livres publiés, aussi bien dans la liste que lorsqu'un
client connaît directement l'identifiant d'un brouillon ? Une **extension Doctrine ORM** ajoute une
condition au QueryBuilder utilisé par les providers Doctrine d'API Platform. Elle ne crée pas de
route : c'est le rôle des
[opérations API Platform](/blog/les-operations-avec-symfony-6-et-api-platform-3/).

La vidéo historique concerne Symfony 6 et API Platform 3. Le code ci-dessous a été **exécuté avec
PHP 8.4.26, API Platform 4.4.5, Symfony FrameworkBundle 7.4.21, DoctrineBundle 2.19.1, Doctrine ORM
3.7.5 et DBAL 4.5.0**, sur SQLite. Les composants Symfony du bac à sable sont contraints à la branche
7.4 ; les contrats et polyfills suivent leur versionnement propre. Cette validation ne garantit pas
toutes les combinaisons Symfony 6 / API Platform 3 de la vidéo.

## Préparer le catalogue et son comportement de référence

Reprends l'entité `Book` complète du
[guide des opérations](/blog/les-operations-avec-symfony-6-et-api-platform-3/#pr%C3%A9parer-une-ressource-doctrine-en-lecture-seule) :
`id` entier généré, `title` et `published` booléen, avec `GetCollection` sur `/catalog/books` et `Get`
sur `/catalog/books/{id}`. L'import de routes ajoute le préfixe `/api`.

Avant de continuer, vérifie ces prérequis :

- API Platform utilise ses providers Doctrine ORM, pas un provider personnalisé qui ignore les
  extensions ; la [documentation des extensions](https://api-platform.com/docs/core/extensions/)
  précise cette limite.
- Ta base de test contient un livre publié et un brouillon. Note leurs identifiants ; les exemples
  HTTP utilisent respectivement `1` et `2`.
- Sans extension, la collection renvoie les deux livres et les deux détails sont accessibles.
  C'est le témoin qui permet de vérifier que le filtrage a réellement changé la lecture.

Ce cas ne dépend ni d'un utilisateur connecté ni d'un rôle administrateur : il illustre une règle
de visibilité du catalogue, pas un système multi-tenant ou une politique d'autorisation complète.

## Implémenter les deux points d'entrée

Crée `src/Doctrine/PublishedBookExtension.php`. Les deux interfaces et leurs signatures correspondent
à celles du [code source 4.4.5](https://github.com/api-platform/core/tree/v4.4.5/src/Doctrine/Orm/Extension).

```php
<?php

namespace App\Doctrine;

use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
use ApiPlatform\Doctrine\Orm\Extension\QueryItemExtensionInterface;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use App\Entity\Book;
use Doctrine\ORM\QueryBuilder;

final class PublishedBookExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
{
    public function applyToCollection(
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = [],
    ): void {
        $this->restrict($queryBuilder, $queryNameGenerator, $resourceClass);
    }

    public function applyToItem(
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        array $identifiers,
        ?Operation $operation = null,
        array $context = [],
    ): void {
        $this->restrict($queryBuilder, $queryNameGenerator, $resourceClass);
    }

    private function restrict(
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
    ): void {
        if (Book::class !== $resourceClass) {
            return;
        }

        $alias = $queryBuilder->getRootAliases()[0];
        $parameter = $queryNameGenerator->generateParameterName('published');

        $queryBuilder
            ->andWhere(sprintf('%s.published = :%s', $alias, $parameter))
            ->setParameter($parameter, true);
    }
}
```

Le code limite son action à `Book`, réutilise l'alias racine et ajoute sa condition avec
`andWhere` : il ne remplace pas une condition existante, notamment celle sur l'identifiant du
livre. Le nom de paramètre est généré plutôt que fixé à la main ; cela permet de composer plusieurs
extensions utilisant le même générateur. Si tu ajoutes une jointure, génère aussi son alias avec
`generateJoinAlias()` au lieu de supposer qu'un nom est libre. Les deux méthodes sont visibles dans
[QueryNameGenerator](https://github.com/api-platform/core/blob/v4.4.5/src/Doctrine/Orm/Util/QueryNameGenerator.php).
La jointure reste une piste documentée, non exécutée dans cet exemple sans relation.

## Enregistrer le service une seule fois

Avec la découverte standard des services Symfony, ce bloc de `config/services.yaml` couvre la
classe placée dans `src/Doctrine` :

```yaml
services:
  _defaults:
    autowire: true
    autoconfigure: true

  App\Doctrine\:
    resource: '../src/Doctrine/'
```

Adapte ce bloc à ton fichier existant : s'il charge déjà tout `App` et n'exclut pas `src/Doctrine`,
aucune seconde déclaration n'est nécessaire. L'autoconfiguration associe les interfaces aux tags
API Platform ; ce mécanisme est enregistré dans
[ApiPlatformExtension](https://github.com/api-platform/core/blob/v4.4.5/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php).

Si tu n'utilises pas l'autoconfiguration, choisis **à la place** cette déclaration explicite pour
cette classe :

```yaml
services:
  App\Doctrine\PublishedBookExtension:
    autoconfigure: false
    tags:
      - { name: api_platform.doctrine.orm.query_extension.collection }
      - { name: api_platform.doctrine.orm.query_extension.item }
```

N'empile pas les deux variantes pour forcer le résultat. Dans le bac à sable, chacune a été testée
séparément, avec un seul enregistrement par tag. Pour diagnostiquer ton conteneur :

```bash
php bin/console debug:container --tag=api_platform.doctrine.orm.query_extension.collection
php bin/console debug:container --tag=api_platform.doctrine.orm.query_extension.item
```

La classe doit apparaître dans les deux listes. Une classe PHP présente sur disque mais absente
du conteneur n'agit sur aucune requête.

## Contrôler la collection et l'accès direct

Sur ton application locale, adapte le port et les identifiants :

```bash
curl -i -H 'Accept: application/ld+json' http://127.0.0.1:8000/api/catalog/books
curl -i -H 'Accept: application/ld+json' http://127.0.0.1:8000/api/catalog/books/1
curl -i -H 'Accept: application/ld+json' http://127.0.0.1:8000/api/catalog/books/2
```

**Résultats observés**, après extraction des blocs PHP/YAML exacts de ces deux articles dans le
bac à sable et exécution de requêtes HTTP locales :

- sans extension, la collection contient deux livres et le brouillon est accessible en détail ;
- avec autoconfiguration, elle ne contient que le livre publié et annonce un total de 1 ;
- le détail publié répond 200 et celui du brouillon répond 404, alors que sa ligne existe en base ;
- avec la déclaration manuelle des tags, les mêmes contrôles réussissent ;
- dans un témoin volontairement limité au tag collection, la liste est filtrée mais le détail du
  brouillon redevient accessible : filtrer la liste ne protège donc pas l'URL individuelle.

Un contrôle séparé du QueryBuilder vérifie aussi que la condition d'identifiant est conservée et
que deux applications avec le même générateur produisent deux paramètres distincts. Le SQL généré
et la lecture SQLite ont été vérifiés ; ce n'est pas une mesure de performance PostgreSQL ou MySQL.

## Ne pas confondre filtrage et autorisation

Le 404 du brouillon résulte ici d'une lecture qui ne trouve aucune ligne satisfaisant toutes les
conditions. Il ne prouve pas qu'une règle de sécurité a refusé l'utilisateur. Une lecture directe
avec un repository Doctrine, hors de ces providers, peut encore retrouver le brouillon.

Pour une API privée, définis séparément l'authentification, les autorisations par opération, les
voters et les contrôles d'écriture nécessaires. La
[documentation de sécurité Symfony d'API Platform](https://api-platform.com/docs/symfony/security/)
distingue notamment les contrôles avant et après désérialisation. Ce guide ne configure ni firewall,
ni voter, ni `Post`, ni `Patch` : **aucun scénario d'autorisation ou d'écriture n'a été validé ici**.
Le [guide des scopes et des clés API](/blog/systeme-de-scopes-et-authentification-via-cle-api-avec-symfony-7-et-api-platform-4/)
traite un autre pan du sujet, distinct de cette condition SQL.

## Si le filtrage ne se déclenche pas

Commence par vérifier la classe de ressource reçue, les deux tags et le provider de l'opération.
Si un provider personnalisé exécute lui-même une requête, il doit explicitement intégrer les
extensions ou déléguer au provider Doctrine ; voir les
[state providers](https://api-platform.com/docs/core/state-providers/).

Ne corrige pas une fuite du détail en retirant simplement le lien de la liste. Rejoue toujours le
test avec l'identifiant connu du brouillon. Et si ton besoin est un critère de recherche laissé au
client, étudie plutôt les [filtres](https://api-platform.com/docs/core/filters/) : l'extension de cet
article impose une condition de catalogue, elle n'ajoute pas un paramètre de recherche public.

Tu peux regarder la vidéo associée pour le contexte Symfony 6 / API Platform 3, puis utiliser les
contrôles collection et détail pour vérifier ton adaptation sur les versions de ton projet.
