Geprüfte Templates mit PHPStan und einem generierten AGENTS.md
Ein Blockstudio-Block besteht aus zwei Dateien, die zusammenpassen müssen. Die block.json deklariert die Felder, und das Template liest sie als $a['id'] aus. Zur Laufzeit wird nicht verhindert, dass das Template einen umbenannten, nie deklarierten oder falsch geschriebenen Schlüssel ausliest. Es gibt einfach eine leere Zeichenfolge aus, und der Fehler fällt erst auf, wenn jemand eine leere Überschrift auf einer Live-Seite bemerkt. Dasselbe gilt für die Ausgabemaskierung: Eine nicht maskierte echo funktioniert einwandfrei, bis ein Feldwert Markup enthält.
Das blockstudio/phpstan-Paket verlagert beide Probleme in die Analysephase. Es liest deine block.json-Dateien, leitet daraus Typen für $a ab und meldet Template-Zugriffe, die nicht dazu passen. Optionale Voreinstellungen ergänzen Regeln für die Theme-Struktur, Maskierung sowie Prüfungen für JavaScript und Tailwind. Zum Paket gehören zwei Ergänzungen: ein verwalteter Pre-Commit-Hook, der die Analyse ausführt, und ein Generator, der ein AGENTS.md mit einer Beschreibung deines Projekts für Coding-Agenten erstellt.
Diese Anleitung erstellt ein kleines Theme, lässt absichtlich eines seiner Templates fehlschlagen, zeigt die Analyseausgabe, behebt den Fehler und richtet anschließend die Commit-Prüfung und den Agentenvertrag ein.
Theme einrichten
Beginne mit einem Theme-Ordner, der einen style.css-Header, ein composer.json und einen Block enthält:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Installiere das Paket als Entwicklungsabhängigkeit:
composer require --dev blockstudio/phpstan
Es installiert PHPStan und die WordPress-Stubs von szepeviktor/phpstan-wordpress und richtet drei ausführbare Dateien in vendor/bin ein: blockstudio-phpstan, blockstudio-githooks und blockstudio-agents.
Lege dann fest, was die Analyse ausführen soll. Projektweite Standardwerte stehen im Objekt phpstan von blockstudio.json, damit interaktive Durchläufe, CI und der Commit-Hook dieselben Einstellungen verwenden:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme ist die strengste der drei statischen Voreinstellungen. Die Tabelle weiter unten erklärt, was jede davon ergänzt. excludePaths hält Composer-eigene Dateien aus dem Blockstudio-Scan und der PHP-Analyse heraus.
Ein Template absichtlich fehlerhaft machen
Der Hero-Block deklariert ein einzelnes Feld:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Das Template liest dieses Feld korrekt aus, liest dann aber ein subtitle, das der Block nie deklariert hat, und gibt es ohne Maskierung aus:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
Im Editor und im Frontend wird ein leerer Absatz ohne Fehlermeldung ausgegeben. Führe stattdessen die Analyse aus:
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
Line blockstudio/hero/index.php
------ -------------------------------------------------------------------
2 Variable $a might not be defined.
🪪 variable.undefined
3 Dynamic Blockstudio attributes must be escaped before output.
🪪 blockstudio.output.unescaped
3 Field "subtitle" does not exist in block.json (block: acme/hero).
🪪 blockstudio.field
3 Offset 'subtitle' does not exist on array{heading: string}.
🪪 offsetAccess.notFound
3 Parameter #1 (mixed) of echo cannot be converted to string.
🪪 echo.nonString
3 Variable $a might not be defined.
🪪 variable.undefined
------ -------------------------------------------------------------------
[ERROR] Found 6 errors
Der Befehl wird mit 1 beendet. Die Diagnosen, von der spezifischsten zur allgemeinsten:
blockstudio.fieldist die Template-Regel. Sie hat dasblock.jsonneben dem Template gefunden, dessen Felder aufgelöst und festgestellt, dasssubtitlenicht dazugehört.offsetAccess.notFoundist PHPStan selbst, das zum selben Schluss kommt, weil die Erweiterung$adie konkrete Formarray{heading: string}gibt, abgeleitet ausblock.json. Jedem Feldtyp entspricht ein PHP-Typ:textist einstring,toggleeinbool, und ein Repeater ist ein Array aus Zeilenformen.blockstudio.output.unescapedstammt aus derextreme-theme-Ebene. Ausgegebene Attributwerte müssen eine Maskierungsfunktion wieesc_html(),esc_attr(),esc_url()oderwp_kses_post()durchlaufen.echo.nonStringergibt sich aus dem unbekannten Schlüssel: Ein nicht vorhandener Offset hat keinen Zeichenfolgentyp, der ausgegeben werden könnte.variable.undefinedwird gemeldet, weil PHPStan eine Template-Datei sieht, nicht aber die Renderfunktion, die$avor dem Einbinden definiert. Der Abschnitt zur Fehlerbehebung geht darauf ein.
Fehler beheben
Entscheide, ob subtitle ein echtes Feld ist. Hier ist es das. Deklariere es daher mit einem default, denn die Theme-Ebene verlangt eines für jedes Feld:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" },
{ "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
]
}
}
Maskiere die Ausgabe und deklariere $a mit der von der Erweiterung abgeleiteten Form:
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
Schreibe die Annotation in der exakten Form. Der maßgebliche Befehl führt PHPStan auf Stufe max aus. Eine weniger strenge @var array<string, mixed> $a-Form wird mit varTag.nativeType abgelehnt („PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}“). Unter 7.6 erweitert es außerdem jedes Feld zu mixed, sodass jeder Aufruf von esc_html() argument.type meldet. Die Meldung varTag.nativeType gibt die abgeleitete Form aus und ist daher auch der schnellste Weg, die zu übernehmende Annotation zu finden.
Blockstudio 7.7 behandelt $a in Block-Templates als definiert. Dadurch verschwinden die Diagnosen variable.undefined, und die Annotation wird optional. Unter 7.7 meldet das fehlerhafte Template oben vier statt sechs Fehler; das korrigierte Template besteht auch ohne die Zeile @var.
Voreinstellung auswählen
Bei der Installation des Pakets wird nur die Basiserweiterung aktiviert. Der maßgebliche Befehl verwendet base, sofern ein Projekt keine andere Voreinstellung auswählt. Die Abhängigkeit allein aktiviert also nicht die strengeren Ebenen.
| Voreinstellung | Ergänzt |
|---|---|
base |
Zugriff auf Template-Felder in PHP, Twig und Blade, Prüfungen von Block-Tags, Schema-Validierung für block.json, field.json und page.json, Erweiterung von JSON, db.php, rpc.php und cron.php, Settings::get()-Pfade und blockstudio/*-Hook-Namen. |
theme |
Basis plus Theme-Stammverzeichnisse und style.css-Header, in block.json deklarierte Assets statt manuellem Einreihen, %selector%-Scoping in style.scss, Feld-Standardwerte und Grenzen für Repeater. |
extreme-theme |
Theme plus strikte PHPStan-Flags, abgewiesene Shell- und eval()-Aufrufe, direkte $wpdb-Schreibzugriffe, Output-Escaping sowie Prüfungen für Tailwind, JavaScript und Interactivity API. |
wordpress-render |
Extremes Theme plus eine Live-Render-Prüfung, die du als Befehl bereitstellst. |
Wenn keine Projektkonfiguration eingebunden ist, führt der maßgebliche Befehl außerdem base und theme auf PHPStan-Stufe max aus; extreme-theme legt max selbst fest. Jede Diagnose einer Voreinstellung hat eine stabile Kennung blockstudio.*, die in der PHPStan-Referenz aufgeführt ist.
Die Theme- und Extreme-Ebenen prüfen auch PHP-Dateien. Fehlt einem Feld sein default, und enthält ein script.js einen Konsolenaufruf, meldet derselbe Befehl:
------ -----------------------------------------------------------
Line blockstudio/hero/block.json
------ -----------------------------------------------------------
1 Blockstudio field "subtitle" must define a default value.
🪪 blockstudio.field.default
------ -----------------------------------------------------------
------ ------------------------------------------------------------
Line blockstudio/hero/script.js
------ ------------------------------------------------------------
2 Remove debug output "console.log" from shipped JavaScript.
🪪 blockstudio.javascript.debugOutput
------ ------------------------------------------------------------
Diese Prüfungen werden über den Ergebniscache von PHPStan gemeldet. Nach einer Änderung nur an einem block.json oder Skript kann ein warmer Cache noch [OK] No errors für den alten Stand melden. Übergib --debug nach --, um den Cache zu umgehen, bevor du dich bei Änderungen außerhalb von PHP auf ein erfolgreiches Ergebnis verlässt:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Befehlsoptionen und Exit-Codes
Befehlszeilenwerte ersetzen für einen Durchlauf die entsprechenden blockstudio.json-Werte. Das bedeutet wirklich ersetzen: Sobald du ein --exclude übergibst, wird das konfigurierte excludePaths verworfen. Füge daher beim Ergänzen eines Werts vendor/** erneut hinzu:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Alles nach -- wird an PHPStan übergeben. Der Wrapper erhöht das PHPStan-Speicherlimit auf 1G, sofern du nicht selbst ein --memory-limit übergibst. Die Konfiguration wird im temporären Systemverzeichnis zusammengesetzt, sodass keine generierte Datei im Projekt landet. Bei erfolgreicher Analyse wird 0 zurückgegeben, bei PHPStan-Diagnosen 1 und bei Fehlern in der Verwendung, Konfiguration oder Ausführung 2.
Führe den Befehl über den maßgeblichen Wrapper aus, statt phpstan/extension-installer hinzuzufügen. Die Voreinstellungen enthalten die Erweiterung bereits. Ist der Installer vorhanden, wird dasselbe extension.neon zweimal geladen: PHPStan bricht mit „This file is included multiple times“ ab, bevor es irgendetwas analysiert.
In ein bestehendes Projekt integrieren
Bei der ersten Analyse eines Projekts gibt es meist Befunde. Statt die Voreinstellung abzuschwächen, halte sie in einer Baseline fest, damit für neuen Code weiterhin alle Regeln gelten:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Binde die Baseline in eine Projektkonfiguration ein und verweise phpstan.configuration darauf:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Beim nächsten Durchlauf wird [OK] No errors zusammen mit den erfassten Befunden gemeldet; neue Befunde führen weiterhin zum Fehlschlag. Verwende bei den Voreinstellungen base oder theme außerdem level: max unter parameters in phpstan.neon: Der maßgebliche Befehl legt diese Stufe nur selbst fest, wenn keine Projektkonfiguration eingebunden ist.
Commits an die Analyse knüpfen
Wenn "githooks": { "commit": true } in blockstudio.json eingerichtet ist, synchronisiere den verwalteten Hook einmal nach der Installation der Abhängigkeiten:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Der Befehl schreibt den Hook in Git’s eigenes Verzeichnis, verweist core.hooksPath darauf und reiht einen zuvor eingerichteten Pre-Commit-Hook dahinter ein. Der Hook führt im Projektstamm nur vendor/bin/blockstudio-phpstan -- --no-progress aus: keine Formatierung, keine Umschreibungen. Ein Commit mit dem zuvor fehlerhaften Template wird bei der Analyse gestoppt:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Setze commit auf false und führe sync erneut aus, oder führe vendor/bin/blockstudio-githooks remove aus, um den vorherigen Hook-Pfad wiederherzustellen. Gelöscht werden nur Dateien, die Blockstudio geschrieben hat.
Projektvertrag generieren
Die Analyse zeigt einem Agenten im Nachhinein, was er falsch gemacht hat. Ein AGENTS.md informiert ihn im Voraus: wo sich Blöcke und Seiten befinden, wie Felder in Templates gelangen, welche Funktionen aktiviert sind und was die ausgewählte Voreinstellung ablehnt. blockstudio-agents generiert dieses Dokument direkt aus dem Projekt:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Für das Theme aus dieser Anleitung beginnt die generierte Datei so:
# Blockstudio contract for Acme
## Project
- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.
## What this project contains
- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
Jede Zeile stammt aus einer von drei Quellen. Die Projektdateien liefern den Projekttyp, die Anzahlen, Verzeichnisse, Namensräume und Template-Sprachen. blockstudio.json liefert die aktivierten Funktionen. Deshalb steht der Commit-Hook unter „Enabled features“ und vendor/bin/blockstudio-githooks sync unter „Commands“ – aber nur, weil githooks.commit gesetzt ist. Die ausgewählte Voreinstellung liefert den Abschnitt zu den Qualitätsanforderungen, der Ebene für Ebene aus den Voreinstellungsdateien gelesen wird:
The `theme` layer adds:
- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.
Aktuell halten
Der Vertrag veraltet, wenn sich die Konfiguration ändert. Nach dem Aktivieren von Tailwind in blockstudio.json erkennt der Prüfmodus die Änderung:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Der Befehl wird mit 1 beendet und eignet sich damit als CI-Schritt neben der Analyse. Beim erneuten Generieren kommen ein Funktionseintrag „Tailwind CSS“ und der Befehl wp bs tailwind compile hinzu.
Hinweise bleiben beim erneuten Generieren erhalten
Die Datei endet mit einem Hinweisbereich. Alles zwischen dessen Markierungen bleibt bei jeder erneuten Generierung bytegenau erhalten. Dort gehört Projektwissen hin, das sich nicht aus Dateien ableiten lässt:
## Project notes
Everything above is generated. Text between the markers below is preserved when this file is regenerated.
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Der Generator überschreibt niemals eine Datei, die er nicht selbst geschrieben hat. Wird er auf eine selbst verfasste AGENTS.md angewendet, verweigert er den Vorgang und wird mit 2 beendet:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Um selbst verfassten Text zu erhalten, sichere ihn, führe den Befehl mit --force aus und füge den Text in den Hinweisbereich ein. Weitere Optionen sind --root, --config und --output sowie --stdout, womit der Vertrag ausgegeben statt geschrieben wird.
Änderungen in Blockstudio 7.7
Das Paket 7.7 behält die hier beschriebenen Befehle, Voreinstellungen und Exit-Codes bei. Beim Erstellen dieser Anleitung mit 7.7 zeigten sich zwei Unterschiede: $a benötigt die im Abschnitt zur Fehlerbehebung beschriebene Annotation nicht mehr, und der generierte Vertrag beschreibt die Validierung von Block-Tags umfassender. Er schließt HTML-Elemente ein, die in Seitenquellen Blöcken zugeordnet sind, sowie globale Attribute, die ein Tag weitergeben kann.
Nächste Schritte
- PHPStan-Referenz: alle Regeln, Parameter der Voreinstellungen, Feldtypformen, Live-Render-Prüfungen und Diagnosekennungen.
- KI-Integration: der Dokumentationsindex für Coding-Agenten als Ergänzung zu deinem Projektvertrag.
- Vibecoding mit Blockstudio: Zusammenarbeit mit Coding-Agenten an einem Blockstudio-Projekt.
- Rezeptbuch für Feldmuster: Feldstrukturen mit Template-Schlüsseln, die von der Analyse verstanden werden, darunter Gruppen und Repeater.