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:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Nainstalujte balíček jako závislost pro vývoj:
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í:
{
"$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:
{
"$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í:
<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:
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
Příkaz skončí s kódem 1. Začněme nejkonkrétnější diagnostikou:
blockstudio.fieldje pravidlo pro šablony. Našlo souborblock.jsonvedle šablony, zjistilo jeho pole asubtitlemezi nimi není.offsetAccess.notFounddochází ke stejnému závěru prostřednictvím PHPStan, protože rozšíření přiřadí$akonkrétní tvararray{heading: string}odvozený zblock.json. Každý typ pole se mapuje na typ PHP:textjestring,togglejeboola opakující se pole je polem tvarů řádků.blockstudio.output.unescapedpochází z vrstvyextreme-theme. Vypsané hodnoty atributů musí projít funkcí pro escapování, napříkladesc_html(),esc_attr(),esc_url()nebowp_kses_post().echo.nonStringvyplývá z neznámého klíče: neexistující offset nemá typ řetězce, který by bylo možné vypsat.variable.undefinedse 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:
{
"$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
/** @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
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í:
------ -----------------------------------------------------------
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:
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:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"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:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Zahrňte výchozí seznam do konfigurace projektu a nasměrujte na něj phpstan.configuration:
includes:
- phpstan-baseline.neon
{
"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:
vendor/bin/blockstudio-githooks sync
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í:
[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:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
U tématu z tohoto návodu začíná vygenerovaný soubor takto:
# 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ě:
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á:
vendor/bin/blockstudio-agents --check
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ů:
## 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:
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čů.