Kontrolované šablóny s PHPStan a generovaným AGENTS.md
Blok Blockstudio tvoria dva súbory, ktoré musia byť navzájom v súlade. Súbor block.json deklaruje polia a šablóna ich číta ako $a['id']. Počas behu nič nebráni šablóne čítať kľúč, ktorý bol premenovaný, nikdy nebol deklarovaný alebo je nesprávne napísaný.
Jednoducho sa vykreslí prázdny reťazec a chyba sa odhalí až vtedy, keď si niekto všimne prázdny nadpis na zverejnenej stránke. To isté platí pre escapovanie výstupu: neescapovaný echo funguje bez problémov, kým hodnota poľa neobsahuje značky.
Balík blockstudio/phpstan presúva oba problémy do fázy analýzy. Načíta vaše súbory block.json, určí typy $a z ich obsahu a nahlási nesúlad medzi nimi a čítaniami v šablónach. Voliteľné predvoľby pridávajú pravidlá štruktúry témy, escapovanie a kontroly JavaScript a Tailwind. Súčasťou balíka sú aj dva pomocné nástroje: spravovaný hook pred commitom, ktorý spúšťa analýzu, a generátor, ktorý vytvorí súbor AGENTS.md opisujúci projekt pre kódovacích agentov.
Táto príručka vytvorí malú tému, zámerne poškodí jednu z jej šablón, prečíta výstup analýzy, opraví ju a potom nastaví kontrolu commitov a zmluvu pre agenta.
Nastavenie témy
Začnite priečinkom témy, ktorý obsahuje hlavičku style.css, súbor composer.json
a jeden blok:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Nainštalujte balík ako vývojovú závislosť:
composer require --dev blockstudio/phpstan
Pridá PHPStan a stuby WordPress z szepeviktor/phpstan-wordpress
a nainštaluje tri spustiteľné súbory do vendor/bin: blockstudio-phpstan,
blockstudio-githooks a blockstudio-agents.
Potom určte, čo má analýza spúšťať. Predvolené nastavenia pre celý projekt sú v objekte phpstan v blockstudio.json, takže interaktívne spustenia, CI aj hook pred commitom používajú rovnaké nastavenia:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme je najprísnejšia z troch statických predvolieb. Nižšie uvedená tabuľka vysvetľuje, čo každá z nich pridáva. excludePaths vylúči vlastné súbory Composer z kontroly Blockstudio aj z analýzy PHP.
Zámerné poškodenie šablóny
Blok hero deklaruje jedno pole:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Šablóna správne číta toto pole, potom však číta subtitle, ktoré blok nikdy nedeklaroval, a vypíše ho bez escapovania:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
V editore aj na frontende sa vykreslí prázdny odsek bez chyby. Namiesto toho spustite analýzu:
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
Príkaz skončí s kódom 1. Diagnostické hlásenia čítajte od najkonkrétnejšieho:
blockstudio.fieldje pravidlo pre šablóny. Našloblock.jsonvedľa šablóny, určilo jeho polia a zistilo, žesubtitlemedzi ne nepatrí.offsetAccess.notFounddospel k rovnakému záveru aj samotný PHPStan, pretože rozšírenie priradí$akonkrétny tvararray{heading: string}odvodený zblock.json. Každý typ poľa zodpovedá typu PHP:textjestring,togglejeboola opakovač je pole tvarov riadkov.blockstudio.output.unescapedpochádza z vrstvyextreme-theme. Vypísané hodnoty atribútov musia prejsť cez funkciu na escapovanie, napríkladesc_html(),esc_attr(),esc_url()alebowp_kses_post().echo.nonStringvyplýva z neznámeho kľúča: pre neexistujúci offset neexistuje reťazcový typ, ktorý by sa dal vypísať.variable.undefinedsa zobrazí preto, že PHPStan vidí súbor šablóny, nie vykresľovaciu funkciu, ktorá pred jeho zahrnutím definuje$a. Vysvetlenie opravy nájdete v príslušnej časti.
Oprava
Rozhodnite, či je subtitle skutočné pole. V tomto prípade je, preto ho deklarujte aj s default, ktorý vrstva témy vyžaduje pri každom poli:
{
"$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": "" }
]
}
}
Escapujte výstup a deklarujte $a v tvare, ktorý odvodí rozšírenie:
<?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
Anotáciu zapíšte v presnom tvare. Kanonický príkaz spúšťa PHPStan na úrovni max, kde voľnejší zápis @var array<string, mixed> $a skončí chybou varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). Vo verzii 7.6 sa navyše každé pole rozšíri na mixed, takže každé volanie esc_html() nahlási argument.type. Hlásenie varTag.nativeType vypíše odvodený tvar, a preto je najrýchlejším spôsobom, ako zistiť, ktorú anotáciu skopírovať.
Blockstudio 7.7 považuje $a za definované v šablónach blokov, takže diagnostické hlásenia variable.undefined zmiznú a anotácia bude voliteľná. Pri verzii 7.7 poškodená šablóna vyššie nahlási štyri chyby namiesto šiestich a opravená šablóna prejde bez riadka @var.
Výber predvoľby
Inštalácia balíka povolí iba základné rozšírenie. Kanonický príkaz spúšťa base, ak projekt nevyberie inú predvoľbu, takže pridaním závislosti sa prísnejšie vrstvy samy nezapnú.
| Predvoľba | Pridáva |
|---|---|
base |
Prístup k poliam šablón v PHP, Twig a Blade, kontroly značiek blokov, validáciu schém pre block.json, field.json, page.json, rozšírenie JSON, cesty db.php, rpc.php a cron.php, ako aj názvy hookov Settings::get() a blockstudio/*. |
theme |
Základ plus korene témy a hlavičky style.css, prostriedky deklarované v block.json namiesto ručného pridávania do frontu, ohraničenie %selector% v style.scss, predvolené hodnoty polí a limity opakovačov. |
extreme-theme |
Téma plus prísne príznaky PHPStan, zakázané volania shellu a eval(), priame zápisy $wpdb, escapovanie výstupu, kontroly Tailwind, JavaScript a API Interactivity. |
wordpress-render |
Extrémna téma plus živá kontrola vykreslenia, ktorú zadáte ako príkaz. |
Ak konfigurácia projektu nie je zahrnutá, kanonický príkaz spustí aj base a theme na úrovni PHPStan max; extreme-theme nastaví samotné max.
Každé diagnostické hlásenie predvolieb má stabilný identifikátor blockstudio.* uvedený v referencii PHPStan.
Vrstvy témy a extrémnej predvoľby kontrolujú aj súbory PHP. Ak poľu chýba default a script.js zapisuje do konzoly, rovnaký príkaz nahlási:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Tieto kontroly sa nahlasujú cez vyrovnávaciu pamäť výsledkov PHPStan. Po úprave iba súboru block.json alebo skriptu môže teplá vyrovnávacia pamäť nahlásiť [OK] No errors pre starý stav. Po -- zadajte --debug, čím sa vyrovnávacia pamäť obíde, a až potom dôverujte úspešnému výsledku pri zmenách, ktoré sa netýkajú PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Možnosti príkazu a návratové kódy
Hodnoty z príkazového riadka nahradia zodpovedajúce hodnoty blockstudio.json pre jedno spustenie. Nahradenie znamená úplnú náhradu: pri zadaní ľubovoľnej hodnoty --exclude sa odstráni nakonfigurovaná hodnota excludePaths, preto pri pridávaní jednej zopakujte vendor/**:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Všetko za -- sa odovzdá nástroju PHPStan. Obalový skript zvýši limit pamäte PHPStan na 1G, ak nezadáte vlastné --memory-limit, a konfiguráciu skladá v dočasnom systémovom adresári, takže v projekte nevznikne žiadny vygenerovaný súbor. Pri úspešnej analýze skončí s kódom 0, pri diagnostických hláseniach z PHPStan s kódom 1 a pri chybách použitia, konfigurácie alebo vykonávania s kódom 2.
Spúšťajte ho cez kanonický príkaz namiesto pridania phpstan/extension-installer. Predvoľby už toto rozšírenie zahŕňajú a pri prítomnom inštalátore sa rovnaký extension.neon načíta dvakrát: PHPStan skončí s hlásením „This file is included multiple times“ ešte pred začiatkom analýzy.
Použitie v existujúcom projekte
Pri prvej analýze projektu sa zvyčajne nájdu problémy. Namiesto zmiernenia predvoľby ich zaznamenajte do základného súboru, aby nový kód podliehal všetkým pravidlám:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Zahrňte základný súbor do konfigurácie projektu a nastavte, aby ho phpstan.configuration používal:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Pri ďalšom spustení sa nahlási [OK] No errors s už zaznamenanými nálezmi a všetko nové bude naďalej viesť k zlyhaniu. Pri predvoľbe base alebo theme nastavte aj level: max pod parameters v phpstan.neon: kanonický príkaz túto úroveň nastaví sám iba vtedy, keď konfigurácia projektu nie je zahrnutá.
Kontrola commitov pomocou analýzy
Keď je "githooks": { "commit": true } v blockstudio.json, po inštalácii závislostí jednorazovo zosynchronizujte spravovaný hook:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Príkaz zapíše hook do vlastného adresára Git, nasmeruje naň core.hooksPath a pridá zaň všetko, čo bolo nastavené ako hook pred commitom. Hook spustí z koreňového adresára projektu iba vendor/bin/blockstudio-phpstan -- --no-progress, bez formátovača a bez prepísania súborov. Commit poškodenej šablóny z predchádzajúceho príkladu sa zastaví pri analýze:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Nastavte commit na false a znova spustite sync alebo spustite vendor/bin/blockstudio-githooks remove, aby ste obnovili predchádzajúcu cestu k hooku.
Odstránia sa iba súbory vytvorené príkazom Blockstudio.
Generovanie projektovej zmluvy
Analýza agentovi spätne oznámi, čo urobil nesprávne. Súbor AGENTS.md mu to oznámi vopred: kde sa nachádzajú bloky a stránky, ako sa polia dostávajú do šablón, ktoré funkcie sú povolené a čo vybraná predvoľba zamietne.
blockstudio-agents vygeneruje tento dokument priamo z projektu:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Pre tému z tejto príručky sa vygenerovaný súbor začína takto:
# 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.
Každý riadok pochádza z jedného z troch zdrojov. Súbory projektu určujú jeho typ, počty, adresáre, menné priestory a jazyky šablón.
blockstudio.json určuje povolené funkcie, takže hook pred commitom sa zobrazí v časti „Povolené funkcie“ a vendor/bin/blockstudio-githooks sync v časti „Príkazy“ iba preto, že je nastavené githooks.commit. Vybraná predvoľba určuje časť o správnosti, ktorá sa načítava z vrstiev súborov predvoľby:
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.
Udržiavanie aktuálneho stavu
Pri zmene konfigurácie zmluva zastará. Po povolení Tailwind v blockstudio.json si kontrolný režim všimne zmenu:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Príkaz skončí s kódom 1, takže ho možno použiť ako krok CI vedľa analýzy.
Opätovné generovanie pridá položku funkcie „Tailwind CSS“ a príkaz wp bs tailwind compile.
Poznámky zachované pri opätovnom generovaní
Súbor sa končí oblasťou poznámok. Všetko medzi jej značkami sa pri každom opätovnom generovaní zachová bajt po bajte, takže patria sem poznatky o projekte, ktoré nemožno odvodiť zo súborov:
## 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 -->
Generátor nikdy nenahradí súbor, ktorý sám nevytvoril. Ak ho spustíte nad ručne napísaným súborom AGENTS.md, odmietne to a skončí s kódom 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Ak chcete zachovať ručne napísaný text, najprv si ho skopírujte, spustite príkaz s --force a vložte ho do oblasti poznámok. Ďalšie možnosti sú --root, --config, --output a --stdout, ktorá vypíše zmluvu namiesto jej zápisu.
Čo sa mení vo verzii Blockstudio 7.7
Balík 7.7 zachováva príkazy, predvoľby a návratové kódy opísané v tejto príručke.
Pri jeho použití na prípravu príručky sa ukázali dva rozdiely: $a už nepotrebuje anotáciu, ako je uvedené v časti o oprave, a vygenerovaná zmluva opisuje validáciu značiek blokov širšie; zahŕňa prvky HTML mapované na bloky v zdrojoch stránok aj globálne atribúty, ktoré značka môže odovzdať ďalej.
Ďalšie kroky
- PHPStan referencia: každé pravidlo, prednastavený parameter, typ poľa, živá kontrola vykreslenia a identifikátor diagnostiky.
- Integrácia AI: register dokumentácie pre programovacích agentov, ktorý dopĺňa zmluvu vášho projektu.
- Vibecoding s Blockstudio: spolupráca s programovacími agentmi na projekte Blockstudio.
- Kuchárska kniha vzorov polí: štruktúry polí, ktorých kľúčom šablóny analýza rozumie vrátane skupín a opakovačov.