Deptrac : protéger votre architecture Symfony en 15 minutes

Tu as passé des semaines à mettre en place une architecture hexagonale propre dans ton projet Symfony. Domain, Application, Infrastructure — les couches sont séparées, les dépendances pointent dans le bon sens. Puis un vendredi soir, un collègue pressé ajoute un use Doctrine\ORM\EntityManagerInterface dans une entité du Domain. L'architecture est cassée, et personne ne s'en rend compte. Deptrac existe pour empêcher ça.

Qu'est-ce que Deptrac ?

Deptrac est un vérificateur de règles de dépendances pour PHP. Tu définis des couches (Domain, Application, Infrastructure), des règles (le Domain ne peut pas dépendre de l'Infrastructure) et Deptrac vérifie que ton code les respecte. C'est le garde-fou architectural qui manque à PHPStan.

Contrairement à PHPStan qui vérifie la correction du code (types, null safety), Deptrac vérifie l'architecture — les frontières entre couches, les dépendances circulaires, l'isolation du domaine métier.

Installation : 2 minutes

# Installation via Composer
composer require --dev qossmic/deptrac

# Vérifier l'installation
vendor/bin/deptrac --version

Configuration pour architecture hexagonale : 10 minutes

Crée un fichier deptrac.yaml à la racine du projet. Voici la configuration complète pour une architecture hexagonale Symfony classique :

# deptrac.yaml
deptrac:
  paths:
    - ./src

  layers:
    - name: Domain
      collectors:
        - type: directory
          value: src/Domain/.*

    - name: Application
      collectors:
        - type: directory
          value: src/Application/.*

    - name: Infrastructure
      collectors:
        - type: directory
          value: src/Infrastructure/.*

    - name: Presentation
      collectors:
        - type: directory
          value: src/Presentation/.*

  ruleset:
    # Le Domain ne dépend de RIEN
    Domain:

    # L'Application dépend uniquement du Domain
    Application:
      - Domain

    # L'Infrastructure dépend du Domain et de l'Application
    Infrastructure:
      - Domain
      - Application

    # La Présentation dépend de tout
    Presentation:
      - Domain
      - Application
      - Infrastructure

La logique est simple : chaque couche dans ruleset liste les couches dont elle a le droit de dépendre. Si le Domain est vide, c'est qu'il n'a le droit de dépendre de rien — exactement ce qu'on veut.

Lancer l'analyse : 1 minute

# Analyse complète
vendor/bin/deptrac analyse

# Avec rapport graphique (génère une image)
vendor/bin/deptrac analyse --formatter=graphviz-image \
  --output=deptrac-report.png

# Mode verbose pour voir toutes les dépendances
vendor/bin/deptrac analyse -v

Si ton architecture est propre, tu vois un joli "0 violations". Si ce n'est pas le cas, Deptrac liste chaque violation avec le fichier, la ligne et la dépendance interdite.

Les violations courantes et comment les corriger

• Domain → Infrastructure (Doctrine) : une entité qui utilise EntityManagerInterface ou des annotations Doctrine. Solution : extraire le mapping Doctrine en XML/YAML ou utiliser des attributes dédiés, et injecter les repositories via des interfaces dans le Domain.
• Domain → Application : une entité qui référence un Command ou un Handler. Solution : utiliser des Domain Events pour la communication ascendante.
• Application → Infrastructure : un Handler qui utilise directement un repository Doctrine au lieu de l'interface. Solution : typer sur UserRepositoryInterface (Domain) et non sur UserRepository (Infrastructure).
• Dépendances circulaires : Module A dépend de Module B qui dépend de Module A. Solution : extraire l'interface partagée dans un module commun ou utiliser des events.

Intégration CI : 2 minutes

Ajoute Deptrac dans ta pipeline CI pour bloquer tout merge qui viole l'architecture :

# .github/workflows/architecture.yml
name: Architecture Check
on: [push, pull_request]
jobs:
  deptrac:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: 8.3 }
      - run: composer install --no-progress
      - run: vendor/bin/deptrac analyse --no-progress

À partir de maintenant, aucune PR ne peut merger si elle viole les règles architecturales. C'est le filet de sécurité qui protège les décisions d'architecture sur le long terme.

Aller plus loin : audit architectural complet

Deptrac est un outil de protection. Pour un diagnostic complet de l'architecture de ta codebase — couplage, cohésion, cycles, respect des patterns — Bear Scan combine Deptrac avec PhpMetrics, PHPMD et une analyse sémantique par Claude Code. Le résultat : un score d'architecture sur 100, les violations classées par impact, et une roadmap d'actions priorisées par ROI. Réserve un appel découverte pour scanner ta codebase.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours