Multi-Root-Projekte: Mehrere Git-Repositories in einem PhpStorm-Fenster

1. Das Problem: Modul-Entwicklung isoliert vom Magento-Core

Ein eigenes Magento-Modul liegt haeufig in einem separaten Git-Repository, etwa unter src/app/code/Mironsoft, waehrend der eigentliche Magento-Core in einem anderen Repository oder als Composer-Abhaengigkeit vorliegt. Oeffnet man nur das Modul-Verzeichnis als Projekt, fehlt PhpStorm der Kontext zu den Core-Klassen, von denen das Modul erbt oder die es per Plugin erweitert. Gerade bei Preference-Overrides oder komplexen Plugin-Ketten ist dieser fehlende Kontext besonders schmerzhaft, weil man staendig zwischen Modul und Core hin und her wechseln muss, um die tatsaechliche Vererbungshierarchie nachzuvollziehen.

Die Folge sind unvollstaendige Code-Vervollstaendigung, fehlerhafte Navigation zu Interface-Definitionen und PHPStorm-Warnungen ueber angeblich unbekannte Klassen, die tatsaechlich im Core existieren. Ein separates zweites PhpStorm-Fenster fuer den Core loest das Navigationsproblem nur teilweise, weil Suche und Refactoring dann nicht projektuebergreifend funktionieren. Man landet stattdessen bei manuellem Kopieren von Klassennamen zwischen zwei Fenstern, was bei laengeren Rechercheaufgaben schnell fehleranfaellig wird und die eigentliche Staerke einer IDE, die integrierte Codenavigation, praktisch aushebelt.

2. Das Grundprinzip: Attach Directory as Content Root

PhpStorm erlaubt es, einem bestehenden Projekt weitere Verzeichnisse als zusaetzliche Content Roots hinzuzufuegen, ueber File, Open und die Auswahl Attach beim Oeffnen eines weiteren Verzeichnisses. Jeder Content Root wird im Project-Tool-Fenster als eigener Wurzelknoten angezeigt, behaelt aber seine eigene Verzeichnisstruktur und, sofern vorhanden, sein eigenes .git-Verzeichnis.

Technisch gesehen entsteht dabei kein zusammengefuehrtes Repository, sondern ein einzelnes PhpStorm-Projekt, das mehrere unabhaengige Dateisystem-Wurzeln referenziert. Die .idea-Konfiguration des Hauptprojekts speichert lediglich die Pfade zu den zusaetzlichen Roots, waehrend jedes Root-Verzeichnis vollstaendig eigenstaendig bleibt. Dieses Prinzip unterscheidet sich grundlegend von Git-Submodulen oder einem klassischen Monorepo, da auf Dateisystemebene keinerlei Verschmelzung stattfindet, sondern ausschliesslich die IDE-Sicht auf die Verzeichnisse erweitert wird.

<!-- .idea/modules.xml im Hauptprojekt -->
<module fileurl="file://$PROJECT_DIR$/modul.iml" filepath="$PROJECT_DIR$/modul.iml" />
<module fileurl="file://$PROJECT_DIR$/../magento-core/core.iml" filepath="$PROJECT_DIR$/../magento-core/core.iml" />

3. Ein Multi-Root-Projekt Schritt fuer Schritt einrichten

Ausgangspunkt ist das Modul-Repository als Hauptprojekt. Ueber File, Open, Auswahl des Magento-Core-Verzeichnisses und die Option Attach im folgenden Dialog wird der Core als zweiter Content Root hinzugefuegt, statt ein neues Fenster zu oeffnen. PhpStorm indiziert daraufhin beide Verzeichnisbaeume und baut eine gemeinsame Symbol-Tabelle auf. Der Dialog fragt dabei explizit, ob das Verzeichnis als neues Fenster geoeffnet oder dem bestehenden Projekt hinzugefuegt werden soll, ein Punkt, an dem viele Entwickler versehentlich die falsche Option waehlen und sich anschliessend wundern, warum zwei getrennte Fenster erscheinen.

Fuer grosse Core-Repositories lohnt es sich, vorab unter Settings, Directories nicht benoetigte Core-Bereiche wie Testverzeichnisse oder Vendor-Unterordner als Excluded zu markieren, um die Indizierungszeit zu verkuerzen. Nach Abschluss der Indizierung funktionieren Go to Declaration, Find Usages und die Code-Vervollstaendigung nahtlos ueber beide Roots hinweg. Bei einem vollstaendigen Magento-Core-Checkout kann die erste Indizierung je nach Rechnerleistung durchaus mehrere Minuten dauern, weshalb es sich anbietet, diesen Schritt bewusst waehrend einer Pause anzustossen statt mitten in einer produktiven Arbeitsphase.

4. Getrennte VCS-Historie pro Root verwalten

PhpStorm erkennt automatisch, dass jeder Content Root sein eigenes .git-Verzeichnis mitbringt, und registriert entsprechend mehrere VCS-Roots im selben Projekt. Im Commit-Dialog werden Aenderungen nach ihrem jeweiligen Repository gruppiert angezeigt, sodass ein Commit niemals versehentlich Aenderungen aus beiden Repositories vermischt.

Auch die Werkzeuge Local History, Annotate und Show History arbeiten korrekt pro Datei innerhalb ihres jeweiligen Repositories, sodass ein Blame fuer eine Core-Datei niemals faelschlich mit dem Modul-Repository verwechselt wird. Der VCS-Dropdown in der Toolbar zeigt bei aktivem Editor-Tab automatisch den passenden Branch-Namen des jeweiligen Roots an. Auch der Update-Vorgang laesst sich pro Root gezielt steuern, sodass man beispielsweise nur den Modul-Root pullt, waehrend der Core-Root bewusst auf einer aelteren, getesteten Version verbleibt.

# Beide Roots bleiben unabhaengige Git-Repositories
src/app/code/Mironsoft/.git      # eigenes Modul-Repository
../magento-core/.git             # Magento-Core-Repository
# git status muss in jedem Root separat ausgefuehrt werden

5. Projektuebergreifende Navigation und Suche

Der eigentliche Gewinn eines Multi-Root-Projekts zeigt sich bei Find Usages: Ruft man diese Aktion fuer eine Interface-Methode aus dem Core auf, listet PhpStorm auch alle Implementierungen und Aufrufe im Modul-Repository auf, obwohl beide in getrennten Git-Repositories liegen. Ohne den zusaetzlichen Content Root wuerde diese Suche stumm im Modul-Verzeichnis enden.

Auch Search Everywhere und Go to Class durchsuchen automatisch alle registrierten Roots gleichzeitig, was besonders beim Nachschlagen von Magento-Core-Interfaces waehrend der eigenen Plugin-Entwicklung Zeit spart. Struktur- und Typhierarchie-Ansichten funktionieren ebenfalls repository-uebergreifend, was bei komplexer Vererbung ueber Core und Modul hinweg besonders wertvoll ist. Selbst die Diagramm-Ansicht fuer Klassenhierarchien zeichnet Core-Klasse und Modul-Override im selben Diagramm ein, was die tatsaechliche Vererbungskette auf einen Blick sichtbar macht, ohne dass man sie sich aus mehreren Dateien manuell zusammensuchen muss.

6. Composer-Autoloading und PHPStan im Multi-Root-Kontext

Damit die Code-Intelligenz tatsaechlich funktioniert, muss PhpStorm die Composer-Autoload-Konfiguration ueber beide Roots hinweg korrekt aufloesen koennen. Meist reicht es, wenn der Core-Root eine eigene composer.json mit vendor-Verzeichnis mitbringt, aus dem PhpStorm die Namespace-Zuordnung automatisch ableitet, sofern Settings, PHP, Composer korrekt auf die richtige composer.json zeigt.

Fuer PHPStan-Analysen ist zu beachten, dass sich der Aufruf weiterhin nur auf das Modul-Verzeichnis bezieht, etwa bin/analyse app/code/Mironsoft/SeoSuite --level=5, waehrend der zusaetzliche Content Root lediglich fuer die IDE-Navigation dient und nicht automatisch in jede Analyse einbezogen wird.

7. Vor- und Nachteile gegenueber separaten Fenstern

Der groesste Vorteil eines Multi-Root-Projekts ist die nahtlose Navigation und Suche ueber Repository-Grenzen hinweg, kombiniert mit einer einzigen Fensterumgebung statt zwei parallel laufenden PhpStorm-Instanzen, die jeweils eigenen Arbeitsspeicher beanspruchen. Gerade bei begrenztem Arbeitsspeicher auf Entwickler-Notebooks macht das einen spuerbaren Unterschied.

Der Nachteil zeigt sich bei der Indizierung: Ein grosser Magento-Core-Root verlaengert die initiale Indizierungszeit erheblich, und Suchergebnisse ueber Search Everywhere enthalten haeufiger Core-Treffer, die man eigentlich gar nicht meinte. Wer ausschliesslich am Modul arbeitet und den Core nur gelegentlich braucht, faehrt mit zwei separaten Fenstern und gezieltem Fenster-Wechsel mitunter besser. Auch bei mehreren gleichzeitig geoeffneten Content Roots steigt der Arbeitsspeicherbedarf der IDE messbar an, was auf Notebooks mit begrenztem RAM zu denselben Symptomen fuehren kann, die auch bei generell zu knapp bemessenen Heap-Einstellungen auftreten.

8. Einen Content Root wieder entfernen, ohne Dateien zu loeschen

Ein hinzugefuegter Content Root laesst sich jederzeit ueber Settings, Directories und die Schaltflaeche Detach Directory wieder aus dem Projekt entfernen. Dabei werden ausschliesslich die PhpStorm-internen Projektreferenzen geloescht, die Dateien und das zugehoerige Git-Repository auf der Festplatte bleiben vollstaendig unberuehrt.

Das ist besonders praktisch, wenn man den Core-Root nur temporaer fuer eine einzelne Refactoring-Aufgabe braucht, etwa um eine Interface-Signatur ueber viele Aufrufer hinweg zu pruefen, und ihn danach wieder entfernt, um die Indizierungslast fuer den taeglichen Gebrauch gering zu halten.

9. Empfehlung fuer typische Magento-Team-Setups

Fuer Entwicklerteams, die regelmaessig zwischen eigenem Modul-Code und Magento-Core-Interna wechseln muessen, etwa bei tiefen Plugin-Ketten oder komplexen Preference-Ueberschreibungen, ist ein dauerhaftes Multi-Root-Projekt meist die produktivere Wahl. Die einmalige Indizierungszeit amortisiert sich schnell durch die eingesparten Fensterwechsel. In der Praxis hat es sich bewaehrt, diese Entscheidung nicht projektweit vorzugeben, sondern jeder Entwicklerin und jedem Entwickler selbst zu ueberlassen, da individuelle Arbeitsgewohnheiten und die Leistungsfaehigkeit der eigenen Maschine hier eine ebenso grosse Rolle spielen wie die reine Projektstruktur.

Fuer reine Frontend-Arbeit an Hyva-Templates oder isolierte Modulentwicklung ohne haeufigen Core-Bezug lohnt sich der zusaetzliche Content Root selten. Hier bleibt ein schlankes Einzelprojekt mit gezieltem, temporaerem Attach bei Bedarf die praktikablere Loesung.

10. Zusammenfassung

11. FAQ: Multi-Root-Projekte in PhpStorm: Das Wichtigste auf einen Blick