API Platform GraphQL avec Symfony : Schémas, Mutations et Questions d'Entretien 2026

L'intégration de GraphQL dans les applications Symfony représente une évolution majeure dans la conception d'API modernes. API Platform simplifie considérablement cette intégration en offrant une génération automatique de schémas GraphQL à partir des entités Doctrine. Ce tutoriel explore en profondeur les concepts essentiels pour maîtriser API Platform GraphQL dans un contexte Symfony.

Installation et Configuration Initiale

L'installation de GraphQL dans un projet API Platform nécessite quelques dépendances spécifiques. La bibliothèque webonyx/graphql-php constitue le moteur principal de l'exécution GraphQL.

composer require api-platform/graphql

La configuration s'effectue dans le fichier de configuration d'API Platform. L'activation de GraphQL expose automatiquement un endpoint dédié.

# config/packages/api_platform.yaml
api_platform:
    graphql:
        enabled: true
        graphiql:
            enabled: true
        introspection:
            enabled: true

Cette configuration active GraphiQL, l'interface interactive permettant d'explorer et tester les requêtes GraphQL directement depuis le navigateur.

Définition des Schémas GraphQL

Les schémas GraphQL dans API Platform sont générés automatiquement à partir des attributs PHP définis sur les entités. Chaque ressource API devient un type GraphQL avec ses champs correspondants.

<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GraphQl\Query;
use ApiPlatform\Metadata\GraphQl\QueryCollection;
use ApiPlatform\Metadata\GraphQl\Mutation;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(
    graphQlOperations: [
        new Query(),
        new QueryCollection(),
        new Mutation(name: 'create'),
        new Mutation(name: 'update'),
        new Mutation(name: 'delete'),
    ]
)]
class Article
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private string $title;

    #[ORM\Column(type: 'text')]
    private string $content;

    #[ORM\Column]
    private \DateTimeImmutable $publishedAt;

    // Getters et setters...
}

Cette définition génère automatiquement les types GraphQL correspondants, incluant les types d'entrée pour les mutations et les types de sortie pour les requêtes.

Requêtes GraphQL Avancées

Les requêtes GraphQL permettent de récupérer exactement les données nécessaires. API Platform supporte les filtres, la pagination et le tri directement dans les requêtes GraphQL.

query GetArticles {
  articles(first: 10, after: "cursor123", order: { publishedAt: "DESC" }) {
    edges {
      node {
        id
        title
        content
        publishedAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

La pagination utilise le standard Relay Connection, offrant une navigation efficace à travers les collections de données volumineuses.

Mutations et Validation

Les mutations permettent de modifier les données côté serveur. API Platform intègre automatiquement la validation Symfony dans le processus de mutation.

<?php

namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    graphQlOperations: [
        new Mutation(
            name: 'create',
            validationContext: ['groups' => ['create']]
        ),
        new Mutation(
            name: 'update',
            validationContext: ['groups' => ['update']]
        ),
    ]
)]
class Article
{
    #[Assert\NotBlank(groups: ['create', 'update'])]
    #[Assert\Length(min: 5, max: 255, groups: ['create', 'update'])]
    private string $title;

    #[Assert\NotBlank(groups: ['create'])]
    private string $content;
}

L'exécution d'une mutation avec des données invalides retourne des erreurs structurées conformes à la spécification GraphQL.

mutation CreateArticle {
  createArticle(input: {
    title: "Nouveau titre d'article"
    content: "Contenu détaillé de l'article..."
  }) {
    article {
      id
      title
    }
  }
}

Résolveurs Personnalisés

Pour les cas d'utilisation complexes, API Platform permet de définir des résolveurs personnalisés. Ces résolveurs interceptent l'exécution standard et implémentent une logique métier spécifique.

<?php

namespace App\Resolver;

use ApiPlatform\GraphQl\Resolver\QueryItemResolverInterface;
use App\Entity\Article;
use App\Repository\ArticleRepository;

class ArticleBySlugResolver implements QueryItemResolverInterface
{
    public function __construct(
        private ArticleRepository $repository
    ) {}

    public function __invoke(?object $item, array $context): ?Article
    {
        $slug = $context['args']['slug'] ?? null;
        
        if ($slug === null) {
            return null;
        }

        return $this->repository->findOneBySlug($slug);
    }
}

L'enregistrement du résolveur s'effectue via l'attribut GraphQl\Query avec le paramètre resolver.

#[ApiResource(
    graphQlOperations: [
        new Query(
            name: 'bySlug',
            resolver: ArticleBySlugResolver::class,
            args: ['slug' => ['type' => 'String!']]
        ),
    ]
)]
class Article
{
    // ...
}

Gestion des Relations

Les relations entre entités sont automatiquement exposées dans le schéma GraphQL. API Platform gère les relations OneToMany, ManyToOne et ManyToMany de manière transparente.

<?php

namespace App\Entity;

use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;

#[ORM\Entity]
#[ApiResource]
class Author
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

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

    #[ORM\OneToMany(mappedBy: 'author', targetEntity: Article::class)]
    private Collection $articles;

    public function __construct()
    {
        $this->articles = new ArrayCollection();
    }
}

Les requêtes GraphQL peuvent traverser ces relations pour récupérer des données imbriquées en une seule requête.

query GetAuthorWithArticles {
  author(id: "/authors/1") {
    name
    articles {
      edges {
        node {
          title
          publishedAt
        }
      }
    }
  }
}

Sécurité et Autorisation

La sécurisation des opérations GraphQL utilise le système de sécurité Symfony. Les expressions de sécurité peuvent être définies au niveau des opérations.

#[ApiResource(
    graphQlOperations: [
        new Query(
            security: "is_granted('ROLE_USER')"
        ),
        new Mutation(
            name: 'create',
            security: "is_granted('ROLE_ADMIN')"
        ),
        new Mutation(
            name: 'update',
            security: "is_granted('ROLE_ADMIN') or object.getAuthor() == user"
        ),
    ]
)]
class Article
{
    // ...
}

Les tentatives d'accès non autorisées génèrent des erreurs GraphQL appropriées avec les codes d'erreur correspondants.

Optimisation des Performances

Les requêtes GraphQL complexes peuvent engendrer le problème N+1. API Platform intègre des mécanismes d'optimisation automatique via les extensions Doctrine.

<?php

namespace App\Extension;

use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use App\Entity\Article;
use Doctrine\ORM\QueryBuilder;

class ArticleEagerLoadingExtension implements QueryCollectionExtensionInterface
{
    public function applyToCollection(
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?string $operationName = null,
        array $context = []
    ): void {
        if ($resourceClass !== Article::class) {
            return;
        }

        $rootAlias = $queryBuilder->getRootAliases()[0];
        $queryBuilder
            ->leftJoin(sprintf('%s.author', $rootAlias), 'a')
            ->addSelect('a');
    }
}

Questions d'Entretien GraphQL API Platform

Les entretiens techniques en 2026 incluent fréquemment des questions sur GraphQL et API Platform. Voici les questions les plus pertinentes.

Question : Quelle différence entre une Query et une Mutation dans GraphQL ?

Les Queries sont des opérations de lecture idempotentes qui ne modifient pas l'état du serveur. Les Mutations sont des opérations d'écriture qui peuvent créer, modifier ou supprimer des données. GraphQL garantit que les Mutations s'exécutent séquentiellement tandis que les Queries peuvent s'exécuter en parallèle.

Question : Comment API Platform génère-t-il le schéma GraphQL ?

API Platform utilise l'introspection des métadonnées PHP (attributs ApiResource) et des mappings Doctrine pour générer automatiquement le schéma GraphQL. Les types, champs et relations sont déduits des entités et leurs propriétés.

Question : Comment gérer la pagination dans GraphQL avec API Platform ?

API Platform implémente la spécification Relay Connection pour la pagination. Les collections retournent des objets avec edges (contenant les nodes et cursors), pageInfo (hasNextPage, hasPreviousPage, cursors) et totalCount. Les arguments first, last, before et after contrôlent la navigation.

Question : Comment sécuriser une mutation GraphQL ?

La sécurisation utilise l'attribut security sur l'opération Mutation. Les expressions de sécurité Symfony (is_granted, object.owner == user) permettent un contrôle d'accès granulaire. Les voters personnalisés peuvent également être utilisés pour des logiques d'autorisation complexes.

Question : Qu'est-ce que le problème N+1 et comment le résoudre ?

Le problème N+1 survient quand une requête initiale est suivie de N requêtes supplémentaires pour charger les relations. Dans API Platform, les extensions Doctrine permettent d'ajouter des jointures et du eager loading. Le DataLoader pattern peut également être implémenté pour regrouper les requêtes.

Question : Comment créer un résolveur personnalisé ?

Un résolveur personnalisé implémente QueryItemResolverInterface ou MutationResolverInterface. Il est enregistré via l'attribut GraphQl\Query ou GraphQl\Mutation avec le paramètre resolver pointant vers la classe du service.

Conclusion

L'intégration de GraphQL dans Symfony via API Platform offre une solution robuste pour construire des API flexibles et performantes. La génération automatique de schémas, combinée aux possibilités de personnalisation avancées, permet de répondre aux exigences des applications modernes. La maîtrise de ces concepts constitue un atout considérable pour les développeurs Symfony en 2026, tant dans les projets professionnels que lors des entretiens techniques.