Docker-Interpreter in PhpStorm sauber aufsetzen

1. Warum Docker-Interpreter statt lokaler PHP-Installation

Der klassische Ansatz – PHP lokal installieren und als PhpStorm-Interpreter konfigurieren – funktioniert, hat aber strukturelle Nachteile: Die lokale PHP-Version weicht schnell von der Produktions-PHP-Version ab. Lokale PHP-Extensions stimmen nicht mit den Container-Extensions überein. Entwickler mit verschiedenen Betriebssystemen haben unterschiedliche PHP-Versionen. Wenn drei Projekte drei verschiedene PHP-Versionen brauchen, wird lokales Version-Management komplex.

Der Docker-Interpreter in PhpStorm löst diese Probleme: PhpStorm kommuniziert mit dem PHP-Prozess im Docker-Container, als wäre es ein lokaler Interpreter. Autocompletion, Typ-Inferenz und Navigations-Features nutzen die PHP-Version und die Extensions aus dem Container – identisch mit der Produktionsumgebung. Tests laufen im Container, XDebug debuggt den Container-PHP-Prozess, Composer installiert Pakete mit der Container-PHP-Version.

Für Magento-Projekte mit dem Mark-Shust-Stack ist das die richtige Wahl: PHP 8.4 läuft im Container, und PhpStorm soll genau diese Version für alle IDE-Features nutzen. Ohne Docker-Interpreter würde PhpStorm möglicherweise lokales PHP 8.2 oder eine völlig andere Version verwenden – mit der Folge, dass Autocompletion falsche Typen vorschlägt und Inspektionen fehlerhafte Warnungen ausgeben.

2. Docker-Verbindung in PhpStorm einrichten

Bevor ein Docker-Interpreter konfiguriert werden kann, muss PhpStorm eine Verbindung zum Docker-Daemon haben. Diese Verbindung wird unter "Settings > Build, Execution, Deployment > Docker" konfiguriert. PhpStorm unterstützt drei Verbindungsarten: Unix-Socket (für macOS und Linux), TCP-Socket und Docker for Windows. Auf macOS und Linux erkennt PhpStorm den Unix-Socket /var/run/docker.sock automatisch.

Nach dem Hinzufügen der Docker-Verbindung erscheint ein grüner Haken wenn die Verbindung erfolgreich ist, und PhpStorm listet die verfügbaren Container und Images im "Services"-Panel (View > Tool Windows > Services). Von dort aus können Container gestartet, gestoppt und ihre Logs eingesehen werden – direkt aus der IDE heraus, ohne das Terminal zu öffnen.

Ein wichtiger Hinweis für den Mark-Shust-Stack: Der Stack verwendet Docker Compose mit mehreren Services. PhpStorm muss die richtige docker-compose.yml kennen und den richtigen Service (phpfpm) als Basis für den Interpreter verwenden. Mehrere Compose-Dateien (z.B. compose.yaml + compose.dev.yaml) können PhpStorm als Override-Datei angegeben werden, exakt wie docker compose -f compose.yaml -f compose.dev.yaml auf der Kommandozeile.

# Verifying Docker connection for PhpStorm interpreter setup
# Run from project root to confirm service is accessible:

# Check running services
docker compose ps

# Expected output for Mark Shust stack:
# NAME            IMAGE                COMMAND   SERVICE    PORTS
# nginx           nginx:1.25           ...       nginx      0.0.0.0:80->80/tcp
# phpfpm          php:8.4-fpm          ...       phpfpm     9000/tcp
# db              mariadb:11.x         ...       db         3306/tcp

# Verify PHP version in container (must match PhpStorm interpreter target)
docker compose exec phpfpm php -v
# PHP 8.4.x (cli) (built: ...)
# with XDebug 3.x

# Check available extensions
docker compose exec phpfpm php -m
# Should show: bcmath, gd, intl, mbstring, pdo_mysql, soap, xsl, zip, Xdebug

3. PHP-Interpreter aus Docker-Container konfigurieren

Die eigentliche Interpreter-Konfiguration geschieht unter "Settings > PHP > CLI Interpreter > + (Add) > From Docker, Vagrant, VM, WSL, Remote". Im Dialog wählt man "Docker Compose", wählt die Compose-Datei (oder mehrere) und den Service (phpfpm). PhpStorm führt dann im Hintergrund ein docker compose run aus, liest die PHP-Version und die verfügbaren Extensions und zeigt diese im Konfigurationsdialog an.

Nach der Konfiguration erscheint der Docker-Interpreter in der Interpreter-Liste mit dem Container-Image und der PHP-Version. Dieser Interpreter kann dann als Standard-PHP-CLI-Interpreter gesetzt werden – er gilt dann für alle PHP-Operationen in PhpStorm: Scratches ausführen, externe Tools aufrufen, Composer-Befehle und mehr.

Unter "Settings > PHP" kann man den Docker-Interpreter auch als Interpreter für die PHP-Sprachebene setzen – das ist die Einstellung, die bestimmt, welche PHP-Features und -Funktionen PhpStorm als verfügbar kennt. Wenn PHP 8.4 im Container läuft, sollte hier "PHP 8.4" stehen, damit PhpStorm PHP-8.4-Features wie Property Hooks korrekt analysiert und keine falschen "nicht unterstützte Syntax"-Warnungen anzeigt.

<?php
// PhpStorm Docker Interpreter — what PhpStorm can now do:

// 1. Type inference with container's PHP 8.4 and extensions
declare(strict_types=1);

class ProductRepository
{
    public function __construct(
        private readonly \Magento\Catalog\Model\ResourceModel\Product\CollectionFactory $collectionFactory,
        private readonly \Psr\Log\LoggerInterface $logger,
    ) {}

    // PhpStorm: knows \Magento\... classes from vendor/ in container
    // Ctrl+Click navigates to actual vendor files mounted in container
    public function findBySkus(string ...$skus): array
    {
        $collection = $this->collectionFactory->create();
        $collection->addAttributeToFilter('sku', ['in' => $skus]);
        // PhpStorm: autocomplete shows actual Magento Collection methods
        // because Docker interpreter reads vendor from container
        return $collection->getItems();
    }
}

// 2. PHP 8.4 features recognized (PHP version from container)
// Property hooks, asymmetric visibility, etc. — no false warnings

4. Composer über den Docker-Interpreter nutzen

Mit einem konfigurierten Docker-Interpreter als Standard-CLI-Interpreter nutzt PhpStorm auch Composer über den Container. Unter "Settings > PHP > Composer" wird als Interpreter der Docker-Interpreter gewählt. Wenn Composer im Container unter /usr/local/bin/composer liegt (Standard bei offiziellen PHP-Images und dem Mark-Shust-Stack), findet PhpStorm ihn automatisch.

Composer-Operationen aus dem "Tools > Composer"-Menü (Pakete hinzufügen/entfernen, composer update, Validierung) werden dann per docker compose exec phpfpm composer ... ausgeführt. Das ist exakt das gleiche wie der manuelle bin/composer-Wrapper im Mark-Shust-Stack. PhpStorm zeigt den Output im Run-Panel und aktualisiert nach Abschluss automatisch seine Indizierung, sodass neu installierte Pakete sofort navigierbar sind.

Ein praktischer Tipp: PhpStorm kann so konfiguriert werden, dass bei jedem Öffnen des Projekts geprüft wird, ob composer.json und vendor/ synchron sind. Das geschieht über "Settings > PHP > Composer > Synchronize IDE settings with composer.json: On". Wenn das Projekt nach einem git pull geöffnet wird und jemand neue Pakete hinzugefügt hat, erinnert PhpStorm automatisch daran, composer install auszuführen.

5. PHPUnit-Tests im Docker-Container ausführen

PHPUnit-Tests in Docker auszuführen erfordert eine Run Configuration, die den Docker-Interpreter verwendet. Unter "Run > Edit Configurations > Add > PHPUnit" wird im Feld "Interpreter" der Docker-Interpreter ausgewählt. PhpStorm fügt automatisch die notwendigen Volume-Mounts hinzu (um den lokalen Projektordner im Container zugänglich zu machen) und führt PHPUnit mit der Container-PHP-Version aus.

Im "PHPUnit"-Konfigurationsformular gibt es zwei Optionen für die Konfigurationsdatei: "Use configuration file" (zeigt auf phpunit.xml im Projekt) oder "Use alternative configuration" für spezifische Szenarien. Das Working Directory muss auf das Projekt-Root zeigen – PhpStorm mappt dieses automatisch in den Container. Die Test-Ergebnisse erscheinen im Test-Runner-Panel mit roter/grüner Statusanzeige, Stack-Traces und direkter Navigation zum fehlerhaften Code.

Für Magento-spezifische Tests (Integration Tests, die eine Datenbank benötigen) muss die Datenbankverbindung im Container verfügbar sein. Das bedeutet: Der db-Service muss laufen, und die Test-Konfiguration (dev/tests/integration/etc/install-config-mysql.php) muss die Container-internen Service-Namen verwenden (z.B. db als Hostname, nicht localhost). PhpStorm führt die Tests im Container-Netzwerk aus, wo diese Service-Namen auflösbar sind.

<?php
// phpunit.xml — configured for Docker interpreter execution
// PhpStorm Run Configuration picks this up automatically

// src/dev/tests/unit/phpunit.xml
/*
<?xml version="1.0"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
         bootstrap="../../../app/bootstrap.php"
         colors="true"
         stderr="true">
    <testsuites>
        <testsuite name="Mironsoft Unit Tests">
            <directory>../../../app/code/Mironsoft</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory suffix=".php">../../../app/code/Mironsoft</directory>
        </include>
    </coverage>
</phpunit>
*/

// Example unit test — runs in Docker container via PhpStorm
namespace Mironsoft\Catalog\Test\Unit\Model;

use Mironsoft\Catalog\Model\PriceCalculator;
use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\DataProvider;

class PriceCalculatorTest extends TestCase
{
    private PriceCalculator $calculator;

    protected function setUp(): void
    {
        $this->calculator = new PriceCalculator();
    }

    #[DataProvider('priceDataProvider')]
    public function testRoundingIsConsistent(float $input, float $expected): void
    {
        self::assertSame($expected, $this->calculator->round($input));
    }

    public static function priceDataProvider(): array
    {
        return [
            'standard rounding' => [10.555, 10.56],
            'no rounding needed' => [10.50, 10.50],
            'zero price' => [0.0, 0.0],
        ];
    }
}

6. XDebug mit Docker-Interpreter konfigurieren

XDebug mit dem Docker-Interpreter in PhpStorm erfordert die korrekte Konfiguration auf beiden Seiten: Im Container muss XDebug installiert und konfiguriert sein, in PhpStorm müssen der Debug-Port und die Server-Konfiguration korrekt gesetzt sein. Der häufigste Fehler ist ein fehlerhaftes Path-Mapping – PhpStorm kann den Breakpoint nicht der korrekten Datei im Container zuordnen.

XDebug-Konfiguration im Container (in conf.d/xdebug.ini oder php.ini): zend_extension=xdebug, xdebug.mode=debug, xdebug.client_host=host.docker.internal (auf Linux: Gateway-IP oder host-gateway aus extra_hosts), xdebug.client_port=9003, xdebug.start_with_request=yes (oder trigger für selektives Debugging).

In PhpStorm: "Settings > PHP > Debug > Xdebug: Debug port: 9003". Unter "Settings > PHP > Servers" einen Server anlegen mit dem Namen, der in PHP_IDE_CONFIG=serverName=... gesetzt ist. Path-Mapping: lokaler Workspace-Pfad -> Container-Pfad (/var/www/html). Dann "Run > Start Listening for PHP Debug Connections" aktivieren – PhpStorm wartet auf XDebug-Verbindungen. Beim nächsten Seitenaufruf (mit XDebug-Trigger oder start_with_request=yes) pausiert PhpStorm am ersten Breakpoint.

7. Path-Mappings verstehen und richtig setzen

Path-Mappings sind die Brücke zwischen dem Filesystem des Hosts (wo PhpStorm arbeitet) und dem Filesystem des Containers (wo PHP ausgeführt wird). Ohne korrekte Path-Mappings kann PhpStorm XDebug-Breakpoints nicht den richtigen Dateien zuordnen, und Test-Fehlermeldungen verweisen auf Container-Pfade die lokal nicht existieren.

Im Mark-Shust-Stack ist das Mapping typischerweise: lokaler Pfad /home/mir/development/mironsoft/src mappt auf Container-Pfad /var/www/html. Diese Einstellung wird in "Settings > PHP > Servers" beim jeweiligen Server-Eintrag gesetzt. Der Servername muss exakt mit dem PHP_IDE_CONFIG-Wert im Container übereinstimmen.

Ein häufiger Fehler: Der lokale Pfad zeigt auf das Repository-Root, der Container-Pfad aber auf ein Unterverzeichnis (oder umgekehrt). Wenn das Magento-src/-Verzeichnis im Container unter /var/www/html gemountet ist, muss das Path-Mapping src/ -> /var/www/html lauten, nicht . -> /var/www/html. PhpStorm zeigt in der Debug-Konsole, wenn ein Mapping fehlt, und schlägt interaktiv ein Mapping vor – das kann als Ausgangspunkt für die manuelle Korrektur genutzt werden.

8. Häufige Fehler und ihre Lösungen

9. Zusammenfassung

Der Docker-Interpreter in PhpStorm verbindet die IDE mit dem PHP-Prozess im Container – ohne lokale PHP-Installation, ohne Versions-Inkonsistenzen. Die Einrichtung erfolgt in vier Schritten: Docker-Verbindung unter "Settings > Build, Execution, Deployment > Docker" herstellen, PHP-Interpreter unter "Settings > PHP > CLI Interpreter" aus dem Docker-Compose-Service ableiten, Composer auf denselben Interpreter konfigurieren, XDebug-Port und Path-Mappings unter "Settings > PHP > Debug" und "PHP > Servers" setzen.

Path-Mappings sind der kritische Punkt bei allen Docker-basierten Interpreter-Konfigurationen: PhpStorm muss wissen, welcher lokale Verzeichnispfad welchem Container-Pfad entspricht. Ohne korrekte Mappings funktionieren XDebug-Breakpoints nicht. Mit korrekten Mappings ist der Docker-Interpreter funktional identisch zu einem lokalen Interpreter – mit dem entscheidenden Vorteil, dass er die exakte PHP-Version und Extensions des Produktions-Containers nutzt.

10. FAQ: Docker-Interpreter in PhpStorm