Kontrollerade mallar med PHPStan och en genererad AGENTS.md
Ett Blockstudio-block består av två filer som måste stämma överens. block.json deklarerar fälten, och mallen läser dem som $a['id']. Inget hindrar mallen från att läsa en nyckel som har bytt namn, aldrig deklarerats eller stavats fel. Den renderar bara en tom sträng, och misstaget upptäcks först när någon ser en tom rubrik på en publicerad sida. Detsamma gäller output-escaping: oescapad echo fungerar utmärkt tills ett fältvärde innehåller markup.
Paketet blockstudio/phpstan flyttar båda problemen till analystillfället. Det läser dina block.json-filer, härleder typer för $a från dem och rapporterar malläsningar som inte stämmer. De valfria förinställningarna lägger till regler för temastruktur, escaping samt kontroller av JavaScript och Tailwind. Samma paket innehåller två tillägg: en hanterad pre-commit-hook som kör analysen och en generator som skriver ett AGENTS.md med en beskrivning av projektet för kodningsagenter.
Den här guiden bygger ett litet tema, bryter avsiktligt en av dess mallar, läser analysutdata, åtgärdar felet och kopplar sedan in commit-kontrollen och agentkontraktet.
Konfigurera temat
Börja med en temamapp som har ett style.css-huvud, ett composer.json och ett block:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Installera paketet som ett utvecklingsberoende:
composer require --dev blockstudio/phpstan
Det hämtar in PHPStan och stubbarna för WordPress från szepeviktor/phpstan-wordpress och installerar tre körbara filer i vendor/bin: blockstudio-phpstan, blockstudio-githooks och blockstudio-agents.
Ange sedan vad analysen ska köra. Projektgemensamma standardvärden finns i objektet phpstan i blockstudio.json, så interaktiva körningar, CI och commit-hooken använder samma inställningar:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme är den striktaste av de tre statiska förinställningarna. Tabellen längre ned förklarar vad varje förinställning lägger till. excludePaths håller Composers egna filer utanför genomsökningen med Blockstudio och analysen av PHP.
Bryt en mall avsiktligt
Hero-blocket deklarerar ett enda fält:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Mallen läser fältet korrekt och läser sedan ett subtitle som blocket aldrig deklarerade och skriver ut det utan escaping:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
I redigeraren och i frontend renderas detta som ett tomt stycke utan fel. Kör analysen i stället:
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
Kommandot avslutas med 1. Läs diagnostikmeddelandena med början från det mest specifika:
blockstudio.fieldär mallregeln. Den hittadeblock.jsonbredvid mallen, slog upp dess fält och konstaterade attsubtitleinte finns bland dem.offsetAccess.notFounddrar samma slutsats om PHPStan, eftersom tillägget ger$aden konkreta formenarray{heading: string}, härledd frånblock.json. Varje fälttyp motsvarar en PHP-typ:textär enstring,toggleenbooloch en repeater en array av radformer.blockstudio.output.unescapedkommer från lagretextreme-theme. Ekoade attributvärden måste gå genom en escaping-funktion somesc_html(),esc_attr(),esc_url()ellerwp_kses_post().echo.nonStringföljer av den okända nyckeln: ett offset som inte finns har ingen strängtyp att skriva ut.variable.undefinedvisas eftersom PHPStan ser en mallfil, inte renderingsfunktionen som definierar$ainnan den inkluderas. Avsnittet om åtgärden tar upp det.
Åtgärda felet
Avgör om subtitle är ett riktigt fält. Här är det det, så deklarera det med en default, eftersom temalagret kräver en för varje fält:
{
"$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": "" }
]
}
}
Escapa utdata och deklarera $a med den form som tillägget härleder:
<?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
Skriv annoteringen med exakt den här formen. Det kanoniska kommandot kör PHPStan på nivå max, där en mindre strikt @var array<string, mixed> $a avvisas med varTag.nativeType (“PHPDoc-tagg @var med typen array<string, mixed> är inte en undertyp av den inbyggda typen array{heading: string, subtitle: string}”). I 7.6 breddas dessutom varje fält till mixed, så varje anrop till esc_html() rapporterar argument.type. Meddelandet varTag.nativeType skriver ut den härledda formen och är därför också det snabbaste sättet att hitta annoteringen att kopiera.
I 7.7 behandlar Blockstudio $a som definierat i blockmallar, så diagnostikmeddelandena från variable.undefined försvinner och annoteringen blir valfri. Med 7.7 rapporterar den trasiga mallen ovan fyra fel i stället för sex, och den åtgärdade mallen klarar kontrollen utan raden @var.
Välj en förinställning
När paketet installeras aktiveras bara bastillägget. Det kanoniska kommandot kör base om inte ett projekt väljer en annan förinställning, så beroendet aktiverar inte de striktare lagren i sig.
| Förinställning | Innehåller |
|---|---|
base |
Åtkomst till mallfält i PHP, Twig och Blade, kontroller av blocktaggar, schemavalidering för block.json, field.json, page.json, tilläggets JSON, db.php, rpc.php och sökvägarna cron.php, Settings::get() samt hooknamn för blockstudio/*. |
theme |
Basen samt temarötter och style.css-huvuden, resurser deklarerade i block.json i stället för att läggas till manuellt, avgränsning av %selector% i style.scss, fältstandardvärden och gränser för repeaters. |
extreme-theme |
Tema samt strikta flaggor för PHPStan, avvisade anrop till shell och eval(), råa skrivningar med $wpdb, output-escaping samt kontroller av Tailwind, JavaScript och Interactivity API. |
wordpress-render |
Extremt tema samt en live-renderingskontroll som du tillhandahåller som ett kommando. |
När ingen projektkonfiguration ingår kör det kanoniska kommandot även base
och theme på nivån PHPStan max; extreme-theme ställer själv in max.
Varje förinställd diagnostik har en stabil identifierare blockstudio.*, som finns i
referensen PHPStan.
Tema- och extremalagren granskar även PHP-filer. Om ett fält saknar sitt default och en script.js loggar till konsolen rapporterar samma kommando:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Dessa kontroller rapporteras via resultatcachen i PHPStan. Om du bara har redigerat en block.json eller ett skript kan en varm cache rapportera [OK] No errors för det gamla tillståndet. Skicka med --debug efter --, vilket kringgår cachen, innan du litar på ett godkänt resultat för ändringar som inte gäller PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Kommandoalternativ och avslutningskoder
Kommandoradsvärden ersätter motsvarande värden för blockstudio.json vid en körning. Ersätta betyder ersätta: om du anger något --exclude försvinner det konfigurerade excludePaths, så upprepa vendor/** när du lägger till ett:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Allt efter -- skickas till PHPStan. Wrappern höjer minnesgränsen för PHPStan till 1G om du inte anger ett eget --memory-limit, och sätter samman konfigurationen i systemets temporära katalog så att inga genererade filer hamnar i projektet. Kommandot avslutas med 0 när analysen godkänns, 1 när PHPStan rapporterar diagnostik och 2 vid fel i användning, konfiguration eller körning.
Kör det via det kanoniska kommandot i stället för att lägga till phpstan/extension-installer. Förinställningarna innehåller redan tillägget, och när installeraren finns laddas samma extension.neon två gånger: PHPStan avbryts med ”Den här filen inkluderas flera gånger” innan någon analys har gjorts.
Inför det i ett befintligt projekt
Ett projekt som analyseras för första gången har vanligtvis anmärkningar. Sänk inte förinställningen; registrera dem i en baslinje så att ny kod måste följa de fullständiga reglerna:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Inkludera baslinjen från en projektkonfiguration och ange den för phpstan.configuration:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Nästa körning rapporterar [OK] No errors med de registrerade anmärkningarna på plats, medan allt nytt fortfarande leder till fel. Med förinställningen base eller theme ska du även ange level: max under parameters i phpstan.neon: det kanoniska kommandot ställer bara in den nivån när ingen projektkonfiguration ingår.
Stoppa commits vid analysfel
Med "githooks": { "commit": true } i blockstudio.json synkroniserar du den hanterade hooken en gång efter att beroendena har installerats:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Kommandot skriver hooken i den egna katalogen för Git, pekar core.hooksPath på den och kedjar ihop den med eventuell pre-commit-hook som var konfigurerad tidigare. Hooken kör vendor/bin/blockstudio-phpstan -- --no-progress från projektroten och inget annat: ingen formatterare och inga omskrivningar. Om du försöker committa den trasiga mallen från tidigare stoppas det vid analysen:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Ställ in commit på false och kör sync igen, eller kör vendor/bin/blockstudio-githooks remove för att återställa den tidigare sökvägen till hooken. Bara filer som Blockstudio har skrivit tas bort.
Generera projektkontraktet
Analysen talar om för en agent vad den gjorde fel i efterhand. Ett AGENTS.md informerar den i förväg: var block och sidor finns, hur fält når mallar, vilka funktioner som är aktiverade och vad den valda förinställningen kommer att avvisa.
blockstudio-agents genererar dokumentet från själva projektet:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
För temat i den här guiden börjar den genererade filen så här:
# 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.
Varje rad hämtas från en av tre källor. Projektets filer anger projekttyp, antal, kataloger, namnrymder och mallspråk. blockstudio.json anger aktiverade funktioner, så commit-hooken visas under ”Aktiverade funktioner” och vendor/bin/blockstudio-githooks sync under ”Kommandon” enbart för att githooks.commit är inställt. Den valda förinställningen anger avsnittet om korrekthet, som hämtas från förinställningsfilerna lager för lager:
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.
Håll det uppdaterat
Kontraktet blir inaktuellt när konfigurationen ändras. När Tailwind har aktiverats i blockstudio.json upptäcker kontrolläget det:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Det avslutas med 1, vilket gör att det kan användas som ett CI-steg bredvid analysen. Om du genererar på nytt läggs en funktionspost till med namnet ”Tailwind CSS” samt kommandot wp bs tailwind compile.
Anteckningar som bevaras vid generering
Filen avslutas med ett anteckningsområde. Allt mellan markörerna bevaras byte för byte vid varje ny generering, så projektkunskap som inte går att härleda från filer hör hemma där:
## 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 -->
Generatorn ersätter aldrig en fil som den inte själv har skrivit. Om du kör den mot ett handskrivet AGENTS.md vägrar den och avslutas med 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Om du vill behålla handskriven text kopierar du undan den, kör med --force och klistrar in den i anteckningsområdet. De andra alternativen är --root, --config och --output, samt --stdout som skriver ut kontraktet i stället för att skriva det till en fil.
Vad som ändras i Blockstudio 7.7
Paketet 7.7 har kvar kommandona, förinställningarna och avslutningskoderna som beskrivs här. Två skillnader framkom när guiden togs fram med den versionen: $a behöver inte längre en annotering, som beskrivs i avsnittet om åtgärden, och det genererade kontraktet beskriver validering av blocktaggar bredare. Det omfattar HTML-element som kopplas till block i sidkällor samt de globala attribut som en tagg kan vidarebefordra.
Nästa steg
- PHPStan-referens: varje regel, förinställd parameter, fälttyp och struktur, live-renderingskontroll och diagnostisk identifierare.
- AI-integration: dokumentationsindexet för kodningsagenter som kompletterar projektets kontrakt.
- Vibekodning med Blockstudio: arbeta med kodningsagenter i ett Blockstudio-projekt.
- Kokbok med fältmönster: fältstrukturer vars mallnycklar analysen förstår, inklusive grupper och upprepningsfält.