Gecontroleerde templates met PHPStan en een gegenereerde AGENTS.md
Een Blockstudio-blok bestaat uit twee bestanden die op elkaar moeten aansluiten. De block.json declareert de velden en de template leest ze als $a['id']. Tijdens runtime wordt niets tegengehouden als de template een sleutel leest die is hernoemd, nooit is gedeclareerd of verkeerd is gespeld. Er wordt gewoon een lege tekenreeks weergegeven en de fout komt aan het licht wanneer iemand een lege kop op een livepagina opmerkt. Hetzelfde geldt voor uitvoerescaping: een niet-geëscapete echo werkt prima totdat een veldwaarde markup bevat.
Het pakket blockstudio/phpstan verplaatst beide problemen naar de analysetijd. Het leest uw bestanden van block.json, bepaalt de typen van $a daaruit en meldt templatelezingen die niet overeenkomen. De optionele presets voegen regels toe voor de themastructuur, escaping en controles voor JavaScript en Tailwind. Hetzelfde pakket bevat twee aanvullende onderdelen: een beheerde pre-commit-hook die de analyse uitvoert en een generator die een AGENTS.md schrijft waarin uw project voor codeeragents wordt beschreven.
Deze handleiding bouwt een klein thema, breekt met opzet een van de templates, bekijkt de analyseresultaten, lost het probleem op en configureert daarna de commitcontrole en het agentcontract.
Het thema instellen
Begin met een themamap met een style.css-header, een composer.json en één blok:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Installeer het pakket als ontwikkelafhankelijkheid:
composer require --dev blockstudio/phpstan
Het haalt PHPStan en de WordPress-stubs van szepeviktor/phpstan-wordpress op en installeert drie uitvoerbare bestanden in vendor/bin: blockstudio-phpstan, blockstudio-githooks en blockstudio-agents.
Geef daarna aan de analyse op wat deze moet uitvoeren. Projectbrede standaardwaarden staan in het object phpstan van blockstudio.json, zodat interactieve uitvoeringen, CI en de commit-hook dezelfde instellingen gebruiken:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme is de strengste van de drie statische presets. Verderop in de tabel staat wat elke preset toevoegt. excludePaths houdt de eigen bestanden van Composer buiten de scan van Blockstudio en buiten de analyse van PHP.
Breek met opzet een template
Het hero-blok declareert één veld:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
De template leest dat veld correct en leest vervolgens een subtitle die het blok nooit heeft gedeclareerd en die zonder escaping wordt uitgevoerd:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
In de editor en aan de voorkant wordt hierdoor een lege alinea weergegeven en verschijnt er geen fout. Voer in plaats daarvan de analyse uit:
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
De opdracht eindigt met 1. Hieronder staan de diagnostische meldingen, van specifiek naar algemeen:
blockstudio.fieldis de templaterregel. Deze heeft deblock.jsonnaast de template gevonden, de velden ervan bepaald en vastgesteld datsubtitleer niet bij hoort.offsetAccess.notFoundis PHPStan zelf, dat tot dezelfde conclusie komt omdat de extensie$ade concrete vormarray{heading: string}geeft, afgeleid vanblock.json. Elk veldtype wordt omgezet naar een PHP-type:textis eenstring,toggleeenbool, en een repeater een array met rijvormen.blockstudio.output.unescapedkomt uit deextreme-theme-laag. Uitgevoerde attribuutwaarden moeten door een escapingfunctie gaan, zoalsesc_html(),esc_attr(),esc_url()ofwp_kses_post().echo.nonStringvolgt uit de onbekende sleutel: een niet-bestaande offset heeft geen tekenreekstype dat kan worden uitgevoerd.variable.undefinedverschijnt omdat PHPStan een templatebestand ziet en niet de renderfunctie die$adefinieert voordat het bestand wordt ingesloten. In het gedeelte over de oplossing leest u hoe u dit verhelpt.
De fout oplossen
Bepaal of subtitle een echt veld is. Hier is dat zo, dus declareer het met een default, omdat de themalaag dit voor elk veld vereist:
{
"$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": "" }
]
}
}
Escape de uitvoer en declareer $a met de vorm die de extensie afleidt:
<?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
Schrijf de annotatie in exact de juiste vorm. De canonieke opdracht voert PHPStan uit op niveau max, waar een minder specifieke @var array<string, mixed> $a wordt afgewezen met varTag.nativeType (“PHPDoc-tag @var met type array<string, mixed> is geen subtype van het native type array{heading: string, subtitle: string}”). Op 7.6 wordt elk veld bovendien verbreed tot mixed, zodat elke aanroep van esc_html() een melding argument.type oplevert. De melding varTag.nativeType geeft de afgeleide vorm weer en is dus ook de snelste manier om de annotatie te vinden die u kunt overnemen.
Blockstudio 7.7 behandelt $a als gedefinieerd in bloktemplates. Daardoor verdwijnen de diagnostische meldingen van variable.undefined en is de annotatie optioneel. Met 7.7 geeft de eerder kapotte template vier fouten in plaats van zes en slaagt de gerepareerde template zonder de regel @var.
Een preset kiezen
Na installatie van het pakket is alleen de basisextensie ingeschakeld. De canonieke opdracht voert base uit, tenzij een project een andere preset selecteert. Alleen de afhankelijkheid toevoegen schakelt de strengere lagen dus niet in.
| Preset | Voegt toe |
|---|---|
base |
Toegang tot templatevelden in PHP, Twig en Blade, controles op bloktags, schemavalidatie voor block.json, field.json, page.json, extensie-JSON, db.php, paden van rpc.php en cron.php, en hooknamen van Settings::get() en blockstudio/*. |
theme |
Basis plus themamappen en style.css-headers, assets die in block.json worden gedeclareerd in plaats van handmatig in de wachtrij te worden gezet, bereikafbakening van %selector% in style.scss, standaardwaarden voor velden en grenzen voor repeaters. |
extreme-theme |
Thema plus strenge vlaggen van PHPStan, geweigerde shell- en eval()-aanroepen, onbewerkte $wpdb-schrijfbewerkingen, uitvoerescaping, Tailwind, JavaScript en controles van API voor Interactivity. |
wordpress-render |
Extreem thema plus een live renderprobe die u als opdracht aanlevert. |
Als er geen projectconfiguratie is opgenomen, voert de canonieke opdracht base
en theme ook uit op niveau PHPStan max; extreme-theme stelt max zelf in.
Elke vooraf ingestelde diagnose heeft een stabiele blockstudio.*-identificatie, vermeld in de
PHPStan-naslag.
De thema- en extreme lagen controleren ook bestanden van PHP. Met een veld zonder default en een script.js die naar de console schrijft, meldt dezelfde opdracht:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Deze controles worden gerapporteerd via de resultaatcache van PHPStan. Na het bewerken van alleen een block.json of script kan een warme cache [OK] No errors rapporteren voor de oude toestand. Geef na -- --debug door, waarmee de cache wordt omzeild, voordat u een geslaagde uitvoering vertrouwt bij wijzigingen die niet met PHP te maken hebben:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Opdrachtopties en afsluitcodes
Opdrachtregelwaarden vervangen de overeenkomstige waarden van blockstudio.json voor één uitvoering. Vervangen betekent vervangen: als u een --exclude doorgeeft, vervalt de geconfigureerde excludePaths. Geef daarom vendor/** opnieuw op wanneer u er een toevoegt:
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 na -- wordt doorgegeven aan PHPStan. De wrapper verhoogt de geheugenlimiet van PHPStan naar 1G, tenzij u zelf een --memory-limit doorgeeft. De configuratie wordt samengesteld in de tijdelijke systeemmap, zodat er geen gegenereerd bestand in het project terechtkomt. De opdracht eindigt met 0 als de analyse slaagt, met 1 als PHPStan diagnostische meldingen rapporteert en met 2 bij fouten in het gebruik, de configuratie of de uitvoering.
Voer dit uit via de canonieke opdracht in plaats van phpstan/extension-installer toe te voegen. De presets bevatten de extensie al. Als de installer aanwezig is, wordt dezelfde extension.neon twee keer geladen en stopt PHPStan met de melding “This file is included multiple times” voordat er iets wordt geanalyseerd.
Toepassen op een bestaand project
Bij een eerste analyse van een project komen doorgaans bevindingen aan het licht. Verlaag de preset niet, maar sla ze op in een basislijn, zodat nieuwe code aan de volledige set regels moet voldoen:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Neem de basislijn op in een projectconfiguratie en wijs phpstan.configuration ernaar:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Bij de volgende uitvoering rapporteert [OK] No errors de geregistreerde bevindingen en blijft alles nieuws fouten opleveren. Stel bij de preset base of theme ook level: max in onder parameters in phpstan.neon: de canonieke opdracht stelt dat niveau alleen zelf in als er geen projectconfiguratie is opgenomen.
Commits blokkeren op basis van de analyse
Met "githooks": { "commit": true } in blockstudio.json synchroniseert u de beheerde hook één keer na het installeren van de afhankelijkheden:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
De opdracht schrijft de hook in de eigen map van Git, verwijst core.hooksPath ernaar en voert ook de pre-commit-hook uit die eerder was ingesteld. De hook voert vanuit de projecthoofdmap alleen vendor/bin/blockstudio-phpstan -- --no-progress uit: geen formatter, geen herschrijvingen. Bij het committen stopt de eerder kapotte template tijdens de analyse:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Stel commit in op false en voer sync opnieuw uit, of voer vendor/bin/blockstudio-githooks remove uit om het vorige hookpad te herstellen. Alleen bestanden die Blockstudio heeft geschreven, worden verwijderd.
Het projectcontract genereren
Een analyse vertelt een agent achteraf wat er fout ging. Een AGENTS.md vertelt dit vooraf: waar blokken en pagina’s staan, hoe velden templates bereiken, welke functies zijn ingeschakeld en wat de geselecteerde preset afwijst.
blockstudio-agents genereert dat document op basis van het project zelf:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Voor het thema in deze handleiding begint het gegenereerde bestand als volgt:
# 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.
Elke regel is afkomstig uit een van drie bronnen. De projectbestanden geven het projecttype, de aantallen, mappen, naamruimten en templatelanguages op.
blockstudio.json geeft de ingeschakelde functies op, zodat de commit-hook onder “Ingeschakelde functies” verschijnt en vendor/bin/blockstudio-githooks sync onder “Opdrachten”, uitsluitend omdat githooks.commit is ingesteld. Het geselecteerde preset bepaalt het gedeelte over correctheid, dat laag voor laag uit de presetbestanden wordt gelezen:
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.
Actueel houden
Het contract raakt verouderd wanneer de configuratie verandert. Nadat u Tailwind in blockstudio.json hebt ingeschakeld, merkt de controlemodus dit op:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
De opdracht eindigt met 1, waardoor deze naast de analyse als CI-stap kan worden gebruikt. Door opnieuw te genereren wordt een functie-item “Tailwind CSS” en de opdracht wp bs tailwind compile toegevoegd.
Opmerkingen die bij opnieuw genereren behouden blijven
Het bestand eindigt met een opmerkingengebied. Alles tussen de markeringen blijft bij elke nieuwe generatie byte voor byte behouden. Projectkennis die niet uit bestanden kan worden afgeleid, hoort daar dus thuis:
## 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 -->
De generator vervangt nooit een bestand dat hij niet zelf heeft geschreven. Als u de opdracht uitvoert met een handgeschreven AGENTS.md, weigert de generator dit en eindigt met 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Als u handgeschreven tekst wilt behouden, kopieert u deze naar een veilige plek, voert u de opdracht uit met --force en plakt u de tekst in het opmerkingengebied. De andere opties zijn --root, --config, --output en --stdout, waarmee het contract wordt afgedrukt in plaats van opgeslagen.
Wat verandert in Blockstudio 7.7
De pakketversie 7.7 behoudt de hier beschreven opdrachten, presets en afsluitcodes. Bij het maken van deze handleiding voor die versie kwamen twee verschillen aan het licht: voor $a is geen annotatie meer nodig, zoals beschreven in het gedeelte over de oplossing, en het gegenereerde contract beschrijft de validatie van bloktags ruimer. Die omvat HTML-elementen die in paginabronnen aan blokken zijn gekoppeld en de globale attributen die een tag mag doorgeven.
Volgende stappen
- PHPStan verwijzing: elke regel, vooraf ingestelde parameter, veldtype, vorm, live rendercontrole en diagnostische identificatie.
- AI-integratie: de documentatie-index voor codeerassistenten die je projectcontract aanvult.
- Vibecoding met Blockstudio: samenwerken met codeerassistenten aan een Blockstudio-project.
- Kookboek met veldpatronen: veldstructuren waarvan de analysesjabloonsleutels worden herkend, waaronder groepen en herhalers.