Magento-spezifische PhpStorm-Einstellungen: generated, vendor, Tests & Templates

1. Die Besonderheiten von Magento im IDE-Kontext

Ein frisches Magento-2-Projekt hat nach der Installation mehrere zehntausend PHP-Dateien – allein im vendor/-Verzeichnis liegen die Bibliotheken für Magento Core, Composer-Abhängigkeiten und Drittanbieter-Module. Hinzu kommen die generierten Klassen in generated/: Proxies, Interceptors und Factories, die Magento beim ersten Seitenaufruf oder bei setup:di:compile erzeugt. PhpStorm versucht standardmäßig, alle diese Dateien zu indizieren – was einerseits Code-Completion verbessert, andererseits die IDE spürbar verlangsamen kann.

Die Herausforderung liegt im richtigen Gleichgewicht: zu viel ausschließen bedeutet fehlende Code-Completion und falsche Fehler-Markierungen. Zu wenig ausschließen bedeutet eine träge IDE, die bei jeder Änderung Minuten für die Reindizierung braucht. Das Directories-Feature von PhpStorm (Modul-Einstellungen) erlaubt die präzise Kontrolle darüber, welche Verzeichnisse als Source-Root gelten, welche nur als Libraries indiziert werden und welche komplett ausgeschlossen sind.

Magento-Tests spielen in drei Schichten: Unit-Tests in dev/tests/unit/, Integration-Tests in dev/tests/integration/ und API-Functional-Tests in dev/tests/api-functional/. Jede Schicht hat eine eigene phpunit.xml.dist, eigene Bootstrap-Dateien und unterschiedliche Anforderungen an die laufende Umgebung. PhpStorm kann alle drei Schichten ausführen, aber nur wenn die Run-Konfigurationen korrekt auf die jeweilige Bootstrap-Datei zeigen.

2. Directories: Sources, Tests und Excluded richtig setzen

Die wichtigste Konfiguration für ein Magento-Projekt in PhpStorm findet sich unter Rechtsklick auf das Projekt → Modul-Einstellungen → Sources. Hier definiert man für jeden Verzeichnistyp die korrekte Rolle. Das src/-Verzeichnis (oder das Magento-Root) ist der Source Root. Die Verzeichnisse dev/tests/unit/, dev/tests/integration/ und alle Test/-Unterverzeichnisse in Modulen werden als Test Source Root markiert. Damit trennt PhpStorm produktiven Code von Test-Code und bietet in Test-Dateien test-spezifische Inspections und Navigation.

Als Excluded markiert man Verzeichnisse, die PhpStorm gar nicht indizieren soll: var/, pub/static/, pub/media/, dev/tests/api-functional/ (wenn kein API-Testing geplant ist) und temporäre Verzeichnisse. Diese Ausschlüsse reduzieren den Speicherverbrauch des PhpStorm-Index und beschleunigen die Suche erheblich, weil irrelevante Dateien nicht durchsucht werden. Das node_modules/-Verzeichnis in Hyvä-Themes sollte ebenfalls ausgeschlossen werden.

<?php
/**
 * Example: Test bootstrap configuration for Magento Unit Tests.
 * PhpStorm Run Configuration points to this file via:
 * Settings → PHP → Test Frameworks → PHPUnit → Path to script
 *
 * File: dev/tests/unit/framework/bootstrap.php (Magento default)
 * Custom modules bootstrap at: app/code/Vendor/Module/Test/Unit/
 */

declare(strict_types=1);

// Magento unit test bootstrap — do not modify, set via PhpStorm config
define('BP', dirname(__DIR__, 4));
define('TESTS_TEMP_DIR', BP . '/dev/tests/unit/tmp');

// Register Magento autoloader for unit tests
require_once BP . '/vendor/autoload.php';

// Initialize test environment
\Magento\Framework\TestFramework\Unit\Helper\Bootstrap::setObjectManagerFactory(
    new \Magento\TestFramework\ObjectManager\Factory()
);

3. generated/-Code: indizieren oder ausschließen?

Das generated/-Verzeichnis enthält automatisch erzeugte Klassen, die Magento für jede konkrete Implementierung generiert. Proxies ermöglichen Lazy-Loading, Interceptors realisieren das Plugin-System und Factories erzeugen neue Instanzen über den ObjectManager. Diese Klassen sind nicht zur manuellen Bearbeitung bestimmt, aber sie sind essential für das Verständnis des Magento-DI-Systems und für korrekte Code-Completion.

Die Empfehlung: generated/ als Sources Root markieren, aber nicht als reguläres Source-Verzeichnis – sondern als zusätzliche Library. Damit findet PhpStorm die generierten Klassen für Code-Completion und Navigation, markiert sie aber nicht als eigene Projektdateien. Konkret: Modul-Einstellungen → Sources → generated/-Verzeichnis als Sources Root markieren. PhpStorm kann dann von einer SomeClass\Proxy-Referenz direkt zur generierten Datei springen, ohne Fehler zu melden.

Wichtig: generated/ muss nach jedem bin/magento setup:di:compile neu indiziert werden. PhpStorm erkennt Dateiänderungen automatisch und löst die Reindizierung aus, aber bei sehr großen Projekten kann es sinnvoll sein, die Reindizierung manuell über File → Invalidate Caches / Restart anzustoßen, wenn nach einem Compile-Lauf die Code-Completion unvollständig erscheint.

4. vendor/ effizient navigieren

Das vendor/-Verzeichnis eines Magento-Projekts enthält den Magento-Core und alle Abhängigkeiten – insgesamt mehrere Gigabyte PHP-Code. PhpStorm indiziert dieses Verzeichnis vollständig als Library, was die vollständige Code-Completion für alle Magento-Core-Klassen ermöglicht. Die Navigate-to-Class-Funktion (Ctrl+N) findet jede Core-Klasse sofort, auch wenn sie tief in der Vendor-Hierarchie liegt.

Für die tägliche Arbeit besonders wichtig: Go to Declaration (Ctrl+B) springt von einem Interface zu seiner Implementierung, auch wenn diese in vendor/ liegt und über die DI-Konfiguration aufgelöst wird. Das Magento PhpStorm Plugin erweitert diese Navigation um die DI-XML-Auflösung: von einer prefer-Konfiguration in di.xml springt man direkt zur Implementierungsklasse. Diese bidirektionale Navigation – von Code zu Konfiguration und zurück – ist einer der größten Vorteile des Magento-Plugins gegenüber einem einfachen PHP-Editor.

5. PHPUnit für Magento-Tests einrichten

Magento-Unit-Tests laufen mit PHPUnit und einer eigenen Bootstrap-Datei. In PhpStorm konfiguriert man PHPUnit unter Settings → PHP → Test Frameworks → + → PHPUnit by Remote Interpreter (wenn ein Docker-Interpreter eingerichtet ist). Als Path to phpunit.phar or script gibt man den Pfad zur phpunit-Binär-Datei im Docker-Container an: /var/www/html/vendor/bin/phpunit. Als Default Configuration File wählt man /var/www/html/dev/tests/unit/phpunit.xml.dist.

Nach dieser Konfiguration erscheint neben jeder Test-Methode ein grünes Play-Icon in der Gutter. Ein Klick darauf führt diesen einzelnen Test aus, ohne die gesamte Test-Suite zu starten. Das ist für die Magento-Entwicklung wertvoll, weil die vollständige Unit-Test-Suite mehrere Minuten laufen kann. Einzelne Tests für eine neu geschriebene Methode laufen in Sekunden und geben sofortiges Feedback direkt im Editor.

<?php
/**
 * Example Magento Unit Test using PhpStorm test runner.
 * Run this with the green gutter icon or via Run → Run 'Test'.
 * PhpStorm shows pass/fail directly in the test window.
 */

declare(strict_types=1);

namespace Mironsoft\Module\Test\Unit\Model;

use Mironsoft\Module\Model\PriceCalculator;
use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\MockObject\MockObject;
use Magento\Framework\App\Config\ScopeConfigInterface;

/**
 * Unit test for PriceCalculator model.
 */
class PriceCalculatorTest extends TestCase
{
    private PriceCalculator $calculator;
    private MockObject&ScopeConfigInterface $scopeConfigMock;

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

    /**
     * @dataProvider priceProvider
     */
    public function testCalculateDiscountedPrice(float $base, float $discount, float $expected): void
    {
        $this->scopeConfigMock->method('getValue')->willReturn((string)$discount);
        $result = $this->calculator->calculateDiscountedPrice($base);
        self::assertEqualsWithDelta($expected, $result, 0.001);
    }

    public static function priceProvider(): array
    {
        return [
            'ten percent off 100'  => [100.0, 10.0, 90.0],
            'twenty percent off 50' => [50.0, 20.0, 40.0],
            'zero discount'        => [75.0, 0.0, 75.0],
        ];
    }
}

6. Integration- und API-Tests in PhpStorm ausführen

Magento-Integration-Tests erfordern eine laufende Datenbank und eine separate Magento-Installation im Testmodus. Die install-config-mysql.php in dev/tests/integration/etc/ enthält die Datenbankverbindung für die Testdatenbank. In der Mark-Shust-Docker-Umgebung legt man eine zweite Datenbank für Integration-Tests an und trägt diese in der Konfigurationsdatei ein. PhpStorm führt die Tests dann über eine separate Run-Konfiguration aus, die auf die dev/tests/integration/phpunit.xml.dist zeigt.

Integration-Tests in Magento sind mit @magentoDbIsolation enabled und @magentoDataFixture-Annotationen ausgestattet. PhpStorm erkennt diese PHPDoc-Annotationen und bietet Autovervollständigung für Fixture-Pfade. Das Ausführen von Integration-Tests dauert deutlich länger als Unit-Tests, weil sie die vollständige DI-Auflösung und Datenbankoperationen einschließen. Für die Entwicklung empfiehlt sich, Integration-Tests in der CI-Pipeline auszuführen und lokal nur die betroffenen Test-Klassen direkt über PhpStorm zu starten.

7. phtml-Templates: Syntax-Highlighting und Navigation

Magento-Templates haben die Endung .phtml und enthalten PHP-Code, der direkt in HTML eingebettet ist. PhpStorm erkennt .phtml-Dateien standardmäßig als PHP-Dateien und bietet vollständiges Syntax-Highlighting und Code-Completion auch innerhalb von eingebetteten PHP-Tags. Für Hyvä-Themes mit Alpine.js-Direktiven ist es zusätzlich sinnvoll, das Alpine.js-PhpStorm-Plugin zu installieren, das x-data, x-on und andere Alpine-Direktiven im HTML kennt.

Eine praktische Einstellung: unter Settings → Editor → File Types die Zuordnung von *.phtml zu dem PHP-File-Type prüfen. Falls phtml-Dateien als unbekannter Typ erkannt werden, fügt man die Erweiterung manuell hinzu. Für Tailwind-CSS-Klassen in phtml-Templates bietet das Tailwind CSS-Plugin Autovervollständigung – vorausgesetzt, die Tailwind-Konfigurationsdatei liegt im Projektroot oder im Theme-Verzeichnis und wurde einmalig erkannt.

8. Magento XML-Konfigurationen in PhpStorm navigieren

Magento 2 verwendet XML-Konfiguration für fast jeden Aspekt des Systems: di.xml für Dependency Injection, events.xml für Observer, routes.xml für Routing, layout.xml und default.xml für das Layout-System. Das Magento PhpStorm Plugin reichert PhpStorm mit Verständnis dieser XML-Schemas an. In einer di.xml kann man von einem type name="SomeClass"-Attribut direkt zur PHP-Klasse springen. In einer plugin-Konfiguration springt man zur Plugin-Klasse und von dort zur betroffenen Methode der Originalklasse.

PhpStorm bietet für XML-Dateien auch Structure-View (Alt+7), der die Hierarchie der XML-Elemente übersichtlich darstellt. Bei großen di.xml-Dateien mit hunderten von Einträgen navigiert man so schnell zu dem gewünschten Plugin oder Preference, ohne manuell durch das Dokument zu scrollen. Find Usages (Alt+F7) auf einem Klassennamen in einer XML-Datei zeigt alle anderen XML-Konfigurationen, die diese Klasse referenzieren – eine wichtige Funktion beim Refactoring von Klassen, die an mehreren Stellen konfiguriert sind.

9. Konfigurationsvergleich: Standard vs. Magento-optimiert

Ein direkter Vergleich zwischen Standard-PhpStorm-Konfiguration und einer für Magento optimierten Konfiguration zeigt die konkreten Unterschiede in täglichen Workflows.

Die Summe dieser Konfigurationsschritte macht eine erhebliche Qualitätsdifferenz aus. Eine unoptimierte PhpStorm-Konfiguration für Magento ist nicht nur langsamer, sie zeigt auch falsche Fehler (fehlende generierte Klassen), findet Typen nicht (weil var/ durchsucht wird statt generated/) und erlaubt keine direkte Test-Ausführung. Die Investition von ein bis zwei Stunden in die Konfiguration zahlt sich täglich aus.

10. Zusammenfassung

Die magento-spezifische PhpStorm-Konfiguration besteht aus mehreren aufeinander aufbauenden Schritten. Das Directories-Management trennt Source-Code, Test-Code und ausgeschlossene Verzeichnisse – das beschleunigt die Suche und verhindert falsche Fehler. Der generated/-Ordner als Sources Root stellt sicher, dass Proxy- und Interceptor-Klassen für Navigation und Code-Completion zur Verfügung stehen. PHPUnit mit Docker-Interpreter ermöglicht das Ausführen einzelner Tests direkt aus dem Editor, ohne Kontext-Wechsel ins Terminal.

Die phtml-Template-Konfiguration mit Tailwind- und Alpine.js-Plugins schließt die Lücke zwischen Backend-PHP-Entwicklung und Frontend-Template-Arbeit in Hyvä-Themes. Das Magento PhpStorm Plugin macht XML-Konfigurationen navigierbar und verbindet DI-Konfiguration, Plugin-Definitionen und Observer-Registrierungen mit den zugehörigen PHP-Klassen. Die Gesamtheit dieser Konfigurationen verwandelt PhpStorm von einem generischen PHP-Editor in eine Magento-spezifische Entwicklungsplattform.

11. FAQ: Magento-spezifische PhpStorm-Einstellungen