File Watchers in PhpStorm richtig einsetzen – ohne unnötige Nebenwirkungen

1. Was File Watchers sind und was sie nicht sind

File Watchers in PhpStorm sind eine Automatisierungsfunktion, die einen externen Befehl ausführt, sobald eine Datei im Projekt gespeichert wird – oder nach einer konfigurierbaren Verzögerung. Der Befehl wird mit der geänderten Datei als Argument aufgerufen und kann eine Ausgabedatei produzieren, die PhpStorm in das Projekt einbindet. Das klassische Anwendungsbeispiel: Eine .scss-Datei wird gespeichert, der Watcher kompiliert sie zu .css, PhpStorm zeigt die kompilierte CSS-Datei sofort im Projektbaum an.

Was File Watchers nicht sind: kein Task-Runner-Ersatz, kein CI-System und kein Ersatz für das Terminal bei komplexen Build-Prozessen. Wenn ein Build-Schritt mehrere Eingabedateien kombiniert (wie Tailwind CSS das macht – alle Template-Dateien scannen um das CSS zu generieren), passt das Einzeldatei-Modell der File Watchers nicht. In solchen Fällen ist ein externer Watch-Prozess (npm run watch) oder eine Run Configuration besser geeignet.

Die File Watchers befinden sich unter "Settings > Tools > File Watchers". PhpStorm liefert vorgefertigte Templates für häufige Anwendungsfälle: Sass/SCSS, Less, TypeScript, CoffeeScript und mehr. Diese Templates sind sorgfältig konfiguriert und ein guter Ausgangspunkt – sie direkt zu übernehmen ist in vielen Fällen besser als von Grund auf neu zu konfigurieren.

2. Grundlegende Konfiguration eines File Watchers

Jeder File Watcher hat folgende Kernfelder: Name (beschreibend, z.B. "SCSS -> CSS"), File type (welcher Dateityp den Watcher auslöst), Scope (in welchem Verzeichnis), Program (welches Binary ausgeführt wird), Arguments (mit Makros wie $FileName$, $FileDir$) und Output paths to refresh (welche Ausgabedateien PhpStorm nach der Ausführung einlesen soll).

Die wichtigste und am häufigsten falsch konfigurierte Option ist "Trigger the watcher on external changes". Wenn aktiviert, wird der Watcher auch ausgelöst wenn eine andere Anwendung (z.B. ein anderer Watcher) eine Datei ändert – nicht nur wenn der Entwickler speichert. Das ist der häufigste Auslöser für Endlosschleifen: Watcher A ändert Datei X, Watcher B überwacht Datei X, ändert Datei Y, Watcher A überwacht Datei Y... Ein Loop entsteht.

Die Option "Auto-save edited files to trigger the watcher" bestimmt, ob der Watcher bei jedem Keystroke (mit einer kleinen Verzögerung) oder nur beim expliziten Speichern (Ctrl+S) ausgelöst wird. Für rechenintensive Operationen wie Scss-Compilation oder PHP-Formatierung sollte diese Option deaktiviert sein – der Watcher soll nur beim bewussten Speichern laufen, nicht bei jedem Tipp-Schritt.

// PhpStorm File Watcher configuration structure (exported as XML)
// Settings > Tools > File Watchers > Export

<TaskOptions>
  <option name="arguments" value="--style compressed $FileName$:$FileNameWithoutExtension$.css" />
  <option name="checkSyntaxErrors" value="true" />
  <option name="description" />
  <option name="exitCodeBehavior" value="ERROR" />
  <option name="fileExtension" value="scss" />
  <option name="immediateSync" value="false" />  <!-- Do NOT trigger on external changes -->
  <option name="name" value="SCSS -> CSS (compressed)" />
  <option name="output" value="$FileNameWithoutExtension$.css:$FileNameWithoutExtension$.css.map" />
  <option name="outputFilters">
    <array>
      <FilterInfo pattern="$FILE_PATH$:$LINE$:$COLUMN$: $MESSAGE$" />
    </array>
  </option>
  <option name="outputFromStdout" value="false" />
  <option name="program" value="$ProjectFileDir$/node_modules/.bin/sass" />
  <option name="runOnExternalChanges" value="false" /> <!-- Key: prevents loops -->
  <option name="scopeName" value="Project Files" />
  <option name="trackOnlyRoot" value="false" />
  <option name="workingDir" value="$FileDir$" />
</TaskOptions>

3. Scss/Less Watcher richtig konfigurieren

Der Scss-Watcher ist das Paradebeispiel für einen sinnvollen File Watcher: Eine Eingabedatei (style.scss) erzeugt eine Ausgabedatei (style.css). Das Datei-zu-Datei-Modell passt perfekt. PhpStorm liefert ein vorgefertigtes Template für Sass/SCSS – dieses als Ausgangspunkt nehmen und nur den Pfad zum Sass-Binary anpassen.

Wichtige Anpassungen: Das Sass-Binary muss über einen lokalen Pfad angegeben werden, nicht über ein systemweites Binary. In einem Projekt mit node_modules empfiehlt sich $ProjectFileDir$/node_modules/.bin/sass. Das Working Directory sollte auf $FileDir$ gesetzt sein, damit relative Import-Pfade in der Scss-Datei korrekt aufgelöst werden. Source-Maps (--source-map) sind für die Entwicklung sinnvoll und sollten in der Output-Pfad-Konfiguration berücksichtigt werden.

Für Magento-Projekte mit Hyvä und Tailwind CSS ist der Scss-Watcher nur für Projekte relevant, die Legacy-Scss-Dateien neben dem Tailwind-Build verwenden. Im reinen Tailwind-CSS-4-Setup (CSS-first approach) gibt es keine Scss-Dateien – hier ist der Watch-Prozess des Tailwind-Compilers die richtige Lösung, nicht ein PhpStorm File Watcher.

// Correct Scss File Watcher configuration for Magento theme
// (Only for projects that actually use Scss - not needed for pure Tailwind v4)

// Program: $ProjectFileDir$/web/node_modules/.bin/sass
// Arguments: --no-source-map --style=compressed $FileName$:$FileNameWithoutExtension$.css
// Working dir: $FileDir$
// Output: $FileNameWithoutExtension$.css

// Scope: Project Files (not "All Places" - avoids vendor/node_modules)
// "Trigger on external changes": DISABLED
// "Auto-save to trigger": DISABLED (only on explicit Ctrl+S)

// For Magento Hyvä with Tailwind CSS v4 — use Run Configuration instead:
// npm run watch --prefix app/design/frontend/Mironsoft/default/web/tailwind
// This is better than File Watcher because Tailwind scans ALL template files
// not just the single changed file — File Watcher model doesn't apply here

// Example: tailwind.config.js equivalent for CSS-first approach
// @source "../../../Magento_Theme/templates/**/*.phtml"
// @source "../../../Magento_Catalog/templates/**/*.phtml"
// Watcher can't handle this multi-file input -> use npm run watch

4. Prettier als File Watcher – wann es sinnvoll ist

Prettier als File Watcher zu konfigurieren macht in Projekten Sinn, in denen der Editor beim Speichern formatieren soll, aber kein "Format on Save" aus der IDE-Formatierung genutzt wird. Das ist typisch wenn das Team eine gemeinsame .prettierrc verwendet und sicherstellen möchte, dass jeder Commit bereits formatiert ist – ohne auf Pre-Commit-Hooks allein zu vertrauen.

PhpStorm hat seit 2022.x auch eine native Prettier-Integration ("Settings > Languages & Frameworks > JavaScript > Prettier: On save"), die als Alternative zum File Watcher funktioniert und einfacher zu konfigurieren ist. Der Unterschied: Die native Integration läuft direkt in PhpStorm, der File Watcher startet einen externen Prozess. Für Performance und Konfigurationseinfachheit ist die native Integration vorzuziehen.

Wenn Prettier als File Watcher konfiguriert wird, ist die kritische Einstellung: Output path leer lassen (Prettier überschreibt die Eingabedatei). Das bedeutet aber: Wenn Prettier eine Datei ändert und "Trigger on external changes" aktiviert ist, löst das den Watcher erneut aus (die Datei hat sich geändert) – ein Loop entsteht. Die Lösung: "Trigger on external changes" deaktivieren. Prettier läuft dann nur beim bewussten Speichern und nicht wenn die Output-Datei (= Eingabedatei, überschrieben durch Prettier) sich ändert.

5. PHP CS Fixer als File Watcher – Fallstricke kennen

PHP CS Fixer als File Watcher einzusetzen ist verlockend – aber mit mehreren Fallstricken verbunden. Der offensichtlichste: PHP CS Fixer ändert die Eingabedatei in-place. Wie bei Prettier entsteht ein Loop, wenn "Trigger on external changes" aktiviert ist. Das ist ein häufiger Fehler, weil das Template im PhpStorm-Dialog diese Option standardmäßig aktiviert hat.

Ein weniger offensichtlicher Fallstrick: PHP CS Fixer kann Änderungen im Code produzieren, die der Entwickler nicht beabsichtigt hat – etwa durch automatisches Sortieren von Use-Statements oder das Hinzufügen von declare(strict_types=1). Wenn das beim Speichern passiert, ohne dass der Entwickler es sieht, landen solche Änderungen im nächsten Commit. Das kann git-Historien verunreinigen und Diffs schwer lesbar machen.

Die bessere Alternative für PHP CS Fixer: Als Quality Tool unter "Settings > PHP > Quality Tools > PHP CS Fixer" konfigurieren, nicht als File Watcher. Dann erscheinen CS-Probleme als Inspektions-Warnungen im Editor, aber die automatische Korrektur erfolgt nur auf expliziten Benutzeraufruf (Ctrl+Alt+L oder "Apply Fix"). Das gibt dem Entwickler die Kontrolle zurück und verhindert unerwartete Änderungen.

<?php
// PHP CS Fixer — configured as Quality Tool (NOT File Watcher)
// Settings > PHP > Quality Tools > PHP CS Fixer

// .php-cs-fixer.php configuration for Magento PHP 8.4 projects
use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$finder = Finder::create()
    ->in(__DIR__ . '/src/app/code/Mironsoft')
    ->name('*.php')
    ->notPath('Test/Integration') // Skip integration tests
    ->notPath('generated');       // Never touch generated code

return (new Config())
    ->setRules([
        '@PSR12' => true,
        '@PHP84Migration' => true,
        'declare_strict_types' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
        'no_unused_imports' => true,
        'array_syntax' => ['syntax' => 'short'],
        'trailing_comma_in_multiline' => true,
        'phpdoc_order' => true,
    ])
    ->setFinder($finder)
    ->setUsingCache(true)  // Important: much faster on repeated runs
    ->setRiskyAllowed(false); // Avoid risky fixers in File Watcher context

// As Quality Tool: shows warnings inline, fix on demand
// NOT as File Watcher: avoids unintended auto-changes on save
// Pre-commit hook (git hooks / lint-staged) for CI enforcement

6. Endlosschleifen erkennen und vermeiden

Eine Endlosschleife durch File Watchers entsteht, wenn die Ausgabe eines Watchers eine Datei verändert, die einen anderen (oder denselben) Watcher auslöst. Das Symptom: Die IDE wird langsam, die CPU-Auslastung steigt permanent, im File-Watcher-Status erscheint immer wieder "Running". Im schlimmsten Fall produziert der Watcher hunderte von Log-Einträgen oder Ausgabedateien in kurzer Zeit.

Das Hauptwerkzeug zur Vermeidung: "Trigger the watcher on external changes" deaktivieren. Mit dieser Einstellung reagiert der Watcher nur auf Änderungen durch den Entwickler in PhpStorm (Speichern), nicht auf Änderungen durch externe Prozesse (andere Watcher, Editoren, Build-Tools). Ein Watcher der in-place editiert (wie Prettier oder PHP CS Fixer) kann dann nicht sich selbst neu auslösen, weil seine Ausgabe als "externe Änderung" gilt.

Ein zweites Schutzwerkzeug ist der Scope: Statt "All Places" einen eingeschränkten Scope verwenden, der nur die relevanten Quelldateien enthält – nicht node_modules/, nicht vendor/, nicht var/, nicht pub/static/. Ein Scss-Watcher der auf "All Places" konfiguriert ist, würde bei jedem npm-Build ausgelöst, weil npm CSS-Dateien in node_modules schreibt. Das ist unnötig und kann zu Loops führen.

// PhpStorm File Watcher — checklist to prevent infinite loops

// 1. "Trigger on external changes" DISABLED
//    -> Watcher only fires on developer save, not on tool output

// 2. Scope: use named scope, not "All Places"
//    Settings > Appearance & Behavior > Scopes > Add
//    Pattern: file[mironsoft-default]:src/app/design/frontend/Mironsoft/default/web/css/src//*.scss
//    Exclude: node_modules, vendor, var, pub/static, generated

// 3. For in-place formatters (Prettier, PHP CS Fixer):
//    Output paths to refresh: EMPTY (PhpStorm refreshes the input file)
//    -> PhpStorm doesn't interpret the overwritten file as "new output"
//    -> No second trigger

// 4. Use "Track only root files" for partials:
//    If style/_variables.scss changes -> don't run watcher on _variables.scss
//    Only run on style.scss (the root that imports partials)
//    Prevents N watcher runs for N partial changes

// 5. Check via Help > Diagnostic > Show Log in Explorer
//    Filter for "FileWatcher" -> shows all watcher triggers with timestamps
//    "2026-05-10 14:23:45 FileWatcher: Triggered for _variables.scss" -> too many

7. Alternativen zu File Watchers

Für viele Anwendungsfälle gibt es bessere Alternativen zu File Watchers. Format on Save in PhpStorm ("Settings > Tools > Actions on Save") führt Formatierung beim Speichern aus – direkt in der IDE, ohne externen Prozess, mit allen IDE-Formatierungsregeln. Das ist für die meisten PHP- und HTML-Formatierungsaufgaben die bessere Wahl als ein File Watcher mit PHP CS Fixer oder Prettier.

Für Build-Prozesse die mehrere Eingabedateien kombinieren (Tailwind CSS, Webpack, Rollup) sind Run Configurations besser geeignet. Eine Run Configuration startet den Build-Prozess als langlebigen Prozess (npm run watch) und zeigt seinen Output live im Run-Panel. Das ist stabiler, debugbarer und für komplexe Build-Prozesse flexibler als ein File Watcher.

Pre-Commit-Hooks (über lint-staged oder Husky) erzwingen Code-Qualität im CI-Kontext, ohne den lokalen Entwicklungsfluss zu unterbrechen. Der Entwickler schreibt Code, speichert nach Belieben, und erst beim Commit wird die Formatierung erzwungen. Das trennt Entwicklungs-Komfort von Qualitäts-Enforcement sauber. Für Teams ist das oft die robustere Lösung als File Watchers, die pro Entwickler unterschiedlich konfiguriert sein können.

8. File Watchers im Vergleich: wann sinnvoll, wann nicht

9. Zusammenfassung

File Watchers in PhpStorm sind ein mächtiges Werkzeug für klare Datei-zu-Datei-Transformationen wie Scss-Compilation – aber ein risikoreiches Werkzeug für komplexere Anwendungsfälle wie Formatierung und Multi-File-Builds. Die wichtigste Einstellung ist "Trigger on external changes" deaktivieren – das verhindert Endlosschleifen in fast allen Szenarien. Einen eingeschränkten Scope statt "All Places" zu verwenden verhindert, dass Watcher durch Build-Tool-Ausgaben in Drittanbieter-Verzeichnissen ausgelöst werden.

Für Magento-Projekte mit Hyvä und Tailwind CSS v4 sind File Watchers weniger relevant: Der Tailwind-Build ist kein 1:1-Dateitransformation, sondern scannt alle Template-Dateien – dafür ist eine Run Configuration mit npm run watch die richtige Wahl. PHP-Formatierung über PHP CS Fixer gehört als Quality Tool in die IDE oder als Pre-Commit-Hook in den Git-Workflow, nicht als File Watcher der bei jedem Speichern automatisch Änderungen am Code vornimmt. Das Ergebnis sind sauberere Git-Historien, weniger überraschende Commits und eine IDE die nicht durch Endlosschleifen gebremst wird.

10. FAQ: File Watchers in PhpStorm