PhpStorm als Zentrale für Docker- und Magento-Projekte

1. Was PhpStorm wirklich zur Zentrale macht

PhpStorm ist keine Ansammlung von Einzelfunktionen, sondern ein integriertes System. Der Schlüssel liegt darin zu verstehen, welche Teile dieses Systems bei Docker- und Magento-Projekten tatsächlich zusammenarbeiten und wie sie sich gegenseitig verstärken. Ein Remote-PHP-Interpreter, der auf den Docker-Container zeigt, ist die Grundlage für alles andere: Autocompletion mit dem richtigen PHP-Kontext, PHPUnit-Ausführung im Container, Xdebug-Sessions die funktionieren, und externe Tools die die richtige PHP-Version verwenden.

Für Magento-Projekte mit dem Mark-Shust-Docker-Setup kommt hinzu, dass die Entwicklung ausschließlich über Container-Befehle läuft. Das lokale PHP spielt keine Rolle. PhpStorm muss diese Realität abbilden, damit Autocompletion, Navigation und Debugging mit demselben PHP-Kontext arbeiten, der auch im Browser sichtbar ist. Sobald der Remote-Interpreter korrekt eingerichtet ist, ergibt sich vieles von selbst: PhpStorm erkennt den PHP-Kontext, Xdebug-Konfiguration zeigt automatisch die richtigen Optionen, und Run Configurations nutzen den Container-PHP.

Die Grenze von PhpStorm liegt dort, wo Docker-Orchestrierung komplexer wird. Docker-Compose mit vielen Services starten, Logs aus mehreren Containern gleichzeitig beobachten, Build-Prozesse steuern – das bleibt effizienter im Terminal. PhpStorm ergänzt den Terminal-Workflow, ersetzt ihn nicht vollständig.

2. Remote-PHP-Interpreter für Docker einrichten

Der Remote-PHP-Interpreter ist die wichtigste Einstellung für Docker-basierte PHP-Projekte in PhpStorm. Er verbindet PhpStorm mit dem PHP im Container und ermöglicht, dass alle IDE-Funktionen mit dem richtigen PHP-Kontext arbeiten. Die Einrichtung erfolgt unter Settings → PHP, wo man bei "CLI Interpreter" ein neues Profil anlegen kann.

Für das Mark-Shust-Setup wählt man als Interpreter-Typ "Docker Compose" und wählt die entsprechende compose.yaml aus. PhpStorm startet dann für Analysen und Werkzeugaufrufe den PHP-Container. Alternativ kann man einen SSH-Tunnel zum Container nutzen oder den Interpreter direkt über den Docker-Socket verbinden. Wichtig: die PHP-Version im Remote-Interpreter muss mit der im Container übereinstimmen – bei PHP 8.4 mit strikten Typen ist das besonders relevant, weil PhpStorm sonst falsche Typ-Fehler anzeigt.

# compose.yaml (Mark Shust Setup) — relevanter phpfpm-Service
services:
  phpfpm:
    image: markoshust/magento-php:8.4-fpm-0
    volumes:
      # Lokales src/ wird unter /var/www/html im Container gemountet
      - ./src:/var/www/html:cached
      - ~/.composer:/var/www/.composer:cached
      - ~/.ssh/id_rsa:/var/www/.ssh/id_rsa:cached
    environment:
      XDEBUG_MODE: "${XDEBUG_MODE:-off}"
      XDEBUG_CLIENT_HOST: "${XDEBUG_CLIENT_HOST:-host.docker.internal}"
      XDEBUG_CLIENT_PORT: "9003"
    extra_hosts:
      - "host.docker.internal:host-gateway"

# PhpStorm Remote-Interpreter Konfiguration:
# Server: Docker Compose
# Configuration files: ./compose.yaml
# Service: phpfpm
# Path mappings: ./src → /var/www/html

Nach der Einrichtung des Remote-Interpreters erscheint in PhpStorm unter der PHP-Version ein Symbol, das den Verbindungsstatus anzeigt. Ein Klick auf "Refresh" synchronisiert die installierten PHP-Erweiterungen und aktivierten Module. So weiß PhpStorm, welche Funktionen und Klassen im Container verfügbar sind – inklusive Magento-spezifischer Autoloader-Informationen.

3. Xdebug im Docker-Container mit PhpStorm verbinden

Xdebug im Container ist oft der erste Stolperstein bei Docker-basierten PhpStorm-Setups. Das grundlegende Prinzip: Xdebug im Container verbindet sich aktiv zu PhpStorm auf dem Host (nicht umgekehrt). PhpStorm lauscht auf Port 9003, Xdebug kennt die Host-Adresse über host.docker.internal und stellt die Verbindung her, sobald eine Debug-Session startet.

Mit dem Mark-Shust-Setup ist Xdebug bereits vorkonfiguriert. Das Skript bin/xdebug enable setzt die Umgebungsvariable XDEBUG_MODE=debug und startet den PHP-Container neu. In PhpStorm reicht es, unter Run → Start Listening for PHP Debug Connections zu aktivieren. Breakpoints in PhpStorm werden dann bei der nächsten HTTP-Anfrage erreicht. Wichtig: die Path Mappings müssen korrekt sein, damit PhpStorm die Container-Pfade auf lokale Dateien abbilden kann.

# Xdebug-Konfiguration im Container (automatisch durch Mark Shust Setup)
# /usr/local/etc/php/conf.d/xdebug.ini

[xdebug]
zend_extension=xdebug

; debug = Breakpoints, remote_autostart
; coverage = Code Coverage für PHPUnit
; profile = Profiling (nie im Dev-Betrieb aktiv lassen)
xdebug.mode=debug

; Container verbindet sich aktiv zum Host
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

; Session-ID für Browser-Trigger (XDEBUG_SESSION Cookie)
xdebug.idekey=PHPSTORM

; Start Debug-Session ohne Browser-Trigger (für CLI-Debugging)
; xdebug.start_with_request=yes  ← nur für bin/debug-cli aktivieren

; Log für Verbindungsprobleme
xdebug.log=/tmp/xdebug.log
xdebug.log_level=3

Für CLI-Debugging – zum Beispiel Magento-Migrations oder Konsolenbefehle debuggen – nutzt man bin/debug-cli enable, das XDEBUG_SESSION=PHPSTORM als Umgebungsvariable setzt. Damit startet Xdebug bei jedem CLI-PHP-Aufruf automatisch eine Debug-Session, ohne dass ein Browser-Cookie gesetzt werden muss. In PhpStorm muss dann ebenfalls "Listen" aktiv sein.

4. Magento-CLI-Befehle aus PhpStorm starten

Magento-CLI-Befehle aus PhpStorm zu starten spart Kontextwechsel. Über Run Configurations (Typ "Shell Script") kann man beliebige Wrapper-Skripte aus dem bin/-Verzeichnis einbinden. Nützliche Konfigurationen: bin/magento cache:flush auf einem Shortcut, bin/magento setup:upgrade als dedizierter Run-Task, oder ein kombinierter Task der CSS-Build, Static-Deploy und Cache-Flush hintereinander ausführt.

Eine Compound Run Configuration ermöglicht, mehrere dieser Tasks in einer Konfiguration zu bündeln und mit einem einzigen Klick zu starten. Das ist besonders nützlich für den Deploy-Workflow: CSS bauen, Static Files löschen, Static Content deployen, Cache leeren – alles in einem Schritt aus PhpStorm heraus.

#!/usr/bin/env bash
# Beispiel: Compound-Deploy-Skript als Run Configuration
# Script path: bin/deploy-dev
# PhpStorm: Run → Edit Configurations → + → Shell Script

set -euo pipefail

# 1. CSS neu bauen (Tailwind v4)
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run build

# 2. Static Files löschen — immer zuerst!
cd src && rm -rf var/view_preprocessed/* pub/static/frontend/*
cd ..

# 3. Static Content deployen
bin/magento setup:static-content:deploy de_DE \
    -t Mironsoft/default \
    --jobs=4 \
    -f

# 4. Cache leeren
bin/magento cache:flush

echo "Deploy abgeschlossen."

Für häufig verwendete einzelne Magento-Befehle lohnt sich die Konfiguration unter Settings → Tools → External Tools statt als Run Configuration – externe Tools können direkt im Kontextmenü angezeigt werden und sind sofort verfügbar, ohne die Run-Configuration-Auswahl öffnen zu müssen.

5. Path Mappings: Container-Pfade und lokale Pfade abbilden

Path Mappings sind die Brücke zwischen dem lokalen Dateisystem und dem Container. PhpStorm muss wissen, dass /var/www/html/app/code/Vendor/Module/Model/Foo.php im Container identisch ist mit /home/mir/development/mironsoft/src/app/code/Vendor/Module/Model/Foo.php lokal. Ohne diese Zuordnung funktioniert Xdebug: Breakpoints werden nicht erkannt, weil PhpStorm die Dateipfade aus Xdebug-Nachrichten nicht auflösen kann.

Path Mappings konfiguriert man an mehreren Stellen in PhpStorm: im Remote-Interpreter (für Autocompletion-Kontext), im Xdebug-Server unter Settings → PHP → Servers (für Breakpoints), und in den Run Configurations für PHPUnit (für Test-Ausführung). Alle drei Stellen müssen konsistent konfiguriert sein. Im Mark-Shust-Setup ist die Grundregel einfach: lokales ./src entspricht Container-Pfad /var/www/html.

6. Docker-Compose-Services aus PhpStorm steuern

PhpStorm erkennt compose.yaml-Dateien automatisch und bietet einen Services-Tab im Tool-Window, der den Status aller Services anzeigt. Von dort aus lassen sich einzelne Services starten, stoppen und neu starten, ohne das Terminal zu öffnen. Für den täglichen Workflow mit Magento reicht das für einfache Operationen wie den Nginx- oder phpfpm-Neustart nach Konfigurationsänderungen.

Der echte Mehrwert liegt aber im Services-Window für Logs: Jeder Container-Service hat einen eigenen Log-Stream, der direkt in PhpStorm angezeigt wird. So kann man während der Entwicklung den phpfpm-Log und den Nginx-Log gleichzeitig im Blick haben, ohne zwei Terminal-Tabs zu öffnen. Bei Magento-Fehlern der Art "502 Bad Gateway" sieht man sofort im phpfpm-Log, was die eigentliche Ursache ist.

7. Container-Logs direkt in PhpStorm verfolgen

Container-Logs und Magento-eigene Logs können beide direkt in PhpStorm angezeigt werden. Für Container-Logs nutzt man das Services-Window. Für Magento-Logs (var/log/exception.log, var/log/system.log) eignen sich Run Configurations vom Typ "Shell Script" mit dem Befehl bin/log exception.log. Alternativ gibt es eine Log-Viewer-Konfiguration unter Run Configuration → Logs, die bestimmte Dateien im Projekt beobachtet und bei Änderungen automatisch aktualisiert.

Besonders nützlich: Im Run-Window kann man einen Magento-Befehl und gleichzeitig den Log-Viewer aktiv haben. So sieht man beim Ausführen von bin/magento setup:upgrade sofort, wenn Fehler in der exception.log auftauchen – ohne manuell zwischen Terminal und Log zu wechseln.

8. Was besser im Terminal bleibt

PhpStorm ist kein vollständiger Ersatz für das Terminal. Bestimmte Workflows sind im Terminal schneller und effizienter. Dazu gehören: komplexe Docker-Compose-Operationen mit mehreren Flags, das initiale Setup einer Magento-Umgebung (bin/setup), Composer-Operationen (bin/composer install, bin/composer update), SSH-Verbindungen in den Container (bin/bash) für interaktive Debugging-Sessions, und Build-Prozesse die viele Ausgaben erzeugen und bei denen man den vollständigen Scroll-Verlauf braucht.

Das integrierte Terminal in PhpStorm (View → Tool Windows → Terminal) bietet einen guten Mittelweg: Man bleibt in PhpStorm, hat aber ein vollständiges Terminal mit dem Arbeitsverzeichnis des Projekts. Für die meisten täglichen Magento-Operationen ist das ausreichend, ohne extra Fenster zu wechseln.

9. Vergleich: PhpStorm-Integration vs. Terminal-Workflow

Die Entscheidung, was in PhpStorm und was im Terminal erledigt wird, hängt von der Häufigkeit und Komplexität der Operation ab. Die folgende Tabelle zeigt die Aufteilung für den typischen Magento-Entwicklungsworkflow.

Der produktivste Workflow kombiniert beide Ansätze: PhpStorm als Zentrale für Autocompletion, Debugging und häufige Befehle, das integrierte Terminal für alles andere. Wer versucht, alles in PhpStorm abzubilden, kämpft gegen die IDE – wer das Terminal komplett ignoriert, verzichtet auf Geschwindigkeit bei komplexen Operationen.

10. Zusammenfassung

PhpStorm wird zur echten Zentrale für Docker- und Magento-Projekte, wenn der Remote-PHP-Interpreter korrekt konfiguriert ist. Alles andere – Xdebug-Integration, PHPUnit im Container, externe Tool-Aufrufe mit dem richtigen PHP – baut darauf auf. Xdebug im Container funktioniert zuverlässig mit dem Mark-Shust-Setup, sobald Path Mappings und der Listener in PhpStorm korrekt konfiguriert sind. Magento-CLI-Befehle als Run Configurations und externe Tools sparen Kontextwechsel beim täglichen Arbeiten.

Die wichtigste Erkenntnis: PhpStorm ersetzt das Terminal nicht, sondern ergänzt es. Debugging, Autocompletion, Code-Navigation und häufige Befehle profitieren von der IDE-Integration. Komplexe Docker-Operationen, Composer und interaktive Shell-Sessions bleiben effizienter im Terminal. Wer diese Grenze kennt, nutzt beide Werkzeuge optimal.

11. FAQ: PhpStorm als Zentrale für Docker und Magento