PHPStan, Psalm und PHP_CodeSniffer in PhpStorm direkt nutzbar machen

1. Warum lokale Integration überhaupt sinnvoll ist

Der typische Workflow ohne lokale Integration sieht so aus: Entwickler schreiben Code, pushen, die CI-Pipeline läuft durch, zehn Minuten später kommt eine E-Mail mit PHPStan-Fehlern. Das ist verschwendete Zeit – für den Entwickler, der den Kontext schon gewechselt hat, und für die Pipeline, die unnötig lief. PHPStan, Psalm und PHP_CodeSniffer in PhpStorm zu integrieren heißt, diesen Feedbackzyklus von Minuten auf Sekunden zu verkürzen.

PhpStorm bringt eigene Inspektionen mit, die PHP-Fehler, Typprobleme und Code-Style-Verstöße direkt im Editor anzeigen. Diese Inspektionen sind jedoch nicht dasselbe wie ein vollständiger PHPStan-Lauf auf Level 8 oder Psalm mit strikter Typisierung. Die IDE-eigenen Prüfungen sind schnell und inkrementell, externe Tools wie PHPStan analysieren den gesamten Aufrufgraphen, kennen Typen aus phpstan.neon-Stubs und erkennen Fehler, die PhpStorm nicht sieht. Beide Ansätze ergänzen sich – und genau diese Kombination ist das Ziel dieses Artikels.

Ein weiterer Grund für die lokale Integration: PHPCS mit projektspezifischen Regelsets (z.B. Magento Coding Standard) formatiert Code konsistent, bevor er überhaupt in die Review gelangt. PHPCBF, der automatische Fixer von PHPCS, kann direkt aus PhpStorm als externer Tool-Aufruf ausgeführt werden und korrigiert die meisten Stil-Verstöße ohne manuelles Eingreifen.

2. PHPStan als externes Tool in PhpStorm einrichten

Der erste Schritt ist die Installation von PHPStan über Composer. Für Projekte mit Docker-Umgebung – wie das Mark-Shust-Setup für Magento – wird PHPStan im Container ausgeführt. PhpStorm unterstützt genau diesen Anwendungsfall über externe Tools mit einem konfigurierten PHP-Interpreter, der auf den Container zeigt.

In PhpStorm öffnet man Settings → Tools → External Tools und legt ein neues Tool an. Als Programm gibt man den Pfad zum PHP-Interpreter an (oder den Docker-Wrapper), als Argumente den Pfad zu vendor/bin/phpstan gefolgt von analyse --no-progress $FilePath$. Das Makro $FilePath$ übergibt die aktuell geöffnete Datei. Mit $ProjectFileDir$ als Working Directory läuft PHPStan immer im richtigen Kontext. Das Ergebnis erscheint im Tool-Window, Doppelklick auf eine Fehlermeldung springt direkt zur entsprechenden Zeile.

# phpstan.neon — Projektkonfiguration im Projektstamm
parameters:
    level: 8
    paths:
        - src/app/code
    excludePaths:
        - src/vendor
        - src/generated
    # Magento-spezifische Erweiterungen
    bootstrapFiles:
        - phpstan-bootstrap.php
    ignoreErrors:
        # Bekannte falsch-positive bei Magento-Proxies
        - '#Call to an undefined method [a-zA-Z0-9\\_]+Proxy::#'
    # PHP 8.4 Features aktivieren
    phpVersion: 80400
    checkMissingIterableValueType: false

services:
    -
        class: PHPStan\Rules\Classes\InstantiationRule
        tags:
            - phpstan.rules.rule

Für die schnelle Ausführung auf nur einer Datei legt man in PhpStorm unter Settings → Keymap einen Shortcut für das externe Tool an. So lässt sich PHPStan mit einem Tastendruck auf der aktuellen Datei ausführen, ohne das Terminal zu wechseln. Wichtig: den --memory-limit-Parameter setzen, wenn das Projekt groß ist – PHPStan kann bei Magento-Codebasen mit vielen Klassen in den OOM-Bereich laufen.

3. Psalm integrieren: Unterschiede zu PHPStan und gemeinsame Konfiguration

Psalm und PHPStan lösen ähnliche Probleme, haben aber unterschiedliche Stärken. Psalm ist besonders gut bei der Erkennung von Nullability-Fehlern, hat ein ausgefeilteres Typ-System mit Template-Typen und bietet mit Psalter einen automatischen Fixer für viele gefundene Probleme. PHPStan hingegen ist oft schneller und hat ein größeres Ökosystem an Erweiterungen für Frameworks wie Magento oder Laravel.

Die Integration in PhpStorm erfolgt analog zu PHPStan: externes Tool unter Settings → Tools → External Tools, Programm auf den PHP-Interpreter oder Docker-Wrapper, Argumente vendor/bin/psalm --output-format=emacs $FilePath$. Das emacs-Ausgabeformat erzeugt Zeilen in einem Format, das PhpStorm parsen und als klickbare Fehlermeldungen anzeigen kann – sofern man unter Output Filters den passenden Regex konfiguriert: $FILE_PATH$:$LINE$:$COLUMN$: $MESSAGE$.

<?xml version="1.0"?>
<!-- psalm.xml — Projektkonfiguration -->
<psalm
    errorLevel="3"
    resolveFromConfigFile="true"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://getpsalm.org/schema/config"
    xsi:schemaLocation="https://getpsalm.org/schema/config
        vendor/vimeo/psalm/config.xsd"
    findUnusedVariablesAndParams="true"
    checkForThrowsDocblock="false"
>
    <projectFiles>
        <directory name="src/app/code" />
        <ignoreFiles>
            <directory name="src/vendor" />
            <directory name="src/generated" />
        </ignoreFiles>
    </projectFiles>

    <!-- Stubs für Magento-Klassen die Psalm nicht kennt -->
    <stubs>
        <file name="psalm-stubs/magento-facades.phpstub" />
    </stubs>

    <!-- Psalm-Plugins -->
    <plugins>
        <pluginClass class="Psalm\PhpUnitPlugin\Plugin" />
    </plugins>
</psalm>

In Projekten, in denen sowohl PHPStan als auch Psalm eingesetzt werden, empfiehlt es sich, die Baseline-Dateien separat zu pflegen und die CI-Pipeline so zu konfigurieren, dass beide Tools auf unterschiedlichen Codeabschnitten eingesetzt werden: Psalm auf dem eigenen Anwendungscode mit striktem Level, PHPStan auf dem gesamten Projekt mit einer sinnvollen Baseline für bestehende Probleme.

4. PHP_CodeSniffer: PHPCS und PHPCBF in PhpStorm

PhpStorm hat eine native Integration für PHP_CodeSniffer unter Settings → PHP → Quality Tools → PHP_CodeSniffer. Dort trägt man den Pfad zur phpcs-Binary ein und wählt das Standard/Ruleset aus. Sobald die Integration aktiv ist, zeigt PhpStorm PHPCS-Warnungen direkt als Inspektionen an – mit der gleichen gelben und roten Wellenlinie wie eigene Fehler. Das ist die direkteste Form der Integration und spart den Umweg über ein separates Tool-Window.

Für Magento-Projekte verwendet man das Magento Coding Standard-Ruleset, das über Composer installiert wird. Die phpcs.xml-Datei im Projektstamm definiert, welche Pfade geprüft werden und welche Regeln gelten. PhpStorm liest diese Konfiguration automatisch, wenn sie im Projektstamm liegt.

<?xml version="1.0"?>
<!-- phpcs.xml — PHPCS-Konfiguration für Magento-Projekt -->
<ruleset name="Mironsoft">
    <description>Coding Standard für Mironsoft Magento-Projekt</description>

    <!-- Zu prüfende Pfade -->
    <file>src/app/code</file>
    <file>src/app/design/frontend/Mironsoft</file>

    <!-- Ausschlüsse -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/generated/*</exclude-pattern>
    <exclude-pattern>*/Test/*</exclude-pattern>

    <!-- Magento Coding Standard -->
    <rule ref="Magento2">
        <!-- Regel deaktivieren die mit PHP 8.4 kollidiert -->
        <exclude name="Magento2.Annotation.MethodAnnotationStructure"/>
    </rule>

    <!-- PSR-12 Ergänzungen -->
    <rule ref="PSR12">
        <exclude name="PSR12.Files.FileHeader"/>
    </rule>

    <!-- PHP-Version -->
    <config name="php_version" value="80400"/>

    <!-- Anzahl Zeichen pro Zeile -->
    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="120"/>
            <property name="absoluteLineLimit" value="0"/>
        </properties>
    </rule>
</ruleset>

PHPCBF – der automatische Fixer – lässt sich ebenfalls als externes Tool einrichten. Damit kann man mit einem Shortcut die aktuelle Datei automatisch korrigieren lassen. In der External-Tool-Konfiguration: Programm auf den PHP-Interpreter, Argumente vendor/bin/phpcbf $FilePath$, und unter "Synchronize files after execution" aktivieren, damit PhpStorm die korrigierte Datei sofort neu lädt. So werden die meisten PHPCS-Verstöße repariert, ohne die Datei manuell anfassen zu müssen.

5. File Watchers: automatisch beim Speichern prüfen

File Watchers in PhpStorm überwachen Dateiänderungen und führen automatisch einen Befehl aus, sobald eine Datei gespeichert wird. Das Plugin ist seit PhpStorm 2023.2 nativ integriert und findet sich unter Settings → Tools → File Watchers. Für PHPCS bietet sich ein File Watcher an, der beim Speichern einer PHP-Datei sofort PHPCBF ausführt und Stil-Verstöße korrigiert. Wichtig: den Scope auf app/code und app/design einschränken, nicht auf vendor anwenden.

Für PHPStan empfehle ich keinen File Watcher – die Analyse dauert zu lange für ein On-Save-Feedback und blockiert den Cursor zu oft. Stattdessen lieber als Run Configuration oder externes Tool mit Shortcut. PHPCS hingegen ist schnell genug für automatische Ausführung und profitiert von der File-Watcher-Integration erheblich.

6. Run Configurations für schnelle Analyseläufe

Run Configurations unter Run → Edit Configurations eignen sich für Analyseläufe, die mehrere Tools kombinieren oder auf das gesamte Projekt angewendet werden sollen. Eine Compound Run Configuration startet mehrere Konfigurationen nacheinander oder parallel – zum Beispiel erst PHPCS auf dem gesamten Pfad, dann PHPStan auf Level 6. Das Ergebnis jeder Konfiguration erscheint in einem eigenen Tab im Run-Window.

Für Docker-basierte Projekte (Mark Shust Setup) legt man Run Configurations mit dem Shell Script-Typ an und ruft die Wrapper-Skripte auf: bin/phpcs, bin/phpstan oder bin/analyse. Das stellt sicher, dass die Tools im Container mit dem richtigen PHP und den richtigen Umgebungsvariablen laufen – und nicht lokal mit einer anderen PHP-Version.

7. PHPStan, Psalm und PHPCS sinnvoll kombinieren

Alle drei Tools gleichzeitig auf demselben Code laufen zu lassen kann sinnvoll sein, muss aber organisiert werden, damit es nicht zur Verwirrung führt. Eine bewährte Aufteilung: PHPCS läuft beim Speichern via File Watcher und kümmert sich ausschließlich um Formatierung und Code-Style. PHPStan läuft via Run Configuration oder Shortcut auf der aktuellen Datei und liefert Typ-Feedback. Psalm läuft in der CI-Pipeline und auf eigenem Code beim Pre-Commit-Hook – nicht ständig lokal.

Redundanz zwischen PHPStan und den PhpStorm-Inspektionen ist unvermeidlich. Beide finden Typfehler, aber PHPStan kennt die projektspezifischen Stubs und Erweiterungen, die PhpStorm nicht hat. Statt PhpStorm-Inspektionen zu deaktivieren, sollte man sie auf einem niedrigeren Severity-Level belassen und PHPStan als authoritative Quelle für Typ-Fehler betrachten. So hat man schnelles inkrementelles Feedback von PhpStorm und vollständige Analyse von PHPStan.

8. Vergleich: Externe Tools vs. PhpStorm-Inspektionen

Die Frage, wann man externe Tools und wann PhpStorm-eigene Inspektionen nutzen soll, ist nicht immer offensichtlich. Die folgende Tabelle zeigt die wichtigsten Unterschiede und hilft bei der Entscheidung.

Der entscheidende Vorteil externer Tools: Sie laufen lokal mit denselben Konfigurationsdateien wie in der CI-Pipeline. Was lokal grün ist, ist auch in der Pipeline grün – wenn man mit denselben Composer-Versionen und derselben PHP-Version arbeitet. Das ist der Grund, warum Docker-basierte Setups wie Mark Shust für lokale Qualitätsprüfungen so wertvoll sind: Die Umgebung ist identisch.

9. Zusammenfassung

PHPStan, Psalm und PHP_CodeSniffer in PhpStorm zu integrieren ist kein Aufwand von Tagen, sondern von Stunden – und zahlt sich täglich aus. PhpStorm bietet dafür externe Tools, Run Configurations, File Watchers und native PHPCS-Integration. Die sinnvolle Kombination: PHPCS via File Watcher beim Speichern, PHPStan als externes Tool mit Shortcut auf der aktuellen Datei, Psalm in CI und Pre-Commit-Hook. PhpStorm-eigene Inspektionen liefern schnelles inkrementelles Feedback und ergänzen die externen Tools.

Für Magento-Projekte mit Docker-Setup empfiehlt sich die Nutzung der Wrapper-Skripte (bin/phpcs, bin/phpstan) in Run Configurations und externen Tools, um sicherzustellen, dass alle Tools im Container mit der richtigen PHP-Version und den richtigen Umgebungsvariablen laufen. Eine phpstan.neon-Baseline für bestehende Fehler erlaubt es, PHPStan auf Level 8 zu setzen, ohne sofort alle Legacy-Probleme beheben zu müssen – aber neue Fehler werden sofort erkannt.

10. FAQ: PHPStan, Psalm und PHPCS in PhpStorm