Remote PHP-Interpreter vs. lokal in PHPStorm: Wann welches Setup besser ist

1. Was der PHP-Interpreter in PHPStorm wirklich macht

Der konfigurierte PHP-Interpreter in PHPStorm ist nicht nur für die direkte Ausführung von PHP-Code zuständig. Er ist die Grundlage für mehrere IDE-Kernfunktionen: die Erkennung installierter Extensions (die Autocomplete und Code-Inspection beeinflussen), die Auflösung von PHP-Versionsfeatures, die Ausführung von Composer-Befehlen über die IDE, das Starten von PHPUnit-Runs und die Verbindung zu Xdebug. Wenn der Interpreter falsch konfiguriert ist, sind all diese Funktionen entweder fehlerhaft oder komplett inaktiv.

PHPStorm unterscheidet grundsätzlich zwischen drei Interpreter-Kategorien: lokal (eine PHP-Binary auf dem Entwicklerrechner), remote via Docker oder Docker Compose (PHP läuft in einem Container) und remote via SSH (PHP läuft auf einem entfernten Server). Jede Kategorie hat spezifische Vor- und Nachteile, die von der Projektstruktur abhängen. In modernen Docker-basierten Projekten wie Magento 2 mit Mark-Shust-Setup ist die Antwort meistens eindeutig: Docker Compose Interpreter.

2. Lokaler Interpreter: Stärken und Grenzen

Ein lokaler PHP-Interpreter ist der schnellste Ansatz: keine Container, keine Verbindungsaufbaupause, keine Netzwerk-Overhead. PHPStorm kann sofort mit dem lokal installierten PHP kommunizieren. Das ist ideal für einfache PHP-Projekte ohne spezifische Systemanforderungen, für Composer-global-Tools oder für Entwickler, die auf macOS oder Linux ein lokales PHP identisch zur Produktionsumgebung installiert haben.

Die Grenzen des lokalen Interpreters zeigen sich sofort in Container-Projekten. Wenn das Projekt PHP 8.4 mit spezifischen Extensions wie sodium, gd oder Magento-spezifischen Konfigurationen benötigt, muss das lokale PHP exakt diese Konfiguration haben – sonst liefert PHPStorm falsche Autocomplete-Hinweise und übersieht Extension-spezifische Funktionen. Noch kritischer: Wenn das Deployment-PHP eine andere Version als das lokale PHP ist, führen Type-Error-freie lokale PHPStan-Analysen zu PHP-Fehlern in der Produktion.

<?php
// Beispiel: Extension-Konflikt zwischen lokalem und Container-PHP

declare(strict_types=1);

// Lokal: PHP 8.2 ohne sodium-Extension
// Container: PHP 8.4 mit sodium

// PHPStorm mit lokalem Interpreter markiert sodium_crypto_box() als
// "undefined function" — obwohl es im Container existiert

// Mit Docker Compose Interpreter: PHPStorm sieht alle Extensions
// des Containers und markiert sodium_crypto_box() korrekt als vorhanden

$ciphertext = sodium_crypto_box(
    message: 'Hello Magento',
    nonce: random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES),
    key_pair: sodium_crypto_box_keypair()
);

// Autocomplete-Qualität hängt direkt vom Interpreter ab

3. Docker Compose Interpreter: das beste Setup für Docker-Projekte

Für Docker-basierte Projekte ist der Docker Compose Interpreter die überlegene Wahl. PHPStorm startet beim Verbinden einen temporären Container (oder nutzt den laufenden phpfpm-Container) und liest direkt aus dem Container: PHP-Version, installierte Extensions, php.ini-Konfiguration und Composer-Pakete. Autocomplete und Type Inference basieren dann auf dem tatsächlichen Laufzeit-PHP.

Die Konfiguration in PHPStorm: Settings → PHP → CLI Interpreters → + → From Docker, Vagrant, VM, WSL, Remote. Server: Docker Compose. Konfigurationsdatei: das Haupt-compose.yaml des Projekts. Service: phpfpm (oder wie der PHP-Service im Projekt heißt). PHPStorm ermittelt dann automatisch den PHP-Pfad im Container. Der einzige Overhead gegenüber dem lokalen Interpreter: PHPStorm braucht beim ersten Verbinden einen kurzen Moment, um Container-Informationen zu laden. Danach läuft alles transparent.

<?php
// PHPStorm Docker Compose Interpreter Setup
// Settings → PHP → CLI Interpreters

/*
Interpreter-Konfiguration (Beispiel für Mark-Shust-Setup):
- Name: Docker PHP 8.4 (mironsoft)
- Server: Docker Compose
- Configuration files: ./compose.yaml; ./compose.dev-linux.yaml
- Service: phpfpm
- PHP executable: (auto-detected: /usr/local/bin/php)
- Debugger: Xdebug 3.x (auto-detected)

Path Mappings:
- Local:     /home/mir/development/mironsoft/src
- Container: /var/www/html
*/

declare(strict_types=1);

// Mit diesem Interpreter erkennt PHPStorm:
// - PHP 8.4 Features (Property Hooks, Asymmetric Visibility)
// - Alle Container-Extensions (sodium, gd, imagick, redis, etc.)
// - Composer-Pakete aus /var/www/html/vendor/
// - Magento-spezifische Klassen und Interfaces aus vendor/magento/

// Correct autocompletion for PHP 8.4 property hooks:
class Product
{
    public string $name {
        get => strtoupper($this->name);
        set => $this->name = trim($value);
    }
}

4. SSH-Interpreter: für Remote-Server und CI-Szenarien

Der SSH-Interpreter verbindet PHPStorm mit einem PHP, das auf einem entfernten Server läuft. Das ist sinnvoll für Staging-Umgebungen, auf die mehrere Entwickler zugreifen, oder für Szenarien, in denen der Entwicklungsserver aus Hardware- oder Lizenzgründen zentral betrieben wird. Der SSH-Interpreter nutzt SFTP für den Dateitransfer und führt PHP-Befehle remote aus.

Die Einrichtung: Settings → PHP → CLI Interpreters → + → SSH Credentials. SSH-Verbindung, Benutzername und Schlüsseldatei konfigurieren, dann den Pfad zur PHP-Binary auf dem Server angeben. Der Nachteil des SSH-Interpreters gegenüber Docker Compose: Jede PHP-Ausführung (Autocomplete-Vervollständigung, PHPUnit-Run) geht über das Netzwerk. Das ist bei guter Verbindung kaum spürbar, bei langsamen oder instabilen Verbindungen aber merklich. Für tägliche Entwicklung auf dem eigenen Rechner ist Docker Compose die bessere Wahl.

5. WSL-Interpreter unter Windows

Unter Windows bietet PHPStorm seit Version 2021.2 native WSL2-Unterstützung. Der WSL-Interpreter verhält sich aus PHPStorm-Sicht wie ein lokaler Interpreter, läuft aber in einem Windows-Subsystem-for-Linux-Container. Das ist eine saubere Alternative zu Docker-Compose-Interpretern unter Windows, wenn Docker-Desktop-Performance-Probleme bestehen. Der Overhead ist geringer als bei Docker Compose, die Isolation aber auch schwächer.

Für Teams, die gemischt auf Windows und macOS/Linux entwickeln, empfiehlt sich trotz WSL-Unterstützung der Docker-Compose-Interpreter, weil er plattformunabhängig konfiguriert werden kann und das gleiche PHP nutzt wie alle anderen Teammitglieder. Ein WSL-Interpreter löst Windows-spezifische Probleme elegant, schafft aber einen Sonderfall in der Team-Konfiguration, der dokumentiert werden muss.

<?php
// WSL-Interpreter vs. Docker Compose – Entscheidungshilfe
// (als PHPDoc-Kommentar strukturiert, kein ausführbarer Code)

/*
 * LOKALER INTERPRETER
 * Wann sinnvoll:
 * - Einfaches PHP-Projekt ohne spezifische Extension-Anforderungen
 * - Composer-Global-Tools (phpstan, phpcs standalone)
 * - Keine Docker-Umgebung vorhanden
 *
 * Wann problematisch:
 * - Docker-Projekt mit abweichendem Container-PHP
 * - Magento 2 mit Extension-spezifischen Funktionen
 *
 * DOCKER COMPOSE INTERPRETER
 * Wann sinnvoll:
 * - Alle Docker-basierten Projekte (Standard für Magento 2)
 * - Mehrere PHP-Projekte mit unterschiedlichen PHP-Versionen
 * - Wenn Xdebug und PHPUnit aus dem Container laufen sollen
 *
 * SSH INTERPRETER
 * Wann sinnvoll:
 * - Entwicklung auf zentralem Remote-Server
 * - Staging-Umgebungen zur Inspektion
 * - Wenn kein Docker lokal verfügbar ist
 *
 * WSL INTERPRETER (Windows)
 * Wann sinnvoll:
 * - Windows-Entwickler mit Docker-Desktop-Performance-Problemen
 * - Nur wenn Docker Compose nicht funktioniert
 */

6. Path Mappings: der kritische Punkt bei jedem Remote-Interpreter

Bei jedem Remote-Interpreter – ob Docker Compose, SSH oder WSL – sind Path Mappings der häufigste Fehlergrund. PHPStorm muss wissen, dass ein lokaler Pfad auf dem Entwicklerrechner einem Pfad im Container oder auf dem Remote-Server entspricht. Ohne korrekte Mappings öffnet PHPStorm beim Xdebug-Breakpoint keine lokale Datei, sondern zeigt einen Fehler. PHPUnit-Runs können keine Fehler auf lokale Dateizeilen mappen.

Die korrekte Konfiguration der Path Mappings: Im Interpreter-Dialog unter Path Mappings das lokale Projektverzeichnis (z.B. /home/mir/development/mironsoft/src) dem Container-Pfad (/var/www/html) zuordnen. Für Magento-Projekte mit Mark-Shust-Setup ist der Container-Pfad standardmäßig /var/www/html. Zusätzlich werden Path Mappings unter Settings → PHP → Servers für den Xdebug-Server benötigt. Beide Stellen müssen konsistent sein.

7. Xdebug-Unterschiede zwischen den Interpreter-Typen

Xdebug verhält sich je nach Interpreter-Typ unterschiedlich. Mit dem lokalen Interpreter ist Xdebug einfach: PHPStorm und PHP laufen auf dem gleichen Rechner, keine Netzwerk-Konfiguration nötig. Mit dem Docker-Compose-Interpreter muss Xdebug im Container den Weg zurück zur IDE auf dem Host finden. Das ist der Punkt, an dem unter Linux host.docker.internal via extra_hosts: host.docker.internal:host-gateway in der Compose-Datei konfiguriert werden muss.

Mit dem SSH-Interpreter ist Xdebug am komplexesten: der Server muss eine Verbindung zur Entwicklermaschine zurück aufbauen können, was in vielen Netzwerken durch Firewalls blockiert wird. Die Alternative: SSH-Tunnel aufbauen und Xdebug so konfigurieren, dass es den Tunnel nutzt. Für tägliche Entwicklung ist das zu aufwändig – Docker Compose bleibt die zuverlässigste Xdebug-Umgebung. Der SSH-Interpreter ist für Staging-Debugging in kontrollierten Netzwerken geeignet.

8. Direkter Vergleich: lokal vs. Docker Compose vs. SSH

9. Zusammenfassung

Die Wahl des PHP-Interpreters in PHPStorm ist keine Kleinigkeit – sie bestimmt die Qualität von Autocomplete, die Zuverlässigkeit von Xdebug und die Korrektheit von PHPStan-Analysen. Für Docker-basierte Projekte wie Magento 2 mit Mark-Shust-Setup ist der Docker-Compose-Interpreter die richtige Wahl: er basiert auf dem tatsächlichen Container-PHP und ist für das ganze Team einheitlich konfigurierbar. Der lokale Interpreter ist nur für einfache PHP-Projekte ohne spezifische Extension-Anforderungen geeignet. SSH-Interpreter sind für Remote-Staging-Szenarien sinnvoll, für tägliche Entwicklung aber zu aufwändig.

10. FAQ: Remote PHP-Interpreter vs. lokal in PHPStorm