Přejít k obsahu

Kontrolované šablony s PHPStan a generovaným AGENTS.md

Blok Blockstudio tvoří dva soubory, které si musí odpovídat. Soubor block.json deklaruje pole a šablona je čte jako $a['id']. Za běhu nic nezabrání šabloně přečíst klíč, který byl přejmenován, nikdy nebyl deklarován nebo je chybně napsaný. Jednoduše se vykreslí prázdný řetězec a chyba se projeví, až si někdo všimne prázdného nadpisu na živé stránce. Totéž platí pro escapování výstupu: neescapovaný echo funguje bezchybně, dokud hodnota pole neobsahuje značky.

Balíček blockstudio/phpstan přesouvá oba problémy do fáze analýzy. Čte vaše soubory block.json, odvozuje z nich typy $a a hlásí přístupy šablon, které s nimi nejsou v souladu. Volitelné předvolby přidávají pravidla struktury motivu, escapování a kontroly JavaScript a Tailwind. Součástí balíčku jsou také dva doplňky: spravovaný hook před commitem, který spustí analýzu, a generátor, jenž vytvoří AGENTS.md popisující váš projekt pro programovací agenty.

Tento návod vytvoří malé téma, záměrně rozbije jednu z jeho šablon, projde výstup analýzy, chybu opraví a nakonec nastaví kontrolu commitů i smlouvu pro agenta.

Nastavení tématu

Začněte složkou tématu, která obsahuje hlavičku style.css, soubor composer.json a jeden blok:

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

Nainstalujte balíček jako závislost pro vývoj:

Shell
composer require --dev blockstudio/phpstan

Instaluje PHPStan a definice typů WordPress z szepeviktor/phpstan-wordpress a do vendor/bin přidá tři spustitelné soubory: blockstudio-phpstan, blockstudio-githooks a blockstudio-agents.

Pak určete, co má analýza spouštět. Výchozí nastavení pro celý projekt se ukládá do objektu phpstan v blockstudio.json, takže interaktivní spuštění, CI i hook před commitem používají stejná nastavení:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["vendor/**"]
  },
  "githooks": {
    "commit": true
  }
}

extreme-theme je nejpřísnější ze tří statických předvoleb. Níže uvedená tabulka popisuje, co každá z nich přidává. excludePaths vyřazuje vlastní soubory Composer z kontroly Blockstudio i z analýzy PHP.

Záměrné rozbití šablony

Blok úvodního banneru deklaruje jediné pole:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" }
    ]
  }
}

Šablona pole správně načte, pak ale čte subtitle, které blok nikdy nedeklaroval, a vypíše ho bez escapování:

PHP
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
</section>

V editoru i na frontendu se vykreslí prázdný odstavec a neobjeví se žádná chyba. Místo toho spusťte 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

Příkaz skončí s kódem 1. Začněme nejkonkrétnější diagnostikou:

  • blockstudio.field je pravidlo pro šablony. Našlo soubor block.json vedle šablony, zjistilo jeho pole a subtitle mezi nimi není.
  • offsetAccess.notFound dochází ke stejnému závěru prostřednictvím PHPStan, protože rozšíření přiřadí $a konkrétní tvar array{heading: string} odvozený z block.json. Každý typ pole se mapuje na typ PHP: text je string, toggle je bool a opakující se pole je polem tvarů řádků.
  • blockstudio.output.unescaped pochází z vrstvy extreme-theme. Vypsané hodnoty atributů musí projít funkcí pro escapování, například esc_html(), esc_attr(), esc_url() nebo wp_kses_post().
  • echo.nonString vyplývá z neznámého klíče: neexistující offset nemá typ řetězce, který by bylo možné vypsat.
  • variable.undefined se zobrazí, protože PHPStan vidí soubor šablony, nikoli vykreslovací funkci, která před jeho vložením definuje $a. Řešením se zabývá část o opravě.

Oprava

Rozhodněte, zda je subtitle skutečným polem. Tady je, proto ho deklarujte a přidejte default, protože vrstva motivu ho vyžaduje u každého pole:

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 ve tvaru odvozeném rozšířením:

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

Zapište anotaci přesně v tomto tvaru. Kanonický příkaz spouští PHPStan na úrovni max, kde volnější @var array<string, mixed> $a odmítne s chybou varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). Ve verzi 7.6 navíc rozšíří typ každého pole na mixed, takže každé volání esc_html() hlásí argument.type. Zpráva varTag.nativeType vypíše odvozený tvar, takže podle ní také nejrychleji zjistíte, jakou anotaci zkopírovat.

Verze Blockstudio 7.7 považuje $a za definované v šablonách bloků, takže diagnostika variable.undefined zmizí a anotace bude volitelná. Při kontrole oproti verzi 7.7 hlásí výše uvedená rozbitá šablona čtyři chyby místo šesti a opravená šablona projde bez řádku @var.

Výběr předvolby

Instalace balíčku povolí pouze základní rozšíření. Kanonický příkaz spouští base, pokud projekt nezvolí jinou předvolbu, takže samotné přidání závislosti přísnější vrstvy nezapne.

Předvolba Přidává
base Přístupy k polím šablon v PHP, Twig a Blade, kontroly tagů bloků, ověřování schémat pro block.json, field.json a page.json, rozšíření JSON, db.php, cesty rpc.php a cron.php a názvy hooků Settings::get(), blockstudio/*.
theme Základ plus kořeny tématu a hlavičky style.css, prostředky deklarované v block.json místo ručního přidávání do fronty, vymezení %selector% v style.scss, výchozí hodnoty polí a limity opakujících se polí.
extreme-theme Téma plus přísné příznaky PHPStan, odmítání volání shellu a eval(), přímé zápisy $wpdb, escapování výstupu, kontroly Tailwind, JavaScript a Interactivity API.
wordpress-render Extrémní téma plus živá kontrola vykreslení pomocí vámi zadaného příkazu.

Pokud projektová konfigurace není součástí běhu, kanonický příkaz spouští také base a theme na úrovni PHPStan max; samotné extreme-theme nastavuje max. Každá diagnostika předvoleb má stabilní identifikátor blockstudio.* uvedený v referenci PHPStan.

Vrstvy tématu a extrému kontrolují i soubory PHP. Pokud poli chybí jeho default a script.js zapisuje do konzole, stejný příkaz ohlásí:

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

Tyto kontroly se ukládají do výsledkové mezipaměti PHPStan. Po úpravě pouze block.json nebo skriptu může zahřátá mezipaměť vrátit [OK] No errors pro předchozí stav. Před spoléháním na úspěšný běh po změnách, které se netýkají PHP, proto po -- předejte --debug, které mezipaměť obejde:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --debug

Možnosti příkazu a návratové kódy

Hodnoty z příkazového řádku pro jedno spuštění nahrazují odpovídající hodnoty blockstudio.json. Nahrazení znamená úplné nahrazení: zadáním libovolného --exclude se odstraní nakonfigurovaný excludePaths, takže při přidávání jednoho vendor/** zopakujte:

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še za -- se předá PHPStan. Obalový skript zvýší limit paměti PHPStan na 1G, pokud nepředáte vlastní --memory-limit. Konfiguraci sestaví v dočasném systémovém adresáři, takže v projektu nevznikne žádný generovaný soubor. Při úspěšné analýze skončí s kódem 0, při nálezech hlášených nástrojem PHPStan s kódem 1 a při chybě použití, konfigurace nebo provádění s kódem 2.

Spouštějte ho kanonickým příkazem místo přidávání phpstan/extension-installer. Předvolby rozšíření už obsahují, takže s nainstalovaným balíčkem se načte stejné extension.neon dvakrát: PHPStan skončí hlášením “This file is included multiple times” ještě před zahájením analýzy.

Nasazení ve stávajícím projektu

Při první analýze se v projektu obvykle najdou problémy. Místo snížení úrovně předvolby je zaznamenejte do výchozího seznamu, aby se na nový kód dál vztahovala plná pravidla:

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

Zahrňte výchozí seznam do konfigurace projektu a nasměrujte na něj phpstan.configuration:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["vendor/**"],
    "configuration": "phpstan.neon"
  }
}

Další běh ohlásí [OK] No errors spolu se zaznamenanými nálezy a všechny nové chyby budou dál znamenat neúspěch. U předvoleb base nebo theme také nastavte level: max pod parameters v phpstan.neon: kanonický příkaz nastaví tuto úroveň sám pouze v případě, že není součástí běhu projektová konfigurace.

Kontrola commitů pomocí analýzy

Když máte "githooks": { "commit": true } v blockstudio.json, po instalaci závislostí jednou synchronizujte spravovaný hook:

Shell
vendor/bin/blockstudio-githooks sync
Text
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit

Příkaz zapíše hook do vlastního adresáře Git, nastaví na něj core.hooksPath a naváže na něj dříve nakonfigurovaný hook před commitem. Hook spustí z kořenového adresáře projektu pouze vendor/bin/blockstudio-phpstan -- --no-progress, nic dalšího: žádný formátovač ani přepisování souborů. Při commitu dříve rozbité šablony se analýza zastaví:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Nastavte commit na false a znovu spusťte sync nebo spusťte vendor/bin/blockstudio-githooks remove, abyste obnovili předchozí cestu k hooku. Smažou se pouze soubory vytvořené pomocí Blockstudio.

Vygenerování projektové smlouvy

Analýza agentovi zpětně sdělí, co udělal špatně. AGENTS.md mu to řekne předem: kde jsou bloky a stránky, jak se pole předávají do šablon, které funkce jsou zapnuté a co vybraná předvolba odmítne. blockstudio-agents vytvoří tento dokument přímo z projektu:

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

U tématu z tohoto návodu začíná vygenerovaný soubor 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ý řádek vychází z jednoho ze tří zdrojů. Soubory projektu určují jeho typ, počty, adresáře, jmenné prostory a jazyky šablon. blockstudio.json určuje zapnuté funkce, takže se hook před commitem objeví v části „Zapnuté funkce“ a vendor/bin/blockstudio-githooks sync v části „Příkazy“ pouze tehdy, když je nastaveno githooks.commit. Vybraná předvolba určuje část o správnosti, kterou tvoří vrstvy předvolby čtené postupně:

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žujte ji aktuální

Při změně konfigurace smlouva zastará. Po zapnutí Tailwind v blockstudio.json kontrolní režim tuto změnu zaznamená:

Shell
vendor/bin/blockstudio-agents --check
Text
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.

Příkaz skončí s kódem 1, takže ho lze použít jako krok CI vedle analýzy. Opětovné vygenerování přidá záznam funkce „Tailwind CSS“ a příkaz wp bs tailwind compile.

Poznámky zachované při opětovném generování

Soubor končí oblastí pro poznámky. Vše mezi jejími značkami se při každém generování zachová beze změny bajt po bajtu, takže sem patří znalosti o projektu, které nelze odvodit ze souborů:

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í soubor, který sám nevytvořil. Pokud narazí na ručně napsaný AGENTS.md, odmítne pokračovat a skončí s kódem 2:

Text
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.

Chcete-li zachovat ručně napsaný text, nejprve ho zkopírujte stranou, spusťte příkaz s --force a vložte text do oblasti pro poznámky. Další možnosti jsou --root, --config, --output a --stdout, které smlouvu vypíše místo zápisu do souboru.

Co se mění ve verzi Blockstudio 7.7

Balíček ve verzi 7.7 zachovává zde popsané příkazy, předvolby a návratové kódy. Při přípravě tohoto návodu se ukázaly dva rozdíly: $a už nepotřebuje anotaci, jak je popsáno v části o opravě, a vygenerovaná smlouva popisuje ověřování tagů bloků obecněji. Zahrnuje prvky HTML mapované na bloky ve zdrojích stránek i globální atributy, které tag může předávat dál.

Další kroky

  • PHPStan reference: každé pravidlo, parametr předvolby, typ pole, tvar, živá kontrolní sonda vykreslení a diagnostický identifikátor.
  • Integrace AI: rejstřík dokumentace pro programovací agenty, který doplňuje smlouvu vašeho projektu.
  • Vibecoding s Blockstudio: spolupráce s programovacími agenty na projektu Blockstudio.
  • Kuchařka vzorů polí: struktury polí, jejichž klíčům šablon analýza rozumí, včetně skupin a opakovačů.