Navigation in großen Projekten: Scopes, Custom Searches und Structural Search in PhpStorm

1. Das Navigationsproblem in großen Projekten

Ein typisches Magento 2 Projekt hat nach composer install mehr als 100.000 Dateien im vendor/-Verzeichnis. Dazu kommen die generierten Klassen im generated/-Verzeichnis, gecachte Dateien in var/cache/ und statische Ressourcen in pub/static/. Eine einfache Textsuche (Find in Files, Ctrl+Shift+F) ohne Scope-Einschränkung liefert tausende Treffer aus diesen Verzeichnissen – von denen keiner relevant ist, weil der Entwickler nur den eigenen Code in app/code/ und app/design/ suchen will.

Das zweite Problem ist die Qualität der Suche: Mit regulären Ausdrücken lassen sich syntaktische Muster finden, aber keine semantischen Code-Muster. Wer alle Stellen sucht, an denen ein bestimmter Service ohne Constructor Injection direkt über den ObjectManager instanziiert wird, kommt mit einer Regex nicht weit – die syntaktischen Variationen sind zu vielfältig. Structural Search löst dieses Problem, weil es PHP-Code als AST (Abstract Syntax Tree) analysiert und strukturelle Muster erkennt, nicht nur Zeichenfolgen.

2. Scopes: Suche auf relevante Verzeichnisse begrenzen

PhpStorm-Scopes sind benannte Gruppen von Dateien und Verzeichnissen, die für verschiedene IDE-Aktionen verwendet werden: Suche, Inspektionen, Versionskontrolle und Code-Analyse. Die Standard-Scopes (Project Files, Project Production Files, Changed Files) sind ein guter Ausgangspunkt, aber für Magento-Projekte sind Custom Scopes unverzichtbar. Unter Settings → Scopes können beliebig viele Scopes mit Pfad-Mustern definiert werden.

Die Scope-Syntax verwendet Pfad-Muster: file:app/code/Mironsoft//* schließt alle Dateien in eigenen Modulen ein. !file:app/code/Mironsoft//generated//* schließt generierte Dateien wieder aus. Scopes können über && (AND) und || (OR) kombiniert werden. Ein einmal definierter Scope erscheint in allen relevanten Dialogen als Auswahloption – bei der Dateisuche, bei Find Usages, bei Inspektionen und bei der Analyse-Konfiguration. Das spart bei jeder Suche mehrere Sekunden Nachbearbeitung von irrelevanten Treffern.

# PhpStorm Scope-Definitionen für Magento 2 Projekt
# Einstellungen: Settings → Scopes → + (New Scope)

# Scope 1: "Eigene Module" — nur app/code/Mironsoft
# Scope-Ausdruck:
file:app/code/Mironsoft//*

# Scope 2: "Frontend + Backend Code" — eigene Module + Design
# Scope-Ausdruck:
file:app/code/Mironsoft//* || file:app/design/frontend/Mironsoft//*

# Scope 3: "Alle PHP-Dateien außer Vendor/Generated"
# Scope-Ausdruck:
file:*.php && !file:vendor//* && !file:generated//* && !file:pub//*

# Scope 4: "Layout und Template Dateien"
# Scope-Ausdruck:
file:*.xml && file:app//* || file:*.phtml && file:app//*

# Scope 5: "Nur geänderte Dateien in eigenen Modulen" (kombiniert mit VCS-Status)
# Nutze den eingebauten Scope "Changed Files" + eigene Einschränkung

# Verwendung in Find in Files (Ctrl+Shift+F):
# Scope-Dropdown auf "Eigene Module" → Suche findet nur relevante Dateien
# Keine Treffer mehr aus vendor/magento, vendor/hyva-themes etc.

3. Custom Scopes für Magento-Projekte definieren

Für ein professionelles Magento 2 Projekt empfiehlt sich eine Scope-Bibliothek, die verschiedene Entwicklungsszenarien abdeckt. Ein Module-Scope für jedes eigene Modul erlaubt gezielte Suchen innerhalb eines Moduls ohne Ablenkung durch andere Module. Ein Frontend-Scope begrenzt Suchen auf phtml-Templates, Tailwind-CSS-Dateien und Alpine.js-Komponenten. Ein XML-Configuration-Scope umfasst alle etc/-Verzeichnisse eigener Module für die Suche in Konfigurationsdateien wie di.xml, routes.xml und events.xml.

Custom Scopes in PhpStorm sind persistent und werden im Projektverzeichnis unter .idea/scopes/ als XML-Dateien gespeichert. Das bedeutet, sie können ins Git-Repository eingecheckt und mit dem Team geteilt werden – ähnlich wie Live Templates. Neue Teammitglieder haben nach dem Checkout sofort alle definierten Scopes verfügbar. Die Scope-Dateien sind menschenlesbar und klein, sodass diffs nachvollziehbar bleiben. Das ist ein erheblicher Vorteil gegenüber teamspezifischen Editor-Konfigurationen, die manuell synchronisiert werden müssen.

4. Find Usages mit Scope: gezielt statt global

Find Usages (Alt+F7) ist eines der mächtigsten Navigations-Features in PhpStorm. Es findet alle Verwendungen einer Klasse, Methode, Variable oder eines Interfaces – unter Berücksichtigung des PHP-Typsystems, Vererbung und Interfaces. Das bedeutet: Find Usages auf einem Interface findet alle implementierenden Klassen und alle Stellen, an denen das Interface als Typ-Hint verwendet wird, nicht nur den String-Match des Interface-Namens.

Standardmäßig sucht Find Usages im gesamten Projekt, was in Magento-Projekten tausende Treffer aus vendor/ liefert. Mit Find Usages Settings (Alt+Shift+F7 oder Rechtsklick → Find Usages Advanced) kann ein Scope ausgewählt werden. Im Dialog erscheint das Scope-Dropdown mit allen definierten Custom Scopes. Ein Find Usages auf ProductRepositoryInterface mit dem Scope "Eigene Module" zeigt nur Verwendungen in eigenem Code – ein wesentlich kürzere und relevantere Liste als die hunderte Treffer aus dem gesamten Magento-Core.

<?php
// Find Usages Advanced — Anwendungsbeispiele
// PhpStorm versteht PHP-Typsystem, nicht nur String-Matching

declare(strict_types=1);

namespace Mironsoft\Catalog\Api;

/**
 * ProductRepositoryInterface defines the contract for product data access.
 *
 * Find Usages auf diesem Interface findet:
 * - alle Klassen die es implementieren (ProductRepository)
 * - alle Konstruktoren die es als Typehint verwenden (via DI)
 * - alle Methoden die es als Parameter oder Rückgabetyp deklarieren
 * - alle di.xml-Einträge (als String-Referenz)
 *
 * Mit Scope "Eigene Module" nur eigener Code — kein Magento-Core-Rauschen.
 */
interface ProductRepositoryInterface
{
    /**
     * Find product by ID.
     *
     * @param int  $productId  The product entity ID
     * @param bool $editMode   Load in edit mode (bypasses cache)
     * @return \Mironsoft\Catalog\Api\Data\ProductInterface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function getById(int $productId, bool $editMode = false): Data\ProductInterface;

    /**
     * Save product entity.
     *
     * @param \Mironsoft\Catalog\Api\Data\ProductInterface $product
     * @return \Mironsoft\Catalog\Api\Data\ProductInterface
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function save(Data\ProductInterface $product): Data\ProductInterface;

    /**
     * Delete product by ID.
     *
     * @param int $productId
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     * @throws \Magento\Framework\Exception\CouldNotDeleteException
     */
    public function deleteById(int $productId): void;
}

5. Structural Search: Code-Muster strukturell finden

Structural Search (Ctrl+Shift+S) ist eines der am meisten unterschätzten Features in PhpStorm. Im Gegensatz zur Textsuche (die nach Zeichenketten sucht) und zur Regex-Suche (die nach textuellen Mustern sucht) analysiert Structural Search den PHP-AST und findet Code-Muster unabhängig von Formatierung, Variablennamen und Zeilenumbrüchen. Das ermöglicht Suchen wie: "Alle Methoden, die $this->objectManager->create() aufrufen" oder "Alle catch-Blöcke, die die Exception nur loggen und nicht re-throwen".

Das Structural Search Template nutzt $VARIABLEN$-Platzhalter, die für beliebige AST-Knoten stehen. $method$ steht für einen beliebigen Methodenaufruf, $expression$ für einen beliebigen Ausdruck. Mit Count-Constraints (Minimum/Maximum) lässt sich festlegen, wie oft ein Platzhalter matchen muss. Mit Type-Constraints wird der Platzhalter auf Ausdrücke eines bestimmten Typs eingeschränkt. Die Ergebnisse werden im Find-Panel mit vollständigem Kontext angezeigt und sind klickbar – wie bei einer normalen Suche, aber semantisch präziser.

<?php
// Structural Search Templates für häufige Magento-Problemmuster
// Öffnen: Ctrl+Shift+S → Template-Text eingeben

// Template 1: ObjectManager direkt aufrufen (Anti-Pattern in Magento)
// Such-Template:
// \Magento\Framework\ObjectManagerInterface::$method($args)
// Findet alle direkten ObjectManager-Aufrufe unabhängig von Variablennamen

// Beispiele die gefunden werden:
$this->objectManager->create(\Mironsoft\Catalog\Model\Product::class);
$om->get('Magento\Catalog\Model\ProductFactory');
$objectManager->create($type, $arguments); // auch mit $type als Variable

// Template 2: Exception wird gefangen aber nicht weitergeworfen
// Such-Template:
// try { $statements$; } catch ($ExceptionType$ $e$) { $logger$->$logMethod$($e); }
// Findet catch-Blöcke die Exception nur loggen

// Template 3: echo ohne escapeHtml (Sicherheitsproblem in phtml)
// Such-Template:
// echo $variable$;
// In Scope "Frontend" — findet alle unescapten Echo-Ausgaben

// Anwendungsfall für Hyvä: Alle phtml-Dateien finden wo <?= ohne escapeHtml
// Template für Structural Search and Replace:
// Suche:  <?= $block->$getterMethod$() ?>
// Ersetze: <?= $block->escapeHtml($block->$getterMethod$()) ?>
// WICHTIG: Nicht blind anwenden — einige Getter geben bereits escapetes HTML zurück

6. Structural Search and Replace: Massenänderungen sicher durchführen

Structural Search and Replace (Ctrl+Shift+M) erweitert die Suche um eine strukturell korrekte Ersetzung. Das Replacement-Template nutzt dieselben $VARIABLEN$ wie das Such-Template und kann sie in neuer Anordnung ausgeben. Das Ergebnis ist eine Ersetzung, die die ursprüngliche Formatierung, Variablennamen und Typen respektiert – im Gegensatz zu einfachen Regex-Replacements, die blind Text ersetzen.

Ein typischer Einsatzfall für Magento-Upgrades: PHP 8.4 führt Property Hooks ein, die bestimmte Getter/Setter-Muster ersetzen können. Mit Structural Search and Replace lässt sich ein Pattern für "privates Property mit Getter" finden und durch ein Property mit Getter-Hook ersetzen – strukturell korrekt für jeden Variablennamen, ohne jeden Treffer manuell anpassen zu müssen. Dasselbe gilt für die Migration von alten Magento-APIs zu neuen Service Contracts: Statt manuell jede Verwendung der deprecated Methode zu finden und zu ersetzen, definiert man ein Structural Replace Template und wendet es auf alle eigenen Module an.

7. Weitere Navigations-Shortcuts für große Projekte

Go to Class (Ctrl+N) und Go to File (Ctrl+Shift+N) sind die schnellsten Wege zu einer bekannten Datei oder Klasse. PhpStorm nutzt CamelCase-Matching: PRI findet ProductRepositoryInterface, CatProd findet CatalogProductRepository. Die Suche ist fuzzy und berücksichtigt Camel-Case-Wortgrenzen. Mit einem Doppelpunkt nach dem Klassennamen (ProductRepository:42) springt man direkt zu einer bestimmten Zeile.

Recent Files (Ctrl+E) und Recent Locations (Ctrl+Shift+E) sind die effizientesten Wege zurück zu kürzlich bearbeiteten Stellen. Recent Locations zeigt nicht nur die Datei, sondern den Codeausschnitt, der zuletzt bearbeitet wurde – besonders nützlich wenn man in mehreren Klassen parallel Änderungen vornimmt. Back/Forward Navigation (Ctrl+Alt+←/→) springt in der Navigationshistorie vor und zurück – wie der Browser-Back-Button, aber für Code. Für Magento-Projekte mit tiefen Plugin-Ketten ist das unverzichtbar, wenn man einem Methodenaufruf durch mehrere Interceptor-Ebenen folgt und dann zurücknavigieren möchte.

Ein praktisches Beispiel aus dem Magento-Alltag: Man findet in einem Stack-Trace einen Klassenname wie Magento\Catalog\Plugin\Category\Collection. Mit Go to Class (Ctrl+N) und dem Klassennamen springt PhpStorm direkt zu dieser Datei in vendor/ – ohne manuell durch den Dateibaum zu navigieren. Von dort kann man mit Find Usages prüfen, ob das eigene Modul diese Klasse beeinflusst. Das gesamte Navigations-Szenario dauert in PhpStorm weniger als 10 Sekunden; im Terminal wäre es eine Kombination aus find vendor/ -name "Collection.php" | grep Plugin und manueller Analyse.

9. Zusammenfassung

Scopes, Custom Searches und Structural Search sind die drei Säulen effizienter Navigation in großen PHP-Projekten wie Magento 2. Scopes begrenzen alle Such- und Analyse-Operationen auf relevante Verzeichnisse und eliminieren das Rauschen aus vendor/, generated/ und anderen nicht-relevanten Bereichen. Find Usages mit Scope findet semantisch korrekte Verwendungen von Klassen, Methoden und Interfaces – unter Berücksichtigung des PHP-Typsystems, nicht nur als Textsuche. Structural Search findet Code-Muster, die mit Regex nicht sinnvoll beschreibbar sind, und Structural Replace ermöglicht Massenänderungen die strukturell korrekt sind.

Die Custom Scopes sind als .idea/scopes/*.xml-Dateien versionierbar und können mit dem Team geteilt werden. Structural Search Templates können als Inspection-Konfiguration gespeichert und für automatische Code-Review-Checks genutzt werden. Die Investition in die initiale Konfiguration zahlt sich täglich aus: Jede Suche ohne Vendor-Rauschen, jede semantisch korrekte Usages-Analyse und jede strukturell sichere Massenänderung spart messbare Zeit im Entwicklungsalltag eines Magento-Teams.

10. FAQ: Navigation in großen Projekten mit PhpStorm