PHPStorm und Docker Compose: Mehrere Services richtig anbinden

1. Warum die IDE-Integration mehr als ein Interpreter-Pfad ist

Viele Entwickler konfigurieren ihren Docker-Compose-basierten PHP-Interpreter in PHPStorm, stellen fest, dass die grundlegende Syntaxprüfung funktioniert – und belassen es dabei. Das verschenkt einen erheblichen Teil des Mehrwerts, den PHPStorm in containerisierten Projekten bieten kann. Eine vollständige Integration bedeutet: der Debugger pausiert an Breakpoints im Container, Datenbankabfragen laufen direkt aus der IDE, Composer-Befehle werden im richtigen Container-Kontext ausgeführt, und PHPUnit-Tests laufen mit Coverage-Analyse, ohne dass ein Terminal geöffnet werden muss.

Der Aufwand, all das einzurichten, ist einmalig pro Projekt – danach arbeitet das gesamte Team mit identischer IDE-Konfiguration, sofern die PHPStorm-Einstellungen im Repository mit versioniert werden. Gerade in Magento-Projekten mit Mark-Shust-Docker-Setup, wo Interpreter, CLI-Tools und Datenbank auf getrennten Services laufen, lohnt sich die vollständige Konfiguration doppelt: kein manuelles Wechseln zwischen Terminal und IDE mehr, kein Raten über Werte in der Datenbank.

2. Das Docker-Compose-Setup: Voraussetzungen schaffen

Bevor PHPStorm überhaupt einen Container anbinden kann, müssen einige Voraussetzungen im Compose-Setup erfüllt sein. Der PHP-Container braucht installierte Xdebug-Extension und eine korrekte xdebug.ini. Der MySQL-Container muss einen exponierten Port haben, über den PHPStorm die Datasource erreicht. Bei Mark-Shust-Setup ist der PHP-Container typischerweise als Service phpfpm definiert, der MySQL-Container als db mit Port 3306 auf Host-Port 3306 gemappt.

Wichtig: PHPStorm kommuniziert mit dem Container-Interpreter nicht über Docker-Netzwerke, sondern über den Docker-Daemon via Unix Socket oder TCP. Der Daemon muss in PHPStorm unter Settings → Build, Execution, Deployment → Docker eingetragen sein. Auf Linux zeigt der Pfad auf /var/run/docker.sock, auf macOS auf den Docker Desktop Socket. Ohne diese Grundkonfiguration erscheint kein einziger Container im Interpreter-Dialog.

# docker-compose.yml — relevant excerpt for PHPStorm integration
services:
  phpfpm:
    build: .docker/phpfpm
    volumes:
      - ./src:/var/www/html:cached
      # Composer cache for performance
      - ~/.composer:/var/www/.composer:cached
    environment:
      XDEBUG_MODE: "debug,develop"
      XDEBUG_CONFIG: "client_host=host-gateway idekey=PHPSTORM"
    extra_hosts:
      - "host-gateway:host-gateway"

  db:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD}"
      MYSQL_DATABASE: "${MYSQL_DATABASE}"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Der Eintrag extra_hosts: host-gateway:host-gateway ist entscheidend für Xdebug auf Linux: Der Container muss die IP des Host-Rechners kennen, um die Debugger-Verbindung zurück zu PHPStorm aufzubauen. Auf macOS funktioniert host.docker.internal als Hostname direkt. Die Umgebungsvariable XDEBUG_CONFIG mit client_host=host-gateway sorgt dafür, dass Xdebug die Verbindung zum richtigen Host aufbaut – ohne diese Einstellung läuft der Debugger im Leerlauf.

3. Remote PHP-Interpreter in PHPStorm einrichten

Der Remote-Interpreter wird in PHPStorm unter Settings → PHP → CLI Interpreter angelegt. Klick auf das Plus-Symbol, dann From Docker, Vagrant, VM, WSL, Remote auswählen. Im Dialog erscheint die Auswahlmöglichkeit zwischen Docker und Docker Compose. Für Compose-Projekte wählt man Docker Compose, trägt die compose.yaml-Datei ein und wählt den Service phpfpm. PHPStorm startet dann den Container kurz, liest die PHP-Version und die Extension-Liste aus und zeigt sie im Dialog an.

Nach dem Anlegen des Interpreters muss unter Settings → PHP das PHP-Language-Level auf die im Container installierte Version gesetzt werden – zum Beispiel PHP 8.4. Damit aktiviert PHPStorm die korrekten Syntax-Checks und Code-Completion für die tatsächliche Laufzeitumgebung. Wer hier die falsche Version wählt, bekommt falsche Deprecation-Warnungen oder vermisst neue PHP 8.x-Features in der Autovervollständigung.

4. Xdebug im Container konfigurieren und mit PHPStorm verbinden

Die Xdebug-Konfiguration im Container muss auf den richtigen Listening-Port von PHPStorm zeigen. Standardmäßig hört PHPStorm auf Port 9003. Die xdebug.ini im PHP-Container setzt xdebug.client_port=9003, xdebug.mode=debug und xdebug.start_with_request=yes für Always-On-Debugging oder trigger für Cookie-basiertes Debugging. In PHPStorm unter Settings → PHP → Debug muss Port 9003 eingetragen sein und Xdebug als Debugger-Extension gewählt sein.

Der häufigste Fehler: PHPStorm zeigt "Waiting for incoming connection", aber der Debugger verbindet sich nicht. Ursache ist fast immer der falsche client_host-Wert in der Xdebug-Konfiguration. Auf Linux muss die tatsächliche Host-IP eingetragen werden oder host-gateway (wenn im Compose-File als extra_host definiert). Ein schneller Test: docker exec phpfpm php -r "var_dump(ini_get('xdebug.client_host'));" zeigt den aktuellen Wert direkt. Der Validation-Dialog unter Settings → PHP → Debug → Validate führt automatisch durch die häufigsten Diagnose-Schritte.

; .docker/phpfpm/xdebug.ini — Xdebug 3 configuration for Docker Compose
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug,develop
; Port PHPStorm listens on (default 9003 for Xdebug 3)
xdebug.client_port=9003
; On Linux: use host-gateway (mapped in compose extra_hosts)
; On macOS: use host.docker.internal
xdebug.client_host=host-gateway
; trigger = only debug when XDEBUG_TRIGGER cookie/env is set
; yes = always debug (useful during development, off in CI)
xdebug.start_with_request=trigger
xdebug.idekey=PHPSTORM
; Log to diagnose connection issues
xdebug.log=/tmp/xdebug.log
xdebug.log_level=3
; Coverage for PHPUnit
xdebug.mode=debug,develop,coverage

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

Path Mappings sind das Bindeglied zwischen lokalem Dateisystem und dem Container-Dateisystem. Ohne korrektes Mapping weiß PHPStorm nicht, dass /var/www/html/app/code/Mironsoft im Container der lokalen Datei ./src/app/code/Mironsoft entspricht. Wenn Xdebug eine Datei meldet und PHPStorm das Mapping nicht kennt, wird kein Breakpoint gesetzt und die IDE zeigt nur eine leere Datei. Path Mappings werden im Interpreter-Dialog unter Path Mappings eingetragen: links der absolute lokale Pfad, rechts der absolute Container-Pfad.

Bei Mark-Shust-Setup mit Volume-Mount ./src:/var/www/html lautet das Mapping: lokaler Pfad /home/user/project/src → Container-Pfad /var/www/html. Wichtig: der lokale Pfad muss absolut sein, kein Tilde-Pfad. PHPStorm speichert die Path Mappings in .idea/workspace.xml – diese Datei sollte nicht ins Repository commitet werden, da absolute Pfade entwicklerspezifisch sind. Stattdessen die Mappings über .idea/php.xml mit relativen Angaben teilen, was PHPStorm ab Version 2023.1 unterstützt.

6. Datenbank-Datasource für den MySQL-Container anlegen

PHPStorm bietet einen vollständigen Datenbank-Client, der direkt mit dem MySQL-Container kommuniziert. Die Datasource wird unter Database → + → Data Source → MySQL angelegt. Als Host trägt man localhost ein, Port 3306 (der auf dem Host exponierte Port), Datenbankname, Username und Passwort aus der .env-Datei. PHPStorm lädt automatisch den JDBC-Treiber herunter, wenn er noch nicht vorhanden ist.

Nach dem Verbindungsaufbau erscheint die gesamte Datenbankstruktur im Database-Panel: alle Tabellen, Views, Stored Procedures und Indizes mit Typen und Constraints. SQL-Dateien in PHPStorm erhalten automatisch Code-Completion für Tabellen- und Spaltennamen dieser Datasource. Das ist besonders nützlich bei Magento-Projekten, wo die Datenbankstruktur aus hunderten Tabellen besteht – Autocomplete für catalog_product_entity-Spalten spart erhebliche Recherchezeit. Die Datasource-Konfiguration (ohne Passwort) kann über .idea/dataSources.xml mit dem Team geteilt werden.

7. Composer und CLI-Interpreter für Run-Konfigurationen

Composer-Befehle sollen im PHP-Container laufen, nicht im lokalen System – das ist der Kern des containerisierten Workflows. PHPStorm kann Composer direkt im Container ausführen: unter Settings → PHP → Composer wählt man den Remote-Interpreter aus und trägt den Pfad zur Composer-PHAR im Container ein (/usr/local/bin/composer). Danach führt Tools → Composer → Install den Befehl im Container aus, sieht das Ergebnis im IDE-Output und aktualisiert die vendor-Verzeichnis-Indexierung automatisch.

Run-Konfigurationen für PHPUnit, PHPStan und andere CLI-Tools werden ebenfalls auf den Remote-Interpreter gesetzt. Unter Run → Edit Configurations → PHP Script wählt man den Container-Interpreter, trägt das Skript ein und setzt Umgebungsvariablen. So kann man zum Beispiel bin/magento cache:flush direkt aus PHPStorm starten, den Output im Run-Panel sehen und bei Fehler direkt zum betroffenen Code springen – alles ohne Terminal.

<?php
// .idea/php.xml — PHPStorm project settings (commit this, no absolute paths)
// This XML is maintained by PHPStorm; shown here for illustration only.
// Key sections to configure via UI, reflected here:

/*
<component name="PhpProjectSharedConfiguration">
  <option name="phpLanguageLevel" value="8.4" />
</component>

<component name="PhpInterpreters">
  <interpreters>
    <interpreter id="docker-compose-phpfpm"
                 name="Docker Compose: phpfpm"
                 home="docker-compose://[path/to/compose.yaml]:phpfpm/usr/bin/php">
      <path_mappings>
        <mapping local-root="$PROJECT_DIR$/src"
                 remote-root="/var/www/html" />
      </path_mappings>
    </interpreter>
  </interpreters>
</component>
*/

// Verify interpreter connection from PHPStorm Terminal:
// docker exec phpfpm php --version
// docker exec phpfpm php -m | grep xdebug

8. Konfigurationsvarianten im Vergleich

Es gibt verschiedene Wege, PHPStorm mit Docker zu verbinden – jeder mit eigenen Stärken je nach Projektgröße und Teamgröße. Die Wahl der richtigen Variante beeinflusst nicht nur die initiale Einrichtungszeit, sondern auch die tägliche Arbeitsgeschwindigkeit und wie gut sich die Konfiguration ins Team verbreiten lässt.

Für Magento-Projekte mit Mark-Shust-Docker-Setup ist die Docker-Compose-Variante klar die beste Wahl. Sie bildet das tatsächliche Service-Netzwerk ab, erlaubt PHPStorm den Zugriff auf alle Dienste und stellt sicher, dass der Interpreter dieselbe PHP-Version und dieselben Extensions verwendet wie die Produktionsumgebung. Der initiale Einrichtungsaufwand von etwa 30 Minuten amortisiert sich bereits in der ersten Debugging-Session.

9. Häufige Probleme und wie man sie behebt

Das häufigste Problem nach der Einrichtung: Xdebug verbindet sich nicht, obwohl alles korrekt konfiguriert scheint. Checkliste: (1) Ist der Xdebug-Listener in PHPStorm aktiv (grünes Telefon-Icon)? (2) Ist Port 9003 in der Firewall des Host-Systems geöffnet? Auf Linux kann sudo ufw allow 9003 helfen. (3) Stimmt der client_host-Wert in der xdebug.ini? (4) Ist XDEBUG_TRIGGER als Cookie oder Environment-Variable gesetzt, wenn start_with_request=trigger aktiv ist?

Ein weiteres häufiges Problem: PHPStorm findet die Breakpoint-Dateien nicht, weil Path Mappings fehlen oder falsch sind. Der einfachste Diagnose-Weg: im Xdebug-Log (/tmp/xdebug.log im Container) steht, welche Dateipfade Xdebug meldet. Diese Container-Pfade müssen exakt in der rechten Spalte der Path Mappings eingetragen sein. Ein Tipp für Magento: Das Magento-Root (/var/www/html) als einziges Mapping einzutragen reicht aus – PHPStorm leitet alle Unterpfade automatisch ab.

<?php
// Diagnostic commands — run in terminal to verify Docker/PHPStorm integration

// 1. Verify Xdebug is loaded in the container
// docker exec phpfpm php -m | grep -i xdebug

// 2. Check Xdebug config values
// docker exec phpfpm php -r "
//   echo 'client_host: ' . ini_get('xdebug.client_host') . PHP_EOL;
//   echo 'client_port: ' . ini_get('xdebug.client_port') . PHP_EOL;
//   echo 'mode: ' . ini_get('xdebug.mode') . PHP_EOL;
//   echo 'start_with_request: ' . ini_get('xdebug.start_with_request') . PHP_EOL;
// "

// 3. Test connection from container to host port 9003
// docker exec phpfpm bash -c 'timeout 2 bash -c "</dev/tcp/host-gateway/9003" && echo OK || echo FAIL'

// 4. Tail Xdebug log inside container
// docker exec phpfpm tail -f /tmp/xdebug.log

// 5. Verify MySQL datasource port is accessible from host
// nc -zv 127.0.0.1 3306 && echo "MySQL port open" || echo "Port closed"

10. Zusammenfassung

Die vollständige Integration von PHPStorm mit einem Docker-Compose-Setup erfordert Arbeit an vier Stellen: Docker-Daemon-Konfiguration in PHPStorm, Remote-Interpreter mit korrekten Path Mappings, Xdebug-Konfiguration mit richtigem client_host, und Datenbank-Datasource für den direkt exponierten MySQL-Port. Jede dieser vier Konfigurationen ist eigenständig und muss korrekt sein – eine fehlerhafte Stelle bricht die gesamte Integration. Der systematische Aufbau von Schritt 1 bis 4 verhindert, dass man im Kreis debuggt.

Der langfristige Gewinn ist erheblich: kein Terminal mehr für Composer-Befehle, Xdebug mit Breakpoints an jeder Zeile, SQL-Queries direkt aus der IDE mit Autocomplete auf die echte Datenbankstruktur, und PHPUnit mit einer Run-Konfiguration statt langer Kommandozeilen. Gerade in Magento-Projekten, wo der Code über Dutzende Module verteilt ist und Datenbankabfragen komplex werden, ist das ein echter Produktivitätsgewinn für den gesamten Entwicklungsalltag.

11. FAQ: PHPStorm und Docker Compose