Zero-Config Docker-Compose-Erkennung in PhpStorm im Detail

1. Zero-Config als Versprechen und als Realitaet

Der Begriff Zero-Config weckt die Erwartung, dass ein Projekt geoeffnet wird und alles sofort funktioniert, ohne eine einzige manuelle Einstellung. Bei PhpStorm und Docker Compose trifft das fuer einfache Setups tatsaechlich weitgehend zu: Eine einzelne docker-compose.yml mit einem PHP-Service und einer Datenbank wird beim Oeffnen des Projekts erkannt, und PhpStorm bietet direkt an, daraus eine Run-Configuration zu erzeugen. Fuer viele kleinere Projekte reicht das vollstaendig aus.

Sobald ein Setup aber mehrere Compose-Dateien kombiniert, etwa eine Basis-Datei und mehrere Override-Dateien fuer verschiedene Umgebungen, wie es beim Mark-Shust-Docker-Setup fuer Magento ueblich ist, wird aus der Zero-Config-Erfahrung ein Ausgangspunkt, der Nachjustierung braucht. Das ist kein Fehler von PhpStorm, sondern eine logische Konsequenz daraus, dass Compose-Overrides zur Laufzeit kombiniert werden und PhpStorm diese Kombination nicht immer eindeutig vorhersagen kann.

2. Voraussetzungen: Docker-Integration in PhpStorm aktivieren

Die Docker-Unterstuetzung ist in den meisten PhpStorm-Editionen als Bundled Plugin bereits vorinstalliert, muss aber unter Settings, Plugins ueberprueft und gegebenenfalls aktiviert werden. Zusaetzlich muss unter Settings, Build, Execution, Deployment, Docker eine Verbindung zur lokalen Docker-Engine eingerichtet werden, entweder ueber den lokalen Docker-Socket unter Linux und macOS oder ueber die entsprechende Named-Pipe-Konfiguration unter Windows.

Ist die Verbindung korrekt eingerichtet, erscheint am unteren Rand der IDE das Docker Tool Window, das laufende Container, Images und Compose-Stacks anzeigt. Dieses Tool Window ist die zentrale Anlaufstelle, um zu pruefen, ob PhpStorm ueberhaupt Kontakt zur Docker-Engine hat, bevor irgendeine automatische Erkennung von Compose-Dateien ueberhaupt sinnvoll funktionieren kann.

Settings > Build, Execution, Deployment > Docker
  + (Docker Verbindung hinzufuegen)
  Linux/macOS: Unix socket, Standardpfad meist automatisch erkannt
  Test: "Connection successful" muss erscheinen

3. Wie die automatische Erkennung im Detail ablaeuft

Oeffnet PhpStorm ein Projektverzeichnis, durchsucht es die Projektwurzel und definierte Unterordner nach Dateien mit den Namen docker-compose.yml oder compose.yaml. Wird eine solche Datei gefunden, bietet die IDE ueber ein kleines Icon am Dateirand an, daraus direkt eine Run-Configuration vom Typ Docker-Compose zu erstellen. Diese Configuration referenziert automatisch die gefundene Datei und listet alle darin definierten Services zur Auswahl auf.

Fuer jeden Service liest PhpStorm zusaetzlich die exponierten Ports, gemountete Volumes und Umgebungsvariablen aus der Compose-Datei aus und zeigt sie in der generierten Run-Configuration an. Bei einem einzelnen PHP-Service mit klar definiertem build-Kontext funktioniert das zuverlaessig und spart das manuelle Anlegen einer Configuration fast vollstaendig.

4. Praxisbeispiel: Automatische Erkennung bei einem Service

Eine minimale docker-compose.yml mit einem Service namens phpfpm, der auf ein lokales Dockerfile verweist und Port 9000 exponiert, wird von PhpStorm typischerweise ohne jede manuelle Eingabe korrekt interpretiert. Die generierte Run-Configuration erlaubt direkt den Start und Stop des Containers ueber die IDE, ohne ein Terminal oeffnen zu muessen, und der Service erscheint sofort im Docker Tool Window mit Status-Anzeige.

Auch die Zuordnung von Log-Ausgaben funktioniert in diesem einfachen Fall zuverlaessig: Ein Klick auf den laufenden Container im Tool Window oeffnet direkt den Log-Stream innerhalb der IDE, mit Such- und Filterfunktion. Fuer schnelle Debugging-Sessions bei einfachen Setups ersetzt das den Wechsel ins Terminal fast vollstaendig und beschleunigt den Feedback-Zyklus deutlich.

5. Grenzen bei Multi-File-Compose-Setups

Sobald ein Projekt mehrere Compose-Dateien kombiniert, etwa eine docker-compose.yml als Basis und eine docker-compose.dev.yml als Override fuer Entwicklungsumgebungen, wie es beim Mark-Shust-Setup ueblich ist, erkennt PhpStorm oft nur die zuerst gefundene Datei automatisch. Die Override-Datei wird zwar meist ebenfalls als eigenstaendige Compose-Datei erkannt, PhpStorm kombiniert die beiden aber nicht automatisch zu einer gemeinsamen Run-Configuration, wie es der docker compose Befehl mit der Flag -f fuer mehrere Dateien tun wuerde.

Das fuehrt in der Praxis dazu, dass eine automatisch generierte Run-Configuration moeglicherweise nur die Basis-Datei referenziert und dadurch Umgebungsvariablen oder Volume-Mounts fehlen, die eigentlich aus der Override-Datei stammen. Wird dieser Unterschied nicht bemerkt, startet der Container zwar, verhaelt sich aber anders als bei einem manuellen docker compose up mit beiden Dateien, was zu schwer nachvollziehbaren Debugging-Problemen fuehren kann.

6. Umgebungsvariablen und .env-Dateien in der Erkennung

PhpStorm liest eine .env-Datei im selben Verzeichnis wie die docker-compose.yml automatisch ein und loest darin referenzierte Variablen innerhalb der Compose-Datei auf, etwa fuer Image-Tags oder Portnummern. Diese Aufloesung ist meist zuverlaessig, solange die .env-Datei im Standardverzeichnis liegt. Liegt sie an einem abweichenden Pfad oder wird sie explizit ueber die --env-file Option referenziert, erkennt die automatische Konfiguration das haeufig nicht.

Fuer Magento-Setups mit mehreren Umgebungsstufen, etwa getrennten .env-Dateien fuer lokale Entwicklung und CI, bedeutet das, dass die Run-Configuration nach der automatischen Generierung manuell um den korrekten Pfad zur .env-Datei ergaenzt werden muss. Andernfalls verwendet PhpStorm stillschweigend Standardwerte, was insbesondere bei Datenbank-Zugangsdaten zu Verbindungsfehlern fuehrt, die auf den ersten Blick nicht mit der Compose-Konfiguration in Verbindung gebracht werden.

7. Manuelle Nachjustierung der generierten Configuration

Die generierte Run-Configuration laesst sich unter Run, Edit Configurations vollstaendig anpassen. Der wichtigste Schritt bei Multi-File-Setups ist, unter dem Feld Compose Files zusaetzliche Dateien hinzuzufuegen, in der korrekten Reihenfolge von Basis- zu Override-Datei, damit PhpStorm dieselbe Kombination anwendet, die auch der manuelle docker compose Befehl mit mehreren -f Flags erzeugen wuerde.

Zusaetzlich lohnt es sich, unter Environment Variables explizit die Werte einzutragen, die sonst nur ueber die .env-Datei aufgeloest wuerden, falls die automatische Aufloesung nicht funktioniert. Nach der Anpassung sollte die Configuration einmal testweise gestartet und die tatsaechlich verwendeten Umgebungsvariablen ueber das Docker Tool Window im laufenden Container geprueft werden, um sicherzustellen, dass die manuelle Konfiguration tatsaechlich der erwarteten Kombination entspricht.

# Run/Debug Configurations > Docker-Compose
# Compose files (Reihenfolge wichtig):
#   docker-compose.yml
#   docker-compose.dev.yml
# Environment variables (falls .env nicht automatisch aufgeloest wird):
#   PHP_VERSION=8.4
#   MYSQL_ROOT_PASSWORD=magento

8. Debugging-Workflow: Xdebug mit erkannter Compose-Configuration

Fuer PHP-Debugging innerhalb eines Docker-Compose-Containers bietet PhpStorm die Moeglichkeit, einen CLI-Interpreter vom Typ Docker Compose einzurichten, der auf dieselbe Compose-Datei und denselben Service verweist wie die zuvor erstellte Run-Configuration. Dieser Interpreter erscheint unter Settings, PHP, CLI Interpreters und laesst sich anschliessend als Projekt-Interpreter fuer Testlaeufe und Debugging-Sessions auswaehlen.

Wichtig dabei ist, dass die Path Mappings zwischen dem lokalen Projektverzeichnis und dem Pfad innerhalb des Containers korrekt eingetragen sind, da sonst Breakpoints im Editor nicht mit den tatsaechlich ausgefuehrten Dateien im Container uebereinstimmen. Bei automatisch erkannten Setups uebernimmt PhpStorm die Path Mappings meist aus den Volume-Definitionen der Compose-Datei, bei manuell nachjustierten Multi-File-Setups sollten sie nach jeder Aenderung an den Compose-Dateien erneut geprueft werden.

9. Praxis-Setup und Vergleich der Konfigurationsansaetze

Fuer ein neues Projekt empfiehlt sich, zunaechst die automatische Erkennung laufen zu lassen und die generierte Configuration testweise zu starten, bevor manuelle Anpassungen vorgenommen werden. So wird sichtbar, welche Teile bereits korrekt funktionieren und welche tatsaechlich Nacharbeit brauchen, statt von Anfang an alles manuell zu konfigurieren und dabei die eingebaute Erkennung ungenutzt zu lassen.

Die folgende Tabelle vergleicht automatische Erkennung, teilweise manuelle Nachjustierung und vollstaendig manuelle Konfiguration hinsichtlich Aufwand und Zuverlaessigkeit bei unterschiedlicher Setup-Komplexitaet. Sie zeigt, dass die Automatik bei einfachen Projekten den vollen Aufwand einspart, waehrend Multi-File-Setups wie bei Magento fast immer eine gezielte Nachjustierung an Compose-Dateien-Liste und Umgebungsvariablen erfordern.

10. Zusammenfassung

11. FAQ: Docker-Compose-Erkennung in PhpStorm: Das Wichtigste auf einen Blick