layout: default

Le Pattern Repository en Architecture Hexagonale

Ce guide explique comment implémenter correctement le pattern Repository dans une architecture hexagonale, et pourquoi il ne faut pas utiliser directement l'EntityManager.

Table des matières

{: .no_toc .text-delta }

TOC {:toc}

Qu'est-ce que le Pattern Repository ?

Un Repository se comporte comme une collection d'objets du domaine. Il agit comme un intermédiaire entre la couche domaine et la couche de persistance.

Caractéristiques principales

Collection typée : Un GalinetteRepository ne contient que des objets Galinette
Unicité : Impossible d'ajouter deux fois le même objet (identité unique)
Abstraction de la persistance : Le développeur manipule une collection, le repository gère la persistance
Contrat dans le domaine : L'interface est définie dans le domaine, l'implémentation dans l'infrastructure

Pourquoi NE PAS utiliser directement l'EntityManager ?

MAUVAISE PRATIQUE: Problèmes avec l'EntityManager direct

// ❌ MAUVAISE PRATIQUE
class CreateUserHandler
{
    public function __construct(
        private EntityManagerInterface $entityManager
    ) {}

    public function __invoke(CreateUserCommand $command): void
    {
        $user = new User($command->email, $command->name);

        $this->entityManager->persist($user);
        $this->entityManager->flush();
    }
}

Problèmes :

Couplage fort à Doctrine : Votre domaine dépend de Doctrine
Difficile à tester : Vous devez mocker l'EntityManager
Violation du principe d'inversion de dépendance : Le domaine dépend de l'infrastructure
Pas de point central de persistance : La logique de persistance est éparpillée
Migration difficile : Changer de solution de persistance = refactoring massif

BONNE PRATIQUE: Avantages du Repository

// ✅ BONNE PRATIQUE
class CreateUserHandler
{
    public function __construct(
        private UserRepositoryInterface $userRepository
    ) {}

    public function __invoke(CreateUserCommand $command): void
    {
        $userId = $this->userRepository->nextIdentity();
        $user = User::create($userId, $command->email, $command->name);

        $this->userRepository->add($user);
    }
}

Indépendance technologique : Le domaine ne connaît pas Doctrine
Testabilité : Facile de créer un InMemoryUserRepository pour les tests
Principe d'inversion de dépendance : L'infrastructure dépend du domaine
Point central de persistance : Toute la logique est dans le repository

interface RepositoryInterface
{
    /**
     * Génère la prochaine identité disponible
     */
    public function nextIdentity(): EntityId;

    /**
     * Ajoute une entité à la collection
     */
    public function add(Entity $entity): void;

    /**
     * Récupère une entité par son identité
     * [@throws](https://github.com/throws) EntityNotFoundException
     */
    public function get(EntityId $id): Entity;

    /**
     * Supprime une entité (optionnel selon le métier)
     */
    public function remove(EntityId $id): void;
}

<?php
// src/Hunting/Galinette/Domain/Repository/GalinetteRepositoryInterface.php

namespace App\Hunting\Galinette\Domain\Repository;

use App\Hunting\Galinette\Domain\Model\Galinette;
use App\Hunting\Galinette\Domain\ValueObject\GalinetteId;
use App\Hunting\Galinette\Domain\Exception\GalinetteNotFoundException;

interface GalinetteRepositoryInterface
{
    /**
     * Génère un nouvel identifiant unique pour une Galinette
     */
    public function nextIdentity(): GalinetteId;

    /**
     * Ajoute une Galinette à la collection
     *
     * [@throws](https://github.com/throws) PersistenceException Si la persistance échoue
     */
    public function add(Galinette $galinette): void;

    /**
     * Récupère une Galinette par son identité
     *
     * [@throws](https://github.com/throws) GalinetteNotFoundException Si la Galinette n'existe pas
     * [@throws](https://github.com/throws) PersistenceException Si la récupération échoue
     */
    public function get(GalinetteId $id): Galinette;

    /**
     * Note : remove() n'est pas nécessaire car une Galinette
     * ne se supprime pas, elle va au paradis (goToHeaven())
     */
}

<?php
// src/Hunting/Galinette/Infrastructure/Persistence/Doctrine/DoctrineGalinetteRepository.php

namespace App\Hunting\Galinette\Infrastructure\Persistence\Doctrine;

use App\Hunting\Galinette\Domain\Model\Galinette;
use App\Hunting\Galinette\Domain\Repository\GalinetteRepositoryInterface;
use App\Hunting\Galinette\Domain\ValueObject\GalinetteId;
use App\Hunting\Galinette\Domain\Exception\GalinetteNotFoundException;
use App\Hunting\Galinette\Domain\Exception\PersistenceException;
use Doctrine\ORM\EntityManagerInterface;
use Ramsey\Uuid\Uuid;

final class DoctrineGalinetteRepository implements GalinetteRepositoryInterface
{
    public function __construct(
        private EntityManagerInterface $entityManager
    ) {}

    public function nextIdentity(): GalinetteId
    {
        try {
            return GalinetteId::fromString(Uuid::uuid4()->toString());
        } catch (\Exception $e) {
            throw new PersistenceException(
                'Failed to generate identity',
                0,
                $e
            );
        }
    }

    public function add(Galinette $galinette): void
    {
        try {
            $this->entityManager->persist($galinette);
            $this->entityManager->flush();
        } catch (\Exception $e) {
            throw new PersistenceException(
                sprintf('Failed to persist Galinette with id %s', $galinette->getId()),
                0,
                $e
            );
        }
    }

    public function get(GalinetteId $id): Galinette
    {
        try {
            $galinette = $this->entityManager->find(
                Galinette::class,
                $id->toString()
            );

            if (null === $galinette) {
                throw new GalinetteNotFoundException(
                    sprintf('Galinette with id %s not found', $id->toString())
                );
            }

            return $galinette;
        } catch (GalinetteNotFoundException $e) {
            throw $e;
        } catch (\Exception $e) {
            throw new PersistenceException(
                sprintf('Failed to retrieve Galinette with id %s', $id->toString()),
                0,
                $e
            );
        }
    }
}

<?php
// src/Repository/UserRepository.php

namespace App\Repository;

use App\Entity\User;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;

class UserRepository extends ServiceEntityRepository
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, User::class);
    }

    // ❌ Retourne des tableaux
    public function findActiveUsers(): array
    {
        return $this->createQueryBuilder('u')
            ->where('u.active = :active')
            ->setParameter('active', true)
            ->getQuery()
            ->getResult();
    }

    // ❌ Retourne des scalaires
    public function countActiveUsers(): int
    {
        return $this->createQueryBuilder('u')
            ->select('COUNT(u.id)')
            ->where('u.active = :active')
            ->setParameter('active', true)
            ->getQuery()
            ->getSingleScalarResult();
    }

    // ❌ Retourne un QueryBuilder
    public function getActiveUsersQueryBuilder(): QueryBuilder
    {
        return $this->createQueryBuilder('u')
            ->where('u.active = :active')
            ->setParameter('active', true);
    }

    // ❌ Méthode qui expose le détail de la persistance
    public function save(User $user, bool $flush = false): void
    {
        $this->getEntityManager()->persist($user);

        if ($flush) {
            $this->getEntityManager()->flush();
        }
    }
}