Composer Scripts und Custom Tools in PhpStorm: Buttons gießen

1. Warum Buttons statt Terminal – der eigentliche Gewinn

Der Wechsel zwischen IDE und Terminal kostet mehr als die reine Tippzeit. Jedes Mal, wenn ein Entwickler in das Terminal wechselt, einen Befehl eingibt und auf das Ergebnis wartet, unterbricht er den Entwicklungsfluss. Schlimmer noch: Wenn der Befehl in einem neuen Terminalfenster ausgeführt wird, fehlt der Kontext – welche Datei war gerade offen, welche Zeile war markiert? PhpStorm löst dieses Problem durch die Integration von Werkzeugen direkt in die IDE.

Die Ausgabe von External Tools und Composer Scripts erscheint im Run-Fenster von PhpStorm, das direkt mit dem Editor verknüpft ist. Fehlerausgaben werden geparst, und wenn das Tool Dateinamen und Zeilennummern ausgibt – wie phpcs oder phpstan –, sind diese direkt anklickbar. Ein Klick auf die Fehlermeldung öffnet die betroffene Datei an der exakten Position. Das ist keine Zeitersparnis von Sekunden, sondern eine qualitative Verbesserung des Entwicklungsprozesses. Außerdem lassen sich Buttons und Shortcuts in `.idea/`-Dateien speichern und im Team teilen, sodass alle denselben Workflow nutzen.

2. Composer Scripts: was sie können und wo ihre Grenzen liegen

Composer Scripts sind Shell-Kommandos oder PHP-Callbacks, die in der composer.json unter dem Schlüssel scripts definiert werden und über composer run-script scriptname ausgeführt werden. Sie eignen sich hervorragend für projektspezifische Werkzeuge, die ohnehin über Composer verwaltet werden: phpcs, phpstan, phpunit, php-cs-fixer. Der Vorteil ist, dass jeder Entwickler, der composer install ausführt, automatisch dieselben Skripte verfügbar hat – keine separate Dokumentation, kein manuelles Einrichten.

Composer Scripts haben jedoch Grenzen: Sie laufen immer im Verzeichnis, in dem composer.json liegt, und können keine Kontextinformationen aus der IDE – wie die aktuell geöffnete Datei – automatisch als Parameter erhalten. Für den Einsatz als IDE-Button, der auf die aktuelle Datei reagiert, braucht man External Tools. Außerdem fehlt Composer Scripts die Möglichkeit, Umgebungsvariablen oder Dateiparameter dynamisch zu übergeben. Für einfache projektweite Analyseläufe sind sie aber ideal und deutlich schlanker als eine vollständige Run Configuration.

{
  "require-dev": {
    "squizlabs/php_codesniffer": "^3.9",
    "phpstan/phpstan": "^1.11",
    "phpstan/phpstan-strict-rules": "^1.6"
  },
  "scripts": {
    "cs": "phpcs --standard=PSR12 src/app/code/",
    "cs-fix": "phpcbf --standard=PSR12 src/app/code/",
    "analyse": "phpstan analyse --level=8 --memory-limit=512M src/app/code/",
    "test": "phpunit --configuration phpunit.xml",
    "check": [
      "@cs",
      "@analyse"
    ],
    "post-install-cmd": [
      "@composer dump-autoload --optimize"
    ]
  },
  "scripts-descriptions": {
    "cs": "Run PHP_CodeSniffer against app/code",
    "cs-fix": "Auto-fix code style violations",
    "analyse": "Run PHPStan static analysis at level 8",
    "check": "Run all quality checks in sequence"
  }
}

3. Composer Scripts direkt in PhpStorm ausführen

PhpStorm erkennt Composer Scripts automatisch, wenn eine composer.json im Projektstamm liegt. Im Composer-Fenster (View → Tool Windows → Composer) werden alle definierten Scripts aufgelistet. Ein Doppelklick auf einen Script-Namen führt ihn aus, die Ausgabe erscheint im Run-Fenster unten. Damit ist der erste Schritt zur Integration bereits getan – ohne jegliche weitere Konfiguration.

Um einen Composer Script als festen Button in der Toolbar zu verankern, erstellt man zuerst eine Run Configuration vom Typ Composer Script: Run → Edit Configurations → + → Composer Script. Dort wählt man den Script-Namen aus dem Dropdown und gibt bei Bedarf zusätzliche Argumente an. Diese Run Configuration kann dann über den Button rechts neben der Dropdown-Liste der Toolbar fixiert werden. Beim nächsten Start der IDE ist der Button sofort verfügbar. Für das Team empfiehlt es sich, die Run Configuration als Shared zu markieren, damit sie in das .idea/-Verzeichnis geschrieben und ins Git-Repository eingecheckt wird.

4. External Tools: das flexibelste Werkzeug in PhpStorm

External Tools in PhpStorm (Settings → Tools → External Tools) erlauben die Ausführung beliebiger Kommandozeilenprogramme mit dynamischen Parametern aus dem IDE-Kontext. Die Stärke liegt in den Makros: $FilePath$ gibt den absoluten Pfad der aktuell geöffneten Datei zurück, $FileDir$ das Verzeichnis, $ProjectFileDir$ den Projektstamm, $LineNumber$ die aktuelle Zeilennummer. So lässt sich phpcs genau für die aktive Datei ausführen – nicht für das gesamte Verzeichnis.

Ein External Tool besteht aus drei Pflichtfeldern: Program (der Pfad zum Programm), Arguments (Kommandozeilenargumente mit Makros) und Working directory (meist $ProjectFileDir$). Optional lässt sich das Tool einer Gruppe zuordnen, was die Organisation erleichtert wenn man viele Werkzeuge eingerichtet hat. Die Ausgabe erscheint im Run-Fenster, und wenn Open console for tool output aktiviert ist, springt der Fokus automatisch dorthin. Wenn PhpStorm die Ausgabe als Fehlerformat erkennt – zum Beispiel das Format file.php:42 – wird die Zeile in der Ausgabe klickbar.

<!-- External Tool: phpcs für aktuelle Datei -->
<!--
  Name: phpcs (Current File)
  Group: PHP Quality
  Program: $ProjectFileDir$/vendor/bin/phpcs
  Arguments: --standard=PSR12 --report=emacs $FilePath$
  Working directory: $ProjectFileDir$
-->

<!-- External Tool: phpstan für aktuelle Datei -->
<!--
  Name: phpstan (Current File)
  Group: PHP Quality
  Program: $ProjectFileDir$/vendor/bin/phpstan
  Arguments: analyse --level=8 --memory-limit=256M $FilePath$
  Working directory: $ProjectFileDir$
-->

<!-- External Tool: php-cs-fixer für aktuelle Datei -->
<!--
  Name: cs-fixer (Fix Current File)
  Group: PHP Quality
  Program: $ProjectFileDir$/vendor/bin/php-cs-fixer
  Arguments: fix $FilePath$ --rules=@PSR12
  Working directory: $ProjectFileDir$
-->

<!-- External Tool: Magento cache:flush -->
<!--
  Name: Magento cache:flush
  Group: Magento
  Program: $ProjectFileDir$/bin/magento
  Arguments: cache:flush
  Working directory: $ProjectFileDir$
-->

5. Docker-Wrapper-Skripte als External Tools einrichten

In Docker-basierten Entwicklungsumgebungen – wie dem Mark-Shust-Setup für Magento 2 – laufen PHP, phpcs und alle anderen Tools im Container. Auf dem Host-System ist kein PHP installiert. Das bedeutet, dass man nicht direkt vendor/bin/phpcs aufrufen kann, sondern immer den Wrapper bin/phpcs verwenden muss, der den Befehl über docker exec im laufenden Container ausführt.

Das Einrichten solcher Wrapper als External Tool in PhpStorm ist unkompliziert: Im Feld Program gibt man den absoluten oder relativen Pfad zum Wrapper-Skript an, zum Beispiel $ProjectFileDir$/bin/phpcs. Im Feld Arguments folgen die Argumente, die der Wrapper an den Container weitergibt. Wichtig: Das Working directory muss auf $ProjectFileDir$ zeigen, damit der Wrapper-Skript den Container korrekt identifizieren kann. Ein häufiger Fehler ist es, das Programm als absoluten Systempfad einzugeben und damit die Wrapper-Logik zu umgehen. Teste das External Tool immer zuerst über Tools → External Tools → Toolname ausführen, bevor du es in die Toolbar integrierst.

6. Buttons in die Toolbar integrieren

PhpStorm erlaubt es, die Toolbar vollständig anzupassen. Über View → Appearance → Toolbar lässt sich die Haupttoolbar einblenden. Für die eigentliche Anpassung navigiert man zu Settings → Appearance & Behavior → Menus and Toolbars → Main Toolbar → Toolbar Run Actions. Dort lassen sich mit dem Plus-Symbol neue Aktionen hinzufügen. External Tools erscheinen unter External Tools → Gruppe → Tool-Name, Run Configurations über Run Configurations. Ein aussagekräftiges Icon erleichtert die Identifikation: PhpStorm erlaubt die Auswahl aus dem internen Icon-Set.

Eine gute Toolbar-Strategie für PHP-Projekte: Oben liegen die häufig gebrauchten Aktionen wie "phpcs fix current file" und "analyse current file", weiter rechts projektweite Aktionen wie "full analysis" und "cache:flush". Trennlinien zwischen Gruppen helfen bei der visuellen Orientierung. Wenn das Team dieselbe Toolbar nutzen soll, reicht es, die Run Configurations als Shared zu speichern – die Toolbar-Konfiguration selbst liegt in .idea/workspace.xml und ist benutzerspezifisch, aber die zugrunde liegenden Aktionen sind teilbar.

7. Tastenkürzel für External Tools vergeben

Buttons in der Toolbar sind bequem, Tastenkürzel sind schneller. PhpStorm erlaubt es, jedem External Tool ein eigenes Tastenkürzel zuzuweisen. Das geht über Settings → Keymap → External Tools → Gruppe → Tool-Name → Rechtsklick → Add Keyboard Shortcut. Als Konvention empfiehlt sich ein Präfix wie Alt+Q gefolgt von einem eindeutigen Buchstaben: Alt+Q, C für phpcs, Alt+Q, A für phpstan, Alt+Q, F für cs-fixer. Solche Chord-Shortcuts sind selten mit bestehenden Kürzeln belegt und leicht zu merken.

Für Magento-spezifische Befehle bieten sich direkte Einfach-Shortcuts an, sofern sie nicht belegt sind. Shift+F10 ist für Run belegt, aber Ctrl+Shift+F10 ist in vielen Keymaps frei. Wichtig: Keymaps sind benutzerspezifisch in ~/.config/JetBrains/PhpStorm*/keymaps/ gespeichert und werden nicht automatisch ins Repository übernommen. Dokumentiere die empfohlenen Shortcuts im CLAUDE.md oder README des Projekts, damit alle Entwickler dieselben Kürzel nutzen können.

<?php
// PhpStorm External Tool Output Format Examples
// Configure "Output Filters" to make paths clickable

// phpcs emacs format — PhpStorm recognizes this automatically:
// /path/to/file.php:42:1: error - Expected 1 space after IF keyword; 0 found (Squiz.ControlStructures.ControlSignature)

// phpstan output — also recognized automatically:
//  12     Parameter $id of method Mironsoft\Catalog\Model\Product::load()
//         expects int, string given.

// Custom output filter regex for PhpStorm:
// Pattern: $FILE_PATH$\:$LINE$
// Applied to tool output to make lines clickable

// Macro variables available in External Tools:
// $FilePath$        — absolute path to currently open file
// $FileDir$         — directory of currently open file
// $FileName$        — filename without path
// $FileExt$         — file extension without dot
// $ProjectFileDir$  — project root directory
// $LineNumber$      — cursor line in currently open file
// $SelectedText$    — currently selected text in editor
// $Clipboard$       — current clipboard contents

8. Run Configurations für komplexere Workflows

Wenn ein einzelnes Werkzeug nicht ausreicht und mehrere Schritte nacheinander ausgeführt werden sollen, sind Run Configurations die richtige Wahl. Sie unterstützen Before launch-Aktionen: Man kann beispielsweise eine Run Configuration erstellen, die zuerst den CSS-Build ausführt, dann Static Content deployt und schließlich den Cache leert – alles mit einem Klick. Der Typ Shell Script in Run Configurations ist dafür am flexibelsten, da er beliebige Shell-Kommandos und Pipes unterstützt.

Für Magento-2-Projekte mit Docker-Wrapper empfiehlt sich eine Kombination: Die Before-launch-Aktion ruft bin/npm --prefix ... run build auf (als External Tool), die eigentliche Run Configuration führt dann bin/magento setup:static-content:deploy und bin/magento cache:flush aus. Das ergibt eine "Deploy"-Run-Configuration, die den vollständigen Deploy-Zyklus in einem Schritt abbildet. Wenn etwas schiefgeht, ist der Fehler im Run-Fenster sichtbar und der Schritt identifizierbar – deutlich angenehmer als das manuelle Abtippen einer vierstufigen Deploy-Sequenz.

9. Composer Scripts vs. External Tools vs. Run Configurations

Die drei Integrationsarten in PhpStorm ergänzen sich, überlappen sich aber auch. Die richtige Wahl hängt vom Anwendungsfall ab.

Die Empfehlung für Magento-2-Projekte mit Docker: Composer Scripts für qualitätssichernde Werkzeuge (phpcs, phpstan), die jeder Entwickler lokal kennen sollte. External Tools für datei- oder zeilenbezogene Aktionen wie "fix current file". Run Configurations für mehrstufige Workflows wie Deploy-Sequenzen. Alle drei Typen können parallel nebeneinander existieren und ergänzen sich sinnvoll.

10. Zusammenfassung

Composer Scripts, External Tools und Run Configurations in PhpStorm lösen das Problem der unterbrochenen Entwicklung durch Terminal-Wechsel. Composer Scripts definieren projektweite Qualitätswerkzeuge direkt in composer.json und sind für alle Teammitglieder nach einem composer install verfügbar. External Tools integrieren beliebige Kommandozeilenprogramme mit IDE-Kontext wie $FilePath$ und machen phpcs- oder phpstan-Ausgaben direkt klickbar. Run Configurations ermöglichen mehrstufige Workflows mit Before-launch-Aktionen.

Für Docker-basierte Magento-2-Projekte ist der Schlüssel, die vorhandenen Wrapper-Skripte aus dem bin/-Verzeichnis als Program in External Tools einzutragen. So nutzt PhpStorm dieselben Wrapper, die auch manuell im Terminal verwendet werden – ohne Doppelkonfiguration. Buttons in der Toolbar und Tastenkürzel im Keymap ergänzen das Setup und machen Qualitätssicherung zu einem natürlichen Teil des Entwicklungsflusses, nicht zu einem lästigen Pflichtschritt nach dem Entwickeln.

11. FAQ: Composer Scripts und Custom Tools in PhpStorm