PhpStorm für Magento 2 einrichten: Indexing, Excludes, Performance & Autocomplete

1. Das Grundproblem: Magento 2 überfordert unkonfigurierte IDEs

Wer PhpStorm ohne jede Anpassung auf ein frisches Magento-2-Projekt zeigt, erlebt dasselbe: Die IDE beginnt zu indexieren und hört scheinbar nicht auf. Der Grund liegt in der schieren Dateimenge. Eine Standard-Magento-2-Installation mit Composer-Abhängigkeiten, generierten Factories, Interceptors und Frontend-Assets überschreitet problemlos 500.000 Dateien – und PhpStorm versucht standardmäßig, alle davon zu indizieren. Das kostet Arbeitsspeicher, CPU-Zeit und verlängert jede Suche, Code-Navigation und Completion-Anfrage messbar.

Das eigentliche Problem ist nicht Magento, sondern das Verhältnis zwischen relevantem und irrelevantem Code. Die generierten Dateien in generated/, kompilierte Assets in pub/static/, der Composer-Cache in var/cache/ und Frontend-Node-Module – all das ist für PHP-Entwicklung irrelevant. PhpStorm braucht es nicht, um Autocomplete und Navigation zu liefern. Richtig konfiguriert, arbeitet PhpStorm auch mit Magento 2 reaktionsfähig und der Autocomplete-Unterschied ist spürbar: statt generischen Typhinweisen sieht man konkrete Klassen, Interfaces und sogar generierte Factories.

2. Indexing-Excludes: Was PhpStorm nicht indexieren sollte

Der erste und wichtigste Schritt ist das Einrichten von Exclude-Verzeichnissen. In den Projekteinstellungen (File → Settings → Directories) markiert man Verzeichnisse als Excluded. PhpStorm überspringt diese vollständig beim Indexing, bei der Suche und bei Autocomplete-Anfragen. Für Magento 2 sind folgende Verzeichnisse als Excluded zu markieren: generated/, pub/static/, var/, dev/tests/ (wenn man nicht aktiv an Tests arbeitet), setup/ und update/. Node-Module in Frontend-Themes (node_modules/) ebenfalls.

Eine wichtige Feinheit: generated/code/ enthält die generierten Factories, Proxies und Interceptors. Diese sind PHP-Code, der von PhpStorm theoretisch für Autocomplete genutzt werden kann – aber es erzeugt mehr Rauschen als Nutzen. Wer DI-Autocomplete will, löst das besser über das magento-phpstorm-plugin (dazu später mehr), nicht über das Indexing generierter Dateien. Das Plugin von Magento liefert Typ-Informationen direkt aus den XML-Konfigurationsdateien, was präziser und wartungsfreundlicher ist.

// .idea/mironsoft.iml — Mark directories in PhpStorm Project Structure
// Settings → Directories → Mark as Excluded

// EXCLUDE these directories completely:
// generated/          ← generated factories, interceptors, proxies
// pub/static/         ← compiled CSS/JS, no PHP relevance
// var/                ← cache, session, log, compiled templates
// dev/tests/          ← only include when writing integration tests
// setup/              ← Magento install scripts, rarely touched
// node_modules/       ← frontend packages under any theme

// KEEP indexed (Sources Root):
// app/code/           ← custom modules
// app/design/         ← theme templates and layouts
// vendor/magento/     ← core modules for navigation
// vendor/             ← all Composer dependencies

Nach dem Setzen der Excludes lohnt es sich, den PhpStorm-Index einmal manuell zu invalidieren (File → Invalidate Caches) und die IDE neu starten zu lassen. Das initiale Indexing nach dieser Aktion dauert signifikant kürzer als zuvor und die IDE bleibt danach reaktionsfähig, weil der Index deutlich kleiner ist. Auf modernen Maschinen mit SSD ist ein vollständiges Re-Indexing nach Excludes üblicherweise in unter zwei Minuten abgeschlossen – ohne Excludes kann dasselbe Projekt zehn Minuten oder mehr benötigen.

3. PHP-Interpreter korrekt einrichten (lokal und Docker)

Ohne einen korrekt konfigurierten PHP-Interpreter kann PhpStorm keine Code-Qualitätsanalysen, kein PHPStan und keine Echtzeit-Inspection durchführen. Unter Settings → PHP → CLI Interpreter trägt man entweder den lokalen PHP-Binary-Pfad ein oder – bei Docker-Setup wie dem Mark-Shust-Setup – einen Docker-Interpreter. Bei Docker wählt man From Docker, Vagrant, VM... und verbindet PhpStorm mit dem PHP-Container. Wichtig: Den richtigen PHP-Container auswählen, nicht den Nginx- oder MariaDB-Container.

Für das Mark-Shust-Docker-Setup bedeutet das konkret: Den Service phpfpm oder den passenden PHP-Container-Namen aus der compose.yaml auswählen. PhpStorm liest automatisch die PHP-Version aus dem Container und ermittelt installierte Extensions. Das ist wichtig, weil Magento 2.4.x spezifische Extensions wie ext-intl, ext-soap und ext-gd benötigt und PhpStorm diese für korrekte Code-Analyse kennen muss. Ein falsch konfigurierter Interpreter führt dazu, dass die IDE Extension-Aufrufe als Fehler markiert, obwohl sie im Container korrekt laufen.

4. DI-Autocomplete: Interfaces und virtuelle Typen auflösen

Magentos Dependency-Injection-System trennt Interface von Implementierung über di.xml. Wenn ein Controller ProductRepositoryInterface im Konstruktor erhält, weiß PhpStorm ohne zusätzliche Information nicht, welche konkrete Klasse dahintersteckt – und liefert damit nur die Methoden des Interface, nicht die der Implementierung. Das Magento PHPStorm Plugin (verfügbar im JetBrains Marketplace) löst dieses Problem, indem es di.xml-Preferences und virtuelle Typen auswertet und PhpStorm entsprechende Typ-Mappings liefert.

Nach der Installation des Plugins erscheint unter Settings → PHP → Frameworks → Magento ein Konfigurationsbereich. Dort trägt man den Magento-Root-Pfad ein und aktiviert die Framework-Unterstützung. Ab diesem Moment navigiert PhpStorm von einem Interface-Typ im Konstruktor direkt zur konfigurierten Implementierung – inklusive Ctrl+Click-Navigation. Factories wie ProductFactory werden ebenfalls korrekt aufgelöst, auch wenn die Klasse nur als generierte Datei existiert und nicht im Quellcode liegt.

<?php
declare(strict_types=1);

namespace Mironsoft\Catalog\Model;

use Magento\Catalog\Api\ProductRepositoryInterface;
use Magento\Catalog\Model\ProductFactory;
use Magento\Framework\App\Config\ScopeConfigInterface;

/**
 * Product service demonstrating DI autocomplete in PhpStorm.
 * With the Magento PHPStorm Plugin installed, PhpStorm resolves:
 * - ProductRepositoryInterface → Magento\Catalog\Model\ProductRepository
 * - ProductFactory → generated/code/Magento/Catalog/Model/ProductFactory.php
 * - ScopeConfigInterface → Magento\Framework\App\Config
 */
class ProductService
{
    public function __construct(
        private readonly ProductRepositoryInterface $productRepository,
        private readonly ProductFactory $productFactory,
        private readonly ScopeConfigInterface $scopeConfig,
    ) {}

    /**
     * Load product by SKU with full autocomplete on return type.
     */
    public function getBySku(string $sku): \Magento\Catalog\Api\Data\ProductInterface
    {
        // PhpStorm knows the exact return type — navigation works
        return $this->productRepository->get($sku);
    }
}

5. Plugin-Autocomplete und Interceptor-Navigation

Magentos Plugin-System (Interceptors) ist einer der Bereiche, in dem PhpStorm ohne spezifische Unterstützung blind ist. Ein Plugin definiert before-, after- oder around-Methoden für Methoden einer anderen Klasse. Die Verbindung zwischen Plugin und Zielklasse ist nur in di.xml definiert – PhpStorm findet sie ohne Hilfe nicht. Das Magento PHPStorm Plugin zeigt in der Gutter (linke Randleiste des Editors) Icons an, die von einer Methode direkt zu allen ihr zugeordneten Plugins navigieren, und umgekehrt.

Bei der Entwicklung eigener Plugins ist es wichtig, die korrekten Methodensignaturen zu kennen. Ein beforeMethod-Plugin erhält als ersten Parameter das Subjekt (die Zielklasse) und danach die originalen Methodenparameter. Ein aroundMethod-Plugin erhält zusätzlich ein callable $proceed. PhpStorm generiert diese Signaturen bei aktiviertem Plugin korrekt via Code-Completion, wenn man den Methodennamen eintippt. Ohne Plugin muss man die Signaturen manuell nachschlagen – ein echter Produktivitätsverlust bei häufiger Plugin-Entwicklung.

6. Memory-Limits und IDE-Performance-Tuning

PhpStorm läuft auf der JVM und benötigt bei großen Projekten wie Magento ausreichend Heap-Speicher. Der Standard-Wert von 750 MB reicht für Magento 2 nicht aus – 2 GB sind ein sinnvoller Ausgangspunkt, 4 GB empfehlenswert für Entwicklungsmaschinen mit 16+ GB RAM. Die Einstellung findet sich unter Help → Edit Custom VM Options: -Xmx4096m setzt das Maximum auf 4 GB. Nach einem Neustart der IDE merkt man den Unterschied sofort an der Reaktionsgeschwindigkeit von Autocomplete und Suche.

Zusätzlich lohnt es sich, unter Settings → Appearance & Behavior → System Settings die Anzahl der im Hintergrund laufenden Indexing-Threads zu begrenzen. Auf Entwicklungsmaschinen mit parallelen Docker-Containern kann aggressives Hintergrund-Indexing die CPU so belasten, dass andere Prozesse leiden. Eine weitere Optimierung: Den PhpStorm-System-Temp-Ordner auf eine SSD legen oder explizit in idea.system.path konfigurieren, sodass der Index-Cache auf dem schnellsten Laufwerk liegt.

7. Code-Style-Konfiguration für Magento-Coding-Standards

Magento 2 folgt weitgehend dem PSR-12-Standard mit einigen Erweiterungen. PhpStorm lässt sich so konfigurieren, dass es automatisch formatiert und Code-Style-Verstöße als Warnungen anzeigt. Unter Settings → Editor → Code Style → PHP importiert man ein vorgefertigtes Schema oder passt manuell an: 4 Spaces Einrückung, keine Tabs, Zeilenenden LF, maximale Zeilenlänge 120 Zeichen. Die wichtigste Einstellung für Magento-Entwicklung: Blank lines → Around class body auf 1, und Method/Function Body entsprechend der Magento-Konventionen.

Für automatische Formatierung on-save aktiviert man Settings → Tools → Actions on Save → Reformat Code. Das stellt sicher, dass kein Commit mit falsch formatiertem Code in das Repository geht. In Verbindung mit phpcs und dem Magento Coding Standard Ruleset kann PhpStorm zusätzlich direkt im Editor Verstöße anzeigen: Unter Settings → PHP → Quality Tools → PHP_CodeSniffer trägt man den Pfad zum phpcs-Binary und das Ruleset Magento2 ein. Ab diesem Moment erscheinen Coding-Standard-Verstöße als gelbe oder rote Unterstreichungen direkt im Code.

8. Path-Mappings für Docker-Deployments

Bei der Arbeit mit Docker-Setups (wie dem Mark-Shust-Setup) liegen Dateien auf dem lokalen Rechner unter einem anderen Pfad als im Container. PhpStorm muss diese Abweichung kennen, um Xdebug-Sessions korrekt zuzuordnen. Ohne Path-Mappings zeigt PhpStorm bei Xdebug-Breakpoints an, dass es die Datei nicht finden kann – weil der Container-Pfad /var/www/html/ nicht mit dem lokalen Projektpfad übereinstimmt. Die Path-Mappings werden unter Settings → PHP → Servers eingetragen.

Für das Mark-Shust-Setup bedeutet das: Einen Server mironsoft.de anlegen, Host und Port eintragen und unter Path Mappings den lokalen Pfad /home/mir/development/mironsoft/src auf den Container-Pfad /var/www/html mappen. Damit kann PhpStorm Xdebug-Breakpoints korrekt setzen, Stack-Traces auflösen und Remote-Debugging-Sessions vollständig nutzen. Dieselben Path-Mappings werden auch für Remote-PHPUnit-Konfigurationen und für das Ausführen von phpcs im Container benötigt.

<?php
// PhpStorm Path Mapping example for Mark Shust Docker setup
// Settings → PHP → Servers → mironsoft.de

// Local path:     /home/mir/development/mironsoft/src
// Container path: /var/www/html

// .env configuration for Xdebug in Docker:
// XDEBUG_MODE=debug
// XDEBUG_CONFIG="client_host=host.docker.internal client_port=9003"
// XDEBUG_SESSION=PHPSTORM

// In PhpStorm: Settings → PHP → Debug
// Debug Port: 9003
// Server name: mironsoft.de (must match PHP_IDE_CONFIG server name)

// bin/xdebug enable  ← Mark Shust wrapper to toggle Xdebug
// After enabling: restart fpm container, PhpStorm listens on 9003

// Verify mapping works:
// 1. Set breakpoint in Magento\Framework\App\Http::launch()
// 2. Open browser with ?XDEBUG_SESSION=1
// 3. PhpStorm should pause at breakpoint with full variable inspection

9. Konfiguration mit und ohne Optimierung im Vergleich

Der Unterschied zwischen einem unkonfigurierten und einem optimierten PhpStorm-Setup für Magento 2 ist in der täglichen Arbeit deutlich spürbar. Die folgende Tabelle fasst die wichtigsten Unterschiede zusammen und zeigt, welche Einstellungen den größten Effekt haben.

Die Zahlen in der Tabelle sind nicht theoretisch – sie stammen aus der tatsächlichen Einrichtung von PhpStorm auf Magento-2-Projekten. Der größte Einzelgewinn kommt von den Excludes: Wer die generierten Verzeichnisse und den var/-Ordner aus dem Index ausschließt, halbiert oder drittelt die Indexing-Zeit und verbessert die Autocomplete-Geschwindigkeit spürbar. Das Magento PHPStorm Plugin ist der zweite große Schritt, weil es die DI-Auflösung ermöglicht, die Magento ohne Plugin-Unterstützung grundsätzlich verschleiert.

10. Zusammenfassung

Eine gut konfigurierte PhpStorm-Installation für Magento 2 unterscheidet sich in drei Hauptbereichen von einer Standard-Installation: Indexing-Excludes, DI-Autocomplete und Path-Mappings. Die Excludes für generated/, pub/static/ und var/ reduzieren die indizierte Dateimenge drastisch und machen den Index aktuell und präzise. Das Magento PHPStorm Plugin löst die DI-Verbindung zwischen Interface und Implementierung auf und ermöglicht echte Code-Navigation in einem Framework, das seinen Abhängigkeitsgraph vollständig in XML definiert. Path-Mappings verbinden lokale Dateien mit dem Docker-Container und machen Remote-Debugging mit Xdebug nutzbar.

Zusammen verwandeln diese drei Konfigurationsschritte PhpStorm von einem überforderten Editor in eine echte IDE für Magento. Autocomplete, das konkrete Klassen kennt, Navigation, die Interfaces auf Implementierungen auflöst, und ein Debugger, der im Docker-Container bricht – das sind keine Extras, sondern Grundvoraussetzungen für produktive Magento-2-Entwicklung. Die initiale Investition von einer Stunde Konfigurationsarbeit zahlt sich täglich aus.

11. FAQ: PhpStorm für Magento 2 einrichten