PHPStanと生成されたAGENTS.mdでテンプレートを検査
Blockstudioブロックは、互いに一致している必要がある2つのファイルで構成されます。block.jsonでフィールドを宣言し、テンプレートではそれらを$a['id']として読み取ります。実行時には、名前が変更されたキー、未宣言のキー、スペルミスのあるキーをテンプレートが読み取っても止める仕組みがありません。単に空文字列が出力され、公開中のページに空の見出しがあることに誰かが気づいて初めて問題が発覚します。出力のエスケープも同様です。未エスケープのechoは、フィールド値にマークアップが含まれるまでは正常に動作します。
blockstudio/phpstanパッケージを使うと、どちらの問題も解析時に検出できます。block.jsonファイルを読み込み、そこから$aの型を定義し、一致しないテンプレートの読み取りを報告します。オプトインのプリセットでは、テーマ構造のルール、エスケープ、JavaScriptおよびTailwindのチェックも追加できます。同じパッケージには、解析を実行する管理対象のコミット前フックと、コーディングエージェント向けにプロジェクトを説明するAGENTS.mdを生成するツールも含まれています。
このガイドでは、小さなテーマを作成し、テンプレートの1つを意図的に壊して解析結果を確認し、修正します。その後、コミット制御とエージェント向けの仕様を設定します。
テーマをセットアップする
まず、style.cssヘッダー、composer.json、ブロックが1つあるテーマフォルダーを用意します。
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
パッケージを開発用依存関係としてインストールします。
composer require --dev blockstudio/phpstan
szepeviktor/phpstan-wordpressからPHPStanとWordPressスタブを取得し、vendor/binに3つの実行ファイルをインストールします。blockstudio-phpstan、blockstudio-githooks、blockstudio-agentsです。
次に、解析で実行する内容を指定します。プロジェクト全体のデフォルト設定はblockstudio.jsonのphpstanオブジェクトに記述するため、対話的な実行、CI、コミットフックで同じ設定が使われます。
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-themeは3つの静的解析プリセットの中で最も厳しいものです。それぞれのプリセットで追加される内容は後の表で説明します。excludePathsを使うと、Composer自体のファイルがBlockstudioスキャンとPHP解析の対象から除外されます。
テンプレートを意図的に壊す
ヒーローブロックでは、フィールドを1つだけ宣言しています。
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
テンプレートはそのフィールドを正しく読み取った後、ブロックで宣言されていないsubtitleを読み取り、エスケープせずに出力します。
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
エディターでもフロントエンドでも、空の段落が表示されるだけでエラーは出ません。代わりに解析を実行します。
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
コマンドは1で終了します。診断を、より具体的なものから順に見ていきましょう。
blockstudio.fieldはテンプレートのルールです。テンプレートの隣にあるblock.jsonを見つけてフィールドを特定しましたが、subtitleはその中にありません。offsetAccess.notFoundは、PHPStan自体が同じ結論に達したことを示しています。拡張機能によって、$aにblock.jsonから導出された具体的な型array{heading: string}が与えられるためです。各フィールド型はPHP型に対応します。textはstring、toggleはbool、リピーターは行の型を要素とする配列です。blockstudio.output.unescapedはextreme-themeレイヤーによる診断です。エコーする属性値は、esc_html()、esc_attr()、esc_url()、wp_kses_post()などのエスケープ関数を通す必要があります。echo.nonStringは未知のキーに起因します。存在しないオフセットには、出力できる文字列型がありません。variable.undefinedが表示されるのは、PHPStanが$aを定義するレンダー関数よりも、テンプレートファイル自体を認識しているためです。修正方法は後のセクションで説明します。
修正する
subtitleが実際に必要なフィールドか判断します。ここでは必要なので、テーマレイヤーではすべてのフィールドに必須のdefaultとともに宣言します。
{
"$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": "" }
]
}
}
出力をエスケープし、拡張機能が推測した型で$aを宣言します。
<?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
アノテーションには、正確な型を記述してください。標準コマンドはPHPStanのレベルmaxで実行されるため、より緩い@var array<string, mixed> $aはvarTag.nativeTypeで拒否されます(”PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”)。7.6ではすべてのフィールドの型もmixedに拡張されるため、各esc_html()呼び出しでargument.typeが報告されます。varTag.nativeTypeメッセージには推測された型が表示されるため、コピーするアノテーションを最も手早く確認できます。
Blockstudio 7.7では、ブロックテンプレート内で$aが定義済みとして扱われるため、variable.undefinedの診断がなくなり、アノテーションも任意になります。7.7で解析すると、上の壊れたテンプレートではエラーが6件ではなく4件報告され、修正後のテンプレートは@var行なしで検査に通ります。
プリセットを選ぶ
パッケージをインストールすると、ベース拡張機能のみが有効になります。プロジェクトで別のプリセットを選ばない限り、標準コマンドはbaseを実行するため、依存関係を追加しても、より厳しいレイヤーが自動的に有効になることはありません。
| プリセット | 追加される内容 |
|---|---|
base |
PHP、Twig、Bladeでのテンプレートフィールドアクセス、ブロックタグのチェック、block.json、field.json、page.jsonのスキーマ検証、拡張機能JSON、db.php、rpc.php、cron.php、Settings::get()のパス、blockstudio/*のフック名。 |
theme |
Baseの内容に加え、テーマルートとstyle.cssヘッダー、手動でエンキューせずblock.jsonで宣言するアセット、style.scssにおける%selector%スコープ、フィールドのデフォルト値、リピーターの範囲。 |
extreme-theme |
Themeの内容に加え、PHPStanの厳格なフラグ、シェルおよびeval()の呼び出しの拒否、$wpdbへの直接書き込み、出力のエスケープ、Tailwind、JavaScript、Interactivity APIのチェック。 |
wordpress-render |
Extreme themeの内容に加え、指定したコマンドによるライブレンダーの検証。 |
プロジェクト設定ファイルがない場合、標準コマンドはbaseとthemeもPHPStanレベルmaxで実行します。extreme-themeによってmax自体が設定されます。各プリセットの診断には固定のblockstudio.*識別子があり、PHPStanリファレンスに記載されています。
themeレイヤーとextremeレイヤーは、PHPファイル以外も検査します。defaultがないフィールドと、コンソールにログを出力するscript.jsがある場合、同じコマンドで次のように報告されます。
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
これらのチェックはPHPStanの結果キャッシュを通じて報告されます。block.jsonまたはスクリプトだけを編集した後は、キャッシュが温かいと古い状態の[OK] No errorsが報告されることがあります。PHP以外の変更で成功結果を信頼する前に、キャッシュを迂回する--debugを--の後に渡してください。
vendor/bin/blockstudio-phpstan -- --no-progress --debug
コマンドオプションと終了コード
コマンドラインの値は、1回の実行に限り、対応するblockstudio.jsonの値を置き換えます。置き換えとは、文字どおり置き換えるという意味です。--excludeを1つでも渡すと、設定済みのexcludePathsはすべて破棄されるため、1つ追加する場合は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":[]}
--以降のすべてはPHPStanに渡されます。独自の--memory-limitを渡さない限り、ラッパーはPHPStanのメモリ上限を1Gに引き上げます。また、一時システムディレクトリに設定ファイルを組み立てるため、プロジェクト内に生成ファイルは残りません。解析に合格すると0、PHPStanが診断を報告すると1、使用方法、設定、実行のエラーが発生すると2で終了します。
phpstan/extension-installerを追加するのではなく、標準コマンドから実行してください。プリセットには拡張機能がすでに含まれており、インストーラーがある状態で同じextension.neonを2回読み込むと、解析を始める前にPHPStanが”This file is included multiple times”で停止します。
既存プロジェクトに導入する
初めて解析するプロジェクトでは、通常いくつかの指摘事項が見つかります。プリセットを緩めるのではなく、ベースラインに記録して、新しいコードにはすべてのルールを適用しましょう。
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
プロジェクト設定からベースラインを読み込み、phpstan.configurationでそのファイルを指定します。
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
次回の実行では、記録された指摘事項がある状態で[OK] No errorsが報告され、新たな問題があれば引き続き失敗します。baseまたはthemeプリセットを使う場合は、phpstan.neonのparameters内にlevel: maxも設定してください。プロジェクト設定がない場合に限り、標準コマンドがそのレベルを設定するためです。
解析でコミットを制御する
blockstudio.jsonに"githooks": { "commit": true }がある状態で、依存関係をインストールした後に管理対象フックを一度同期します。
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
このコマンドはGit独自のディレクトリ内にフックを書き込み、core.hooksPathをその場所に設定し、以前設定されていたコミット前フックも連続して実行します。このフックがプロジェクトのルートから実行するのはvendor/bin/blockstudio-phpstan -- --no-progressのみです。フォーマッターも書き換えもありません。先ほどの壊れたテンプレートを含めてコミットすると、解析の段階で停止します。
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
commitをfalseに設定してからsyncを再実行するか、vendor/bin/blockstudio-githooks removeを実行すると、以前のフックパスに戻せます。
削除されるのは、Blockstudioが書き込んだファイルのみです。
プロジェクトの仕様を生成する
解析では、エージェントが事後に誤りを知ります。AGENTS.mdがあれば事前に把握できます。ブロックやページの場所、フィールドがテンプレートに渡される仕組み、有効な機能、選択したプリセットで拒否される内容がわかります。blockstudio-agentsはプロジェクト自体からそのドキュメントを生成します。
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
このガイドのテーマでは、生成されたファイルは次のように始まります。
# 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.
各行の情報源は3つのいずれかです。プロジェクトのファイルからは、プロジェクトの種類、件数、ディレクトリ、名前空間、テンプレート言語が取得されます。blockstudio.jsonからは有効な機能が取得されるため、コミットフックが「有効な機能」に、vendor/bin/blockstudio-githooks syncが「コマンド」に記載されるのはgithooks.commitが設定されている場合のみです。選択したプリセットからは、各レイヤーのプリセットファイルを読み取り、正確性のセクションが作られます。
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.
最新の状態に保つ
設定を変更すると仕様が古くなります。blockstudio.jsonでTailwindを有効にした後、チェックモードを実行すると次のように検出されます。
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
1で終了するため、解析と並行してCIのステップとして使えます。再生成すると、「Tailwind CSS」機能の項目とwp bs tailwind compileコマンドが追加されます。
再生成後も残るメモ
ファイルの末尾にはメモ領域があります。マーカーの間にある内容は、再生成のたびにバイト単位で保持されます。ファイルから導き出せないプロジェクトの知識は、ここに記載してください。
## 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 -->
このジェネレーターは、自らが作成していないファイルを置き換えません。手書きのAGENTS.mdを対象に実行すると、拒否して2で終了します。
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
手書きのテキストを残すには、別の場所にコピーし、--forceを指定して実行してから、メモ領域に貼り付けます。ほかのオプションは--root、--config、--output、--stdoutです。これを指定すると、仕様を書き込まずに出力します。
Blockstudio 7.7の変更点
バージョン7.7のパッケージでも、ここで説明したコマンド、プリセット、終了コードは変わりません。このガイドの作成中に確認された違いは2点あります。修正セクションで説明したように、$aにアノテーションが不要になりました。また、生成される仕様ではブロックタグの検証範囲が広がり、ページのソースでブロックにマッピングされたHTML要素と、タグが転送できるグローバル属性が対象になりました。
次のステップ
- PHPStanリファレンス:すべてのルール、プリセットのパラメーター、フィールド型の構造、ライブレンダーの検証、診断識別子。
- AI連携:プロジェクトの仕様を補完する、コーディングエージェント向けのドキュメント一覧。
- Blockstudioを使ったVibecoding:Blockstudioプロジェクトでコーディングエージェントを活用する方法。
- フィールドパターンのクックブック:グループやリピーターを含む、解析でテンプレートキーが認識されるフィールド構造。