Preskočiť na obsah

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:

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

Nainštalujte balík ako vývojovú závislosť:

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

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

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

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

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

Príkaz skončí s kódom 1. Diagnostické hlásenia čítajte od najkonkrétnejšieho:

  • blockstudio.field je pravidlo pre šablóny. Našlo block.json vedľa šablóny, určilo jeho polia a zistilo, že subtitle medzi ne nepatrí.
  • offsetAccess.notFound dospel k rovnakému záveru aj samotný PHPStan, pretože rozšírenie priradí $a konkrétny tvar array{heading: string} odvodený z block.json. Každý typ poľa zodpovedá typu PHP: text je string, toggle je bool a opakovač je pole tvarov riadkov.
  • blockstudio.output.unescaped pochádza z vrstvy extreme-theme. Vypísané hodnoty atribútov musia prejsť cez funkciu na escapovanie, napríklad esc_html(), esc_attr(), esc_url() alebo wp_kses_post().
  • echo.nonString vyplýva z neznámeho kľúča: pre neexistujúci offset neexistuje reťazcový typ, ktorý by sa dal vypísať.
  • variable.undefined sa 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:

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": "" }
    ]
  }
}

Escapujte výstup a deklarujte $a v tvare, ktorý odvodí rozšírenie:

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

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:

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

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:

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

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":[]}

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:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Text
 [OK] Baseline generated with 3 errors.

Zahrňte základný súbor do konfigurácie projektu a nastavte, aby ho phpstan.configuration používal:

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

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

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

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

Pre tému z tejto príručky sa vygenerovaný súbor začína takto:

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.

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:

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.

Udržiavanie aktuálneho stavu

Pri zmene konfigurácie zmluva zastará. Po povolení Tailwind v blockstudio.json si kontrolný režim všimne zmenu:

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

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

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:

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