Inspection-Profile in PhpStorm im Team versionieren und teilen

1. Warum das Standardprofil fuer Magento-Teams selten ausreicht

Das mitgelieferte Default-Profil von PhpStorm deckt allgemeine PHP-Probleme gut ab, kennt aber weder Magento-spezifische Konventionen noch projektinterne Vereinbarungen, etwa zur Nutzung von ViewModels statt Block-Klassen oder zur verpflichtenden PHPDoc-Struktur. Ohne Anpassung entstehen entweder zu viele irrelevante Warnungen oder zu wenige relevante.

Wenn jeder Entwickler das Profil lokal nach eigenem Geschmack veraendert, verschwindet der gemeinsame Massstab fuer Code-Qualitaet vollstaendig. Ein Entwickler sieht eine Warnung zu ungenutzten Imports, ein anderer nicht, was im Review zu Diskussionen fuehrt, die eigentlich die IDE haette klaeren sollen.

Besonders in Projekten mit wechselnden externen Dienstleistern faellt dieser fehlende gemeinsame Massstab ins Gewicht, da jeder neue Entwickler zunaechst sein eigenes Set an Inspections mitbringt und damit implizit eigene Vorstellungen von Codequalitaet durchsetzt, ohne dass dies je bewusst entschieden wurde.

2. Ein eigenes Profil auf Basis des Default-Profils erstellen

Unter Settings, Editor, Inspections laesst sich ausgehend vom Default-Profil ein neues Profil per Copy Profile anlegen. Ab diesem Punkt lassen sich einzelne Inspections gezielt aktivieren, deaktivieren oder in ihrer Severity von Warning auf Error hochstufen, etwa fuer fehlende Typdeklarationen.

Fuer ein PHP-8.4-Projekt lohnt es sich, Inspections wie Strict Types Deklaration, unbenutzte Use-Statements und fehlende Return-Type-Deklarationen konsequent auf Error zu setzen, waehrend stilistische Hinweise wie Zeilenlaenge eher als Warning belassen werden, um das Signal-Rausch-Verhaeltnis sinnvoll zu halten.

Ebenso lohnt es sich, projektspezifische Inspections fuer Magento zu aktivieren, etwa Warnungen zu direkten SQL-Queries statt Verwendung der Repository-Schicht oder zu fehlenden Interface-Implementierungen bei neuen Service-Contracts, da diese Muster in generischen PHP-Profilen naturgemaess fehlen.

3. Wo das Profil gespeichert wird: Project-Level statt IDE-Level

Beim Speichern bietet PhpStorm die Wahl zwischen IDE-Scope, wo das Profil nur lokal existiert, und Project-Level, wo es als XML-Datei direkt im Projektordner landet. Fuer ein Team-Profil ist ausschliesslich Project-Level die richtige Wahl.

Ein Project-Level-Profil erscheint physisch unter .idea/inspectionProfiles/ im Projektverzeichnis. Wird dieser Ordner wie gewohnt in Git eingecheckt, erhaelt jeder Entwickler beim naechsten Pull automatisch die aktuelle Version des Profils, ohne manuell etwas importieren zu muessen.

$ ls -la .idea/inspectionProfiles/
Project_Default.xml
profiles_settings.xml

$ git log --oneline -- .idea/inspectionProfiles/
a1c3f92 Neue Inspection fuer fehlende PHPDoc-Bloecke aktiviert
7d0e441 Severity fuer unused imports auf ERROR gesetzt

4. Die XML-Struktur eines Profils im Detail

Project_Default.xml listet jede angepasste Inspection als eigenen inspection_tool-Eintrag mit class, enabled und level. Nur Abweichungen vom Werkszustand werden gespeichert, was die Datei ueberschaubar haelt und Diffs im Code-Review lesbar macht.

profiles_settings.xml legt fest, welches Profil als aktives Standardprofil fuer das Projekt gilt. Beide Dateien zusammen sorgen dafuer, dass PhpStorm beim Oeffnen des Projekts automatisch das Team-Profil laedt, ohne dass ein Entwickler manuell umschalten muss.

Wer die Datei direkt im Texteditor statt ueber die grafische Oberflaeche anpasst, sollte darauf achten, dass die enabled_by_default-Angabe stets zum urspruenglichen Werkszustand der jeweiligen Inspection passt, da PhpStorm sonst beim naechsten Speichern ueber die UI widerspruechliche Werte erzeugen kann.

<component name="InspectionProjectProfileManager">
  <profile version="1.0">
    <option name="myName" value="Mironsoft Magento" />
    <inspection_tool class="PhpUnusedAliasInspection" enabled="true" level="ERROR" enabled_by_default="true" />
    <inspection_tool class="MissingReturnTypeInspection" enabled="true" level="ERROR" enabled_by_default="false" />
    <inspection_tool class="PhpFieldAssignmentTypeMismatchInspection" enabled="true" level="WARNING" enabled_by_default="true" />
  </profile>
</component>

5. Ausnahmen fuer generierten Code und Vendor-Verzeichnisse

Ohne Ausnahmen wird ein Magento-Projekt schnell von tausenden Warnungen aus var/generated, vendor oder generated/code ueberflutet, obwohl dieser Code weder von Hand geschrieben noch dort veraendert wird. Solche Warnungen verdecken echte Probleme im eigenen app/code-Verzeichnis.

Unter Settings, Editor, Inspections, Scope laesst sich ein Custom Scope definieren, der Verzeichnisse wie var/generated und vendor ausschliesst, und diesen Scope dann fuer das gesamte Profil oder fuer einzelne Inspections gezielt hinterlegen, sodass Analysen sich auf app/code konzentrieren.

Zusaetzlich zu var/generated und vendor lohnt sich ein Ausschluss fuer generated/code und pub/static, da auch dort automatisiert erzeugte Dateien liegen, die eine Inspection-Pruefung nur unnoetig verlangsamen wuerden, ohne jemals manuell bearbeitet zu werden.

<!-- .idea/scopes/AppCode.xml -->
<component name="DependencyValidationManager">
  <scope name="Nur app code" pattern="file:app/code//*&&!file:*/generated//*&&!file:*/var//*" />
</component>

6. Automatische Aktivierung fuer neue Teammitglieder

Da das Profil im .idea-Ordner liegt, muessen neue Teammitglieder nichts manuell einrichten. Ein simples git clone oder git pull genuegt, PhpStorm erkennt das Project-Level-Profil und aktiviert es automatisch als Standardprofil fuer das jeweilige Projekt.

Ein kurzer Hinweis im README, dass Inspections bewusst projektweit vorgegeben sind und nicht lokal veraendert werden sollten, hilft dabei, dass niemand versehentlich ein persoenliches Profil ueberschreibt oder die Team-Vorgabe lokal wieder abschaltet.

Fuer Teams mit strikten Onboarding-Checklisten bietet es sich an, die automatische Uebernahme des Profils explizit als Pruefpunkt aufzunehmen, etwa mit einem Screenshot des erwarteten Profilnamens in der Statusleiste, damit Abweichungen sofort auffallen, statt erst im ersten Code-Review entdeckt zu werden.

7. Verhaeltnis zu PHPStan, PHPCS und der CI-Pipeline

Inspection-Profile in PhpStorm ersetzen weder PHPStan noch PHPCS, sondern ergaenzen sie um sofortiges Feedback direkt im Editor, bevor ein Commit ueberhaupt stattfindet. PHPStan auf Level 5 findet tiefere Typfehler, die eine reine IDE-Inspection oft nicht erkennt.

Sinnvoll ist eine bewusste Arbeitsteilung: Inspections warnen frueh und lokal waehrend des Schreibens, PHPCS erzwingt den Code-Style automatisiert, und PHPStan prueft in der CI-Pipeline nochmals hart, sodass kein Fehler allein auf das Gedaechtnis eines Entwicklers angewiesen ist.

Ein konkretes Beispiel verdeutlicht die Arbeitsteilung: Eine fehlende Typdeklaration faellt sofort als Inspection-Warnung im Editor auf, waehrend ein logischer Fehler in der Typinferenz ueber mehrere Methodenaufrufe hinweg eher von PHPStan erkannt wird, das den gesamten Kontrollfluss analysiert.

8. Pflege des Profils als eigener Review-Prozess

Aenderungen am Team-Profil sollten denselben Review-Prozess durchlaufen wie Aenderungen am Anwendungscode. Wer eine Inspection auf Error hochstuft, sollte begruenden, warum, und im Pull Request zeigen, wie viele bestehende Warnungen dadurch neu auftauchen.

Es empfiehlt sich, das Profil nicht zu haeufig zu aendern, da jede Aenderung potenziell hunderte neue Warnungen im gesamten Projekt erzeugt. Ein ruhiger, aber konsequent gepflegter Kern aus wenigen zwingenden Regeln funktioniert in der Praxis besser als ein staendig wachsendes Regelwerk.

Ein bewaehrter Rhythmus ist die vierteljaehrliche Durchsicht des Profils im Team, bei der gemeinsam entschieden wird, ob neue Inspections aus aktuellen PhpStorm-Versionen aufgenommen werden sollen, statt Aenderungen unregelmaessig und ohne Abstimmung vorzunehmen.

9. Inspection-Profile im Vergleich zu PHPStan, Psalm und PHPCS

Inspection-Profile wirken direkt im Editor und geben sofortiges visuelles Feedback, sind aber an PhpStorm gebunden und laufen nicht in der CI-Pipeline. PHPStan und Psalm sind statische Analysewerkzeuge, die unabhaengig von der IDE in jeder Umgebung laufen und sich fuer harte Build-Gates eignen.

PHPCS konzentriert sich auf Formatierung und Coding-Standards, waehrend Inspections und PHPStan eher auf logische Fehler und Typprobleme abzielen. Fuer ein robustes Setup ergaenzen sich alle drei Werkzeuge, statt sich gegenseitig zu ersetzen, wobei das Inspection-Profil die schnellste Rueckmeldung liefert.

In der Praxis hat sich gezeigt, dass Teams, die alle drei Werkzeuge konsequent kombinieren, deutlich weniger Zeit in spaeten Code-Reviews mit reinen Stil- oder Typdiskussionen verbringen, da die meisten dieser Fragen bereits vor dem Commit automatisiert geklaert wurden.

10. Zusammenfassung

11. FAQ: Inspection-Profile im Team: Das Wichtigste auf einen Blick