wp-phpstan

Überblick über das wp-phpstan-Skill

wp-phpstan ist das richtige Skill, wenn PHPStan in einer WordPress-Codebasis nicht nur „irgendwie laufen“ soll, sondern wirklich sauber arbeitet. Es richtet sich an Plugin-, Theme- und Site-Entwickler, die eine präzisere statische Analyse, weniger False Positives und einen praktikablen Weg für Legacy-Code mit bestehenden Problemen brauchen.

Die zentrale Aufgabe ist Konfiguration und Reparatur: phpstan.neon einbinden, Baselines handhaben, WordPress-Stubs laden und WordPress-bewusste Typannotationen ergänzen, wo PHPStan das Laufzeitverhalten nicht selbst ableiten kann.

Wofür wp-phpstan am besten geeignet ist

Nutze das wp-phpstan-Skill, wenn du:

• PHPStan in einem WordPress-Repo einrichten oder aktualisieren willst
• Fehler reduzieren möchtest, die durch fehlende WordPress-Core-Symbole entstehen
• phpstan-baseline.neon verwalten musst, ohne neue Regressionen zu überdecken
• dynamische WordPress-Muster wie Hooks, REST-Requests und Query-Ergebnisse beheben willst
• mit optionalen Drittanbieter-Plugin-Klassen wie WooCommerce oder ACF umgehen musst

Warum dieses Skill anders ist

Ein generischer PHPStan-Prompt übersieht oft WordPress-spezifische Einschränkungen: zur Laufzeit geladene Klassen, Hook-Callbacks, Plugin-Abhängigkeiten und Analyseumgebungen, die nicht mit der Live-Seite übereinstimmen. wp-phpstan ist deshalb nützlich, weil es zuerst genau diese Grenzfälle adressiert, vor allem das Laden von Stubs und gezielte Ignorierungen.

Wann du es nicht verwenden solltest

Wenn du nur eine schnelle Einmal-Erklärung für einen PHPStan-Befehl brauchst, ist dieses Skill möglicherweise zu viel des Guten. Den größten Nutzen bringt es, wenn die Qualität der Analyse so wichtig ist, dass Setup-Entscheidungen, Baseline-Politik und Typ-Hinweise das Ergebnis spürbar beeinflussen.

So verwendest du das wp-phpstan-Skill

Skill installieren und prüfen

Für wp-phpstan install füge das Skill aus dem WordPress-Agent-Skills-Repo hinzu:

npx skills add WordPress/agent-skills --skill wp-phpstan

Lies nach der Installation zuerst SKILL.md, dann die unterstützenden Referenzen und das Inspektionsskript. Das Repo ist so aufgebaut, dass es die Fragen beantwortet, die die Einführung am stärksten beeinflussen: Was PHPStan sieht, was es ignoriert und was besser typisiert statt unterdrückt werden sollte.

Gib dem Skill die richtigen Eingaben

Das wp-phpstan-Skill arbeitet am besten, wenn du vor der Fehlersuche Projektkontext mitlieferst. Starte mit:

• der Ausgabe von wp-project-triage
• der Frage, ob Composer-Dev-Dependencies geändert werden dürfen
• der Frage, ob die Baseline aktualisiert werden darf
• den konkreten PHPStan-Fehlern oder der Konfigurationsdatei, die geändert werden soll

Ein schwacher Prompt: „Behebe PHPStan in meinem WordPress-Plugin.“

Ein stärkerer Prompt: „Nutze wp-phpstan, um das aktuelle PHPStan-Setup meines Plugins zu prüfen, zu bestätigen, ob szepeviktor/phpstan-wordpress geladen ist, und die kleinste Konfigurationsänderung vorzuschlagen, die unbekannte WordPress-Funktionen ohne pauschale Ignorierungen behebt. Baseline-Änderungen sind nur für bestehende Legacy-Fehler erlaubt.“

Empfohlener Workflow und Dateien

Für die praktische wp-phpstan-Verwendung folge dem Entscheidungsweg des Repos:

1. Setup mit scripts/phpstan_inspect.mjs prüfen
2. Die Hauptkonfiguration und die Baseline-Dateien ansehen
3. references/configuration.md lesen
4. references/third-party-classes.md prüfen
5. references/wordpress-annotations.md verwenden, wenn es um Typinferenz statt um Setup geht

Wenn du den schnellsten Weg zu einem guten Ergebnis willst, schau dir diese Dateien zuerst an:

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

Praktische Prompt-Formulierung

Gute Prompts sagen dem Skill, was feststeht, was offen ist und welches Ergebnis du willst. Zum Beispiel:

• „Prüfe mein phpstan.neon für ein WordPress-Plugin und sag mir, ob ich Stubs ergänzen, ignoreErrors enger fassen oder die Baseline aktualisieren sollte.“
• „Schreibe diese Annotation für einen REST-Controller so um, dass PHPStan die Request-Struktur versteht.“
• „Meine Analyseumgebung enthält WooCommerce nicht; schlage eine eng begrenzte Stub-/Ignore-Strategie für diese fehlenden Klassen vor.“

Diese Detailtiefe hilft wp-phpstan, zwischen Konfigurationsänderungen, Annotationen oder Abhängigkeitsänderungen zu wählen.

FAQ zum wp-phpstan-Skill

Ist wp-phpstan nur für WordPress-Plugins?

Nein. Das wp-phpstan-Skill passt auch für Themes und WordPress-Sites mit eigenem Code. Am nützlichsten ist es überall dort, wo PHPStan Unterstützung braucht, um WordPress-Laufzeitverhalten richtig zu verstehen.

Brauche ich Composer und PHPStan bereits installiert?

Ja, dieses Skill setzt einen Composer-basierten PHPStan-Workflow voraus. Wenn dein Repo kein Composer nutzt oder PHPStan nicht Teil der Toolchain ist, ist das Skill keine gute Wahl.

Ist das besser als ein eigener Prompt?

Meistens ja, wenn dir wiederholbare Setup-Entscheidungen wichtig sind. Ein eigener Prompt kann einen einzelnen Fehler lösen, aber wp-phpstan gibt dir einen besseren Workflow für Baselines, Stubs und WordPress-spezifisches Typing.

Wann sollte ich breite Ignorierungen vermeiden?

Vermeide breite Ignorierungen, wenn die Klasse oder Funktion eigentlich über einen fehlenden Stub, ein Autoload-Problem oder eine nicht passende Analyseumgebung verfügbar wäre. Nutze gezielte Ignorierungen erst dann, wenn du geprüft hast, dass der Abhängigkeitsweg real ist und sich nicht sauber beheben lässt.

So verbesserst du das wp-phpstan-Skill

Nenne den echten PHPStan-Fehlermodus

Die besten wp-phpstan-Ergebnisse entstehen, wenn du den Fehlertyp vor der Lösung benennst:

• unbekannte WordPress-Core-Funktionen → Stubs oder Konfiguration
• Legacy-Rauschen → Baseline-Workflow
• dynamische Request-Daten → @phpstan-param oder wiederverwendbare Typ-Aliase
• optionale Plugin-APIs → gezielte Stubs oder eng begrenzte Ignorierungen

Wenn du nur eine Fehlerliste einfügst, optimiert das Skill womöglich nur das Symptom statt der Ursache.

Teile die Grenze der Analyse mit

Sag dem Skill, was es ändern darf. Die Ergebnisse werden besser, wenn du angibst:

• darf es composer.json bearbeiten?
• darf es Dev-Dependencies hinzufügen?
• darf es phpstan.neon ändern?
• darf es die Baseline neu erzeugen?

Diese Freigaben bestimmen, ob wp-phpstan eher Code-Fixes, Konfigurations-Fixes oder Dependency-Fixes bevorzugen sollte.

Bevorzuge konkrete Eingaben statt allgemeiner Ziele

Stärkere Eingaben führen zu besseren Ergebnissen. Ergänze zum Beispiel:

• den aktuellen PHPStan-Level
• die Verzeichnisse, die analysiert werden
• ob WordPress-Core in CI vorhanden ist
• das genaue Plugin oder die Klasse, die fehlende Symbole auslöst

So kann das wp-phpstan-Skill den passenden Installations- und Nutzungsweg für Backend-Development-Arbeit empfehlen, statt eine generische PHPStan-Checkliste zu liefern.

Iteriere von der Konfiguration zu den Annotationen

Ein guter wp-phpstan guide folgt meist dieser Reihenfolge:

1. Stubs und Discovery prüfen
2. Excludes und Ignorierungen eingrenzen
3. WordPress-spezifische dynamische Typen annotieren
4. Die Baseline nur für akzeptierte Legacy-Schulden aktualisieren

Diese Reihenfolge hält die Analyse streng genug, um neue Probleme zu finden, und reduziert zugleich False Positives dort, wo das dynamische WordPress-Modell eine Inferenz verhindert.