Szablony z weryfikacją przy użyciu PHPStan i wygenerowanego AGENTS.md
Blok Blockstudio składa się z dwóch plików, które muszą być ze sobą zgodne. Plik block.json deklaruje pola, a szablon odczytuje je jako $a['id']. W czasie działania nic nie powstrzymuje szablonu przed odczytaniem klucza, którego nazwę zmieniono, który nigdy nie został zadeklarowany lub który zapisano z błędem. Po prostu renderuje pusty ciąg, a błąd wychodzi na jaw, gdy ktoś zauważy pusty nagłówek na działającej stronie. To samo dotyczy escapowania danych wyjściowych: nieescapowany echo działa bez zarzutu, dopóki wartość pola nie zawiera znaczników.
Pakiet blockstudio/phpstan przenosi oba problemy do etapu analizy. Odczytuje pliki block.json, określa na ich podstawie typy $a i zgłasza niezgodne odczyty w szablonach. Opcjonalne ustawienia wstępne dodają reguły struktury motywu, escapowanie oraz kontrole JavaScript i Tailwind. Pakiet zawiera też dwa narzędzia uzupełniające: zarządzany hook pre-commit uruchamiający analizę oraz generator tworzący plik AGENTS.md opisujący projekt dla agentów programistycznych.
W tym przewodniku utworzymy mały motyw, celowo zepsujemy jeden z jego szablonów, odczytamy wynik analizy, naprawimy go, a następnie skonfigurujemy bramkę commitów i kontrakt dla agenta.
Konfiguracja motywu
Zacznij od folderu motywu zawierającego nagłówek style.css, plik composer.json i jeden blok:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Zainstaluj pakiet jako zależność deweloperską:
composer require --dev blockstudio/phpstan
Pakiet pobiera PHPStan oraz definicje zastępcze WordPress z szepeviktor/phpstan-wordpress i instaluje trzy programy wykonywalne w vendor/bin: blockstudio-phpstan, blockstudio-githooks i blockstudio-agents.
Następnie wskaż analizie, co ma uruchamiać. Domyślne ustawienia dla całego projektu znajdują się w obiekcie phpstan w blockstudio.json, dzięki czemu uruchomienia interaktywne, CI i hook commitów korzystają z tych samych ustawień:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme to najbardziej rygorystyczne z trzech statycznych ustawień wstępnych. Tabela poniżej wyjaśnia, co dodaje każde z nich. excludePaths wyklucza własne pliki Composer ze skanowania Blockstudio i analizy PHP.
Celowe zepsucie szablonu
Blok hero deklaruje jedno pole:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Szablon poprawnie odczytuje to pole, a następnie odczytuje subtitle, którego blok nigdy nie zadeklarował, i wyświetla jego wartość bez escapowania:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
W edytorze i na stronie renderuje się pusty akapit i nie pojawia się żaden błąd. Zamiast tego uruchom analizę:
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
Polecenie kończy się kodem 1. Odczytaj diagnostykę, zaczynając od najbardziej szczegółowej:
blockstudio.fieldto reguła dotycząca szablonów. Wykryła plikblock.jsonobok szablonu, określiła jego pola i ustaliła, żesubtitlenie należy do żadnego z nich.offsetAccess.notFoundto sam PHPStan, który dochodzi do tego samego wniosku, ponieważ rozszerzenie nadaje$akonkretny kształtarray{heading: string}wyprowadzony zblock.json. Każdy typ pola odpowiada typowi PHP:textjest typustring,toggletypubool, a repeater jest tablicą kształtów wierszy.blockstudio.output.unescapedpochodzi z warstwyextreme-theme. Wartości atrybutów wyświetlane za pomocą echo muszą przejść przez funkcję escapującą, taką jakesc_html(),esc_attr(),esc_url()lubwp_kses_post().echo.nonStringwynika z nieznanego klucza: nieistniejący indeks nie ma typu ciągu znaków, który można wyświetlić.variable.undefinedpojawia się, ponieważ PHPStan widzi plik szablonu, a nie funkcję renderującą, która definiuje$aprzed jego dołączeniem. Sekcja naprawy opisuje rozwiązanie.
Naprawa
Zdecyduj, czy subtitle jest rzeczywistym polem. Tutaj jest, więc je zadeklaruj i ustaw default, ponieważ warstwa motywu wymaga go dla każdego pola:
{
"$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": "" }
]
}
}
Escapuj dane wyjściowe i zadeklaruj $a w kształcie wywnioskowanym przez rozszerzenie:
<?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
Zapisz adnotację z dokładnym kształtem. Kanoniczne polecenie uruchamia PHPStan na poziomie max, gdzie luźniejszy @var array<string, mixed> $a zostaje odrzucony z błędem varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). W wersji 7.6 każde pole jest też poszerzane do mixed, więc każde wywołanie esc_html() zgłasza argument.type. Komunikat varTag.nativeType wyświetla wywnioskowany kształt, dlatego najszybciej można z niego skopiować adnotację.
Blockstudio W wersji 7.7 $a jest traktowane jako zdefiniowane wewnątrz szablonów bloków, więc diagnostyka variable.undefined znika, a adnotacja staje się opcjonalna. W wersji 7.7 powyższy zepsuty szablon zgłasza cztery błędy zamiast sześciu, a poprawiony przechodzi bez wiersza @var.
Wybór ustawienia wstępnego
Zainstalowanie pakietu włącza tylko rozszerzenie podstawowe. Kanoniczne polecenie uruchamia base, chyba że projekt wybierze inne ustawienie wstępne, więc samo dodanie zależności nie włącza bardziej rygorystycznych warstw.
| Ustawienie wstępne | Dodaje |
|---|---|
base |
Dostęp do pól szablonu w PHP, Twig i Blade, kontrole znaczników bloków, walidację schematów dla block.json, field.json, page.json, rozszerzenia JSON, db.php, rpc.php i cron.php, ścieżek Settings::get() oraz nazw hooków blockstudio/*. |
theme |
Podstawowe ustawienia oraz katalogi główne motywu i nagłówki style.css, zasoby deklarowane w block.json zamiast ręcznie dodawanych do kolejki, zakresy %selector% w style.scss, wartości domyślne pól i limity repeaterów. |
extreme-theme |
Ustawienia motywu oraz rygorystyczne flagi PHPStan, odrzucane wywołania powłoki i eval(), bezpośrednie zapisy $wpdb, escapowanie danych wyjściowych, Tailwind, JavaScript i kontrole API Interactivity. |
wordpress-render |
Ekstremalne ustawienia motywu oraz dostarczana przez Ciebie komenda sprawdzająca renderowanie na żywo. |
Jeśli konfiguracja projektu nie jest uwzględniona, kanoniczne polecenie uruchamia również base i theme na poziomie PHPStan max; samo extreme-theme ustawia max. Każdy komunikat diagnostyczny ustawień wstępnych ma stabilny identyfikator blockstudio.*, wymieniony w PHPStan dokumentacji.
Warstwy theme i extreme sprawdzają także pliki PHP. Gdy polu brakuje default, a script.js zapisuje coś w konsoli, to samo polecenie zgłasza:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Te kontrole są raportowane przez pamięć podręczną wyników PHPStan. Po edycji wyłącznie block.json lub skryptu ciepły bufor może zgłosić [OK] No errors dla starego stanu. Przekaż --debug po --, aby ominąć bufor, zanim zaufasz pozytywnemu wynikowi dla zmian niezwiązanych z PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Opcje polecenia i kody wyjścia
Wartości przekazane w wierszu poleceń zastępują odpowiadające im wartości blockstudio.json na czas jednego uruchomienia. Zastępują je w całości: przekazanie dowolnego --exclude usuwa skonfigurowane excludePaths, więc dodając jedno, ponownie podaj vendor/**:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Wszystko po -- jest przekazywane do PHPStan. Wrapper zwiększa limit pamięci PHPStan do 1G, chyba że podasz własne --memory-limit. Konfigurację tworzy w systemowym katalogu tymczasowym, więc żaden wygenerowany plik nie trafia do projektu. Zwraca kod 0, gdy analiza przechodzi pomyślnie, 1, gdy PHPStan zgłasza problemy, oraz 2 w razie błędów użycia, konfiguracji lub wykonania.
Uruchom to kanonicznym poleceniem zamiast dodawać phpstan/extension-installer. Ustawienia wstępne zawierają już rozszerzenie, a gdy obecny jest instalator, to samo extension.neon jest ładowane dwukrotnie: PHPStan kończy działanie z komunikatem „This file is included multiple times” przed rozpoczęciem analizy.
Wdrożenie w istniejącym projekcie
Pierwsza analiza projektu zwykle ujawnia problemy. Zamiast obniżać poziom ustawień wstępnych, zapisz je w pliku bazowym, aby nowy kod nadal podlegał pełnym regułom:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Uwzględnij plik bazowy w konfiguracji projektu i wskaż go za pomocą phpstan.configuration:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Kolejne uruchomienie zgłosi [OK] No errors wraz z zapisanymi problemami, a nowe nadal spowodują niepowodzenie. W przypadku ustawienia wstępnego base lub theme ustaw również level: max w parameters w pliku phpstan.neon: kanoniczne polecenie ustawia ten poziom samodzielnie tylko wtedy, gdy konfiguracja projektu nie jest uwzględniona.
Blokowanie commitów na podstawie analizy
Gdy "githooks": { "commit": true } znajduje się w blockstudio.json, po zainstalowaniu zależności jednorazowo zsynchronizuj zarządzany hook:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Polecenie zapisuje hook w katalogu Git, ustawia na niego core.hooksPath i łączy go z wcześniej skonfigurowanym hookiem pre-commit. Hook uruchamia wyłącznie vendor/bin/blockstudio-phpstan -- --no-progress z katalogu głównego projektu: bez formatowania i przepisywania plików. Commit z wcześniej zepsutym szablonem zostanie zatrzymany na etapie analizy:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Ustaw commit na false i ponownie uruchom sync albo uruchom vendor/bin/blockstudio-githooks remove, aby przywrócić poprzednią ścieżkę hooka. Usuwane są tylko pliki zapisane przez Blockstudio.
Generowanie kontraktu projektu
Analiza informuje agenta po fakcie, co zrobił źle. Plik AGENTS.md informuje go z wyprzedzeniem: gdzie znajdują się bloki i strony, jak pola trafiają do szablonów, które funkcje są włączone i co odrzuci wybrane ustawienie wstępne. Polecenie blockstudio-agents generuje ten dokument na podstawie samego projektu:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
W przypadku motywu z tego przewodnika wygenerowany plik zaczyna się tak:
# 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żdy wiersz pochodzi z jednego z trzech źródeł. Pliki projektu dostarczają informacji o jego typie, liczbach, katalogach, przestrzeniach nazw i językach szablonów. blockstudio.json dostarcza informacje o włączonych funkcjach, dlatego hook commitów pojawia się w sekcji „Enabled features”, a vendor/bin/blockstudio-githooks sync w sekcji „Commands” tylko wtedy, gdy ustawiono githooks.commit. Wybrane ustawienie wstępne dostarcza informacje do sekcji poświęconej poprawności, odczytywane z plików ustawień warstwa po warstwie:
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.
Aktualność dokumentu
Kontrakt staje się nieaktualny po zmianie konfiguracji. Po włączeniu Tailwind w blockstudio.json tryb sprawdzania to wykrywa:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Polecenie zwraca kod 1, dzięki czemu można użyć go jako kroku CI obok analizy. Ponowne wygenerowanie dodaje wpis funkcji „Tailwind CSS” oraz polecenie wp bs tailwind compile.
Uwagi zachowywane przy ponownym generowaniu
Plik kończy się sekcją uwag. Wszystko między jej znacznikami jest zachowywane bajt w bajt przy każdym ponownym generowaniu, dlatego należy tam umieszczać wiedzę o projekcie, której nie da się wywnioskować z plików:
## 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 -->
Generator nigdy nie zastępuje pliku, którego sam nie utworzył. Jeśli napotka ręcznie napisany plik AGENTS.md, odmawia i zwraca kod 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Aby zachować ręcznie napisany tekst, skopiuj go w inne miejsce, uruchom z --force, a następnie wklej tekst do sekcji uwag. Pozostałe opcje to --root, --config, --output i --stdout, która wyświetla kontrakt zamiast zapisywać go do pliku.
Zmiany w Blockstudio 7.7
Pakiet 7.7 zachowuje opisane tutaj polecenia, ustawienia wstępne i kody wyjścia. Podczas przygotowywania tego przewodnika z użyciem tej wersji zauważyliśmy dwie różnice: $a nie wymaga już adnotacji, jak opisano w sekcji naprawy, a wygenerowany kontrakt szerzej opisuje walidację znaczników bloków, obejmując elementy HTML mapowane na bloki w źródłach stron oraz globalne atrybuty, które znacznik może przekazywać dalej.
Następne kroki
- PHPStan odwołanie: każda reguła, parametr ustawienia wstępnego, typ pola, struktura kształtu, sonda renderowania na żywo i identyfikator diagnostyczny.
- Integracja z AI: indeks dokumentacji dla agentów programistycznych, który uzupełnia kontrakt projektu.
- Programowanie z Blockstudio: współpraca z agentami programistycznymi przy projekcie Blockstudio.
- Zbiór wzorców pól: struktury pól, których klucze szablonów rozumie analiza, w tym grupy i pola powtarzalne.