Magento Dev-Umgebung in PhpStorm: Docker, CLI, Logs & Templates

1. Warum PhpStorm für Magento 2 ein Unterschied macht

Magento 2 ist eines der komplexesten PHP-Frameworks auf dem Markt. Dependency Injection, Service Contracts, Plugins, Observers, ViewModels und ein tiefes Verzeichnisbaum-System mit generierten Klassen machen das manuelle Navigieren ohne IDE-Unterstützung ineffizient. PhpStorm kennt das Magento-Konzept aus dem Kasten heraus: das Magento PhpStorm Plugin (JetBrains Marketplace) bietet Navigation von XML-Konfigurationen zu Klassen, von Interface-Deklarationen zu konkreten Implementierungen und von Plugin-Definitionen zu den betroffenen Methoden.

Der entscheidende Unterschied liegt im Zusammenspiel mehrerer Features: ein korrekt konfigurierter Docker-PHP-Interpreter stellt sicher, dass Code-Completion auf dem tatsächlich im Container laufenden PHP basiert – inklusive aller Magento-Klassen aus vendor/ und generated/. Ohne diesen Schritt arbeitet PhpStorm mit einer lokalen PHP-Installation, die womöglich eine andere Version hat und keine Magento-Bibliotheken kennt. Das Ergebnis sind unvollständige Autovervollständigungen und fehlende Typ-Warnungen genau dort, wo sie am wichtigsten wären.

Xdebug eliminiert das zeitraubende var_dump-Debugging vollständig. Ein Breakpoint gesetzt, Request im Browser ausgelöst – PhpStorm stoppt die Ausführung an der genauen Stelle, zeigt alle Variablen mit ihren aktuellen Werten und erlaubt schrittweises Durchlaufen des Magento-Request-Flows. Gerade beim Verstehen von Plugin-Chains, Observer-Reihenfolgen und DI-Auflösungen ist das unersetzlich.

2. Docker als PHP-Interpreter einrichten

Der erste Schritt ist die Verbindung von PhpStorm mit dem laufenden PHP-Container. Über Settings → PHP → CLI Interpreter → + → From Docker, Vagrant... wählt man den Docker-Service aus. Beim Mark-Shust-Setup ist das der phpfpm-Container. PhpStorm liest die docker-compose.yaml im Projektverzeichnis und listet alle definierten Services auf. Nach Auswahl von phpfpm und Klick auf Detect erkennt die IDE die PHP-Version, installierte Extensions und den Pfad zur php.ini.

Wichtig: im Dialog Path Mappings muss der lokale Projektpfad auf den Container-Pfad gemappt werden. Beim Mark-Shust-Setup ist das typischerweise /home/user/development/projekt → /var/www/html. Ohne dieses Mapping findet PhpStorm keine Dateien im Container und Debugging schlägt fehl. Nach dem Speichern sollte PhpStorm im PHP-Settings-Bereich die korrekte PHP-Version anzeigen – bei Magento 2.4.8 ist das PHP 8.4.

Sobald der Interpreter eingerichtet ist, indiziert PhpStorm alle PHP-Klassen im Projekt inklusive vendor/. Dieser erste Indizierungsvorgang dauert je nach Projektgröße mehrere Minuten. Danach stehen Navigate-to-Class (Ctrl+N), Navigate-to-Symbol (Ctrl+Alt+Shift+N) und vollständige Code-Completion für alle Magento-Klassen zur Verfügung.

3. Xdebug mit Docker konfigurieren und nutzen

Xdebug ist im Mark-Shust-Setup bereits im Container verfügbar und wird über das Wrapper-Skript bin/xdebug enable aktiviert. Auf PhpStorm-Seite muss unter Settings → PHP → Debug der Port auf 9003 (Xdebug 3) eingestellt werden. Der Debug Port muss mit dem in der xdebug.ini konfigurierten xdebug.client_port übereinstimmen. In der Mark-Shust-Umgebung ist die relevante Konfigurationsdatei unter env/php.ini zu finden.

Für Web-Debugging aktiviert man in PhpStorm den Listen for Debug Connections-Schalter (Telefon-Icon in der Toolbar oder Ctrl+Alt+F5). Im Browser benötigt man eine Xdebug-Browser-Extension (Xdebug Helper für Chrome/Firefox), die das Debug-Cookie XDEBUG_SESSION setzt. Alternativ funktioniert der URL-Parameter ?XDEBUG_SESSION_START=PHPSTORM. Beim ersten Treffer auf einen Breakpoint fragt PhpStorm nach dem Path Mapping – hier nochmals /var/www/html → lokales Projektverzeichnis angeben.

; env/php.ini — Xdebug 3 configuration for Mark Shust Docker setup
[xdebug]
xdebug.mode = debug,develop
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.start_with_request = yes
xdebug.idekey = PHPSTORM
xdebug.log_level = 0

; For CLI debugging (bin/debug-cli enable)
; xdebug.start_with_request = trigger
; then use: XDEBUG_SESSION=1 bin/magento some:command

Für CLI-Debugging mit Magento-Befehlen aktiviert man bin/debug-cli enable. Danach stoppt PhpStorm bei CLI-Ausführungen von bin/magento-Befehlen an gesetzten Breakpoints. Das ist besonders wertvoll beim Debuggen von Upgrade-Skripten, Daten-Patchern und Custom-CLI-Commands. Wichtig: nach dem Debugging bin/xdebug disable ausführen, da Xdebug im aktivierten Zustand Performance signifikant beeinflusst.

4. CLI-Tools und Run-Konfigurationen

PhpStorm erlaubt das Anlegen von Run-Konfigurationen, die direkt im Container ausgeführt werden. Über Run → Edit Configurations → + → PHP Script erstellt man Konfigurationen für häufig benötigte Magento-Befehle. Als Interpreter wählt man den Docker-Container, als Skript /var/www/html/bin/magento und als Parameter den gewünschten Befehl – etwa cache:flush, setup:di:compile oder indexer:reindex. Diese Konfigurationen sind im .idea-Verzeichnis gespeichert und können ins Repository eingecheckt werden.

Noch produktiver ist das Terminal-Feature von PhpStorm (Alt+F12). Das integrierte Terminal öffnet direkt im Projektverzeichnis und erlaubt die Verwendung aller bin/-Wrapper-Skripte ohne Fensterwechsel. PhpStorm färbt die Terminal-Ausgabe und unterstützt mehrere parallele Terminal-Tabs. Die Kombination aus Run-Konfigurationen für häufige Befehle und dem integrierten Terminal für alles andere deckt den gesamten Magento-CLI-Workflow ab.

5. Logs direkt in PhpStorm lesen

Magento-Logs in var/log/ zu beobachten ist im täglichen Entwicklungsalltag unvermeidlich. PhpStorm bietet über Run/Debug Configurations → Logs die Möglichkeit, Log-Dateien direkt in der IDE zu überwachen. Die relevanten Dateien sind var/log/system.log, var/log/exception.log und bei Hyvä-Projekten auch var/log/debug.log. PhpStorm öffnet einen Log-Tab, der neue Einträge in Echtzeit anzeigt und nach Suchbegriffen filtert.

Alternativ nutzt man das File Watcher-Feature oder einfach das Terminal mit bin/log exception.log. Für strukturiertere Log-Analyse bietet sich das PhpStorm Log File Viewer-Plugin an, das JSON-Logs aufbereitet darstellt. Bei Magento ist es sinnvoll, den Log-Level in der Entwicklungsumgebung auf DEBUG zu setzen, um alle Datenbankabfragen, Cache-Operationen und Plugin-Aufrufe zu verfolgen.

6. File-Templates für Magento-Artefakte

Magento-Artefakte folgen strikten Konventionen: ViewModels implementieren ArgumentInterface und nutzen Constructor Property Promotion, Plugins müssen bestimmte Methodenpräfixe einhalten, Repositories implementieren Service-Contract-Interfaces. Diese Konventionen bei jedem neuen File von Hand einzutippen kostet Zeit und führt zu Flüchtigkeitsfehlern. File-Templates in PhpStorm lösen das: über Settings → Editor → File and Code Templates erstellt man wiederverwendbare Vorlagen mit Variablen für Namespace, Klassenname und Modul-Prefix.

Ein ViewModel-Template enthält bereits den korrekten Namespace-Aufbau, die implements ArgumentInterface-Deklaration, einen Beispiel-Constructor mit Property Promotion und PHPDoc-Kommentare. Beim Erstellen einer neuen Klasse über File → New → PHP Class (ViewModel) fragt PhpStorm nur noch nach dem Klassennamen und füllt alle anderen Felder aus dem Template. Das reduziert die Zeit für das Anlegen eines neuen ViewModels von zwei Minuten auf zehn Sekunden.

<?php
/**
 * ViewModel for ${NAME}
 *
 * Provides data and logic for ${NAME} template.
 * Implements ArgumentInterface as required by Magento ViewModel pattern.
 */

declare(strict_types=1);

namespace ${NAMESPACE};

use Magento\Framework\View\Element\Block\ArgumentInterface;

/**
 * Class ${NAME}
 *
 * @package ${NAMESPACE}
 */
class ${NAME} implements ArgumentInterface
{
    /**
     * ${NAME} constructor.
     *
     * @param \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig
     */
    public function __construct(
        private readonly \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig,
    ) {}

    /**
     * Example method — replace with actual business logic.
     *
     * @return bool
     */
    public function isEnabled(): bool
    {
        return (bool) $this->scopeConfig->getValue(
            'mironsoft_module/general/enabled',
            \Magento\Store\Model\ScopeInterface::SCOPE_STORE,
        );
    }
}

7. Live-Templates für wiederkehrende Muster

Live-Templates (Snippets) sind der nächste Produktivitätsschritt nach File-Templates. Während File-Templates komplette Dateien erzeugen, fügen Live-Templates Code-Fragmente an der Cursor-Position ein. In PhpStorm unter Settings → Editor → Live Templates erstellt man Gruppen für Magento und befüllt sie mit häufig benötigten Mustern. Die Abkürzung mvm expandiert zum vollständigen ViewModel-Constructor mit Property Promotion, mpl zur Plugin-Methoden-Signatur mit Before/After-Prefix und mobs zum Observer-Grundgerüst.

Live-Templates unterstützen Variablen und Funktionen. Die Variable $CLASS_NAME$ kann automatisch aus dem aktuellen Klassennamen befüllt werden, $DATE$ fügt das aktuelle Datum ein. Besonders nützlich ist das Live-Template für Magento-Logger-Aufrufe: mlog expandiert zu $this->logger->debug(__METHOD__ . ': ', ['data' => $variable]); – vollständig mit __METHOD__-Kontext, der beim späteren Log-Lesen sofort zeigt, aus welcher Methode der Eintrag stammt.

8. Code-Style und Inspections für Magento

Magento folgt dem PSR-2-Standard mit einigen projektspezifischen Erweiterungen. In PhpStorm unter Settings → Editor → Code Style → PHP importiert man das Magento-Code-Style-Schema, das im Magento-Repository als .phpstorm.meta.php und PhpStorm-Einstellungsdatei verfügbar ist. Die Einstellung Reformat Code (Ctrl+Alt+L) formatiert dann jede Datei konsistent nach dem Magento-Standard. Für automatisches Formatieren beim Speichern aktiviert man Actions on Save → Reformat code.

Die PHP Inspections in PhpStorm ergänzt man mit dem PHP Inspections (EA Extended)-Plugin aus dem JetBrains Marketplace. Dieses Plugin erkennt Magento-spezifische Anti-Patterns: direkte Objektinstanziierung statt Dependency Injection, fehlende declare(strict_types=1)-Deklaration und zu breite Exceptions im Catch-Block. Diese Warnings direkt im Editor zu sehen, bevor PHPStan im CI-Lauf sie meldet, beschleunigt die Entwicklung erheblich.

9. Workflow-Vergleich: mit und ohne PhpStorm-Setup

Der Unterschied zwischen einem unkonfigurierten PhpStorm und einer vollständig eingerichteten Magento-Umgebung ist messbar. Während man ohne Konfiguration für jede Klassen-Navigation manuell im Finder oder Explorer nach der Datei sucht, springt man mit Navigate-to-Class in Millisekunden zum Ziel. Xdebug ersetzt stundenlange var_dump-Sessions durch gezielte Breakpoints.

Addiert man diese Einsparungen über einen typischen Arbeitstag mit fünf bis zehn Debugging-Zyklen, einer Handvoll neuer Klassen und zahlreichen Cache-Flush-Operationen, kommt man schnell auf ein bis zwei Stunden täglich, die durch eine korrekt eingerichtete PhpStorm-Umgebung gewonnen werden. Auf Wochen- und Monatssicht ist das ein erheblicher Produktivitätsgewinn, der die Einrichtungszeit vielfach amortisiert.

10. Zusammenfassung

Eine vollständig eingerichtete PhpStorm-Umgebung für Magento 2 besteht aus mehreren Schichten, die zusammen einen erheblichen Produktivitätsvorteil erzeugen. Der Docker-PHP-Interpreter stellt sicher, dass Code-Completion und Typ-Prüfungen auf der tatsächlich verwendeten PHP-Version basieren. Xdebug ersetzt das mühsame var_dump-Debugging durch präzise Breakpoints mit vollständiger Variablen-Inspektion. Run-Konfigurationen machen häufige Magento-Befehle über einen Tastendruck erreichbar. File-Templates garantieren, dass neue Artefakte von Anfang an der Magento-Konvention entsprechen.

Der Aufwand für die initiale Einrichtung beträgt ein bis zwei Stunden. Danach amortisiert sich dieser Aufwand täglich durch eingesparte Debugging-Zeit, schnellere Navigation und weniger Konventionsfehler. Wer die Einstellungen – Run-Konfigurationen, Code-Style-Profile und File-Templates – ins .idea-Verzeichnis des Repositories eincheckt, gibt diesem Produktivitätsgewinn an alle Teammitglieder weiter, ohne dass jede Person die Einrichtung selbst durchlaufen muss.

11. FAQ: PhpStorm Magento Dev-Umgebung