Preverjene predloge z PHPStan in ustvarjenim AGENTS.md
Blok Blockstudio sestavljata dve datoteki, ki se morata ujemati. Datoteka block.json določa polja, predloga pa jih bere kot $a['id']. Med izvajanjem nič ne prepreči predlogi, da bi prebrala ključ, ki je bil preimenovan, nikoli ni bil določen ali je napačno črkovan. Preprosto izriše prazen niz, napaka pa se pokaže šele, ko kdo opazi prazen naslov na objavljeni strani. Enako velja za ubežanje izhoda: neubežani echo deluje brezhibno, dokler vrednost polja ne vsebuje označevanja.
Paket blockstudio/phpstan obe težavi prestavi v čas analize. Prebere vaše datoteke block.json, iz njih določi vrste za $a in opozori na branja v predlogah, ki se ne ujemajo. Izbirne prednastavitve dodajo pravila za strukturo teme, ubežanje ter preverjanja JavaScript in Tailwind. Paket vključuje tudi spremljevalni orodji: upravljan kavelj pred potrditvijo, ki zažene analizo, in generator, ki ustvari datoteko AGENTS.md z opisom vašega projekta za programske agente.
Ta vodnik sestavi majhno temo, namerno pokvari eno od njenih predlog, pregleda izpis analize, odpravi napako, nato pa nastavi preverjanje potrditve sprememb in pogodbo za agenta.
Nastavitev teme
Začnite z mapo teme, ki vsebuje glavo style.css, datoteko composer.json
in en blok:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Namestite paket kot odvisnost za razvoj:
composer require --dev blockstudio/phpstan
Vključi PHPStan in ogrodja WordPress iz szepeviktor/phpstan-wordpress ter namesti tri izvršne datoteke v vendor/bin: blockstudio-phpstan, blockstudio-githooks in blockstudio-agents.
Nato določite, kaj naj analiza zažene. Privzete nastavitve za celoten projekt so v objektu phpstan v blockstudio.json, zato interaktivni zagoni, CI in kavelj ob potrditvi sprememb uporabljajo iste nastavitve:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme je najstrožja od treh statičnih prednastavitev. V spodnji tabeli je pojasnjeno, kaj doda vsaka od njih. excludePaths izloči lastne datoteke Composer iz pregleda Blockstudio in analize PHP.
Namerno pokvarite predlogo
Blok hero določa eno samo polje:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Predloga polje pravilno prebere, nato pa prebere subtitle, ki ga blok ni določil, in ga izpiše brez ubežanja:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
V urejevalniku in na spletnem mestu se izriše prazen odstavek, napake pa ni. Namesto tega zaženite analizo:
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
Ukaz se konča z vrednostjo 1. Diagnostiko preglejte od najbolj specifične navzdol:
blockstudio.fieldje pravilo predloge. Ob predlogi je našloblock.json, razrešilo njegova polja in ugotovilo, dasubtitleni med njimi.offsetAccess.notFoundje PHPStan sam prišel do enakega sklepa, saj razširitev določa konkretno obliko$akotarray{heading: string}, izpeljano izblock.json. Vsaka vrsta polja se preslika v vrsto PHP:textjestring,togglepabool; ponavljalnik je polje oblik vrstic.blockstudio.output.unescapedizhaja iz plastiextreme-theme. Ponovljene vrednosti atributov je treba obdelati s funkcijo za ubežanje, kot soesc_html(),esc_attr(),esc_url()aliwp_kses_post().echo.nonStringizhaja iz neznanega ključa: neobstoječi odmik nima vrste niza, ki bi jo bilo mogoče ponoviti.variable.undefinedse pojavi, ker PHPStan vidi datoteko predloge, ne pa funkcije za izris, ki določa$a, preden jo vključi. Razdelek o odpravi težave to pojasnjuje.
Odprava napake
Odločite se, ali je subtitle pravo polje. Tukaj je, zato ga določite z default, saj plast teme to zahteva za vsako polje:
{
"$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": "" }
]
}
}
Ubežite izhod in določite $a z obliko, ki jo sklepa razširitev:
<?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
Opombo zapišite v natančni obliki. Kanonični ukaz zažene PHPStan na ravni max, kjer je ohlapnejši @var array<string, mixed> $a zavrnjen z varTag.nativeType (»PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}«). V različici 7.6 prav tako razširi vsako polje v mixed, zato vsak klic esc_html() javi argument.type. Sporočilo varTag.nativeType izpiše izpeljano obliko, zato je tudi najhitrejši način, da najdete opombo, ki jo lahko kopirate.
V različici 7.7 Blockstudio obravnava $a kot določeno znotraj predlog blokov, zato diagnostika variable.undefined izgine, opomba pa ni več obvezna. V primerjavi z različico 7.7 pokvarjena predloga zgoraj prikaže štiri napake namesto šestih, popravljena predloga pa prestane preverjanje brez vrstice @var.
Izbira prednastavitve
Namestitev paketa omogoči samo osnovno razširitev. Kanonični ukaz zažene base, razen če projekt izbere drugo prednastavitev, zato dodajanje odvisnosti samo po sebi ne vklopi strožjih plasti.
| Prednastavitev | Dodaja |
|---|---|
base |
Dostop do polj predlog v PHP, Twig in Blade, preverjanja oznak blokov, preverjanje sheme za block.json, field.json, page.json, razširitve JSON, db.php, rpc.php in cron.php, poti Settings::get() ter imena kavljev blockstudio/*. |
theme |
Osnovna prednastavitev ter koreni teme in glave style.css, sredstva, določena v block.json namesto ročnega dodajanja v čakalno vrsto, omejitve %selector% v style.scss, privzete vrednosti polj in meje ponavljalnikov. |
extreme-theme |
Prednastavitev teme ter stroge zastavice PHPStan, zavrnjeni klici lupine in eval(), neposredni zapisi $wpdb, ubežanje izhoda, Tailwind, JavaScript in preverjanja API Interactivity. |
wordpress-render |
Izjemno stroga prednastavitev teme in živa preizkusna izvedba izrisa, ki jo podate kot ukaz. |
Ko konfiguracija projekta ni vključena, se kanonični ukaz izvaja tudi pri ravni PHPStan max z base in theme; extreme-theme sam nastavi max. Vsaka prednastavljena diagnostika ima stabilni identifikator blockstudio.*, naveden v PHPStanreferenčnem priročniku.
Plasti teme in izjemno stroge nastavitve preverjajo tudi PHP datoteke. Če polju manjka njegov default, script.js pa beleži v konzolo, isti ukaz javi:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Ta preverjanja se poročajo prek predpomnilnika rezultatov PHPStan. Če uredite samo block.json ali skript, lahko ogret predpomnilnik za staro stanje javi [OK] No errors. Po -- podajte --debug, ki obide predpomnilnik, preden zaupate uspešnemu zagonu po spremembah, ki niso PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Možnosti ukaza in izhodne kode
Vrednosti ukazne vrstice za en zagon nadomestijo ustrezne vrednosti blockstudio.json. Nadomestijo jih v celoti: če podate katerikoli --exclude, se zavrže nastavljeni excludePaths, zato pri dodajanju ponovite 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":[]}
Vse, kar sledi --, se posreduje programu PHPStan. Ovoj zviša omejitev pomnilnika za PHPStan na 1G, razen če podate svoj --memory-limit, konfiguracijo pa sestavi v začasnem sistemskem imeniku, tako da v projektu ne nastane nobena ustvarjena datoteka. Konča se z vrednostjo 0, če analiza uspe, 1, če PHPStan javi diagnostiko, in 2 pri napakah uporabe, konfiguracije ali izvajanja.
Zaženite ga prek kanoničnega ukaza, namesto da dodate phpstan/extension-installer. Prednastavitve razširitev že vključujejo, ob nameščenem namestitvenem programu pa se ista extension.neon naloži dvakrat: PHPStan se ustavi s sporočilom »This file is included multiple times« še pred začetkom analize.
Uporaba v obstoječem projektu
Pri prvi analizi projekta se običajno najdejo težave. Namesto da znižate raven prednastavitve, jih zabeležite v osnovnem stanju, tako da bodo za novo kodo veljala vsa pravila:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Osnovno stanje vključite v konfiguracijo projekta in usmerite phpstan.configuration nanj:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Naslednji zagon javi [OK] No errors z zabeleženimi ugotovitvami, nove napake pa še vedno povzročijo neuspeh. Pri prednastavitvi base ali theme nastavite tudi level: max pod parameters v phpstan.neon: kanonični ukaz to raven nastavi sam samo, če konfiguracija projekta ni vključena.
Preverjanje potrditev sprememb z analizo
Ko je "githooks": { "commit": true } v blockstudio.json, po namestitvi odvisnosti enkrat sinhronizirajte upravljani kavelj:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Ukaz zapiše kavelj v imenik Git in nastavi, da ga uporablja core.hooksPath, nato pa doda še morebitni predhodno konfigurirani kavelj pred potrditvijo sprememb. Kavelj iz korena projekta zažene vendor/bin/blockstudio-phpstan -- --no-progress in ničesar drugega: brez oblikovalnika, brez prepisov. Če poskusite potrditi pokvarjeno predlogo iz prejšnjega primera, se postopek ustavi pri analizi:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Nastavite commit na false in znova zaženite sync ali pa za obnovitev prejšnje poti do kavlja zaženite vendor/bin/blockstudio-githooks remove.
Izbrišejo se samo datoteke, ki jih je zapisal Blockstudio.
Ustvarjanje projektne pogodbe
Analiza agentu naknadno pove, kaj je naredil narobe. AGENTS.md ga seznani vnaprej: kje so bloki in strani, kako polja dosežejo predloge, katere funkcije so omogočene in kaj bo izbrana prednastavitev zavrnila.
blockstudio-agents ustvari ta dokument iz samega projekta:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Za temo iz tega vodnika se ustvarjena datoteka začne takole:
# 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.
Vsaka vrstica izhaja iz enega od treh virov. Datoteke projekta podajo vrsto projekta, števila, imenike, imenske prostore in jezike predlog. blockstudio.json določa omogočene funkcije, zato je kavelj za potrditve sprememb naveden pod »Omogočene funkcije«, vendor/bin/blockstudio-githooks sync pa pod »Ukazi« samo zato, ker je nastavljen githooks.commit. Izbrana prednastavitev določa razdelek o pravilnosti, ki se bere iz datotek prednastavitve plast za plastjo:
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.
Posodabljanje
Pogodba zastara, ko se spremeni konfiguracija. Ko omogočite Tailwind v blockstudio.json, to zazna način preverjanja:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Konča se z vrednostjo 1, zato ga lahko uporabite kot korak CI poleg analize. Če dokument znova ustvarite, se dodata vnos funkcije »Tailwind CSS« in ukaz wp bs tailwind compile.
Opombe, ki se ohranijo pri ponovnem ustvarjanju
Datoteka se konča z območjem za opombe. Vsebina med njegovimi označevalniki se pri vsakem ponovnem ustvarjanju ohrani povsem enaka, zato vanj sodijo projektno znanje, ki ga ni mogoče izpeljati iz datotek:
## 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 -->
Generator nikoli ne prepiše datoteke, ki je ni ustvaril. Če ga zaženete za ročno napisano datoteko AGENTS.md, zavrne postopek in se konča z vrednostjo 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Če želite ohraniti ročno napisano besedilo, ga shranite drugam, zaženite z --force in ga prilepite v območje za opombe. Druge možnosti so --root, --config, --output in --stdout, ki izpiše pogodbo namesto, da bi jo zapisal.
Kaj se spremeni v različici Blockstudio 7.7
Paket 7.7 ohranja tukaj opisane ukaze, prednastavitve in izhodne kode. Med pripravo tega vodnika za to različico sta se pokazali dve razliki: $a ne potrebuje več opombe, kot je opisano v razdelku o popravku, ustvarjena pogodba pa širše opisuje preverjanje oznak blokov in zajema elemente HTML, preslikane v bloke v virih strani, ter globalne atribute, ki jih oznaka lahko posreduje naprej.
Naslednji koraki
- PHPStan referenca: vsako pravilo, parameter prednastavitve, obliko tipa polja, sondo za sprotno upodabljanje in diagnostični identifikator.
- Integracija z umetno inteligenco: kazalo dokumentacije za programerske agente, ki dopolnjuje pogodbo vašega projekta.
- Vibekodiranje z Blockstudio: sodelovanje s programerskimi agenti pri projektu Blockstudio.
- Kuharica vzorcev polj: strukture polj, katerih ključe predlog analiza razume, vključno s skupinami in ponavljalniki.