Quality Gates lokal in PhpStorm bündeln: PHPStan, PHPUnit, PHPCS, Rector

1. Warum Quality Gates lokal statt nur in CI

Die klassische Herangehensweise: Code schreiben, pushen, Ergebnis in der CI abwarten. Wenn PHPStan Level 8 drei Stellen findet, die nicht stimmen, fährt man die IDE wieder hoch, sucht die Zeile, fixt, pusht erneut, wartet. Dieser Zyklus kostet bei einem mittelgroßen PHP-Projekt leicht 10–20 Minuten pro Runde. Multipliziert mit mehreren Commits pro Tag und mehreren Entwicklern wird daraus ein messbarer Produktivitätsverlust, der sich vollständig vermeiden lässt.

PhpStorm bietet mit seinen External Tools, Run Configurations und der nativen PHPUnit-Integration alle Bausteine, um PHPStan, PHPUnit, PHPCS und Rector direkt in die IDE zu ziehen. Das Ergebnis: PHPStan-Fehler erscheinen mit roter Unterstreichung direkt im Editor, PHPCS-Verstöße werden beim Speichern behoben, und ein Rector-Lauf ist ein einzelner Tastendruck. Die CI dient dann nur noch als finale Absicherung – nicht mehr als primäres Feedback-Werkzeug.

Für Magento-2-Projekte, die PHP 8.4 mit strikten Typen verwenden, ist das besonders relevant. Magento bringt viele Klassen mit komplexen Typen mit, und PHPStan auf Level 6 oder höher findet dort schnell echte Bugs – aber nur, wenn die richtigen Extensions eingebunden sind. In PhpStorm kann man diese Konfiguration einmal hinterlegen und danach bei jedem Aufruf sicher sein, dass exakt dieselbe Analyse läuft wie in der CI.

2. PHPStan in PhpStorm einrichten

PhpStorm hat keine native PHPStan-Integration über ein dediziertes UI-Panel, aber External Tools sind der richtige Weg. Unter Settings → Tools → External Tools legt man ein neues Tool an: Programm ist der Pfad zum PHPStan-Binary (bei Composer-Installation $ProjectFileDir$/vendor/bin/phpstan), die Argumente sind analyse --configuration=$ProjectFileDir$/phpstan.neon --error-format=checkstyle $FilePath$. Als Working Directory gibt man $ProjectFileDir$ an. Mit dem Checkstyle-Format kann PhpStorm die Ausgabe direkt parsen und Fehler als Annotationen im Editor anzeigen, wenn man den Output mit dem entsprechenden File Filter verknüpft.

Die elegantere Lösung ist ein Quality Tools Plugin (z.B. das offizielle PHPStan-Plugin aus dem Marketplace). Es liest die phpstan.neon aus dem Projekt, kennt den konfigurierten Level und zeigt Fehler sofort beim Tippen an – ohne manuellen Aufruf. Für Docker-basierte Projekte muss der PHP-Interpreter auf den Remote-Interpreter zeigen (dazu mehr in Abschnitt 6), damit PHPStan mit der Projektkonfiguration im Container arbeitet und nicht mit einem möglicherweise abweichenden lokalen PHP.

# phpstan.neon — Konfiguration für Magento 2 mit PHP 8.4
parameters:
    level: 6
    paths:
        - app/code/Mironsoft
    excludePaths:
        - app/code/Mironsoft/*/Test
    # Magento-spezifische PHPStan-Extension
    bootstrapFiles:
        - vendor/magento/magento2-base/dev/tests/static/bootstrap.php
    ignoreErrors:
        # Magento Magic Methods — known false positives
        - '#Call to an undefined method Magento\\Framework\\#'
    checkMissingIterableValueType: false
    reportUnmatchedIgnoredErrors: false

includes:
    - vendor/phpstan/phpstan-strict-rules/rules.neon
    - vendor/bitexpert/phpstan-magento/extension.neon

Für den täglichen Einsatz empfiehlt sich eine zweistufige Strategie: Ein "Fast"-Profil analysiert nur die aktuell geöffnete Datei ($FilePath$), ein "Full"-Profil analysiert das gesamte Modul. Beide können als separate External Tools angelegt und über Keyboard Shortcuts erreichbar gemacht werden. So bleibt die schnelle Feedback-Schleife für die aktuelle Arbeit erhalten, während eine vollständige Analyse auf Knopfdruck läuft.

3. PHPUnit-Integration und Test-Runner konfigurieren

Die PHPUnit-Integration in PhpStorm ist eine der ausgereiftesten aller nativen Integrationen. Unter Settings → PHP → Test Frameworks legt man eine PHPUnit-Konfiguration an. Bei Composer-basierten Projekten wählt man "PHPUnit by Composer autoloader" und gibt den Pfad zu vendor/autoload.php an. Die Konfigurationsdatei (phpunit.xml oder phpunit.xml.dist) wird automatisch erkannt, wenn sie im Projektwurzel liegt. PhpStorm liest daraus die Test-Suites und stellt sie im Test-Runner-Panel zur Verfügung.

Nach der Konfiguration kann man einzelne Tests per Klick auf das grüne Play-Icon neben der Methode starten, eine ganze Test-Suite im Run-Panel ausführen oder mit dem Coverage-Runner die Codeabdeckung mit Inline-Highlighting anzeigen. Für Magento-2-Unit-Tests muss man darauf achten, dass der Autoloader korrekt auf den Magento-Bootstrap zeigt und dass alle nötigen Bootstrap-Dateien eingebunden sind, weil Magento eine eigene Objektivfabrik mitbringt, die PHPUnit ohne Bootstrap nicht kennt.

<?xml version="1.0" encoding="UTF-8"?>
<!-- phpunit.xml — Magento 2 Unit Tests mit PhpStorm-Kompatibilität -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="dev/tests/unit/framework/bootstrap.php"
         colors="true"
         columns="120"
         stopOnFailure="false">
    <testsuites>
        <testsuite name="Mironsoft Unit Tests">
            <directory>app/code/Mironsoft/*/Test/Unit</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory suffix=".php">app/code/Mironsoft</directory>
        </include>
        <exclude>
            <directory>app/code/Mironsoft/*/Test</directory>
        </exclude>
    </coverage>
    <php>
        <const name="TESTS_CLEANUP" value="disabled"/>
        <const name="MAGENTO_EXTRA_VERBOSE_CONFIG_ARRAY" value="1"/>
    </php>
</phpunit>

4. PHPCS und PHPCBF als On-Save-Action

PHPCS lässt sich in PhpStorm als nativer Code Quality Tool einrichten: Settings → PHP → Quality Tools → PHP Code Sniffer. Dort gibt man den Pfad zum Binary und den Ruleset an. Mit "Show warnings as" auf "Error" oder "Warning" erscheinen Verstöße direkt im Editor als farbige Markierungen – ohne manuellen Aufruf. Wichtig ist, dass das Ruleset denselben Standard verwendet wie die CI, sonst fixen Entwickler lokal etwas, das die CI wieder als Fehler meldet.

PHPCBF ist das automatische Gegenstück: Es korrigiert alle automatisch behebbaren PHPCS-Verstöße. Als External Tool in PhpStorm eingerichtet, kann man PHPCBF mit einem Shortcut auf die aktuelle Datei anwenden. Noch bequemer ist die Integration als File Watcher oder als Aktion in Settings → Tools → Actions on Save. Seit PhpStorm 2023 gibt es dort dedizierte Einträge für External Tools, sodass PHPCBF nach jedem Speichern automatisch ausgeführt wird – der Cursor springt nicht, die Datei wird still korrigiert.

5. Rector als External Tool für automatisches Refactoring

Rector ist kein Linter, sondern ein automatischer Code-Transformator: Es liest PHP-Code, wendet konfigurierte Regeln an und schreibt die Datei zurück. In einer CI-Pipeline läuft Rector im "dry-run"-Modus und meldet, was es verändern würde. Lokal in PhpStorm will man Rector direkt ausführen, damit die Transformationen sofort sichtbar sind. Als External Tool eingerichtet: Programm vendor/bin/rector, Argumente process $FilePath$ --config=rector.php, Working Directory $ProjectFileDir$.

Nach der Ausführung öffnet PhpStorm automatisch das Diff-View, wenn man "Open console" aktiviert hat und Rector Änderungen vorgenommen hat. Alternativ funktioniert die Integration über das Git-Diff-Panel: Rector ändert die Datei auf der Disk, PhpStorm erkennt die Änderung und zeigt sie im Diff an. Für PHP-8.4-Upgrades – Constructor Property Promotion, Typed Class Constants, Readonly Properties – sind die entsprechenden Rector-Sets mit wenigen Zeilen in der rector.php aktiviert.

<?php
// rector.php — Konfiguration für PHP 8.4 Upgrade und Magento 2
declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;
use Rector\Set\ValueObject\SetList;
use Rector\TypeDeclaration\Rector\ClassMethod\AddReturnTypeDeclarationRector;
use Rector\TypeDeclaration\Rector\Property\TypedPropertyFromAssignsRector;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/app/code/Mironsoft',
    ])
    ->withSkip([
        __DIR__ . '/app/code/Mironsoft/*/Test',
    ])
    ->withSets([
        LevelSetList::UP_TO_PHP_84,
        SetList::TYPE_DECLARATION,
        SetList::EARLY_RETURN,
    ])
    ->withRules([
        AddReturnTypeDeclarationRector::class,
        TypedPropertyFromAssignsRector::class,
    ])
    // Magento generierte Klassen nicht anfassen
    ->withSkip([
        '*/generated/*',
        '*/setup/src/*',
    ]);

6. Remote PHP-Interpreter für Docker-Setups

Bei Docker-basierten Entwicklungsumgebungen wie dem Mark-Shust-Setup gibt es zwei Ansätze für Quality Tools in PhpStorm: einen lokalen PHP-Interpreter verwenden (der möglicherweise andere Extensions hat) oder den Interpreter direkt im Container nutzen. Der zweite Weg ist korrekt. Unter Settings → PHP fügt man einen neuen Interpreter hinzu, wählt "From Docker, Vagrant, VM, WSL, Remote" und konfiguriert die Docker-Verbindung. PhpStorm verbindet sich dann mit dem laufenden Container und nutzt dessen PHP-Binary und alle installierten Extensions.

Das bedeutet: PHPStan läuft mit exakt derselben PHP-Version, denselben Extensions und derselben Konfiguration wie in der CI. PHPCS findet dieselben Abhängigkeiten. PHPUnit nutzt denselben Autoloader. Die Parität zwischen lokaler Analyse und CI-Analyse ist damit gewährleistet – ein häufiges Problem bei Teams, bei denen ein Entwickler PHP 8.3 lokal hat, die CI aber PHP 8.4 nutzt, wird damit vollständig eliminiert.

7. Run Configurations: alles mit einem Klick

Run Configurations in PhpStorm sind benannte, wiederverwendbare Ausführungspläne. Man legt sie unter Run → Edit Configurations an. Für Quality Gates bieten sich Compound Configurations an: Eine einzelne Konfiguration startet nacheinander PHPStan, dann PHPUnit, dann PHPCS und zeigt alle Ergebnisse in je einem Tab. So reicht ein einziger Klick oder Shortcut, um alle Quality Gates zu prüfen – ideal vor einem Commit oder Merge-Request.

Run Configurations lassen sich auch als Datei (.run/) ins Repository einchecken. Das bedeutet, alle Teammitglieder erhalten dieselben vorkonfigurierten Quality-Gate-Runs beim ersten Öffnen des Projekts. Neue Entwickler müssen nichts manuell einrichten: Der PHP-Interpreter ist über die Docker-Konfiguration definiert, die Binaries liegen im Vendor-Verzeichnis, die Run Configuration verweist auf die richtigen Pfade. Onboarding für das Quality-Gate-Setup dauert damit Minuten statt Stunden.

8. Git-Hooks aus PhpStorm heraus steuern

PhpStorm bietet unter Settings → Version Control → Git → Commit die Möglichkeit, Aktionen vor dem Commit auszuführen: "Run Tests" startet die PHPUnit-Suite, "Analyze code" führt die konfigurierten Inspections durch. Das ist die IDE-seitige Entsprechung zu einem pre-commit-Hook. Der Vorteil gegenüber einem Shell-Hook: Man sieht das Ergebnis sofort im Commit-Dialog, kann bei Fehlern direkt zur betroffenen Stelle springen und den Commit abbrechen oder trotzdem fortfahren.

Für Teams, die sowohl PhpStorm als auch andere Editoren nutzen, empfiehlt sich eine Kombination: PhpStorm-seitige Pre-Commit-Checks als komfortable Oberfläche, plus ein Bash-basierter pre-commit-Hook als Netz. Der Hook ruft dieselben Binaries auf (vendor/bin/phpstan analyse, vendor/bin/phpcs), sodass Quality Gates auch dann greifen, wenn jemand via Kommandozeile committet. Die Konfiguration ist in beiden Fällen dieselbe phpstan.neon und .phpcs.xml.

9. Quality-Gate-Strategien im Vergleich

Es gibt mehrere Strategien, Quality Gates in einem PHP-Projekt durchzusetzen. Die Wahl hängt von Teamgröße, CI-Setup und IDE-Präferenzen ab. Die folgende Tabelle zeigt die wichtigsten Ansätze und ihre Kompromisse.

Die Kombination aus PhpStorm-On-Save-Actions für PHPCS/PHPCBF, dem PHPStan-Plugin für Echtzeit-Analyse und Compound Run Configurations für den vollständigen Gate-Lauf vor einem Commit ist der praktisch optimale Ansatz. CI bleibt als finale Absicherung bestehen, aber die allermeisten Fehler werden gar nicht erst committet.

10. Zusammenfassung

PHPStan, PHPUnit, PHPCS und Rector in PhpStorm zu bündeln bedeutet, den Feedback-Zyklus von Minuten auf Sekunden zu reduzieren. PHPStan als Plugin oder External Tool zeigt Typfehler sofort im Editor. PHPCS markiert Stilabweichungen, PHPCBF behebt sie beim Speichern automatisch. PHPUnit läuft mit einem Klick als Run Configuration, mit Coverage-Highlighting direkt in der Datei. Rector transformiert Code auf Knopfdruck, das Ergebnis ist sofort im Diff sichtbar.

Der Schlüssel ist CI-Parität: Dieselbe phpstan.neon, dieselbe phpunit.xml, dasselbe PHPCS-Ruleset lokal und in der Pipeline. Mit einem Remote-PHP-Interpreter für Docker-basierte Setups ist sichergestellt, dass die lokale Analyse und die CI-Analyse auf identischen Voraussetzungen basieren. Das eliminiert die häufigste Quelle von "Geht lokal, schlägt in CI fehl" – abweichende PHP-Versionen, fehlende Extensions, unterschiedliche Konfigurationen.

11. FAQ: Quality Gates lokal in PhpStorm