Produktive PHPStorm-Checkliste für Docker, Magento und PHP-Projekte

1. Warum eine Checkliste für PHPStorm?

PHPStorm ist eines der mächtigsten IDEs für PHP-Entwicklung, entfaltet seinen vollen Nutzen aber nur mit der richtigen Konfiguration. In Docker-basierten Projekten – besonders bei Magento 2 – gibt es zahlreiche Stellen, an denen eine falsche oder fehlende Einstellung die Produktivität massiv reduziert. Autocomplete funktioniert nicht, weil der Interpreter lokal statt im Container zeigt. Xdebug startet nicht, weil der Port blockiert ist. Die IDE wird langsam, weil Tausende Vendor-Dateien unnötig indexiert werden.

Diese Checkliste bündelt alle kritischen Einstellungen in der Reihenfolge, die für ein Docker-Magento-Projekt am meisten bringt. Sie ist nicht als einmaliger Setup-Guide gedacht, sondern als Referenz, die man bei jedem neuen Projektsetup oder neuen Teammitglied durchgeht. Jeder Punkt wird mit dem konkreten PHPStorm-Pfad und der Einstellung angegeben, damit kein Raten nötig ist.

2. PHP-Interpreter: Remote vs. lokal korrekt konfigurieren

Der wichtigste Punkt auf jeder PHPStorm-Checkliste für Docker-Projekte ist der PHP-Interpreter. PHPStorm braucht den Interpreter für Autocomplete, Type Inference, Static Analysis und Run Configurations. In einem Docker-Setup gibt es zwei sinnvolle Ansätze: entweder einen Docker-basierten Interpreter, der direkt im Container läuft, oder einen SSH-basierten Remote-Interpreter für komplexere Setups.

Für Mark-Shust-Docker-Setups ist der Docker-Compose-Interpreter die empfohlene Variante. Der Pfad dorthin: Settings → PHP → CLI Interpreter → + → From Docker, Vagrant, VM, WSL, Remote.... Server: Docker Compose, Konfigurationsdatei: compose.yaml, Service: phpfpm. PHPStorm startet dann einen temporären Container, um die PHP-Version und Extensions zu ermitteln. Danach stehen alle Autocomplete-Informationen basierend auf dem tatsächlichen Container-PHP zur Verfügung – nicht basierend auf dem lokalen PHP, das eine andere Version oder andere Extensions haben kann.

<?php
// PHPStorm path mapping check — verify container path resolution
// Settings → PHP → CLI Interpreter → Remote → Path Mappings

// Local:     /home/mir/development/mironsoft/src
// Container: /var/www/html

// Test: create a simple PHP file and check if PHPStorm resolves
// the path correctly when Xdebug hits a breakpoint

declare(strict_types=1);

// If autocomplete works for this class, interpreter is correct
$objectManager = \Magento\Framework\App\ObjectManager::getInstance();

// PHPStorm should show full type info for $objectManager
// if vendor/ is indexed and interpreter points to container

Ein häufiger Fehler auf der Checkliste: Path Mappings werden vergessen. PHPStorm muss wissen, dass /home/mir/development/mironsoft/src lokal dem Container-Pfad /var/www/html entspricht. Ohne diese Mappings funktioniert Xdebug, aber PHPStorm öffnet keine lokalen Dateien beim Halt an einem Breakpoint. Die Mappings werden im Interpreter-Dialog unter "Path Mappings" konfiguriert und sollten für alle relevanten Verzeichnisse angelegt sein.

3. Indexing: Vendor und Generated sinnvoll ausschließen

Das größte Performance-Problem in PHPStorm mit Magento 2 ist das Indexing. Magento hat einen massiven vendor/-Ordner und generiert außerdem Code in generated/. Ohne Ausschlüsse versucht PHPStorm, alles zu indexieren – was bei Magento 2 mehrere Gigabyte PHP-Code bedeutet. Das Ergebnis: eine träge IDE, lange Startup-Zeiten und ein überhitzter Laptop.

Die Checkliste für Indexing-Ausschlüsse bei Magento 2: Settings → Project → Directories. Folgende Verzeichnisse als "Excluded" markieren: var/, pub/static/, generated/, pub/media/. Der Ordner vendor/ sollte nicht vollständig ausgeschlossen werden – PHPStorm braucht ihn für Autocomplete. Aber vendor/magento/framework/generated/ und ähnliche generierte Unterordner können ausgeschlossen werden. Alternativ: vendor/ als "Library Root" markieren, nicht als "Source Root", dann wird er für Autocomplete genutzt aber nicht so aggressiv analysiert.

<?php
// .idea/mironsoft.iml — PHPStorm project structure
// Directories excluded from indexing (XML configuration)

/*
<component name="NewModuleRootManager">
  <content url="file://$MODULE_DIR$">
    <sourceFolder url="file://$MODULE_DIR$/src/app/code" isTestSource="false" />
    <excludeFolder url="file://$MODULE_DIR$/src/var" />
    <excludeFolder url="file://$MODULE_DIR$/src/pub/static" />
    <excludeFolder url="file://$MODULE_DIR$/src/pub/media" />
    <excludeFolder url="file://$MODULE_DIR$/src/generated" />
  </content>
</component>
*/

// Also exclude in Settings → Editor → File Types → Ignore files and folders:
// Add: *.min.js, *.min.css, node_modules, .git (already excluded by default)

// Memory settings: Help → Change Memory Settings
// Recommended for Magento: 4096 MB heap

4. Xdebug mit Docker stabil konfigurieren

Xdebug ist auf der Checkliste jedes PHP-Entwicklers, aber die Konfiguration mit Docker hat spezifische Tücken. Das häufigste Problem: Xdebug im Container kann die IDE auf dem Host nicht erreichen, weil die Docker-Netzwerkkonfiguration den Hostname nicht auflöst. Unter Linux ist der Host vom Container aus über die Docker-Gateway-IP erreichbar, unter macOS und Windows funktioniert host.docker.internal. Unter Linux muss man explizit die Gateway-IP ermitteln oder host.docker.internal über extra_hosts in der Compose-Datei definieren.

Die vollständige Xdebug-Checkliste für Docker: Zunächst in der Container-Konfiguration xdebug.client_host auf die korrekte Host-IP setzen. Dann in PHPStorm unter Settings → PHP → Debug den Port auf 9003 setzen (Xdebug 3). Unter Settings → PHP → Servers einen Server mit dem korrekten Hostnamen und Path Mappings anlegen. Den Debug-Listen-Button in PHPStorm aktivieren (Telefon-Icon in der Toolbar). Danach in der Entwicklungsumgebung eine Anfrage mit dem Xdebug-Cookie oder IDE-Key triggern.

<?php
// docker/phpfpm/xdebug.ini — Xdebug 3 configuration for Docker
/*
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
xdebug.idekey=PHPSTORM
xdebug.log_level=0
xdebug.max_nesting_level=512

; For Linux: use host-gateway instead of host.docker.internal
; Add to compose.yaml under phpfpm service:
; extra_hosts:
;   - "host.docker.internal:host-gateway"
*/

// PHPStorm Settings → PHP → Debug:
// Debug port: 9003
// Check: "Can accept external connections"

// PHPStorm Settings → PHP → Servers:
// Name: mironsoft-docker
// Host: localhost
// Port: 80
// Debugger: Xdebug
// Path Mapping: /home/mir/development/mironsoft/src → /var/www/html

5. Run Configurations für Magento CLI und PHPUnit

Run Configurations sind auf der PHPStorm-Checkliste oft unterschätzt. Statt Befehle immer im Terminal einzutippen, ermöglichen Run Configurations einen Klick-Start für häufige Aufgaben: Magento-Cache leeren, Setup-Upgrade ausführen, Tests starten. In Docker-Projekten verwendet man dafür "Shell Script"-Run-Configurations, die die Wrapper-Skripte im bin/-Verzeichnis aufrufen, oder PHP-Run-Configurations mit dem Remote-Interpreter.

Für PHPUnit in Docker die Checkliste: Run → Edit Configurations → + → PHPUnit. Test Runner: PHPUnit via Composer. Interpreter: der Docker-Compose-Interpreter. Konfigurationsdatei: src/dev/tests/unit/phpunit.xml. Working Directory: /var/www/html (Container-Pfad). Nach dem ersten Start speichert PHPStorm die Konfiguration, sodass künftige Runs über die Run-Leiste oder mit Shift+F10 starten. Für einzelne Testklassen kann man direkt aus dem Editor-Kontextmenü "Run ..." aufrufen.

<?php
// .idea/runConfigurations/Magento_Cache_Flush.xml
/*
<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Magento: Cache Flush"
                 type="ShellScriptRunConfigurationType">
    <option name="SCRIPT_PATH" value="$PROJECT_DIR$/bin/magento" />
    <option name="SCRIPT_PARAMETERS" value="cache:flush" />
    <option name="INTERPRETER_PATH" value="/usr/bin/env" />
    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
  </configuration>
</component>
*/

// Useful Run Configurations for Magento 2:
// 1. bin/magento cache:flush
// 2. bin/magento setup:upgrade --keep-generated
// 3. bin/magento setup:di:compile
// 4. PHPUnit — Unit Tests
// 5. PHPUnit — Integration Tests (separate config)
// 6. bin/phpcs app/code/
// 7. bin/phpstan analyse app/code/

6. Plugins: was wirklich hilft und was bremst

Auf der PHPStorm-Checkliste für Plugins gilt: weniger ist mehr. Jedes Plugin, das aktiv ist, ohne genutzt zu werden, belastet den Indexing-Prozess und verlangsamt die IDE. Die erste Aufgabe ist daher, alle vorinstallierten Plugins zu deaktivieren, die im Projekt nicht benötigt werden: CVS, Subversion, Mercurial (wenn nur Git genutzt wird), CoffeeScript, Haml, Stylus, und ähnliche.

Für PHP-Docker-Magento-Projekte wirklich nützliche Plugins: PHP Annotations (Autocomplete für Magento DI-Annotations), Symfony Support (gibt es auch für Magento DI, da die Prinzipien ähnlich sind), GitToolBox (Inline-Git-Blame), .env files support. Optional: PHPStan für PHPStorm, wenn PHPStan nicht über External Tools laufen soll. Nicht empfehlenswert für Magento: Magento-spezifische Plugins, die oft nicht mehr gepflegt werden und Kompatibilitätsprobleme erzeugen. PHPStorm's nativer Indexer kommt in der Regel mit Magento-Strukturen gut zurecht.

7. Code Style, EditorConfig und Inspections

Code Style in PHPStorm ist auf der Checkliste wichtig für Teamkonsistenz. PHPStorm liest .editorconfig-Dateien automatisch und übernimmt die dort definierten Einstellungen für Einrückung, Zeilenenden und Encoding. Für Magento 2-Projekte: 4 Spaces Einrückung, UTF-8, Unix-Zeilenenden. Die .editorconfig liegt im Projektstamm und wird von PHPStorm ohne zusätzliche Konfiguration gelesen, sobald das EditorConfig-Plugin aktiv ist (standardmäßig aktiviert).

Inspections konfiguriert man unter Settings → Editor → Inspections → PHP. Für produktive Arbeit empfiehlt sich: alle PHPStan- und PHP-CS-Fixer-Inspections auf "Warning" setzen statt "Error", damit der Editor nicht rot wird, wenn PHPStan eine Warnung ausgibt. Die echte Qualitätsprüfung läuft dann über External Tools oder Run Configurations, nicht als Live-Inspektion. Das reduziert das "Warning-Rauschen" erheblich und macht den Editor wieder angenehm benutzbar.

8. Checkliste im Vergleich: häufige Fehler vs. Best Practice

9. Zusammenfassung

Eine produktive PHPStorm-Umgebung für Docker-, Magento- und PHP-Projekte entsteht nicht durch Standardinstallation, sondern durch systematisches Durcharbeiten der Checkliste. Der Remote-Interpreter auf Basis von Docker Compose stellt sicher, dass Autocomplete und Type Inference auf dem tatsächlichen Container-PHP basieren. Korrekte Indexing-Ausschlüsse verhindern, dass PHPStorm an Magento's Vendor-Masse scheitert. Xdebug mit korrektem client_host und Path Mappings macht Debugging zuverlässig. Run Configurations ersetzen wiederholtes Tippen im Terminal.

10. FAQ: PHPStorm-Checkliste für Docker, Magento und PHP