Dev Container und Docker-basierte Workspaces in PhpStorm

1. Dev Container vs. Docker-Interpreter – die richtige Wahl treffen

PhpStorm bietet zwei grundlegend verschiedene Wege, Docker in den Entwicklungsworkflow zu integrieren: Docker-Interpreter und Dev Container. Der Docker-Interpreter-Ansatz bedeutet, dass PhpStorm lokal läuft und für spezifische Operationen – PHP-Ausführung, Composer, XDebug – einen Docker-Container als Interpreter nutzt. Der Code liegt auf dem Host-System, PhpStorm liest und analysiert ihn lokal, und nur die Ausführung delegiert in den Container.

Der Dev Container-Ansatz mit PhpStorms Remote Development geht weiter: Das IDE-Backend (JetBrains IDE Backend) läuft direkt im Container. PhpStorm-UI bleibt lokal, aber Indexierung, Analyse, Navigation und Ausführung passieren vollständig im Container – mit exakt denselben Paketen, PHP-Version und Konfiguration wie in der Produktionsumgebung. Das eliminiert "works on my machine"-Probleme vollständig, erfordert aber etwas mehr Konfigurationsaufwand.

Für Teams ist die Wahl meist klar: Wenn alle Entwickler dasselbe OS nutzen und die PHP-Versionen stabil sind, reicht der Docker-Interpreter. Wenn das Team gemischte Betriebssysteme nutzt, wenn verschiedene Projekte verschiedene PHP-Versionen benötigen oder wenn neue Team-Mitglieder schnell ongeboardet werden sollen, ist der Dev-Container-Ansatz langfristig überlegen.

2. devcontainer.json für PHP-Projekte konfigurieren

Die devcontainer.json ist die zentrale Konfigurationsdatei für Dev Container – sowohl für VS Code als auch für JetBrains IDEs. PhpStorm liest diese Datei automatisch, wenn sie im .devcontainer/-Verzeichnis des Projekts liegt. Die Datei definiert das Container-Image, Ports, Mounts, Extensions (für VS Code) und Features – wiederverwendbare Installationsskripte für gängige Tools.

Für PHP-Projekte sind die wichtigsten Felder: image oder dockerComposeFile für das Basis-Image, postCreateCommand für Setup-Schritte nach dem Container-Start (z.B. composer install), und forwardPorts für die Portweiterleitung. PhpStorm erkennt customizations.jetbrains in der devcontainer.json für IDE-spezifische Einstellungen – etwa welche Plugins automatisch installiert werden sollen.

Features sind vordefinierte, composable Installationsblöcke: ghcr.io/devcontainers/features/php:1 installiert PHP mit konfigurierbarer Version. ghcr.io/devcontainers/features/node:1 fügt Node.js hinzu. ghcr.io/devcontainers/features/docker-in-docker:2 ermöglicht Docker-Befehle innerhalb des Containers. Diese Features sind versioniert und reproduzierbar – ein wesentlicher Vorteil gegenüber manuellen Installationsskripten.

// .devcontainer/devcontainer.json for PHP 8.4 / Magento 2 project
{
  "name": "Mironsoft PHP 8.4 Dev",
  "dockerComposeFile": ["../compose.yaml", "docker-compose.devcontainer.yml"],
  "service": "phpfpm",
  "workspaceFolder": "/var/www/html",
  "forwardPorts": [80, 443, 9003],
  "postCreateCommand": "composer install --no-interaction",
  "remoteUser": "app",
  "customizations": {
    "jetbrains": {
      "backend": "PhpStorm",
      "plugins": [
        "com.jetbrains.php",
        "org.jetbrains.plugins.phpstorm-remote-interpreter"
      ]
    }
  },
  "features": {
    "ghcr.io/devcontainers/features/php:1": {
      "version": "8.4",
      "installComposer": true
    },
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    }
  },
  "mounts": [
    "source=${localWorkspaceFolder}/src,target=/var/www/html,type=bind"
  ]
}

3. PhpStorm Remote Development: IDE-Backend im Container

PhpStorms Remote Development-Feature (seit 2022.3) erlaubt es, das IDE-Backend – den Server-Teil der IDE, der für Indexierung und Analyse zuständig ist – direkt in einem Docker-Container oder auf einem Remote-Server laufen zu lassen. Der Client-Teil (UI) bleibt lokal. Verbindung geschieht über SSH oder direkt via Docker.

Der Einstieg: "File > Remote Development > Dev Containers > Open" oder über das Gateway-Fenster. PhpStorm erkennt devcontainer.json-Dateien im aktuellen Projekt und bietet an, den Container zu starten und das IDE-Backend darin zu installieren. Beim ersten Start lädt PhpStorm das JetBrains IDE Backend-Paket in den Container herunter – das dauert einige Minuten, passiert danach automatisch bei Updates.

Nach dem Start verhält sich die IDE identisch zu einer lokalen Installation: Alle Shortcuts funktionieren, alle Tool-Windows sind verfügbar, die statische Analyse läuft auf den Container-Dateien. Der Unterschied: Ctrl+Click auf eine Klasse navigiert in die Container-Filesystem-Version der Datei, XDebug verbindet sich direkt zum Container-PHP-Prozess, und Composer wird mit dem Container-PHP ausgeführt. Für ein Magento-Projekt bedeutet das: PhpStorm indiziert die tatsächlichen Magento-Quelldateien im Container, mit der exakten PHP-Version und allen installierten Extensions.

4. PHP-Interpreter und Tools im Container einrichten

Auch ohne vollständiges Remote Development kann der PHP-Interpreter auf einen Docker-Container zeigen. Unter "Settings > PHP > CLI Interpreter > Add > Docker / Docker Compose" wählt man den Service aus der docker-compose.yml (z.B. phpfpm) und den PHP-Pfad im Container. PhpStorm verbindet sich beim Öffnen des Dialogs zum Container und liest die verfügbaren Interpreter automatisch aus.

Mit dem Docker-Interpreter als PHP-Interpreter arbeiten automatisch auch: PHPUnit (Tests werden im Container ausgeführt), PHPStan (Analyse im Container mit den dortigen Paketen), PHP CS Fixer und PhpCS (Formatierung nach Container-Konfiguration) und XDebug (wenn im Container konfiguriert). Der Entwickler muss keine Tools lokal installieren – alles kommt aus dem Container.

Ein praktischer Hinweis für Magento: Der generated/-Ordner im Magento-Root enthält automatisch generierte Klassen (Interceptors, Factories). Diese existieren nur nach bin/magento setup:di:compile – also nach einer Aktion im Container. Wenn PhpStorm auf die Container-Dateien zugreift (Remote Development), sind diese Klassen sofort navigierbar. Bei lokalem Zugriff mit Docker-Interpreter muss der generated/-Ordner als Library-Root markiert werden, damit PhpStorm ihn indiziert.

# docker-compose.devcontainer.yml — extends compose.yaml for Dev Container
version: '3.9'
services:
  phpfpm:
    # Add dev-only tools not needed in production
    build:
      context: .
      dockerfile: Dockerfile.dev
    environment:
      XDEBUG_MODE: "develop,debug"
      XDEBUG_CONFIG: "client_host=host.docker.internal client_port=9003"
      PHP_IDE_CONFIG: "serverName=mironsoft-local"
    volumes:
      # Persist Composer cache between container rebuilds
      - composer_cache:/root/.composer/cache
      # Mount SSH keys for private Composer repositories
      - ${HOME}/.ssh:/root/.ssh:ro
    ports:
      - "9003:9003"  # XDebug

volumes:
  composer_cache:

# PhpStorm: Settings > PHP > CLI Interpreter > Add > Docker Compose
#   Service: phpfpm
#   PHP executable: /usr/local/bin/php
#   Detected: PHP 8.4.x with Xdebug 3.x

5. Dev Container für Magento 2 mit Mark-Shust-Stack

Der Mark-Shust-Stack für Magento (docker-magento) bringt bereits alle notwendigen Services mit: phpfpm, nginx, db (MySQL), redis, elasticsearch und optional rabbitmq. Ein Dev Container für dieses Setup ergänzt die bestehenden Compose-Dateien um eine spezifische devcontainer.json und eine docker-compose.devcontainer.yml, die Dev-spezifische Einstellungen überschreibt, ohne den Production-Stack zu verändern.

Wichtige Anpassungen für das Magento-Dev-Container-Setup: Der phpfpm-Service benötigt XDebug (nicht in Production-Images enthalten), SSH-Keys für Composer (private Adobe-Commerce-Pakete), und erhöhtes PHP-Memory-Limit für die IDE-Backend-Ausführung. Das workspaceFolder in der devcontainer.json zeigt auf /var/www/html – den Magento-Root im Container.

Nach dem Start des Dev Containers startet PhpStorm automatisch die Indizierung. Bei einem Magento-Projekt mit 30.000+ PHP-Dateien (Core, Module, Vendor) dauert die erste Indizierung 10-20 Minuten. Danach ist sie im Container gecacht und wird bei Dateisystemänderungen inkrementell aktualisiert. Für eine bessere Performance empfiehlt es sich, generated/, var/ und pub/static/ als Excluded-Directories zu markieren – diese enthalten keine navigierbaren Quelldateien und verlängern die Indizierungszeit unnötig.

6. XDebug im Dev Container konfigurieren

XDebug im Dev Container erfordert etwas mehr Konfigurationsaufwand als bei einem lokalen Setup, weil PhpStorm und PHP in verschiedenen Netzwerk-Namespaces laufen. Der XDebug-Client (PhpStorm) ist auf dem Host, der XDebug-Server (PHP) ist im Container. Die Verbindung muss vom Container zum Host gehen – das geschieht über host.docker.internal auf macOS und Windows, oder über die Host-Gateway-IP unter Linux.

Die kritischen XDebug-Einstellungen im Container: xdebug.client_host=host.docker.internal (oder die Gateway-IP), xdebug.client_port=9003, xdebug.mode=debug und xdebug.start_with_request=yes für automatisches Debugging ohne Browser-Extension. In PhpStorm muss unter "Settings > PHP > Debug" der Port 9003 konfiguriert sein. Unter "Settings > PHP > Servers" wird ein Server mit dem Namen aus PHP_IDE_CONFIG=serverName=... angelegt, mit Path-Mappings zwischen Host-Pfaden und Container-Pfaden.

Path-Mappings sind der häufigste Stolperstein: PhpStorm sieht die Dateien unter dem Host-Pfad (z.B. /home/user/project/src), PHP läuft sie unter dem Container-Pfad (z.B. /var/www/html). Ohne korrektes Mapping kann PhpStorm XDebug-Breakpoints nicht den richtigen Dateien zuordnen. Mit Remote Development entfällt dieses Problem vollständig – PhpStorm arbeitet direkt mit den Container-Pfaden.

<?php
// XDebug configuration in php.ini / conf.d/xdebug.ini (inside container)
// zend_extension=xdebug
// xdebug.mode=develop,debug
// xdebug.client_host=host.docker.internal
// xdebug.client_port=9003
// xdebug.start_with_request=yes
// xdebug.log=/tmp/xdebug.log
// xdebug.log_level=7

// PhpStorm: Settings > PHP > Servers > Add
//   Name: mironsoft-local  (must match PHP_IDE_CONFIG serverName)
//   Host: localhost
//   Port: 80
//   Debugger: XDebug
//   Path mappings:
//     /home/mir/development/mironsoft/src -> /var/www/html

// Verify connection: Run > Start Listening for PHP Debug Connections
// Then: curl http://localhost/health
// PhpStorm should show "Incoming connection from XDebug" dialog

// Common issue: Linux host.docker.internal not available
// Solution: add to docker-compose.devcontainer.yml:
//   extra_hosts:
//     - "host.docker.internal:host-gateway"

7. Dev Container im Team teilen und standardisieren

Der größte Vorteil von Dev Containern für Teams ist die Reproduzierbarkeit: Die devcontainer.json wird ins Repository eingecheckt und steht allen Entwicklern zur Verfügung. Ein neues Team-Mitglied klont das Repository, öffnet es in PhpStorm, bestätigt "Reopen in Container" – und hat nach wenigen Minuten eine vollständig konfigurierte Entwicklungsumgebung. Keine manuelle PHP-Installation, kein lokales Magento-Setup, keine "funktioniert bei mir aber nicht bei dir"-Diskussionen.

Für die Teamstandardisierung empfiehlt es sich, die devcontainer.json mit folgenden Elementen zu ergänzen: postCreateCommand für composer install und initiale Magento-Konfiguration, postStartCommand für Services die bei jedem Container-Start initialisiert werden müssen, und waitFor um die Reihenfolge der Initialisierungsschritte zu kontrollieren. Umgebungsvariablen für Secrets (API-Keys, Datenbank-Passwörter) kommen aus .env-Dateien die nicht ins Repository eingecheckt werden.

Ein gut strukturiertes Dev-Container-Setup für Magento enthält: Die devcontainer.json im Repository, eine separate docker-compose.devcontainer.yml die die Produktions-Compose-Datei ergänzt, ein Dockerfile.dev mit Dev-spezifischen Tools (XDebug, Composer, Shell-Tools), und ein .devcontainer/setup.sh-Skript für den postCreateCommand. Das Setup-Skript führt composer install, bin/magento setup:upgrade und andere Initialisierungsschritte aus – einmal, nach dem Container-Build.

8. Vergleich: Dev Container Ansätze im Überblick

9. Zusammenfassung

Dev Container und Docker-basierte Workspaces in PhpStorm lösen das fundamentale Problem der Entwicklungsumgebungs-Inkonsistenz. Die devcontainer.json definiert die Umgebung deklarativ und reproduzierbar – eingecheckt im Repository, verfügbar für alle Entwickler. PhpStorms Remote Development bringt das IDE-Backend direkt in den Container, sodass Indexierung, Analyse und Navigation mit den exakten Container-Paketen und der Container-PHP-Version arbeiten.

Für Magento-Projekte mit dem Mark-Shust-Stack ist das Vorgehen klar: bestehende Compose-Dateien werden durch eine docker-compose.devcontainer.yml ergänzt, XDebug wird für Container-zu-Host-Verbindungen konfiguriert, und die devcontainer.json definiert postCreateCommand für die automatische Initialisierung. Das Ergebnis: Neue Team-Mitglieder sind in unter 30 Minuten produktiv, ohne manuelle PHP-Installation oder lokales Magento-Setup. Works on every machine – weil die Maschine der Container ist.

10. FAQ: Dev Container und Docker-basierte Workspaces in PhpStorm