Path Mappings in PhpStorm verstehen statt Trial and Error

1. Was Path Mappings wirklich sind

Ein Path Mapping ist eine Übersetzungsregel zwischen zwei Dateisystemen. Auf der einen Seite liegt das lokale Dateisystem des Entwicklers: der Pfad, unter dem PhpStorm die Quelldateien kennt. Auf der anderen Seite liegt das Remote-Dateisystem: der Pfad, unter dem PHP – sei es in einem Docker-Container, auf einem Staging-Server oder in einem Remote-Interpreter – dieselbe Datei sieht. Ohne diese Übersetzung kann PhpStorm einen Hinweis auf /var/www/html/vendor/magento/module-catalog/Model/Product.php vom Xdebug-Server nicht der lokalen Datei unter /home/mir/development/mironsoft/src/vendor/magento/module-catalog/Model/Product.php zuordnen.

Path Mappings sind kein Feature, das man einmal konfiguriert und vergisst. Jedes Mal, wenn sich die Projektstruktur ändert, ein neues Docker-Volume gemountet wird oder ein neuer Server hinzukommt, müssen die Mappings aktualisiert werden. Das Missverständnis, das zu den meisten Debugging-Problemen führt, ist die Annahme, dass PhpStorm die Pfade automatisch herleiten kann. Das kann die IDE nur in sehr einfachen Fällen – bei Docker-Containern, Remote-Servern und verschachtelten Projektstrukturen muss man sie explizit angeben.

2. Path Mappings für Xdebug konfigurieren

Xdebug verbindet sich mit PhpStorm und teilt der IDE mit, an welcher Datei es gerade arbeitet – mit dem Pfad, wie PHP ihn sieht, nicht wie PhpStorm ihn sieht. PhpStorm muss diesen Pfad übersetzen, um die richtige lokale Datei zu öffnen. Die Konfiguration erfolgt unter Settings → PHP → Debug → DBGp Proxy für die Verbindungsparameter und unter Settings → PHP → Servers für die Path Mappings selbst. Wichtig: Jeder Server-Eintrag in PhpStorm hat einen Namen, und dieser Name muss exakt mit dem Wert der Xdebug-Umgebungsvariable PHP_IDE_CONFIG=serverName=SERVERNAME übereinstimmen.

Die häufigste Fehlerquelle: Man erstellt einen Server-Eintrag mit dem Namen "localhost", setzt aber PHP_IDE_CONFIG=serverName=docker in der Docker-Compose-Datei. PhpStorm kann die eingehende Xdebug-Verbindung keinem Server-Eintrag zuordnen und legt entweder automatisch einen neuen Eintrag ohne Mappings an oder verwirft die Verbindung. Das Ergebnis: Breakpoints werden nie getroffen, obwohl der Debugger verbindet. Die Lösung ist trivial, sobald man das Konzept versteht: Server-Name in PhpStorm = serverName-Wert in PHP_IDE_CONFIG.

# docker-compose.yml — Xdebug-Konfiguration mit korrektem serverName
services:
  phpfpm:
    image: markoshust/magento-php:8.4-fpm
    environment:
      # CRITICAL: serverName must match PhpStorm → Settings → PHP → Servers → Name
      PHP_IDE_CONFIG: "serverName=mironsoft-docker"
      XDEBUG_MODE: "debug"
      XDEBUG_CONFIG: >-
        client_host=host-gateway
        client_port=9003
        start_with_request=trigger
        idekey=PHPSTORM
    volumes:
      - ./src:/var/www/html:delegated

# PhpStorm → Settings → PHP → Servers:
# Name:         mironsoft-docker          ← must match PHP_IDE_CONFIG serverName
# Host:         localhost
# Port:         80
# Debugger:     Xdebug
# Path Mappings:
#   /home/mir/development/mironsoft/src  →  /var/www/html

3. Docker-Container: lokale und Container-Pfade korrekt mappen

In Docker-basierten Projekten ist das Volume-Mapping der zentrale Ausgangspunkt für Path Mappings. Wenn ./src:/var/www/html in der docker-compose.yml definiert ist, dann ist das Path Mapping in PhpStorm genauso einfach: Lokaler Pfad /home/mir/development/mironsoft/src mappt auf Container-Pfad /var/www/html. Dieses eine Mapping genügt für alle Dateien unterhalb dieses Verzeichnisses – PhpStorm löst Unterverzeichnisse automatisch relativ auf.

Komplizierter wird es, wenn mehrere Volumes gemountet sind oder wenn Composer-Pakete außerhalb des Hauptverzeichnisses liegen. In Magento-Projekten, bei denen lokale Module aus app/code und Vendor-Pakete aus vendor alle im selben Container laufen, genügt ein einzelnes Root-Mapping. Kritisch wird es, wenn Symlinks im Spiel sind oder wenn derselbe Code über zwei verschiedene Pfade im Container erreichbar ist. In solchen Fällen muss man zusätzliche, spezifischere Mappings anlegen, die von PhpStorm mit höherer Priorität angewendet werden als das allgemeinere Root-Mapping.

4. Deployment-Server und Upload-Pfade

PhpStorm-Deployment-Konfigurationen unter Settings → Build, Execution, Deployment → Deployment nutzen ebenfalls Path Mappings. Hier gibt es drei Pfade: den Local path (auf dem Entwicklerrechner), den Deployment path (auf dem Remote-Server) und optional einen Web path (für Browser-URL-Zuordnung). Diese drei Felder zusammen bilden das Deployment-Mapping.

Ein häufiger Fehler ist, den Root-Pfad des Projekts korrekt einzutragen, aber den Deployment-Pfad relativ zum Web-Root des Servers falsch zu setzen. Wenn der Server Magento unter /var/www/vhosts/mironsoft.de/httpdocs hostet, aber man /var/www/html einträgt, landen Uploads an der falschen Stelle ohne Fehlermeldung. PhpStorm überträgt die Dateien erfolgreich – nur eben dorthin, wo sie niemand erwartet. Das Testen der Deployment-Konfiguration mit Tools → Deployment → Browse Remote Host zeigt sofort, ob PhpStorm den richtigen Pfad erreicht.

# PhpStorm Deployment-Konfiguration — Settings → Build, Execution, Deployment → Deployment
# Typ: SFTP

# Connection:
# Host:     staging.mironsoft.de
# Port:     22
# User:     deploy
# Auth:     Key pair ~/.ssh/id_ed25519

# Mappings (Tab "Mappings"):
# Local Path:       /home/mir/development/mironsoft/src
# Deployment Path:  /var/www/vhosts/mironsoft.de/httpdocs
# Web Path:         /

# Excluded Paths (Tab "Excluded Paths") — nie hochladen:
# /home/mir/development/mironsoft/src/var
# /home/mir/development/mironsoft/src/pub/static
# /home/mir/development/mironsoft/src/.git
# /home/mir/development/mironsoft/src/vendor

# Automatischer Upload:
# Tools → Deployment → Options → Upload changed files automatically: Always
# (nur für Staging verwenden — nie für Produktion)

5. Remote PHP-Interpreter und deren Pfadkonfiguration

Wenn PhpStorm einen Remote PHP-Interpreter nutzt – also PHP im Docker-Container oder auf einem Remote-Server statt dem lokalen PHP – muss die IDE wissen, wie die Pfade zwischen den Systemen zusammenhängen. Der Remote-Interpreter wird unter Settings → PHP → CLI Interpreter konfiguriert. Bei Docker-basierten Interpretern wählt man den Container aus und gibt den Pfad zum PHP-Binary im Container an.

PhpStorm versucht bei Docker-Interpretern automatisch, die Volume-Mappings aus der docker-compose.yml zu lesen und daraus Path Mappings abzuleiten. Das funktioniert in einfachen Fällen gut, versagt aber bei komplexen Compose-Setups mit mehreren Services oder bei Verwendung von Override-Dateien. In solchen Fällen muss man die Mappings manuell in der Interpreter-Konfiguration eintragen. Der Vorteil manueller Mappings: Sie sind explizit, nachvollziehbar und werden nicht durch Änderungen an der Compose-Datei stillschweigend ungültig.

6. Diagnose: Warum trifft mein Breakpoint nicht?

Wenn Breakpoints in PhpStorm nicht getroffen werden, obwohl Xdebug verbunden ist, sind die häufigsten Ursachen in absteigender Häufigkeit: Falscher Server-Name in PHP_IDE_CONFIG, fehlendes oder falsches Path Mapping, Breakpoint in einer gecachten Datei statt der Quelldatei, oder Xdebug im falschen Modus (xdebug.mode muss debug enthalten). PhpStorm zeigt im Debug-Fenster unter Debugger log die empfangenen Pfade vom Xdebug-Server an – das ist die wichtigste Diagnoseinformation.

Den Debugger-Log aktiviert man unter Help → Diagnostic Tools → Debug Log Settings, dann #com.jetbrains.php.debug eintragen. Nach einem neuen Xdebug-Request erscheinen in der Log-Datei die exakten Pfade, die Xdebug PhpStorm mitteilt. Vergleicht man diese mit den konfigurierten Path Mappings, sieht man sofort, ob ein Mapping fehlt oder falsch ist. Ein typischer Eintrag: received file path from debugger: /var/www/html/app/code/Mironsoft/Blog/Controller/Index.php – und das lokale Mapping muss genau /var/www/html → /home/mir/development/mironsoft/src enthalten.

7. Symlinks und verschachtelte Projekte

Symlinks sind eine häufige Ursache für Breakpoints, die nicht treffen, obwohl die Mappings auf den ersten Blick korrekt aussehen. PHP löst Symlinks standardmäßig auf und meldet Xdebug den realen Pfad, nicht den symbolischen. Wenn eine Datei unter /var/www/html/app/code/Mironsoft/Blog liegt, aber per Symlink von /home/user/modules/blog eingebunden ist, meldet Xdebug den realen Pfad /home/user/modules/blog/Controller/Index.php – und das Mapping auf /var/www/html greift nicht.

Die Lösung: Entweder den realen Pfad des Symlink-Ziels als zusätzliches Path Mapping eintragen, oder in der PHP-Konfiguration xdebug.use_compression=0 setzen und realpath_cache_size=0 in php.ini, damit PHP Symlinks nicht auflöst (nicht empfehlenswert in der Produktion). In Magento-Projekten mit Mark-Shust-Docker-Setup sind keine Symlinks nötig – direkte Volume-Mounts vermeiden das Problem vollständig.

# xdebug.ini — Vollständige Xdebug 3-Konfiguration für Docker-Magento-Projekte
[xdebug]
xdebug.mode = debug,develop
xdebug.start_with_request = trigger
xdebug.client_host = host-gateway
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.max_nesting_level = 512
xdebug.log_level = 0

; Pfad-Auflösung: Symlinks NICHT auflösen (Vorsicht: Performance)
; xdebug.resolve_symlinks = 0

; Für CLI-Debugging (bin/magento-Befehle):
; php -d xdebug.mode=debug -d xdebug.start_with_request=yes bin/magento ...

# PHP_IDE_CONFIG in docker-compose.yml:
# PHP_IDE_CONFIG: "serverName=mironsoft-docker"
# → Muss exakt dem Server-Namen in PhpStorm → Settings → PHP → Servers entsprechen

8. Path Mappings in Magento-2-Projekten mit Docker

Im Mark-Shust-Docker-Setup für Magento 2 liegt der Magento-Root im Container unter /var/www/html. Lokal liegt er unter dem src/-Verzeichnis des Projekts. Das Path Mapping ist damit eindeutig: /home/mir/development/mironsoft/src → /var/www/html. Dieses eine Mapping deckt alle Dateien ab – Magento-Core-Dateien in vendor/magento, eigene Module in app/code, Theme-Dateien in app/design und sogar die generierten Klassen in generated.

Für das Debugging von CLI-Befehlen wie bin/magento cache:flush oder eigenen Konsolenbefehlen braucht man einen separaten Run/Debug-Konfiguration in PhpStorm. Eine PHP Remote Debug-Konfiguration mit demselben Server-Namen genügt nicht – für CLI-Befehle muss man xdebug.start_with_request=yes setzen (statt trigger) und den Befehl mit der Debug-Session starten. Die Path Mappings sind dieselben wie für Web-Requests, da der CLI-PHP-Prozess im selben Container mit denselben Volume-Mounts läuft.

9. Konfigurationsszenarien im Vergleich

Je nach Entwicklungsumgebung ergeben sich unterschiedliche Konfigurationsanforderungen. Die folgende Tabelle gibt einen Überblick über die drei häufigsten Szenarien und ihre typischen Fallstricke.

Ein wichtiger Grundsatz: PhpStorm braucht für jeden Xdebug-Endpunkt einen eigenen Server-Eintrag mit eigenem Namen. Wer PHP in mehreren Containern debuggt – etwa einen FPM-Container für Web-Requests und einen CLI-Container für Cronjobs – muss zwei Server-Einträge anlegen, auch wenn die Path Mappings identisch sind. PHP_IDE_CONFIG enthält dann den Namen des jeweiligen Server-Eintrags.

10. Zusammenfassung

Path Mappings in PhpStorm sind die Brücke zwischen zwei Dateisystemen. Sobald man versteht, dass Xdebug, Deployment und Remote-Interpreter alle denselben Mechanismus nutzen, wird die Konfiguration logisch und vorhersehbar. Der Server-Name in PhpStorm muss dem serverName-Wert in PHP_IDE_CONFIG entsprechen. Das Path Mapping übersetzt den lokalen Pfad in den Container- oder Server-Pfad. Ein Mapping pro Root-Verzeichnis genügt für alle Dateien darunter.

Die schnellste Diagnose bei nicht treffenden Breakpoints: Debugger-Log aktivieren, den von Xdebug gemeldeten Pfad lesen, mit den konfigurierten Mappings vergleichen. In 90% der Fälle ist die Ursache entweder ein falscher Server-Name oder ein vergessenes Mapping. Mit diesem Verständnis löst man Path-Mapping-Probleme in zwei Minuten statt zwei Stunden.

11. FAQ: Path Mappings in PhpStorm