PHPDoc-Generierung und -Validierung in PhpStorm automatisieren

1. Warum PHPDoc trotz nativer Typen weiterhin wichtig ist

Seit PHP 8 lassen sich viele Typinformationen direkt in der Signatur ausdruecken: Union-Types, Nullable-Types, sogar Intersection-Types seit PHP 8.1. Trotzdem bleibt PHPDoc unverzichtbar, weil PHP native Typen fuer generische Collections wie array oder fuer iterable-Rueckgaben mit konkretem Elementtyp nicht ausdruecken kann. Genau diese Faelle sind in Magento-Projekten allgegenwaertig, etwa bei getItems()-Methoden von Collection-Klassen.

Gerade im Projektstandard mit PHPStan auf Level 5 ist PHPDoc kein optionales Dekor, sondern die einzige Quelle, aus der PHPStan die praezisen Array-Shape- und Generics-Informationen zieht. Fehlt der @return-Tag mit dem korrekten Elementtyp, faellt PHPStan auf mixed zurueck und verliert genau die Typinformation, die eigentlich geprueft werden sollte. PHPDoc und statische Analyse sind damit zwei Seiten derselben Medaille.

2. PHPDoc-Bloecke automatisch generieren lassen

PhpStorm generiert einen PHPDoc-Block, sobald man oberhalb einer Methoden- oder Klassendefinition /** eingibt und die Eingabetaste drueckt. Die IDE liest dabei die tatsaechliche Signatur aus: Parameter-Namen, deklarierte Typen und den Rueckgabetyp werden automatisch als @param- und @return-Zeilen eingefuegt, ohne dass man sie manuell abtippen muss.

Bei Konstruktoren mit Constructor Property Promotion, wie sie im Projektstandard fuer alle neuen Klassen vorgeschrieben sind, erkennt PhpStorm die promovierten Properties und uebernimmt deren Typen korrekt in den generierten Block. Das ist besonders wertvoll, weil promovierte Properties sonst leicht vergessen werden, wenn man PHPDoc rein manuell nachtraegt.

/**
 * Laedt die Produktdaten fuer eine gegebene SKU.
 *
 * @param string $sku Die Produkt-SKU.
 * @param StoreInterface $store Der aktuelle Store-Kontext.
 * @return ProductInterface
 * @throws NoSuchEntityException
 */
public function loadProduct(string $sku, StoreInterface $store): ProductInterface
{
    // ...
}

3. Praezise Typen fuer Arrays und Collections inferieren

Der automatisch generierte Block liefert fuer einfache Typen wie string oder ProductInterface sofort korrekte Ergebnisse. Bei Arrays reicht die reine Signaturanalyse aber nicht aus, denn PHP kennt intern nur array, nicht array. Hier hilft PhpStorm durch Typinferenz aus dem Methodenkoerper: Wird innerhalb der Methode erkennbar ein Array aus ProductInterface-Objekten aufgebaut, schlaegt die IDE den praeziseren Array-Shape als Vervollstaendigung vor.

In der Praxis ist es dennoch sinnvoll, den generierten Vorschlag zu pruefen und bei Bedarf manuell zu praezisieren, etwa mit array statt nur ProductInterface[], wenn PHPStan mit generischen Array-Shapes arbeiten soll. Fuer Magento-Collection-Klassen, deren getItems()-Methode intern \Magento\Framework\Data\Collection zurueckgibt, lohnt sich ein expliziter @return \Magento\Catalog\Model\ResourceModel\Product\Collection|ProductInterface[]-Kommentar, damit sowohl IDE-Autovervollstaendigung als auch PHPStan die konkreten Elementtypen kennen.

/**
 * Gibt alle aktiven Produkte der Kategorie zurueck.
 *
 * @return ProductInterface[]
 */
public function getActiveProducts(): array
{
    return array_filter(
        $this->collection->getItems(),
        static fn (ProductInterface $product): bool => $product->getStatus() === 1
    );
}

4. Inspektionen fuer fehlende und veraltete PHPDoc-Kommentare

Unter Settings > Editor > Inspections > PHP > PHPDoc findet sich eine Reihe aktivierbarer Pruefungen, unter anderem 'Missing PHPDoc comment', 'Missing @param tag', 'Missing @return tag' und 'Incorrect PHPDoc'. Nach dem Projektstandard, der PHPDoc fuer jede public, protected und private Methode verlangt, lohnt es sich, diese Inspektionen auf Warning oder sogar Error zu stellen, statt sie auf der Standardeinstellung zu belassen.

Besonders wertvoll ist 'Incorrect PHPDoc', weil diese Inspektion aktiv gegen die tatsaechliche Signatur abgleicht: Aendert sich ein Parametertyp, ohne dass der zugehoerige @param-Tag angepasst wird, markiert PhpStorm die Zeile sofort als Fehler. Das verhindert das haeufigste PHPDoc-Problem in gewachsenen Codebasen, naemlich Kommentare, die eine laengst veraltete Signatur beschreiben und damit aktiv in die Irre fuehren.

5. Projektweite PHPDoc-Luecken mit Code-Inspektion aufdecken

Fuer eine bestehende Codebasis, in der PHPDoc bisher nur unregelmaessig gepflegt wurde, ist die Einzelmethoden-Ansicht zu langsam. Hier hilft Code > Inspect Code mit einem auf die PHPDoc-Kategorie eingeschraenkten Profil, um in einem Durchgang alle betroffenen Dateien in app/code/Mironsoft aufzulisten.

Das Ergebnis erscheint als sortierbare Liste im Inspection-Tool-Window, gruppiert nach Datei und Inspektionstyp. Bei einem neuen Modul empfiehlt es sich, diesen Lauf direkt nach dem ersten Entwurf einer Klasse durchzufuehren, bevor der Code in Review geht, denn fehlende @throws-Tags bei Methoden, die eine NoSuchEntityException werfen koennen, fallen so auf, bevor ein Reviewer sie manuell nachtragen muss.

Code > Inspect Code...
  Scope: app/code/Mironsoft
  Profile: Custom (nur PHPDoc-Inspektionen aktiviert)

Ergebnis im Inspection-Window:
  - 12x Missing @throws tag
  - 4x Incorrect PHPDoc (Parametertyp veraltet)
  - 7x Missing PHPDoc comment (private Methoden)

6. Zusammenspiel zwischen PHPDoc und PHPStan-Typisierung

PHPStan liest PHPDoc-Kommentare als zusaetzliche Typquelle neben den nativen PHP-Typen und kombiniert beide zu einer moeglichst praezisen Typinformation. Widerspricht sich PHPDoc und native Signatur, etwa weil der @return-Tag einen anderen Typ angibt als die tatsaechliche return-Anweisung, meldet PHPStan bereits auf Level 5 einen Fehler. PhpStorm und PHPStan pruefen hier faktisch dieselbe Konsistenz, nur zu unterschiedlichen Zeitpunkten: PhpStorm waehrend des Tippens, PHPStan als expliziter Analyse-Lauf.

Fuer die bekannten Magento-Interface-Luecken aus dem Projektstandard, etwa PageInterface::getData() oder StoreInterface::getBaseUrl(), reicht PHPDoc allein nicht aus, weil die Methode im Interface schlicht fehlt. Hier bleibt @phpstan-ignore-next-line die richtige Loesung, PHPDoc sollte in diesen Faellen trotzdem den tatsaechlich zurueckgegebenen Typ dokumentieren, damit die IDE-Autovervollstaendigung korrekt bleibt, auch wenn PHPStan die Zeile ignoriert.

/** @var \Magento\Cms\Model\Page $page */
$page = $this->pageRepository->getById($pageId);

// @phpstan-ignore-next-line getData() ist nicht im PageInterface, aber im Model vorhanden
$metaTitle = $page->getData('meta_title');

7. Live Templates fuer wiederkehrende PHPDoc-Muster

Fuer haeufig wiederkehrende Docblock-Muster, etwa ViewModel-Klassen, die immer ArgumentInterface implementieren und immer eine getData()-aehnliche Methode mit @return array dokumentieren, lassen sich unter Settings > Editor > Live Templates eigene Vorlagen anlegen. Ein Template mit Platzhaltern fuer Klassenname und Beschreibung reduziert die Zeit fuer einen vollstaendigen, projektstandardkonformen Docblock auf wenige Tastendruecke.

In der Praxis lohnt sich ein eigenes Live-Template-Set pro wiederkehrendem Muster: eines fuer Repository-Methoden mit typischen @throws-Kombinationen, eines fuer ViewModel-Konstruktoren mit Constructor Property Promotion, eines fuer Plugin-Methoden mit dem ueblichen before-, around- oder after-Praefix. Das Team spart so nicht nur Tipparbeit, sondern erreicht auch eine einheitlichere PHPDoc-Struktur ueber alle Module hinweg.

8. PHPDoc bei Refactorings automatisch mitziehen

Ein oft uebersehener Vorteil: Wenn PhpStorm einen Parameter per Refactoring umbenennt oder eine Methode extrahiert, aktualisiert die IDE in vielen Faellen automatisch auch den zugehoerigen PHPDoc-Block. Bei Rename-Refactorings von Parametern wird der @param-Name mitgefuehrt, bei Change-Signature-Refactorings werden neue Parameter als zusaetzliche @param-Zeilen ergaenzt und entfernte Parameter aus dem Block geloescht.

Das funktioniert zuverlaessig genug, um den manuellen Pflegeaufwand deutlich zu senken, ersetzt aber keine abschliessende Pruefung. Bei komplexeren Refactorings, etwa wenn eine Methode in zwei aufgeteilt wird, lohnt sich danach ein kurzer Blick auf die 'Incorrect PHPDoc'-Inspektion, um sicherzugehen, dass keine verwaisten @param-Zeilen fuer laengst entfernte Parameter zurueckbleiben.

9. PHPDoc-Vollstaendigkeit als Teil des Review-Workflows

Damit die Projektregel 'jede Methode braucht PHPDoc' nicht von der Disziplin einzelner Entwickler abhaengt, empfiehlt sich eine Kombination aus lokaler Inspektion in PhpStorm und einem CI-Schritt, der phpcs mit einer Doc-Comment-Sniff-Regel wie Squiz.Commenting.FunctionComment ausfuehrt. So wird eine fehlende oder inkorrekte PHPDoc nicht erst im Review durch einen Menschen entdeckt, sondern bereits vor dem Push durch die IDE und danach automatisiert in der Pipeline.

In der Praxis hat sich bewaehrt, den Inspect-Code-Lauf aus dem vorherigen Abschnitt als festen Schritt vor jedem Pull Request zu etablieren, kombiniert mit bin/phpcs als schnellem Kommandozeilen-Check direkt im Container. Wer beide Ebenen konsequent nutzt, reduziert PHPDoc-Nacharbeiten im Review auf seltene Grenzfaelle statt auf einen wiederkehrenden Kommentarpunkt.

10. Zusammenfassung

11. FAQ: PHPDoc-Automatisierung in PhpStorm: Das Wichtigste auf einen Blick