Doctrine ORM : mapping, relations et migrations Symfony

Doctrine modélise les relations entre tables SQL comme des associations entre objets PHP. Choisir le bon type de relation est la première décision d'architecture dans un projet Symfony.

One-to-One : une entité associée à exactement une autre

Exemple typique : un User a exactement un Profile. La clé étrangère (user_id) est portée par la table profile.

erDiagram
    User ||--|| Profile : "a un"
    User {
        int id
        string email
    }
    Profile {
        int id
        string bio
        int user_id FK
    }

// Profile.php — côté propriétaire (porte la FK)
#[ORM\OneToOne(targetEntity: User::class, inversedBy: 'profile')]
#[ORM\JoinColumn(nullable: false)]
private User $user;

// User.php — côté inverse
#[ORM\OneToOne(targetEntity: Profile::class, mappedBy: 'user', cascade: ['persist', 'remove'])]
private ?Profile $profile = null;

One-to-Many / Many-to-One : la relation la plus fréquente

Exemple : une Category contient plusieurs Article. La clé étrangère (category_id) est dans la table article.

erDiagram
    Category ||--o{ Article : "contient"
    Category {
        int id
        string name
    }
    Article {
        int id
        string title
        int category_id FK
    }

// Article.php — côté Many (porte la FK, côté propriétaire)
#[ORM\ManyToOne(targetEntity: Category::class, inversedBy: 'articles')]
#[ORM\JoinColumn(nullable: false)]
private Category $category;

// Category.php — côté One (côté inverse, pas de FK)
#[ORM\OneToMany(targetEntity: Article::class, mappedBy: 'category', cascade: ['persist'])]
private Collection $articles;

Règle clé : la clé étrangère est toujours du côté ManyToOne. C'est aussi le côté propriétaire : Doctrine ne persiste la relation qu'en modifiant l'entité propriétaire.

Many-to-Many : table de jointure automatique

Exemple : un Article peut avoir plusieurs Tag, et un Tag peut être associé à plusieurs Article. Doctrine crée automatiquement la table de jointure article_tag.

erDiagram
    Article }o--o{ Tag : "tagué avec"
    Article {
        int id
        string title
    }
    article_tag {
        int article_id FK
        int tag_id FK
    }
    Tag {
        int id
        string label
    }

// Article.php — côté propriétaire (définit la table de jointure)
#[ORM\ManyToMany(targetEntity: Tag::class, inversedBy: 'articles')]
#[ORM\JoinTable(name: 'article_tag')]
private Collection $tags;

// Tag.php — côté inverse
#[ORM\ManyToMany(targetEntity: Article::class, mappedBy: 'tags')]
private Collection $articles;

Many-to-Many avec attributs : entité intermédiaire

Dès qu'on veut stocker des données sur la liaison elle-même (date d'association, ordre, statut, quantité...), la ManyToMany ne suffit plus. Il faut remplacer la table de jointure automatique par une entité intermédiaire avec deux ManyToOne.

Exemple : un User peut être membre de plusieurs Group, avec une date d'adhésion et un rôle dans le groupe.

erDiagram
    User ||--o{ Membership : "est membre via"
    Group ||--o{ Membership : "regroupe via"
    User {
        int id
        string email
    }
    Membership {
        int id
        int user_id FK
        int group_id FK
        date joined_at
        string role
    }
    Group {
        int id
        string name
    }

// Membership.php — entité intermédiaire
#[ORM\Entity]
class Membership
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private int $id;

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

    #[ORM\ManyToOne(targetEntity: Group::class, inversedBy: 'memberships')]
    #[ORM\JoinColumn(nullable: false)]
    private Group $group;

    #[ORM\Column(type: 'date')]
    private \DateTimeImmutable $joinedAt;

    #[ORM\Column(length: 20)]
    private string $role = 'member';
}

// User.php — côté inverse
#[ORM\OneToMany(targetEntity: Membership::class, mappedBy: 'user', cascade: ['persist', 'remove'])]
private Collection $memberships;

// Group.php — côté inverse
#[ORM\OneToMany(targetEntity: Membership::class, mappedBy: 'group', cascade: ['persist', 'remove'])]
private Collection $memberships;

Pour créer une adhésion :

$membership = new Membership();
$membership->setUser($user);
$membership->setGroup($group);
$membership->setJoinedAt(new \DateTimeImmutable());
$membership->setRole('admin');

$em->persist($membership);
$em->flush();

Contrairement à une ManyToMany classique où Doctrine gère la jointure en ajoutant l'entité dans la collection, ici on crée et persiste explicitement l'entité intermédiaire.

Lazy loading et N+1

Par défaut, Doctrine charge les relations en lazy loading : la requête SQL n'est exécutée qu'au premier accès à la propriété. Sur une liste, cela génère le problème N+1.

// Problème : 1 requête pour les articles + N requêtes pour les catégories
$articles = $repo->findAll();
foreach ($articles as $article) {
    echo $article->getCategory()->getName(); // déclenche une requête par itération
}

// Solution : fetch JOIN dans le QueryBuilder
$articles = $repo->createQueryBuilder('a')
    ->leftJoin('a.category', 'c')
    ->addSelect('c')             // charge la category dans la même requête
    ->getQuery()
    ->getResult();

Les index Doctrine sont déclarés sur la classe entité via des attributs PHP. Doctrine les intègre dans les migrations générées et les synchronise avec le schéma MySQL.

#[ORM\Entity]
#[ORM\Table(name: 'user')]
#[ORM\Index(columns: ['email'], name: 'idx_user_email')]
#[ORM\Index(columns: ['status', 'created_at'], name: 'idx_status_created_at')]
#[ORM\UniqueConstraint(columns: ['email'], name: 'uq_user_email')]
class User
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private int $id;

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

    #[ORM\Column(length: 20)]
    private string $status;

    #[ORM\Column]
    private \DateTimeImmutable $createdAt;
}

Index composite : l'ordre des colonnes dans columns: [...] est important. MySQL utilise l'index si la requête filtre sur le préfixe gauche des colonnes. ['status', 'created_at'] sert les requêtes WHERE status = ?, WHERE status = ? AND created_at > ?, mais pas WHERE created_at > ? seul.

Après modification : toujours régénérer la migration et vérifier le SQL généré avant de l'appliquer.

php bin/console doctrine:migrations:diff    # génère le fichier de migration
php bin/console doctrine:migrations:migrate # applique en base

// Requête fixe et complexe : préférer DQL au QueryBuilder
$dql = 'SELECT a, c
        FROM App\Entity\Article a
        LEFT JOIN a.category c
        WHERE a.status = :status
          AND a.publishedAt > :since
        ORDER BY a.publishedAt DESC';

$articles = $this->getEntityManager()
    ->createQuery($dql)
    ->setParameter('status', 'published')
    ->setParameter('since', new \DateTimeImmutable('-30 days'))
    ->setMaxResults(20)
    ->getResult();

FROM App\Entity\Article a cible la classe PHP, pas la table SQL. LEFT JOIN a.category c suit l'association Doctrine, pas la colonne category_id. Si l'entité est renommée, la requête DQL doit être mise à jour.

// Requête dynamique (filtres variables) : préférer QueryBuilder
$qb = $this->createQueryBuilder('a')
    ->leftJoin('a.category', 'c')
    ->addSelect('c');

if ($status) {
    $qb->andWhere('a.status = :status')->setParameter('status', $status);
}
if ($since) {
    $qb->andWhere('a.publishedAt > :since')->setParameter('since', $since);
}

return $qb->orderBy('a.publishedAt', 'DESC')
    ->setMaxResults(20)
    ->getQuery()
    ->getResult();

En DQL, une jointure suit une association entre entités (ex : a.category), pas une colonne SQL. Le type de jointure choisi décide du sort des lignes de l'entité de gauche dont l'association est absente : sont-elles conservées ou écartées du résultat ?

join / innerJoin : INNER JOIN

join() est un alias de innerJoin(). La jointure ne conserve que les lignes ayant une association des deux côtés. Un Article sans Category est exclu du résultat.

$articles = $repo->createQueryBuilder('a')
    ->innerJoin('a.category', 'c')
    ->getQuery()
    ->getResult();
// Seuls les articles rattachés à une catégorie sont renvoyés

leftJoin : LEFT OUTER JOIN

La jointure conserve toutes les lignes de gauche, même sans association. Un Article sans Category apparaît quand même, son association valant null (ou une collection vide pour une relation to-many).

$articles = $repo->createQueryBuilder('a')
    ->leftJoin('a.category', 'c')
    ->getQuery()
    ->getResult();
// Tous les articles, catégorie à null si elle est absente

rightJoin : non supporté par Doctrine

Doctrine n'expose aucune méthode rightJoin() sur le QueryBuilder, et DQL ne connaît que INNER et LEFT [OUTER]. Pour obtenir l'équivalent d'un RIGHT JOIN, on inverse le sens de la requête : on part de l'entité de droite et on fait un leftJoin vers la gauche.

// Pas de rightJoin : on part de Category pour garder toutes les catégories
$categories = $em->createQueryBuilder()
    ->select('c')
    ->from(Category::class, 'c')
    ->leftJoin('c.articles', 'a')
    ->getQuery()
    ->getResult();
// Toutes les catégories, y compris celles sans aucun article

Règle clé : le type de jointure décide uniquement des lignes de gauche sans association : INNER les écarte, LEFT les conserve. RIGHT n'existe pas en DQL, on l'exprime avec un LEFT en changeant l'entité de départ.

Fetch JOIN pour éviter le N+1

Toujours charger les relations utilisées dans une boucle avec addSelect().

->leftJoin('article.tags', 'tag')
->addSelect('tag')

Cette règle est spécifique si aucun des champs de tag n'est déjà présent dans le select du QueryBuilder de la requête en question (mais qu'on y accéde en PHP par la suite via l'entité dans une boucle par exemple).

Si un des champs fait déjà partie de l'association fait déjà partie du select dans ce cas la regular join est automatiquement convertit fetch join (pas besoin d'ajouter le addSelect et plus de problème N + 1).

Exemple :

Requête Regular join sur l'adresse :

$query = $em->createQuery("SELECT u FROM User u JOIN u.address a WHERE a.city = 'Berlin'");
$users = $query->getResult();

Requête Fetch join sur l'adresse :

$query = $em->createQuery("SELECT u, a FROM User u JOIN u.address a WHERE a.city = 'Berlin'");
$users = $query->getResult();

getArrayResult() pour les listes en lecture seule

->getResult() hydrate des objets PHP complets. ->getArrayResult() retourne des tableaux associatifs, deux à trois fois plus rapides à hydrater pour les listes d'affichage sans modification.

$rows = $query->getArrayResult(); // tableau PHP, pas d'objets Entity

setMaxResults() systématiquement sur les listes

Sans pagination, une requête findAll() charge toute la table en mémoire. Toujours limiter.

->setMaxResults(50)
->setFirstResult($offset)

clear() dans les batchs d'import

Lors d'un import de masse, l'EntityManager accumule toutes les entités en mémoire (Unit of Work). Vider périodiquement évite l'explosion mémoire.

foreach ($rows as $i => $row) {
    $em->persist(new Article($row));
    if ($i % 200 === 0) {
        $em->flush();
        $em->clear(); // libère la mémoire
    }
}
$em->flush();

Éviter persist() en cascade non contrôlé

cascade: ['persist'] sur une OneToMany peut déclencher des INSERT inattendus si on ajoute un item à la collection sans intention de le persister immédiatement. Préférer persist() explicite sur les entités enfants dans les cas complexes.