Structural-Search-Templates in PhpStorm im Team teilen und wiederverwenden

1. Was Structural Search von einer Regex-Suche unterscheidet

Eine klassische Regex-Suche arbeitet auf reinem Text und muss Variablennamen, Whitespace und Reihenfolge exakt vorhersehen, was bei realem PHP-Code schnell an Grenzen stoesst. Structural Search and Replace, kurz SSR, arbeitet stattdessen auf der abstrakten Syntax des Codes und erkennt Muster unabhaengig von konkreten Bezeichnern.

Ein SSR-Template fuer einen Methodenaufruf mit beliebigem Objekt und beliebigem Argument findet zuverlaessig jede Variante im gesamten Projekt, egal ob die Variable $product, $entity oder $model heisst. Genau diese Unabhaengigkeit von konkreten Namen macht SSR fuer projektweite Refactorings so wertvoll.

Diese Praezision zahlt sich besonders bei Magento-Modulen aus, die ueber Jahre von wechselnden Entwicklern gepflegt wurden, da sich dort Namenskonventionen und Code-Stil oft mehrfach geaendert haben und eine reine Textsuche zwangslaeufig Fundstellen uebersieht.

2. Ein eigenes Suchtemplate im Structural Search Editor bauen

Ueber Edit, Find, Search Structurally oeffnet sich der Editor, in dem ein Codeausschnitt als Muster eingegeben wird. Platzhalter wie $INSTANCE$ oder $ARGS$ markieren Stellen, die variabel sein sollen, waehrend der restliche Code exakt so gesucht wird, wie er dasteht.

Ueber den Filter-Button laesst sich fuer jeden Platzhalter zusaetzlich einschraenken, welchen Typ oder welche Anzahl von Vorkommen er annehmen darf, etwa genau ein Argument oder ein Argument vom Typ string. Diese Filter machen ein Template praezise genug, um Fehltreffer im echten Projekt zu vermeiden.

Fuer komplexere Muster lohnt es sich, das Template schrittweise aufzubauen: zunaechst ein grobes Muster ohne Filter testen, die Trefferliste pruefen und anschliessend Filter gezielt ergaenzen, bis nur noch die tatsaechlich relevanten Stellen im Ergebnis erscheinen.

3. Magento-Beispiel: Veraltete ObjectManager::getInstance()-Aufrufe finden

In gewachsenen Magento-Projekten finden sich haeufig noch direkte Aufrufe von ObjectManager::getInstance(), obwohl Constructor Property Promotion und Dependency Injection der empfohlene Weg sind. Ein SSR-Template macht diese Stellen projektweit sichtbar, unabhaengig davon, in welcher Klasse oder Methode sie stehen.

Das Suchmuster erfasst sowohl die direkte Zuweisung als auch die Verkettung mit einem anschliessenden get-Aufruf, etwa ObjectManager::getInstance()->get(ProductRepositoryInterface::class), und listet alle Fundstellen in einem eigenen Suchergebnis-Tab auf, sortiert nach Datei.

// Search Template
\Magento\Framework\App\ObjectManager::getInstance()->get($CLASS$::class)

// $CLASS$ ist als Platzhalter beliebig konfigurierbar,
// Filter: Minimum count = 1, Maximum count = 1

4. Das passende Replace-Template fuer automatisiertes Refactoring

Zum Suchtemplate gehoert ein Replace-Template, das PhpStorm beim Ausfuehren als Vorschlag fuer jede Fundstelle anbietet. Fuer den ObjectManager-Fall laesst sich der Aufruf durch einen Kommentar-Hinweis ersetzen, der auf die noetige manuelle Umstellung auf Constructor Injection verweist, da eine vollautomatische Umstellung den Konstruktor der Klasse mit betreffen wuerde.

Fuer einfachere Faelle, etwa den Umstieg von array_key_exists auf den Null-Coalescing-Operator, kann das Replace-Template den Code direkt und vollstaendig automatisch ersetzen. PhpStorm zeigt vor jeder Anwendung eine Diff-Vorschau, sodass nichts blind angewendet wird.

Bei besonders sensiblen Codebereichen, etwa im Checkout- oder Zahlungsablauf, empfiehlt es sich zusaetzlich, das Replace-Template zunaechst nur auf einzelne, bewusst ausgewaehlte Dateien anzuwenden und erst nach einer erfolgreichen Testrunde auf den gesamten Fundstellen-Bestand auszuweiten.

// Replace Template
// TODO: ObjectManager::getInstance() durch Constructor Injection fuer $CLASS$ ersetzen
$this->$CLASS_VAR$

5. Templates speichern, sinnvoll benennen und kategorisieren

Ueber Save Template wird ein Muster dauerhaft in der Werkzeugleiste unter Structural Search Inspection oder im Search Everywhere Fenster verfuegbar. Ein sprechender Name wie Magento ObjectManager Direct Call statt eines generischen Template 1 macht das Wiederfinden nach Wochen deutlich einfacher.

Zusaetzlich lassen sich Templates in Kategorien wie Magento Legacy Patterns oder Security Findings gruppieren. Diese Struktur zahlt sich vor allem dann aus, wenn ueber die Zeit ein ganzes Set an wiederkehrenden Suchmustern entsteht, das sonst schnell unuebersichtlich wird.

Ein kurzer Beschreibungstext, den PhpStorm beim Speichern optional abfragt, hilft zusaetzlich dabei, den Zweck eines Templates auch Monate spaeter ohne erneutes Ausprobieren zu verstehen, besonders wenn mehrere aehnliche Templates fuer verwandte, aber nicht identische Muster existieren.

6. Templates exportieren und im Team verteilen

Gespeicherte SSR-Templates liegen lokal in der PhpStorm-Konfiguration und werden standardmaessig nicht automatisch mit dem Team geteilt. Ueber Export lassen sie sich als Konfigurationsdatei sichern und anschliessend an Kollegen weitergeben oder in ein gemeinsames Ablage-Repository legen.

Wer Settings Sync nutzt, kann Structural Search Templates zusaetzlich ueber die persoenliche Kategorie synchronisieren, was aber nur fuer den eigenen Account gilt. Fuer echte Team-Verteilung ist der explizite Export der zuverlaessigere Weg, da er unabhaengig vom individuellen JetBrains-Account funktioniert.

Fuer Teams, die bereits ein zentrales Ablage-Repository fuer interne Tools pflegen, bietet es sich an, die exportierten Template-Dateien dort gemeinsam mit anderen PhpStorm-Konfigurationsdateien wie Live Templates oder Code-Style-Definitionen zu buendeln, statt sie ueber verschiedene Kanaele verstreut zu halten.

# Exportierte Templates liegen typischerweise unter
~/.config/JetBrains/PhpStorm2025.2/options/structuralSearch.xml

# Ablage im Projekt fuer Team-Zugriff
tools/phpstorm/ssr-templates/magento-objectmanager.xml
tools/phpstorm/ssr-templates/README.md

7. Versionierung: Wo Templates im Projekt am besten abgelegt werden

Da PhpStorm SSR-Templates nicht automatisch im .idea-Ordner ablegt, empfiehlt sich ein dediziertes Verzeichnis im Projekt, etwa tools/phpstorm/ssr-templates/, in dem die exportierten XML-Dateien gemeinsam mit einer kurzen README versioniert werden.

Die README beschreibt kurz, wofuer jedes Template gedacht ist und wie es importiert wird, etwa ueber Settings, Editor, Inspections, Structural Search Inspection, Import. So bleibt nachvollziehbar, welche Muster existieren, auch wenn ein Entwickler das jeweilige Template noch nie selbst genutzt hat.

Eine kurze Versionsnummer oder ein Datum im Dateinamen des exportierten Templates erleichtert es zusaetzlich, spaeter nachzuvollziehen, ob ein Kollege bereits eine aktualisierte Fassung importiert hat, gerade wenn ein Muster im Laufe der Zeit praezisiert wurde.

8. Praxisbeispiel: Eine projektweite Migration mit SSR durchziehen

Bei der Migration eines aelteren Magento-Moduls auf Dependency Injection zeigt ein SSR-Template zunaechst alle betroffenen Stellen im gesamten app/code-Verzeichnis in einem einzigen Ergebnisfenster, sortiert nach Datei und Zeile, statt dass jede Klasse einzeln durchsucht werden muss.

Anschliessend arbeitet das Team die Liste ab, Fund fuer Fund, mit der Diff-Vorschau als Sicherheitsnetz vor jeder Aenderung. Fuer eine 40 Dateien umfassende Migration reduziert das den Aufwand von einem ganzen Tag manueller Suche auf wenige Stunden strukturierter Abarbeitung.

// Vorher
class ProductImportProcessor
{
    public function process(int $productId): void
    {
        $repository = \Magento\Framework\App\ObjectManager::getInstance()
            ->get(\Magento\Catalog\Api\ProductRepositoryInterface::class);
        $repository->getById($productId);
    }
}

// Nachher, manuell auf Basis der SSR-Fundstellen umgestellt
final class ProductImportProcessor
{
    public function __construct(
        private readonly \Magento\Catalog\Api\ProductRepositoryInterface $productRepository,
    ) {
    }

    public function process(int $productId): void
    {
        $this->productRepository->getById($productId);
    }
}

9. SSR im Vergleich zu Find and Replace und Rector

Einfaches Find and Replace arbeitet auf reinem Text und eignet sich fuer exakte, unveraenderliche Zeichenketten, scheitert aber sobald Variablennamen oder Formatierung variieren. Structural Search versteht dagegen die Code-Struktur und bleibt auch bei unterschiedlicher Benennung treffsicher.

Rector geht noch einen Schritt weiter und kann komplexe, mehrzeilige Transformationen vollautomatisch und headless in der CI-Pipeline ausfuehren, erfordert dafuer aber eigene Regel-Definitionen in PHP und laeuft ausserhalb der IDE. Fuer schnelle, interaktive Suchen mit sofortiger visueller Kontrolle bleibt SSR in PhpStorm der direktere Weg.

Fuer Teams, die noch keine Erfahrung mit Rector haben, ist SSR haeufig der pragmatischere Einstieg, da sich damit sofort sichtbare Ergebnisse erzielen lassen, bevor in eine dedizierte, headless Toolchain investiert wird.

10. Zusammenfassung

11. FAQ: Structural-Search-Templates im Team: Das Wichtigste auf einen Blick