Patikrinti šablonai su PHPStan ir sugeneruotu AGENTS.md
Blockstudio bloką sudaro du failai, kurių turinys turi sutapti. block.json aprašo laukus, o šablonas nuskaito juos kaip $a['id']. Vykdymo metu niekas netrukdo šablonui nuskaityti rakto, kuris buvo pervadintas, niekada nebuvo deklaruotas arba parašytas su klaida. Jis tiesiog atvaizduoja tuščią eilutę, o klaida išaiškėja tik kam nors pastebėjus tuščią antraštę veikiančiame puslapyje. Tas pats pasakytina apie išvesties kodavimą: neekranuotas echo veikia puikiai, kol lauko reikšmėje neatsiranda žymėjimo kalbos.
Paketas blockstudio/phpstan abi problemas perkelia į analizės etapą. Jis nuskaito jūsų block.json failus, pagal juos nustato $a tipus ir praneša apie neatitinkančius šablonų nuskaitymus. Pasirenkami išankstiniai nustatymai papildo patikras temos struktūros taisyklėmis, kodavimu, taip pat JavaScript ir Tailwind patikromis. Kartu su paketu pateikiamos dvi papildomos priemonės: valdoma priešįrašymo užkarda, vykdanti analizę, ir generatorius, sukuriantis AGENTS.md su jūsų projekto aprašu kodą rašantiems agentams.
Šiame vadove sukursime nedidelę temą, tyčia sugadinsime vieną jos šabloną, peržiūrėsime analizės išvestį, pataisysime šabloną ir nustatysime pakeitimų užkardą bei agento sutartį.
Temos sąranka
Pradėkite nuo temos katalogo, kuriame yra style.css antraštė, composer.json ir vienas blokas:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Įdiekite paketą kaip kūrimo priklausomybę:
composer require --dev blockstudio/phpstan
Įdiegiamos PHPStan ir szepeviktor/phpstan-wordpress esančios WordPress deklaracijos, o vendor/bin įdiegiami trys vykdomieji failai: blockstudio-phpstan, blockstudio-githooks ir blockstudio-agents.
Tada nurodykite analizei, ką vykdyti. Viso projekto numatytosios nuostatos saugomos blockstudio.json objekto phpstan lauke, todėl interaktyvi analizė, CI ir pakeitimų užkarda naudoja tuos pačius nustatymus:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme yra griežčiausias iš trijų statinių išankstinių nustatymų. Toliau esančioje lentelėje paaiškinta, ką prideda kiekvienas iš jų. excludePaths neįtraukia Composer failų į Blockstudio nuskaitymą ir PHP analizę.
Sąmoningai sugadinkite šabloną
Herojaus bloke deklaruotas vienas laukas:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Šablonas teisingai nuskaito šį lauką, o tada nuskaito subtitle, kurio blokas nedeklaravo, ir išveda jį be kodavimo:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
Redaktoriuje ir svetainės priekinėje dalyje atvaizduojama tuščia pastraipa, bet klaida nepateikiama. Vietoj to paleiskite analizę:
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
Komanda baigiama kodu 1. Diagnostikos pranešimai, išdėstyti nuo konkrečiausio iki bendriausio:
blockstudio.fieldyra šablono taisyklė. Ji rado šalia šablono esantįblock.json, nustatė jo laukus, osubtitlenėra vienas iš jų.offsetAccess.notFoundtaip pat daro tokią išvadą apie patį PHPStan, nes plėtinys suteikia$akonkrečią formąarray{heading: string}, išvestą išblock.json. Kiekvienas lauko tipas atitinka PHP tipą:textyrastring,toggleyrabool, kartotinis yra eilučių formų masyvas.blockstudio.output.unescapedkyla išextreme-themesluoksnio. Išvesti atributų reikšmes galima tik jas perdavus kodavimo funkcijai, pavyzdžiui,esc_html(),esc_attr(),esc_url()arbawp_kses_post().echo.nonStringkyla iš nežinomo rakto: neegzistuojančiam poslinkiui nepriskirtas eilutės tipas, todėl jo negalima išvesti.variable.undefinedatsiranda todėl, kad PHPStan mato šablono failą, o ne atvaizdavimo funkciją, kuri prieš įtraukdama šabloną apibrėžia$a. Apie tai rašoma pataisymo skyriuje.
Pataisymas
Nuspręskite, ar subtitle yra tikras laukas. Šiuo atveju taip, todėl jį deklaruokite ir nurodykite default, nes temos sluoksnyje jis privalomas kiekvienam laukui:
{
"$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": "" }
]
}
}
Užkoduokite išvestį ir deklaruokite $a su plėtinio nustatyta forma:
<?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
Įrašykite tiksliai atitinkančią formą. Kanoninė komanda vykdo PHPStan lygiu max, o laisvesnis @var array<string, mixed> $a atmetamas su varTag.nativeType (“PHPDoc žyma @var su tipu array<string, mixed> nėra vietinio array{heading: string, subtitle: string} tipo potipis). 7.6 versijoje visi laukai taip pat praplečiami iki mixed, todėl kiekvienas esc_html() iškvietimas pateikia argument.type. Pranešime varTag.nativeType rodoma nustatyta forma, todėl taip greičiausia rasti, kokią anotaciją nukopijuoti.
Blockstudio 7.7 versijoje $a laikomas apibrėžtu blokų šablonuose, todėl variable.undefined diagnostikos pranešimai išnyksta, o anotacija tampa neprivaloma. Tikrinant su 7.7 versija, aukščiau pateiktas sugadintas šablonas pateikia keturias, o ne šešias klaidas, o pataisytas šablonas praeina ir be eilutės @var.
Pasirinkite išankstinį nustatymą
Įdiegus paketą įjungiamas tik bazinis plėtinys. Kanoninė komanda vykdo base, nebent projektui parenkamas kitas išankstinis nustatymas, todėl vien priklausomybės pridėjimas griežtesnių sluoksnių neįjungia.
| Išankstinis nustatymas | Pridedamos patikros |
|---|---|
base |
Šablono laukų prieigos PHP, Twig ir Blade, blokų žymų patikros, block.json, field.json, page.json schemų tikrinimas, plėtinio JSON, db.php, rpc.php ir cron.php keliai bei Settings::get() blockstudio/* veiksmo pavadinimai. |
theme |
Bazinis nustatymas ir temų šakniniai katalogai bei style.css antraštės, block.json deklaruoti ištekliai, o ne rankiniu būdu įtraukti, %selector% aprėptis style.scss, numatytosios laukų reikšmės ir kartotinių ribos. |
extreme-theme |
Temos nustatymas ir griežtos PHPStan vėliavėlės, atmesti apvalkalo ir eval() iškvietimai, tiesioginiai $wpdb įrašai, išvesties kodavimas, Tailwind, JavaScript ir Interactivity API patikros. |
wordpress-render |
Griežčiausias temos nustatymas ir jūsų pateikiamas tiesioginio atvaizdavimo bandymas, vykdomas kaip komanda. |
Jei projekto konfigūracija nepateikta, kanoninė komanda taip pat vykdo base ir theme su PHPStan lygio reikšme max; pats extreme-theme nustato max. Kiekviena išankstinio nustatymo diagnostika turi stabilų blockstudio.* identifikatorių, pateiktą PHPStan žinyne.
Temos ir griežčiausias sluoksniai tikrina ir PHP failus. Jei lauke trūksta default, o script.js įrašo duomenis į konsolę, ta pati komanda pateikia:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Šios patikros pateikiamos per PHPStan rezultatų talpyklą. Pakeitus tik block.json arba scenarijų, šilta talpykla gali pateikti senos būsenos [OK] No errors. Po -- perduokite --debug, kad talpykla būtų apeita, ir prieš pasitikėdami sėkmingu rezultatu, jei pakeitimai nėra PHP, išvalykite talpyklą:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Komandos parinktys ir išėjimo kodai
Komandinės eilutės reikšmės vienam paleidimui pakeičia atitinkamas blockstudio.json reikšmes. Pakeičia reiškia pakeičia: perdavus bent vieną --exclude, konfigūruotas excludePaths nebeperduodamas, todėl pridėdami parinktį pakartokite 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":[]}
Viskas po -- perduodama PHPStan. Apvalkalas padidina PHPStan atminties limitą iki 1G, nebent nurodote savo --memory-limit, o konfigūracija sudaroma sistemos laikinojoje direktorijoje, todėl projekte nesukuriamas joks sugeneruotas failas. Jei analizė sėkminga, išeinama su kodu 0; jei PHPStan pateikia diagnostikos pranešimų, išeinama su kodu 1; naudojimo, konfigūracijos ar vykdymo klaidų atveju – su kodu 2.
Vykdykite ją kanonine komanda, o ne pridėkite phpstan/extension-installer. Išankstiniai nustatymai plėtinį jau įtraukia, todėl, esant įdiegimo programai, tas pats extension.neon įkeliamas dukart: PHPStan sustoja su pranešimu “This file is included multiple times” dar neprasidėjus analizei.
Pritaikykite esamam projektui
Pirmą kartą analizuojant projektą paprastai randama pažeidimų. Užuot sušvelninę išankstinį nustatymą, įrašykite juos į pradinę atskaitą, kad naujam kodui būtų taikomos visos taisyklės:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Įtraukite pradinę atskaitą į projekto konfigūraciją ir nurodykite phpstan.configuration jos vietą:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Kito vykdymo metu pateikiami [OK] No errors pranešimai, atsižvelgiant į užfiksuotus pažeidimus; nauji pažeidimai vis tiek sukelia klaidą. Jei naudojate base arba theme išankstinį nustatymą, taip pat nustatykite level: max skiltyje parameters faile phpstan.neon: kanoninė komanda šį lygį nustato pati tik tada, kai projekto konfigūracija nepateikta.
Užkirskite kelią pažeidimų įrašymui
Jei "githooks": { "commit": true } įrašytas faile blockstudio.json, įdiegę priklausomybes vieną kartą sinchronizuokite valdomą užkardą:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Komanda įrašo užkardą į paties Git katalogą, nurodo core.hooksPath naudoti ją ir paleidžia anksčiau sukonfigūruotą priešįrašymo užkardą. Užkarda iš projekto šakninio katalogo vykdo tik vendor/bin/blockstudio-phpstan -- --no-progress: jokio formatavimo ar perrašymo. Anksčiau pateikto sugadinto šablono įrašymas sustoja analizės etape:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Nustatykite commit reikšmę false ir vėl paleiskite sync arba vykdykite vendor/bin/blockstudio-githooks remove, kad atkurtumėte ankstesnį užkardos kelią. Ištrinami tik failai, kuriuos sukūrė Blockstudio.
Sugeneruokite projekto sutartį
Analizė po fakto parodo agentui, ką jis padarė ne taip. AGENTS.md iš anksto nurodo, kur saugomi blokai ir puslapiai, kaip laukai pasiekia šablonus, kurios funkcijos įjungtos ir ką parinktas išankstinis nustatymas atmes. blockstudio-agents sugeneruoja šį dokumentą iš paties projekto:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Šiame vadove aprašytai temai sugeneruotas failas prasideda taip:
# 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.
Kiekviena eilutė gaunama iš vieno iš trijų šaltinių. Projekto failai nurodo projekto tipą, objektų skaičius, katalogus, vardų sritis ir šablonų kalbas. blockstudio.json pateikia įjungtas funkcijas, todėl pakeitimų užkarda rodoma skiltyje “Įjungtos funkcijos”, o vendor/bin/blockstudio-githooks sync skiltyje “Komandos” atsiranda tik todėl, kad nustatyta githooks.commit. Pasirinktas išankstinis nustatymas pateikia teisingumo patikrų skyrių, perskaitomą iš išankstinio nustatymo failų sluoksnis po sluoksnio:
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.
Atnaujinkite pagal pakeitimus
Pasikeitus konfigūracijai sutartis pasensta. Įjungus Tailwind faile blockstudio.json, tikrinimo režimas tai aptinka:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Komanda baigiama kodu 1, todėl ją galima naudoti kaip CI žingsnį greta analizės. Sugeneravus iš naujo pridedamas funkcijos “Tailwind CSS” įrašas ir komanda wp bs tailwind compile.
Pastabos išsaugomos generuojant iš naujo
Failo pabaigoje yra pastabų sritis. Viskas tarp jos žymeklių išsaugoma baitas į baitą kiekvieną kartą generuojant iš naujo, todėl ten įrašykite projekto žinias, kurių negalima nustatyti iš failų:
## 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 -->
Generatorius niekada nepakeičia failo, kurio pats nesukūrė. Jei nurodysite ranka parašytą AGENTS.md, jis atsisakys veikti ir baigs darbą kodu 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Jei norite išsaugoti ranka parašytą tekstą, nukopijuokite jį kitur, paleiskite su --force ir įklijuokite į pastabų sritį. Kitos parinktys: --root, --config, --output ir --stdout; ši parinktis atspausdina sutartį, o ne įrašo ją į failą.
Kas keičiasi Blockstudio 7.7 versijoje
7.7 versijos pakete paliekamos čia aprašytos komandos, išankstiniai nustatymai ir išėjimo kodai. Rengiant šį vadovą pagal šią versiją paaiškėjo du skirtumai: $a nebereikia anotacijos, kaip aprašyta pataisymo skyriuje, o sugeneruotoje sutartyje blokų žymų tikrinimas aprašomas plačiau – įtraukiami puslapių šaltinių HTML elementai, susieti su blokais, ir visuotiniai atributai, kuriuos žyma gali perduoti toliau.
Tolesni veiksmai
- PHPStan nuoroda: kiekviena taisyklė, išankstinis nustatymas, lauko tipo struktūra, tiesioginio atvaizdavimo patikra ir diagnostinis identifikatorius.
- Integracija su DI: dokumentacijos rodyklė programavimo agentams, papildanti jūsų projekto sutartį.
- Vibekodavimas su Blockstudio: darbas su kodavimo agentais Blockstudio projekte.
- Laukų šablonų receptų knyga: laukų struktūros, kurių šablonų raktus supranta analizė, įskaitant grupes ir kartotuvus.