コンテンツへスキップ

PHPStan

blockstudio/phpstan拡張機能により、Blockstudioプロジェクトで静的解析を利用できます。解析時にブロックテンプレート、スキーマファイル、設定パス、フック名を検証し、実行時に問題が起きる前にバグを検出します。

インストール

シェル
composer require --dev blockstudio/phpstan

7.7のテンプレート型付けと拡張されたブロックタグチェックには、blockstudio/phpstan 0.1.9以降とPHPStan 2.1.47以降が必要です。プラグインとは別にパッケージを更新してください:

シェル
composer require --dev blockstudio/phpstan:^0.1.9

この拡張機能はPHPStanの拡張インストーラーによって自動検出されます。手動での設定は不要です。

チェック内容

テンプレートのフィールドアクセス

block.jsonの隣にPHPファイルがある場合、この拡張機能は$a['key']へのすべてのアクセスをブロックの宣言済み属性と照合して検証します。

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

Blockstudioが$a、$attributes、$b、$block、$c、$context、$content、$isEditor、$isPreviewと、テンプレートを読み込む前のisland変数を定義することを、この拡張機能は認識しています。そのため、$a['title']のような直接読み取りは未定義の可能性があるものとして報告されず、$aの型はテンプレートの隣にあるblock.jsonから判定されます。絞り込み後も構造は維持されるため、$a['label'] ?? ''、isset( $a['cta']['target'] )、$a['cta']['title'] !== nullには宣言されたフィールド型が引き継がれます。テンプレートが$a自体に値を代入した場合は、その代入時に設定した型が維持されます。/** @var array<string, mixed> $a */のdocblockは追加しないでください。構造が開いた配列に置き換わります。

フィールドキーにはBlockstudioの実行時のフラット化ルールが適用されます。tabsと、idを持たない匿名のgroupコンテナは表示専用のため、その子フィールドは親スコープに残ります。名前付きグループでは、子のキーの先頭にグループIDが付きます:

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

再利用可能なカスタムフィールド

ファイル参照型のcustom/*は、テンプレートキーと配列構造のチェック前に展開されます。この拡張機能は対応するfield.jsonを読み込み、Blockstudioと同じidStructure、overrides、ネストされた参照、グループ、タブ、リピーターのルールを適用します:

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/mytheme/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "id": "title" }
        }
      }
    ]
  }
}

結果として得られるテンプレートキーはtitleとhero_descriptionです。これらはPHP、Twig、Blade、ブロックタグ、推論された属性構造で認識されます。

ファイル参照型の定義が見つからない、曖昧、無効、または循環している場合は、具体的なblockstudio.customField.*エラーが発生します。そのブロックの依存キーのチェックはスキップされるため、定義が1つ未解決でも不明なフィールドに関する誤検出が続けて発生することはありません。

blockstudio/fieldsPHPフィルターを介して実行時のみ登録される定義は、静的解析では推論できません。静的にチェックされるテンプレートキーにフィールドを含める必要がある場合は、field.json定義を使用してください。

Twigテンプレートのアクセス

Twigテンプレートは自動的にスキャンされます。注釈は不要です。

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Bladeテンプレートのアクセス

Bladeテンプレートも同じ方法でスキャンされます。

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

ブロックタグの検証

ブロックタグは、Blockstudioが読み取る場所で検証されます。<bs:>タグと<block>タグ、blockTags.prefixesで設定されたプレフィックスタグ(<acme-card>など。実行時と同様に名前空間の順序で解決)、エイリアスタグを、PHP、Twig、Bladeのブロックテンプレートとページレイアウトで検証します。pages/配下のページソース(index.php、index.html、index.twig、index.blade.php)もチェック対象です。プロジェクトがブロックに対応付けているHTML要素も含まれます。ui.enabledが有効な場合は、同梱のUIブロックも認識されます。

HTML
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->

属性が受け入れられるのは、ブロックがフィールド(カスタムフィールド、およびidStructureを介してブロック型フィールドが引き継ぐフィールドを含む)として宣言している場合、またはBlockstudioがブロックのルート要素へ転送する場合です:data-*、aria-*、id、style、role、title、lang、dir、hidden、tabindex。テンプレートではすべてのhtml-*属性が通過します。ページソースではhtml-プレフィックスは、転送対象の属性名にのみ使用できます。それ以外の属性、特に宣言されていないclassは報告されます。Blockstudioはこれを保存するだけで、レンダリングしないためです。

実行時にはPHPフィルターで要素の対応付けとタグエイリアスを登録しますが、静的解析ではこれらを評価できません。そのため、解析時にはblockstudio.jsonから読み取ります。scanPhpは、モジュール内のコンポーネントマークアップなど、他のプロジェクトPHP内のタグもチェックし、そこで不明なブロックを報告しません:

JSON
{
  "phpstan": {
    "blockTags": {
      "elements": {
        "section": "theme/section",
        "h2": "theme/heading",
        "div": [
          { "attribute": "width", "block": "theme/row" },
          "theme/div"
        ]
      },
      "aliases": { "theme-button": "bsui/button" },
      "scanPhp": true
    }
  }
}

要素はブロック名、または順に評価されるルールに対応します。属性を持つ最初のルールが適用され、通常のブロック名は常に一致します。プロジェクトで対応付けられていない要素はコアブロックのままとなり、チェックされません。診断ではblockstudio.blockTag.unknown、blockstudio.blockTag.attribute、blockstudio.blockTag.classを使用します。

データベースレコードの型付け

Db::get()はdb.phpスキーマに基づいた型付きインスタンスを返します。レコードの構造は自動的に推論されます。

PHP
return [
    'storage' => 'table',
    'fields' => [
        'email' => ['type' => 'string', 'required' => true],
        'name'  => ['type' => 'string'],
    ],
];
PHP
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // string
echo $record['name'];  // string|null (optional field)
echo $record['typo'];  // Error: Offset 'typo' does not exist

必須フィールドはnull不可です。任意フィールドはtype|nullです。idフィールド(int)は常に存在します。同じ型付けはPHPネイティブのBlockstudio\\Db\\Schema / Blockstudio\\Db\\Fieldビルダー構文でも機能します。

設定パスの検証

Settings::get()パスは既知の設定スキーマと照合してチェックされます。

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

フック名の検証

Blockstudioフィルター名とアクションフック名が検証されます。

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

blockstudio/settings/tailwind/enabledのような動的設定フックは常に許可されます。blockstudio以外のフックは無視されます。

スキーマ検証

この拡張機能は、プロジェクト内のBlockstudioスキーマファイルをすべて検証します。

block.json:

  • nameフィールドがない
  • フィールドtypeがない
  • 必須のidが値フィールドにない
  • 不明なフィールドタイプ
  • フィールドタイプが受け付けないプロパティ("translate"ではなく"translat"など)。最も近い既知のプロパティが候補として示されます
  • select/radio/checkboxにoptionsまたはpopulateがない
  • フィールドIDの重複
  • リピーター内、またはidのないグループ内にtabsフィールドがある
  • 無効なpluginDependencies宣言

groupやtabsのようなコンテナフィールドと、custom/*フィールド参照は、他のフィールドを展開またはラップするだけの場合、idを省略できます。

フィールドのプロパティは、各組み込みフィールドタイプでschemas/block.jsonが宣言するプロパティと、すべてのフィールドが受け付けるプロパティに照らしてチェックされます。custom/*参照に固有のラッパープロパティと、プロジェクトで定義された名前空間付きフィールドタイプは、このチェックの対象外です。既存のフィールドタイプ検証とカスタム参照検証は引き続き適用されます。識別子はblockstudio.blockJson.propertyとblockstudio.fieldJson.propertyです。

これは値だけでなくプロパティ名もチェックします。minimizedはリピーターでは有効ですが、テキストフィールドでは報告されます。プラグインの実行時の動作は変わりません。プロジェクトで組み込みフィールドに独自のメタデータを意図的に付与している場合は、他の構造チェックを無効にせず、これらの指摘だけを抑制してください。

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

再利用可能なfield.json内の組み込みフィールドは、custom/*参照に独自のラッパーオプションがあっても引き続きチェックされます。拡張ファイルはこれらのプロパティ名診断の対象外です。拡張固有のsetルールは引き続き有効です。

field.json(再利用可能なカスタムフィールド):

  • nameがない
  • attributesがない、または空
  • 属性オブジェクトが無効、またはフィールドtypeがない
  • 値フィールドで必要なidがない
  • 不明なフィールドタイプ
  • フィールドタイプが受け付けないフィールドプロパティ
  • リピーター内のtabsフィールド。直接配置されている場合、またはidのないグループ内にある場合
  • ネストされたcustom/*参照がない、曖昧、無効、または循環している

拡張JSON(extensions/内のブロック拡張):

  • name(対象ブロック)がない
  • blockstudioキーがない
  • blockstudio.extendキーがない

page.json(ファイルベースのページ):

  • titleがない
  • slugがない
  • postStatusの値が無効

db.php:

  • fields配列がない
  • フィールド型が無効
  • 従来の配列とBlockstudio\\Db\\Schema / Blockstudio\\Db\\Fieldの両方をサポート

rpc.php:

  • HTTPメソッドが無効
  • publicの値が不正(true、false、'open'のいずれかである必要があります)
  • 従来の配列と属性付きオブジェクトの戻り値の両方をサポート

cron.php:

  • 設定済みタスクにscheduleがない
  • 設定済みタスクにcallbackがない
  • 従来の配列と属性付きオブジェクトの戻り値の両方をサポート

blockstudio.json:

  • "tailwind": trueのような省略形のブール値(ネストされたオブジェクト形式{"enabled": true, "config": ""}を使用する必要があります)

設定

この拡張機能は、デフォルトで解析対象プロジェクト内のBlockstudioファイルを検出します。プロジェクトルート外のライブラリにあるブロックや再利用可能なフィールドを使う場合は、そのライブラリのパスをblockstudioScanRootsに追加してください。このパスからblock.jsonとfield.jsonの定義を両方スキャンし、外部ブロックタグとそのカスタムフィールドをまとめて検証します。

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

ファイルを無視するには、PHPStan標準のexcludePaths設定を使用してください。

解析プリセット

自動検出される拡張機能は、互換性を保つための基本機能です。Blockstudio 7.6では、既存のプロジェクトを変更せずに、オプトインのレイヤーを追加できます:

プリセット 動作
base.neon 既存のスキーマ、テンプレート、フック、設定、APIの解析。
theme.neon 基本機能に加え、WordPressテーマルート、スタイルヘッダー、Blockstudioアセット、セレクターのスコープ、フィールドのデフォルト値、リピーターの上限を解析。
extreme-theme.neon テーマ機能に加え、PHPStanmax、安全でないPHP、出力エスケープ、Tailwind、JavaScript、InteractivityのAPIチェック。
wordpress-render.neon 最も厳格なテーマ機能に、呼び出し元が指定するライブWordPressレンダープローブを追加。

blockstudio/phpstanをインストールすると、基本拡張機能のみが有効になります。既存のPHPStan設定にオプトインのレイヤーを追加してください:

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

blockstudioThemeExcludePathsはテーマスキャナーを制御します。 PHPStan標準のexcludePathsは、PHPの解析を別途制御します。

blockstudio.json内の標準コマンドのphpstan.excludePaths設定(および--excludeオプション)は、両方のレイヤーを設定します。相対パターンは、設定されたすべてのルートを基準に解決されます。そのため、vendor/**のような項目はPHPStanの解析とBlockstudioのプロジェクトスキャンの両方を制限します。

_dist/**やnode_modules/**のようにディレクトリを1つ指定するパターンは、テーマルートの隣にある場合だけでなく、どこにあってもそのディレクトリを除外します。assets/*/docs/**のようにスラッシュを含むパターンは、ルートを基準に固定されます。生成されたブロックアセットは各ブロック内の_distディレクトリに置かれるため、コンパイル済みの出力を解析対象から除外するには単一ディレクトリ形式を使用します。

標準コマンド

このパッケージは解析用の実行ファイルとしてvendor/bin/blockstudio-phpstanをインストールします。プロジェクトで別のプリセットを選択しない限り、baseプリセットで実行されます。そのため、パッケージをインストールしただけではテーマレイヤーや最も厳格なテーマレイヤーは有効になりません:

シェル
vendor/bin/blockstudio-phpstan --root . -- --no-progress

プリセットには拡張機能自体が含まれています。標準コマンドを実行するプロジェクトにphpstan/extension-installerを追加しないでください:インストーラーがある状態でextension.neonを読み込むと、二重読み込みとなり、解析を始める前に「このファイルは複数回読み込まれています」というエラーでPHPStanが停止します。

コマンドはPHPStanのメモリ上限をデフォルトで1Gに設定します。Composerで管理されるWordPressプロジェクトが、一般的な128MCLIの上限を引き継がないようにするためです。上書きするには、--の後に-- --memory-limit=512M --no-progressなどのPHPStanオプションを明示的に渡してください。

既存プロジェクトで解析を導入する

これまで解析したことがないプロジェクトでは、通常、初回実行時に指摘事項が報告されます。プリセットの厳しさを下げる代わりに、PHPStanのベースラインを生成し、それを含むプロジェクト設定をphpstan.configurationに指定してください。これにより、新しいコードには完全なプリセットが適用され、記録済みの指摘事項は妨げになりません:

シェル
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "phpstan": {
    "configuration": "phpstan.neon"
  }
}

baseおよびthemeプリセットでは、levelの行を残してください。プロジェクト設定を含めない場合、標準コマンドはこれらのプリセットに対してレベルmaxのみを設定します。レベルがないとPHPStanは「No rules detected」で停止します。extreme-themeプリセットはレベルmaxを独自に設定します。

相対パスはblockstudio.jsonを起点に解決されます。標準コマンドと管理対象のコミットフックはどちらもこのファイルを読み込むため、バックログを先に解消しなくても、フックによって新たな指摘を防げます。

プロジェクト全体のコマンドのデフォルト値はblockstudio.jsonに記述します。

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

相対ルートは、それを宣言したファイルを起点に解決されます。明示的なCLIの値は、対応するJSONの値を置き換えます。別の設定ソースを指定するには--blockstudio-json path/to/project.jsonを渡します。形式が不正なJSON、未サポートのphpstanキー、無効な値、明示したソースの欠落は、いずれも終了コード2で確実にエラーになります。

別のプリセットを選択するか、プロジェクト設定を含めるか、繰り返し指定できるルートと除外対象を追加するか、PHPStanにJSONを指定してください。

シェル
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

ラッパーはシステムの一時ディレクトリ内で設定を組み立て、終了時に削除します。生成した設定、ベースライン、フック、キャッシュを解析対象のプロジェクトに書き込むことはありません。呼び出し元はPHPStan標準のキャッシュを引き続き明示的に設定できます。

終了時の動作は次のとおりです。

  • 解析に合格した場合は0
  • PHPStanが診断結果を報告した場合は1
  • 使用方法、設定、またはプロセスの実行が無効な場合は2

管理対象のコミットフック

extremeテーマの解析をリポジトリのコミット時チェックにするには、blockstudio.jsonでBlockstudioが管理するフックを有効にします。

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

依存関係をインストールした後、または設定を変更した後に同期します。

シェル
vendor/bin/blockstudio-githooks sync

このコマンドはGitの共通ディレクトリ内に生成したpre-commitフックと所有権レコードを書き込み、core.hooksPathを管理対象のフックディレクトリに設定し、以前に設定されていたpre-commitフックを安全に連結します。同期を繰り返しても生成ファイルだけが更新されるため、パッケージのアップグレードを何度行っても結果は変わりません。

commitをfalseに設定するか、削除するか、blockstudio.jsonを削除してからsyncを実行すると、記録されたフックのパスが復元され、Blockstudioが所有するファイルだけが削除されます。次のコマンドも実行できます。

シェル
vendor/bin/blockstudio-githooks remove

ユーザーが所有するファイルは上書きも削除もされません。Blockstudioを有効にした後でcore.hooksPathが変更された場合、削除時には新しい設定が保持されます。生成されるフックは、リンクされたGitチェックアウトや、パスに空白が含まれる場合にも対応しており、コミット時に現在のリポジトリとプロジェクトのルートを解決します。そのルートから標準コマンドを実行するため、対話実行とコミットで同じphpstanオブジェクトが使われ、引数が重複して生成されることはありません。

フックが実行するのはvendor/bin/blockstudio-phpstanだけです。Blockstudioはフォーマッターを実行せず、フックがプロジェクトのファイルを書き換えることもありません。依存関係の不足や解析の失敗があると、問題への対処方法を示すエラーでコミットを停止します。

ライブWordPressレンダリング

ライブレイヤーの動作は明示的です。呼び出し元がWordPress環境を管理し、argv配列を指定します。

シェル
vendor/bin/blockstudio-phpstan \
  --preset wordpress-render \
  --render-command='["wp","eval-file","tools/render-probe.php"]' \
  --render-working-directory=. \
  --render-timeout=60 \
  --root .

コマンドはシェルを介さずに実行され、JSONオブジェクトを1つ出力する必要があります。

JSON
{"ok":true}

プローブでは、特定の失敗を報告できます。

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

ゼロ以外の終了コード、タイムアウト、形式が不正なJSON、ok: falseはblockstudio.wordpress.renderを生成します。

blockstudio.javascript.domContractは、解析対象のマークアップにその属性を持つものがない場合に、スクリプトがquerySelector()、querySelectorAll()、closest()、またはmatches()に渡す[data-*]属性セレクターを報告します。マークアップには、解析対象ルート配下のすべてのPHP、Twig、Blade、HTMLファイルと、すべてのReact.tsxおよび.jsxコンポーネントが含まれ、除外パスは対象外です。コンポーネントは解析されます。JSX属性名も、オブジェクトリテラルの文字列キーも対象です。そのため、要素にスプレッドされた属性オブジェクトはセレクターを満たしますが、クラス名やその他の属性値は満たしません。

Interactivity APIチェックは同じReactコンポーネントを読み取ります。JSX要素上のdata-wp-interactive名前空間は、blockstudio.interactivity.orphanに対するテンプレート参照として扱われ、その内部のdata-wp-*ディレクティブは、最も近い外側の名前空間、または値に含まれるnamespace::プレフィックスを基準に解決されます。JSX属性、または属性オブジェクトの文字列キーとして記述された静的な文字列値を持つディレクティブは、既存のストアハンドラーとパスを指定する必要があります(blockstudio.interactivity.handler、blockstudio.interactivity.binding)。また、ストアコードは、バインド先の属性やクラスを変更してはなりません(blockstudio.interactivity.derivedState)。Reactは属性値をエスケープするため、コンポーネント内のdata-wp-contextは報告されず、動的な値もチェックされません。bsui/配下の名前空間は、バンドルされたUIブロックに属します。これらのストアは解析対象ルートの外でBlockstudioとともに提供されるため、孤立したものとして扱われることはありません。

診断ID

新しいプリセット診断には、安定したblockstudio.*IDが割り当てられます。

  • テーマ構造: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • アセットとフィールド: blockstudio.theme.asset.manualEnqueue, blockstudio.theme.asset.selectorScope, blockstudio.theme.asset.missing, blockstudio.field.default, blockstudio.field.repeaterBounds
  • PHP: blockstudio.php.forbiddenFunction, blockstudio.wordpress.rawDatabaseWrite, blockstudio.output.unescaped
  • Tailwind: blockstudio.tailwind.compilerMissing, blockstudio.tailwind.compile, blockstudio.tailwind.unknownUtility, blockstudio.tailwind.semanticToken
  • JavaScript: blockstudio.javascript.syntax, blockstudio.javascript.debugOutput, blockstudio.javascript.bannedApi, blockstudio.javascript.leakedGlobal, blockstudio.javascript.importSpecifier, blockstudio.javascript.rootGuard, blockstudio.javascript.initShape, blockstudio.javascript.domContract, blockstudio.javascript.listenerCleanup, blockstudio.javascript.reducedMotion
  • インタラクティブ機能: blockstudio.interactivity.import, blockstudio.interactivity.moduleImport, blockstudio.interactivity.namespace, blockstudio.interactivity.scopedDom, blockstudio.interactivity.derivedState, blockstudio.interactivity.handler, blockstudio.interactivity.binding, blockstudio.interactivity.context, blockstudio.interactivity.orphan

パフォーマンス

スキャナーは通常の実体化されたディレクトリを受け付け、ルートの重複を除去し、依存関係、ビルド、キャッシュの各ディレクトリをスキップして、ファイルの読み込みをメモリ上にキャッシュし、診断結果を一定の順序で並べ替えます。ルートを絞り、フィクスチャや生成物のディレクトリを除外し、大きなリポジトリではファイル数の上限を設定してください。JavaScriptとTailwindは個別に無効化できます。ライブレンダリングは、そのプリセットが選択されている場合にのみ実行されます。

テーマ、JavaScript、Tailwindの診断結果は、PHPStanの結果キャッシュを通じて報告されます。block.jsonまたはスクリプトだけを変更した後は、キャッシュが温まっていると以前の結果が報告されることがあります。このような変更を確認するときは、--の後に--debugを渡してキャッシュを回避してください。

コーディングエージェント向けのプロジェクト仕様

パッケージは3つ目の実行ファイルvendor/bin/blockstudio-agentsをインストールします。このコマンドは実行先のプロジェクトを説明するAGENTS.mdを書き出します。これは、コーディングエージェントが何かを変更する前に必要とする情報です。プロジェクトで何を開発しているか、どのBlockstudio機能が有効か、どのような解析でエラーになるか、どのコマンドを使うかが記載されます。

シェル
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/project/AGENTS.md

出力には固定のテンプレートがなく、すべての行は次の3つのソースのいずれかから生成されます。

  • プロジェクト独自のファイル。 style.cssヘッダー、ブロック、ファイルベースのページを持つテーマと、ブロックを登録するだけのプラグインでは、生成されるドキュメントが異なります。件数、ディレクトリ、ブロックの名前空間、テンプレート言語は、解析で実際に見つかった内容に基づきます。ルートと除外対象には解析と同じ設定が使われます。
  • blockstudio.json。 有効な機能だけが、設定値とともに記載されます。ブロックタグのプレフィックスと、その解決に使う名前空間、Tailwind、同梱のUI、エディターのアセットリセット、キャッシュパス、パフォーマンスプロファイル、静的プリレンダリングと動的パス、テーマのデフォルト値、Content Sync、コミットフックが対象です。
  • 選択したphpstan.preset。 正確性に関するセクションは、プリセットファイル自体からレイヤーごとに読み込まれるため、そのプリセットが登録するルールだけが列挙されます。baseでは、スキーマ、テンプレート、フック、設定のルールが記載されます。extreme-themeではさらに、テーマ構造のルール、PHPStanの厳格なフラグ、安全でないPHP、出力のエスケープ、Tailwind、JavaScriptも記載されます。プリセットにルールが追加されると、生成ドキュメントにも反映されます。

コマンドのセクションも同じ原則に従います。静的プリレンダリングが有効な場合はwp bs prerender statusが、githooks.commitが設定されている場合はvendor/bin/blockstudio-githooks syncが、プロジェクトに実際にdb.phpがある場合はwp bs db schemasが記載されます。

オプション 動作
--root <path> プロジェクトのルート(デフォルト: 現在のディレクトリ)
--config <path> blockstudio.jsonのパス(デフォルト: <root>/blockstudio.json)
--output <path> 仕様のパス(デフォルト: <root>/AGENTS.md)
--stdout 書き込まずに仕様を出力
--check ディスク上の仕様が最新でない場合に1で終了
--force Blockstudioが所有していないファイルを置き換える

--checkを使うと、コミットフックで解析を必須にするのと同様に、仕様をCIのチェックとして設定できます。

シェル
vendor/bin/blockstudio-agents --check

所有権

生成ファイルには、管理対象のコミットフックと同じ種類のマーカーが付き、同じルールが適用されます。Blockstudioは、自ら書き込んでいないファイルを置き換えません。コマンドを実行する前から存在するAGENTS.mdや、作成者が手動で書いたファイルがある場合、--forceが指定されるまで変更せずに残し、終了コード2で拒否します。

安全に再生成できます。ファイルの末尾にはメモ用の領域があり、各マーカーの間にあるバイト列は再生成しても保持されます。

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

終了コードは、仕様を書き込んだ場合、最新である場合、または出力した場合は0、--checkによって仕様が古いと判定された場合は1、使用方法、設定、ファイルシステムのエラーが発生した場合は2です。

フィールド型の形状

この拡張機能は、すべてのBlockstudioフィールド型を具体的なPHP型に対応付けます。

フィールドタイプ PHPタイプ
text、textarea、richtext、wysiwyg、code string
date、datetime、classes、html-tag、unit、gradient string
number、range int|float
toggle bool
select、radio、checkbox(単数) string|int
select、checkbox(複数) list<string|int>
color array{value: string, opacity: float|null}
link array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null}
icon array{set: string, subSet: string, icon: string}
files(単数) array{id: int, url: string, alt: string|null, mime_type: string|null}
files(複数) list<array{id: int, url: string, ...}>
group 名前付きグループではアンダースコアの接頭辞を使用し、名前のないグループは親スコープにフラット化されます
repeater list<array{...child fields...}>
tabs 親スコープにフラット化されます

APIのスタブ

この拡張機能には、Blockstudioの公開API一式のスタブが含まれています。

  • bs_render_block(), bs_block_values(), bs_get_group(), bs_get_scoped_class(), bs_db_form(), bs_is_editor(), bs_is_preview(), bs_is_buffering(), bs_strip_render_markers()
  • Db::get(), Db::create(), Db::list(), Db::get_record(), Db::update(), Db::delete()
  • Settings::get(), Settings::get_all()
  • Field_Registry::instance(), Field_Registry::all(), Field_Registry::get()
  • Build::blocks(), Build::extensions(), Build::get_build_dir()

これにより、手元のマシンにBlockstudioプラグインのソースがなくても、コード補完や型チェックを利用できます。

必要条件

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer(自動検出のため推奨)

パッケージはBC Math互換プロバイダーを自動的にインストールします。そのため、テーマまたはextremeプリセットでJavaScriptチェックを有効にする場合も、ネイティブext-bcmathは不要です。新規生成したテーマでも同様です。