NCA Social Media
Erstellt:
Aktualisiert:
Autor:
Roland Golla
Grüne und rote Rohre im Gebäude, Frau schließt Ventil, Schild Deptrac

Was ist Deptrac?

Deptrac ist ein Werkzeug zur statischen Analyse, das Regeln für Abhängigkeiten zwischen den Schichten eurer PHP Anwendung durchsetzt. Ihr legt fest, welcher Layer welchen anderen nutzen darf, und Deptrac meldet jeden Verstoß mit Datei und Zeile.
Das Paket heißt heute deptrac/deptrac. Der alte Name qossmic/deptrac ist abandoned, das alte Repository archiviert. Die aktuelle Version 4 braucht PHP 8.2 und läuft als Dev Abhängigkeit lokal und in der Pipeline.
Inhalt
NCA KI Workshop für Developer

Agentic Coding im Team, nicht nur im Glossar

Ein Tag inhouse mit Benjamin Klein für Developer, Tester und Admins. Context Engineering, Harness, ADRs und zwei Hands on Blöcke mit KI Agenten in eurem Setup.

  1. 1
    Kostenloses Vorgespräch
    Stand, Rollen und Ziele klären
  2. 2
    Workshoptag bei euch
    Praxis am Vormittag, Hands on danach
  3. 3
    Praxistag optional
    Agenten im eigenen Projekt
Benjamin Klein
Benjamin Klein
Senior Consultant
Zum Workshop für Developer arrow_forward

Deptrac mit NCA richtig einordnen

Softwarequalität ist unser Kerngeschäft. Wir arbeiten täglich mit PHPStan, Psalm und Rector in Symfony Projekten und bauen Quality Gates in GitHub Actions und GitLab CI. Roland Golla beschäftigt sich seit über 20 Jahren mit Testing und Refactoring. Schichtregeln gehören für uns in die Pipeline, damit sie auch unter Zeitdruck halten.
Teams begleiten wir im PHP Consulting, bei der Legacy Modernisierung und beim PHP Refactoring. Wenn KI Agents mitschreiben, setzen die NCA PHP AI Coding Guidelines den Rahmen. Fachlich hängt Deptrac eng an Domain Driven Design und dem sauberen Schnitt von Bounded Contexts.

So arbeitet Deptrac mit Layern, Regeln und Verstößen

Deptrac kennt drei Grundbegriffe. Wer sie verstanden hat, kann jede Konfiguration lesen.
  • Layer sind benannte Gruppen von Code, zum Beispiel alle Controller. Welche Klassen dazugehören, bestimmen Collector. Eine Klasse kann in mehreren Layern liegen.
  • Ruleset legt fest, welcher Layer welchen anderen nutzen darf. Alles, was nicht erlaubt ist, ist verboten.
  • Violations sind Abhängigkeiten, die gegen das Ruleset verstoßen. Deptrac nennt Datei und Zeile.
Dazu kommen zwei Sonderfälle. Uncovered sind Abhängigkeiten zu Klassen, die in keinem Layer liegen. Mit --report-uncovered zeigt Deptrac sie an, mit --fail-on-uncovered bricht die Analyse ab. Skipped sind bekannte Verstöße, die ihr bewusst unter skip_violations eintragt, um sie Schritt für Schritt abzubauen.

Deptrac installieren und einrichten

Deptrac kommt als Dev Abhängigkeit ins Projekt. Der Befehl init legt eine erste Konfiguration an.
Code:
          

composer require --dev deptrac/deptrac
vendor/bin/deptrac init

Eine einfache Konfiguration in YAML sieht so aus. Alles steht unter dem Schlüssel deptrac, paths legt fest, welcher Code geprüft wird.
Code:
          

# deptrac.yaml
deptrac:
  paths:
    - src/
  layers:
    - name: Controller
      collectors:
        - type: classLike
          value: .*Controller.*
    - name: Service
      collectors:
        - type: classLike
          value: .*Service.*
    - name: Repository
      collectors:
        - type: classLike
          value: .*Repository.*
  ruleset:
    Controller:
      - Service
    Service:
      - Repository
    Repository: ~

Controller dürfen Services nutzen, Services dürfen Repositories nutzen. Repositories hängen von keinem anderen Layer ab. Ruft ein Repository einen Controller auf, schlägt die Analyse an.
Code:
          

vendor/bin/deptrac analyse

Tipp für größere Projekte: Seit Version 4.7 erkennt Deptrac eine deptrac.php automatisch und bevorzugt sie vor der YAML Datei. In PHP legt ihr Layer als Variablen an und nutzt sie in den Regeln wieder. Das spart Tippfehler bei Layer Namen. Die Konfigurationsklassen liegen im Namespace Deptrac\Deptrac\Contract\Config und fallen unter das Versprechen zur Rückwärtskompatibilität.
Code:
          

// deptrac.php
use Deptrac\Deptrac\Contract\Config\DeptracConfig;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (DeptracConfig $config, ContainerConfigurator $containerConfigurator): void {
    // Layer, Collector und Regeln hier definieren
};

Wichtige Collector im Überblick

Collector Was er sammelt Typischer Einsatz
classLike Klassen, Interfaces, Traits und Enums nach Namen per Regex Schichten nach Namenskonvention wie Controller oder Repository
directory Klassen nach ihrem Ordner im Projekt Module oder Bounded Contexts, die in eigenen Ordnern liegen
implements, extends Klassen, die ein Interface umsetzen oder von einer Klasse erben Alle Event Subscriber oder alle Entities als eigener Layer
composer Code aus bestimmten Paketen der composer.json Den Zugriff auf Frameworks oder externe Bibliotheken begrenzen
layer, bool Andere Layer wiederverwenden und Bedingungen kombinieren Ausnahmen bauen, zum Beispiel Controller ohne Admin Bereich

Deptrac im Legacy Projekt mit Baseline einführen

In gewachsenem Code findet Deptrac beim ersten Lauf oft hunderte Verstöße. Alles auf einmal zu beheben, ist unrealistisch. Dafür gibt es den Baseline Formatter. Er schreibt alle heutigen Verstöße in eine eigene Datei.
Code:
          

vendor/bin/deptrac analyse --formatter=baseline

Die Datei deptrac.baseline.yaml bindet ihr in eure Konfiguration ein. Ab dann ist die Pipeline grün, und jeder neue Verstoß fällt sofort auf.
Code:
          

# deptrac.yaml
imports:
  - deptrac.baseline.yaml

  1. Quality Gates zuerst. Statische Analyse, Unit Tests, Functional Tests und Cypress E2E laufen in der Pipeline.
  2. Layer grob schneiden. Lieber wenige klare Layer als ein feines Raster, das niemand pflegt.
  3. Baseline erzeugen. Der Ist Stand wird eingefroren, neuer Code muss die Regeln einhalten.
  4. Baseline abbauen. Verstöße Stück für Stück von Hand mit KI als Helfer auflösen und jede Änderung reviewen.
Ein Detail hilft beim Aufräumen: Trifft ein Eintrag in skip_violations auf keinen Verstoß mehr zu, meldet Deptrac das als Fehler. So bleibt die Baseline sauber und wächst nicht heimlich mit.

Formatter für Konsole, GitLab, GitHub und Diagramme

Deptrac gibt seine Ergebnisse in vielen Formaten aus. Standard ist eine Tabelle in der Konsole, gruppiert nach Layer. Für die Pipeline gibt es eigene Formatter, die Verstöße direkt im Merge Request oder Pull Request zeigen.

Deptrac Formatter im Überblick

Formatter Ausgabe Passt für
Table Tabelle in der Konsole, gruppiert nach Layer Den Alltag lokal im Terminal
Codeclimate Issues im Codeclimate Format GitLab CI, Verstöße erscheinen im Merge Request
GitHubActions Annotations im Pull Request GitHub Actions, dort automatisch aktiv
Baseline Datei mit allen heutigen Verstößen Den Einstieg in Legacy Projekte
Graphviz, MermaidJS Diagramme der Layer und Verstöße Doku, Reviews und Architektur Gespräche
JUnit, JSON Maschinenlesbare Reports CI Tools und eigene Auswertungen

Deptrac als Guardrail für KI Coding

KI Agents lösen eine Aufgabe auf dem kürzesten Weg. Braucht ein Repository eine Info aus dem Controller, holt sich der Agent sie einfach. Der Code läuft, die Architektur bröckelt. Im Review fällt das bei großen Diffs leicht durch.
Deptrac in der Pipeline stoppt genau das. Der Agent bekommt den Verstoß mit Datei und Zeile zurück und muss eine saubere Lösung finden. Zusammen mit PHPStan und Type Coverage entsteht so ein Satz Leitplanken, der ohne Diskussion greift. Wie solche Guardrails im Team aufgebaut werden, zeigen wir im Vibe Coding Consulting.

Deptrac, PHPat und PHP Arkitect im Vergleich

Für Architekturregeln in PHP gibt es drei bekannte Werkzeuge. Sie lösen dasselbe Problem auf unterschiedlichen Wegen. Mehr zu den beiden anderen steht im Glossar unter PHPat und PHP Arkitect.

Werkzeuge für Architekturregeln in PHP

Werkzeug Ansatz Passt, wenn
Deptrac Eigenes CLI Tool, Layer per Collector, Regeln in YAML oder PHP ihr Schichten und Module projektweit absichern und visualisieren wollt
PHPat PHPStan Erweiterung, Architekturregeln als PHP Klassen PHPStan schon läuft und ihr kein weiteres Tool wollt
PHP Arkitect Eigenes Tool, Regeln in PHP mit lesbarer Fluent API ihr Regeln wie Sätze formulieren wollt
PHPStan Typen und Fehler im Code, keine Schichtregeln von Haus aus als Basis immer, Deptrac ergänzt es

helps you communicate, visualize and enforce architectural decisions in your projects.

Denis Brumann – Talk An intro to Deptrac auf Speaker Deck

Die NCA Erfahrung mit Architekturregeln in PHP

NCA berät Teams, deren PHP Code über Jahre gewachsen ist. Oft weiß niemand mehr genau, welcher Teil von welchem abhängt. Deptrac macht das sichtbar und hält neue Regeln in der Pipeline fest.
Fachliche Grenzen finden Teams mit Event Storming und halten sie mit Context Mapping fest. Wo alter und neuer Code sich treffen, schützt ein Anti Corruption Layer die neue Welt. Ist ein Projekt zu alt für Pflege, begleiten wir den Weg heraus als paralleles neues Projekt, etwa mit dem Strangler Fig Pattern. Vorher sichern Characterization Tests ab, was der Code heute tut.
CYPRESS.IO Ambassador und IT Consultant für QA Engenieering und Qualität in PHP Projekten.
Erreichen Sie unsere PHP Consultant Spezialisten

Wir arbeiten seit über 20 Jahren mit PHP und Symfony. Wir helfen bei PHP Updates und PHP Refactoring und beraten remote zu allen Fragen rund um PHP. Zuerst sichern Tests und statische Analyse den Code ab, dann räumen wir auf. Automatische CI/CD Deployments und eine stabile Docker Umgebung sorgen dafür, dass jede Änderung sicher live geht.

Häufige Fragen zu Deptrac

Die wichtigsten Antworten zu Deptrac: Version und Umstieg, Konfiguration, Baseline, Formatter und der Vergleich mit anderen Werkzeugen.
Was ist Deptrac 2026?

Deptrac ist ein Werkzeug zur statischen Analyse für PHP. Es prüft, ob die Abhängigkeiten zwischen den Schichten eurer Anwendung euren Regeln folgen. Ihr fasst Code per Collector zu Layern zusammen und legt im Ruleset fest, welcher Layer welchen nutzen darf. Jeder Verstoß erscheint mit Datei und Zeile, lokal oder in der CI Pipeline.

Welche Deptrac Version ist 2026 aktuell?

Aktuell ist die Version 4 unter dem Paketnamen deptrac/deptrac. Sie verlangt PHP 8.2. Das alte Paket qossmic/deptrac ist abandoned und das alte Repository archiviert. Seit Version 4.7 erkennt Deptrac außerdem eine deptrac.php automatisch als Konfiguration und bevorzugt sie vor der YAML Datei.

Wie steige ich 2026 von qossmic/deptrac auf deptrac/deptrac um?

Ihr entfernt das alte Paket mit composer remove qossmic/deptrac --dev und installiert das neue mit composer require --dev deptrac/deptrac. Danach prüft ihr eure Konfiguration. Ältere YAML Dateien ohne den Schlüssel deptrac oder mit veralteten Collector Namen solltet ihr an das aktuelle Format anpassen. Der Upgrade Guide auf der Projektseite hilft dabei.

Sollte ich 2026 YAML oder PHP für die Deptrac Konfiguration nutzen?

Für kleine Projekte reicht YAML völlig. In größeren Projekten spielt PHP seine Stärken aus. Layer liegen als Variablen vor und werden in Regeln und Formattern wiederverwendet, das verhindert Tippfehler. Außerdem lassen sich eigene Collector und Regeln einbinden. Die Konfigurationsklassen fallen unter das Versprechen zur Rückwärtskompatibilität.

Hilft Deptrac 2026 bei KI generiertem Code?

Ja. KI Agents greifen gern direkt auf Klassen zu, die eigentlich tabu sind, weil das der kürzeste Weg ist. Deptrac in der Pipeline fängt das ab und meldet Datei und Zeile. Der Agent muss dann eine Lösung finden, die zur Architektur passt. Das ist ein einfacher Guardrail, der auch bei hohem Tempo hält.

Wie führe ich Deptrac in ein Legacy Projekt ein?

Mit dem Baseline Formatter. Der Befehl vendor/bin/deptrac analyse --formatter=baseline schreibt alle heutigen Verstöße in die Datei deptrac.baseline.yaml. Die bindet ihr per imports in eure Konfiguration ein. Ab dann bleibt die Pipeline grün, neue Verstöße fallen sofort auf, und die alten baut ihr Schritt für Schritt ab.

Was sind uncovered Dependencies in Deptrac?

Das sind Abhängigkeiten zu Klassen, die in keinem Layer liegen. Deptrac kann sie nicht bewerten, weil keine Regel für sie gilt. Mit der Option --report-uncovered zeigt Deptrac sie an, mit --fail-on-uncovered schlägt die Analyse fehl. Interne PHP Klassen ignoriert Deptrac dabei standardmäßig.

Welche Collector gibt es in Deptrac?

Deptrac bringt rund zwanzig Collector mit. Häufig genutzt werden classLike für Namen per Regex, directory für Ordner, implements und extends für Vererbung sowie composer für Code aus bestimmten Paketen. Mit layer und bool kombiniert ihr Layer und baut Ausnahmen. Die vollständige Liste steht in der Dokumentation.

Wie zeige ich Deptrac Verstöße in GitLab an?

Mit dem Codeclimate Formatter. Er gibt Verstöße in einem Format aus, das GitLab CI als Code Quality Report versteht. Die Verstöße erscheinen dann direkt im Merge Request. In GitHub Actions ist der GitHubActions Formatter automatisch aktiv und zeigt Verstöße als Annotations im Pull Request.

Was ist der Unterschied zwischen Deptrac und PHPStan?

PHPStan prüft Typen und findet Fehler im Code, etwa falsche Aufrufe oder fehlende Methoden. Deptrac prüft die Architektur, also welche Teile des Codes voneinander abhängen dürfen. Beide ergänzen sich. Ein Projekt kann fehlerfrei durch PHPStan laufen und trotzdem quer durch alle Schichten verdrahtet sein.

Deptrac, PHPat oder PHP Arkitect, was passt besser?

Deptrac ist ein eigenes Tool mit vielen Collectorn, Baseline und Diagrammen. PHPat hängt sich als Erweiterung in PHPStan ein und braucht kein weiteres Tool. PHP Arkitect formuliert Regeln in PHP fast wie Sätze. Für große, gewachsene Projekte mit vielen Modulen ist Deptrac oft die flexibelste Wahl.

Kann Deptrac Abhängigkeiten grafisch darstellen?

Ja. Die Graphviz Formatter erzeugen Diagramme als Bild, HTML oder dot Datei. Der MermaidJS Formatter liefert eine Diagramm Definition, die ihr direkt in Markdown Dokumentation einbetten könnt. So seht ihr Layer, erlaubte Wege und Verstöße auf einen Blick, etwa für Reviews oder Architektur Gespräche im Team.