Ugrás a tartalomhoz

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:

Kód
acme/
├── blockstudio/
│   └── hero/
│       ├── block.json
│       └── index.php
├── blockstudio.json
├── composer.json
└── style.css
CSS
/*
Theme Name: Acme
*/

Telepítse a csomagot fejlesztési függőségként:

Shell
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:

JSON
{
  "$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:

JSON
{
  "$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:

PHP
<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:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 ------ -------------------------------------------------------------------
  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.field a sablonszabály. Megtalálta a sablon mellett lévő block.json fájlt, feloldotta a mezőket, és megállapította, hogy a subtitle nincs közöttük.
  • A offsetAccess.notFound maga az PHPStan jut ugyanerre a következtetésre, mert a bővítmény a block.json alapján származtatott konkrét array{heading: string} alakot rendeli a $a elemhez. Minden mezőtípus egy PHP típusnak felel meg: a text string, a toggle bool, az ismétlő pedig soralakok tömbje.
  • A blockstudio.output.unescaped a extreme-theme rétegből származik. A kiírt attribútumértékeket olyan escape-elő függvényen kell átengedni, mint a esc_html(), a esc_attr(), a esc_url() vagy a wp_kses_post().
  • A echo.nonString az ismeretlen kulcsból következik: egy nem létező eltolásnak nincs karakterlánc-típusa, amelyet ki lehetne írni.
  • A variable.undefined azé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:

JSON
{
  "$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
<?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>
Shell
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 [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:

Text
 ------ -----------------------------------------------------------
  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:

Shell
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:

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --root . \
  --exclude 'vendor/**' \
  --exclude 'fixtures/**' \
  --error-format json \
  -- --no-progress
Text
{"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:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Text
 [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:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "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:

Shell
vendor/bin/blockstudio-githooks sync
Text
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:

Text
 [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ő:

Shell
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/acme/AGENTS.md

Az útmutatóban szereplő téma esetén a generált fájl így kezdődik:

Markdown
# 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:

Markdown
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:

Shell
vendor/bin/blockstudio-agents --check
Text
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:

Markdown
## 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:

Text
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