Ellenőrzött sablonok PHPStan-val és generált AGENTS.md-val
Egy Blockstudio blokk két fájlból áll, amelyeknek összhangban kell lenniük. A block.json deklarálja a mezőket, a sablon pedig $a['id'] formájában olvassa be őket. Futás közben semmi sem akadályozza meg, hogy a sablon olyan kulcsot olvasson be, amelynek neve megváltozott, sosem volt deklarálva vagy el van írva. Egyszerűen üres karakterláncot jelenít meg, a hibára pedig csak akkor derül fény, amikor valaki üres címsort vesz észre egy éles oldalon. Ugyanez igaz a kimenet escape-elésére: egy escape-elés nélküli echo tökéletesen működik, amíg egy mezőérték jelölést nem tartalmaz.
A blockstudio/phpstan csomag mindkét problémát az elemzés idejére helyezi át. Beolvassa az block.json fájlokat, típust rendel a bennük lévő $a adatokhoz, és jelzi azokat a sablonbeli hivatkozásokat, amelyek nem egyeznek. Az opcionálisan bekapcsolható előbeállítások témaszerkezeti szabályokat, escape-elést, valamint JavaScript és Tailwind ellenőrzéseket adnak hozzá. A csomag két kiegészítőt is tartalmaz: egy felügyelt pre-commit horgot, amely futtatja az elemzést, valamint egy generátort, amely a projektet leíró AGENTS.md fájlt készít a kódoló ügynökök számára.
Ez az útmutató létrehoz egy kis témát, szándékosan elrontja az egyik sablonját, megvizsgálja az elemzés kimenetét, kijavítja a hibát, majd beállítja a commitellenőrzést és az ügynök szerződését.
A téma beállítása
Kezdje egy olyan témamappával, amelyben van egy style.css fejléc, egy composer.json és egy blokk:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Telepítse a csomagot fejlesztési függőségként:
composer require --dev blockstudio/phpstan
Ez telepíti a PHPStan csomagot és a szepeviktor/phpstan-wordpress által biztosított WordPress csonkokat, és három futtatható fájlt helyez el az vendor/bin könyvtárban: blockstudio-phpstan, blockstudio-githooks és blockstudio-agents.
Ezután adja meg az elemzésnek, mit futtasson. A projekt egészére vonatkozó alapértékek az blockstudio.json phpstan objektumában találhatók, így az interaktív futtatások, a CI és a commit hook is ugyanazokat a beállításokat olvassa be:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
A extreme-theme a három statikus előbeállítás közül a legszigorúbb. A táblázat később részletezi, mit adnak hozzá az egyes előbeállítások. A excludePaths kihagyja a Composer saját fájljait a Blockstudio vizsgálatából és a PHP elemzésből.
Sablon szándékos elrontása
A kiemelt blokk egyetlen mezőt deklarál:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
A sablon helyesen olvassa be ezt a mezőt, majd beolvas egy subtitle értéket, amelyet a blokk sosem deklarált, és escape-elés nélkül ír ki:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
A szerkesztőben és a frontend felületen ez üres bekezdést jelenít meg, hiba nélkül. Futtassa inkább az elemzést:
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
A parancs 1 kóddal lép ki. A diagnosztikai üzeneteket a legkonkrétabbtól kezdve áttekintve:
- A
blockstudio.fielda sablonszabály. Megtalálta a sablon mellett lévőblock.jsonfájlt, feloldotta a mezőket, és megállapította, hogy asubtitlenincs közöttük. - A
offsetAccess.notFoundmaga az PHPStan jut ugyanerre a következtetésre, mert a bővítmény ablock.jsonalapján származtatott konkrétarray{heading: string}alakot rendeli a$aelemhez. Minden mezőtípus egy PHP típusnak felel meg: atextstring, atogglebool, az ismétlő pedig soralakok tömbje. - A
blockstudio.output.unescapedaextreme-themerétegből származik. A kiírt attribútumértékeket olyan escape-elő függvényen kell átengedni, mint aesc_html(), aesc_attr(), aesc_url()vagy awp_kses_post(). - A
echo.nonStringaz ismeretlen kulcsból következik: egy nem létező eltolásnak nincs karakterlánc-típusa, amelyet ki lehetne írni. - A
variable.undefinedazért jelenik meg, mert a PHPStan egy sablonfájlt lát, nem pedig azt a renderelő függvényt, amely a$aértéket definiálja a fájl beillesztése előtt. A javításról szóló rész foglalkozik vele.
Javítás
Döntse el, hogy a subtitle valódi mező-e. Itt az, ezért deklarálja egy default értékkel, mivel a téma rétege minden mezőnél megköveteli:
{
"$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-elje a kimenetet, és deklarálja a $a értéket a bővítmény által kikövetkeztetett alakban:
<?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
Az annotációba pontosan a megfelelő alakot írja. A kanonikus parancs a max szintű PHPStan-t futtatja, ahol a kevésbé szigorú @var array<string, mixed> $a elutasításra kerül varTag.nativeType hibával (“A @var típusú PHPDoc-címke típusa array<string, mixed> nem altípusa a natív array{heading: string, subtitle: string} típusnak”). A 7.6-os verzióban emellett minden mezőt mixed típusra bővít, ezért minden esc_html() hívás argument.type hibát jelez. A varTag.nativeType üzenet kiírja a kikövetkeztetett alakot, így ezzel találhatja meg a leggyorsabban a bemásolandó annotációt.
A Blockstudio 7.7 a $a elemet a blokksablonokon belül definiáltnak tekinti, ezért eltűnnek a variable.undefined diagnosztikai üzenetek, és az annotáció is elhagyható. A fenti hibás sablon a 7.7-es verzióval hat helyett négy hibát jelez, a kijavított sablon pedig a @var sor nélkül is átmegy az ellenőrzésen.
Előbeállítás kiválasztása
A csomag telepítése csak az alapbővítményt engedélyezi. Ha a projekt nem választ másik előbeállítást, a kanonikus parancs base beállítással fut, így a függőség hozzáadása önmagában nem kapcsolja be a szigorúbb rétegeket.
| Előbeállítás | Hozzáadott ellenőrzések |
|---|---|
base |
Sablonmező-hozzáférés a PHP, Twig és Blade elemekben, blokkcímke-ellenőrzések, sémaellenőrzés a block.json, field.json, page.json és JSON elemekhez, db.php, rpc.php és cron.php, továbbá Settings::get() útvonalak és blockstudio/* hooknevek. |
theme |
Az alaphoz hozzáadja a témagyökereket és az style.css fejléceket, a kézzel sorba állítás helyett block.json fájlban deklarált eszközöket, az style.scss-beli %selector% hatókörét, a mezők alapértékeit és az ismétlők korlátait. |
extreme-theme |
A témaréteghez szigorú PHPStan jelzőket ad, tiltja a shell- és eval() hívásokat, a nyers $wpdb írásokat, valamint ellenőrzi a kimenet escape-elését, a Tailwind, a JavaScript és az Interactivity API elemeket. |
wordpress-render |
A legszélsőségesebb témaelőbeállítás egy Ön által megadott paranccsal végzett élő renderelési próbát ad hozzá. |
Ha nincs projektkonfiguráció, a kanonikus parancs base és theme beállítással is fut, PHPStan max szinten; magát az max értéket a extreme-theme állítja be.
Minden előbeállítás diagnosztikai üzenetének stabil blockstudio.* azonosítója van, ezek az PHPStan referenciában találhatók.
A téma- és szélsőséges rétegek a PHP fájlokon túlra is kiterjednek. Ha egy mezőből hiányzik a default, és van egy konzolra naplózó script.js, ugyanaz a parancs ezt jelzi:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Ezeket az ellenőrzéseket a PHPStan eredménygyorsítótára jelenti. Ha csak egy block.json fájlt vagy egy szkriptet szerkesztett, a meleg gyorsítótár a korábbi állapotra [OK] No errors eredményt jelezhet. A gyorsítótár megkerüléséhez adja meg a --debug kapcsolót a -- után. Ezt tegye meg, mielőtt megbízik egy zöld futásban nem-PHP módosítások esetén:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Parancsbeállítások és kilépési kódok
A parancssori értékek egy futtatás erejéig felülírják a megfelelő blockstudio.json értékeket. A felülírás teljes cserét jelent: bármely --exclude megadása elveti a konfigurált excludePaths értéket, ezért újabb hozzáadásakor ismételje meg a vendor/** kapcsolót:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
A -- utáni összes argumentum a PHPStan elemhez kerül. A wrapper a PHPStan memóriakorlátját 1G értékre emeli, kivéve, ha saját --memory-limit értéket ad meg. A konfigurációt a rendszer ideiglenes könyvtárában állítja össze, ezért nem kerül generált fájl a projektbe. Sikeres elemzés esetén 0 kóddal lép ki, ha a PHPStan diagnosztikai üzeneteket jelez, akkor 1 kóddal, használati, konfigurációs vagy végrehajtási hiba esetén pedig 2 kóddal.
Futtassa a kanonikus parancsot, és ne adja hozzá a phpstan/extension-installer elemet. Az előbeállítások már tartalmazzák a bővítményt, és ha a telepítő is jelen van, ugyanaz a extension.neon kétszer töltődik be: a PHPStan leáll a „This file is included multiple times” üzenettel, mielőtt bármit elemezne.
Bevezetés meglévő projektben
Az első elemzéskor a projektben általában találhatók hibák. Az előbeállítás enyhítése helyett rögzítse ezeket egy alapállományban, így az új kódnak továbbra is minden szabálynak meg kell felelnie:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Vegye fel az alapállományt a projekt konfigurációjába, és mutasson rá a phpstan.configuration értékkel:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
A következő futás a rögzített hibákkal együtt [OK] No errors eredményt ad, az új hibák viszont továbbra is sikertelen futást okoznak. A base vagy theme előbeállításnál állítsa be a level: max értéket a phpstan.neon parameters alatt is: a kanonikus parancs ezt a szintet csak akkor állítja be, ha nincs projektkonfiguráció.
Commitok ellenőrzése az elemzéssel
Ha a blockstudio.json tartalmazza a "githooks": { "commit": true } elemet, a függőségek telepítése után egyszer szinkronizálja a felügyelt hookot:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
A parancs a hookot a Git saját könyvtárába írja, a core.hooksPath elemet erre állítja, és meghívja a korábban beállított pre-commit hookot is. A hook a vendor/bin/blockstudio-phpstan -- --no-progress parancsot futtatja a projekt gyökeréből, és semmi mást: nincs formázó és nincs átírás. A korábban bemutatott hibás sablon commitja itt, az elemzésnél megáll:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Állítsa a commit értéket false-ra, majd futtassa újra a sync parancsot, vagy futtassa a vendor/bin/blockstudio-githooks remove parancsot az előző hookútvonal visszaállításához.
Csak azokat a fájlokat törli, amelyeket a Blockstudio hozott létre.
A projektszerződés létrehozása
Az elemzés utólag jelzi az ügynöknek, ha hibázott. Az AGENTS.md előre tájékoztatja: hol találhatók a blokkok és oldalak, hogyan jutnak el a mezők a sablonokhoz, mely funkciók vannak engedélyezve, és mit utasít el a kiválasztott előbeállítás.
Az blockstudio-agents ezt a dokumentumot közvetlenül a projektből állítja elő:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Az útmutatóban szereplő téma esetén a generált fájl így kezdődik:
# 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.
Minden sor három forrás egyikéből származik. A projektfájlok adják meg a projekt típusát, a darabszámokat, a könyvtárakat, a névtereket és a sablonnyelveket.
Az blockstudio.json adja meg az engedélyezett funkciókat, ezért a commit hook az „Engedélyezett funkciók” alatt, a vendor/bin/blockstudio-githooks sync pedig a „Parancsok” alatt jelenik meg, kizárólag azért, mert be van állítva a githooks.commit. A kiválasztott előbeállítás adja meg a megfelelőségi részt, amelyet a rendszer az előbeállítás fájljaiból, rétegenként olvas be:
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.
Tartsa naprakészen
A konfiguráció módosításakor a szerződés elavul. Az blockstudio.json Tailwind használatával történő engedélyezése után az ellenőrzési mód ezt észreveszi:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
A parancs 1 kóddal lép ki, így az elemzés mellett CI-lépésként is használható.
Az újbóli generálás hozzáad egy „Tailwind CSS” funkcióbejegyzést és a wp bs tailwind compile parancsot.
Újrageneráláskor is megőrzött megjegyzések
A fájl egy megjegyzéseknek fenntartott résszel zárul. A jelölők közötti tartalom minden újrageneráláskor bájtról bájtra megmarad, ezért ide írja azokat a projektre vonatkozó ismereteket, amelyek nem következtethetők ki a fájlokból:
## 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 -->
A generátor soha nem cserél le olyan fájlt, amelyet nem ő írt. Ha kézzel írt AGENTS.md fájlt talál, megtagadja a műveletet és 2 kóddal lép ki:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
A kézzel írt szöveg megőrzéséhez másolja félre, futtassa a parancsot a --force kapcsolóval, majd illessze be a szöveget a megjegyzéseknek fenntartott részbe. A további beállítások: --root, --config, --output és --stdout; ez utóbbi a szerződés fájlba írása helyett kiírja azt.
Mi változik a Blockstudio 7.7-es verziójában
A 7.7-es csomag megtartja az itt leírt parancsokat, előbeállításokat és kilépési kódokat. Az útmutató elkészítése során két különbség derült ki: a javítási részben leírtak szerint a $a már nem igényel annotációt, a generált szerződés pedig tágabban írja le a blokkcímkék ellenőrzését. Ez kiterjed az oldalak forrásaiban blokkokhoz rendelt HTML elemekre és azokra a globális attribútumokra is, amelyeket egy címke továbbíthat.
Következő lépések
- PHPStan referencia: minden szabály, előre beállított paraméter, mezőtípus, alakzat, élő renderelési vizsgálat és diagnosztikai azonosító.
- AI-integráció: a kódoló ügynökök dokumentációs indexe, amely kiegészíti a projekt szerződését.
- Vibekódolás a következővel: Blockstudio: munka kódoló ügynökökkel egy Blockstudio projektben.
- Mezőminták szakácskönyve: olyan mezőstruktúrák, amelyek sablonkulcsait az elemzés felismeri, többek között csoportok és ismétlők.