PHPStan을 사용한 검사 템플릿과 생성된 AGENTS.md
Blockstudio 블록은 서로 일치해야 하는 두 파일로 구성됩니다. block.json는 필드를 선언하고 템플릿은 해당 필드를 $a['id']로 읽습니다. 런타임에는 템플릿이 이름이 변경되었거나 선언되지 않았거나 철자가 틀린 키를 읽더라도 이를 막을 방법이 없습니다. 그저 빈 문자열을 렌더링하고, 실제 페이지의 제목이 비어 있는 것을 누군가 발견할 때서야 실수가 드러납니다. 출력 이스케이프도 마찬가지입니다. 이스케이프되지 않은 echo는 필드 값에 마크업이 포함되기 전까지는 문제없이 작동합니다.
blockstudio/phpstan 패키지는 두 문제를 분석 단계에서 해결합니다. block.json 파일을 읽고 해당 파일에서 $a의 유형을 지정해 일치하지 않는 템플릿 읽기를 보고합니다. 선택형 프리셋을 사용하면 테마 구조 규칙, 이스케이프 검사, JavaScript 및 Tailwind 검사도 추가됩니다. 같은 패키지에는 분석을 실행하는 관리형 사전 커밋 훅과 코딩 에이전트용 프로젝트 설명 AGENTS.md를 작성하는 생성기도 포함되어 있습니다.
이 가이드에서는 작은 테마를 만들고 템플릿 하나를 일부러 망가뜨린 다음, 분석 출력을 살펴보고 문제를 수정합니다. 그런 다음 커밋 게이트와 에이전트 계약을 설정합니다.
테마 설정
먼저 style.css 헤더와 composer.json, 블록 하나가 있는 테마 폴더를 준비합니다:
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에 실행 파일 세 개를 설치합니다: 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는 세 가지 정적 프리셋 중 가장 엄격합니다. 아래 표에서 각 프리셋에 추가되는 항목을 설명합니다. excludePaths는 Composer 자체 파일이 Blockstudio 검사와 PHP 분석에 포함되지 않도록 합니다.
일부러 템플릿 망가뜨리기
히어로 블록은 필드 하나를 선언합니다:
{
"$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은 확장 기능이$a에block.json에서 파생된 구체적인 형태인array{heading: string}을 부여하기 때문에 PHPStan 자체도 같은 결론에 도달합니다. 각 필드 유형은text은string,toggle은bool, 반복 필드는 행 형태의 배열과 같이 PHP 유형에 대응합니다.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
주석에는 정확한 형태를 지정합니다. 표준 명령은 max 수준에서 PHPStan를 실행하며, 더 느슨한 @var array<string, mixed> $a는 varTag.nativeType로 거부됩니다(“PHPDoc 태그 @var의 array 유형<string, mixed>은 네이티브 유형 array{heading: string, subtitle: string}의 하위 유형이 아닙니다”). 7.6에서는 모든 필드를 mixed로 확장하므로 각 esc_html() 호출이 argument.type를 보고합니다. varTag.nativeType 메시지에는 추론된 형태가 출력되므로 복사할 주석을 가장 빠르게 찾을 수 있는 방법이기도 합니다.
Blockstudio 7.7에서는 블록 템플릿 안에서 $a가 정의된 것으로 처리하므로 variable.undefined 진단이 사라지고 주석은 선택 사항이 됩니다. 7.7에서는 위의 문제가 있는 템플릿이 오류 네 개를 보고합니다. 수정한 템플릿은 @var 줄 없이 통과합니다.
프리셋 선택
패키지를 설치하면 기본 확장 기능만 활성화됩니다. 프로젝트에서 다른 프리셋을 선택하지 않으면 표준 명령은 base를 실행하므로 종속 항목을 추가하는 것만으로 더 엄격한 계층이 활성화되지는 않습니다.
| 프리셋 | 추가 항목 |
|---|---|
base |
PHP, Twig, Blade의 템플릿 필드 접근, 블록 태그 검사, block.json, field.json, page.json의 스키마 검증, 확장 기능 JSON, db.php, rpc.php 및 cron.php, Settings::get() 경로, blockstudio/* 훅 이름. |
theme |
기본 프리셋에 테마 루트와 style.css 헤더, 직접 큐에 넣는 대신 block.json에 선언한 에셋, style.scss에서의 %selector% 범위 지정, 필드 기본값, 반복 필드 범위를 추가합니다. |
extreme-theme |
테마 프리셋에 엄격한 PHPStan 플래그, 차단되는 셸 및 eval() 호출, 원시 $wpdb 쓰기, 출력 이스케이프, Tailwind, JavaScript 및 Interactivity API 검사를 추가합니다. |
wordpress-render |
익스트림 테마 프리셋에 사용자가 명령으로 제공하는 실시간 렌더링 테스트를 추가합니다. |
프로젝트 구성이 포함되지 않으면 표준 명령은 base 및 theme도 PHPStan 수준에서 max 실행합니다. extreme-theme가 max 자체를 설정합니다.
모든 프리셋 진단에는 안정적인 blockstudio.* 식별자가 있으며, PHPStan참조에 나열되어 있습니다.
테마 및 익스트림 계층은 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
명령 옵션 및 종료 코드
명령줄 값은 한 번 실행하는 동안 해당 blockstudio.json 값을 대체합니다. 말 그대로 대체하므로 --exclude를 전달하면 설정된 excludePaths가 사라집니다. 하나를 추가할 때는 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가 두 번 불러와집니다. 분석이 시작되기 전에 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.
모든 줄은 세 가지 출처 중 하나에서 가져옵니다. 프로젝트 파일은 프로젝트 유형, 개수, 디렉터리, 네임스페이스, 템플릿 언어를 제공합니다. 활성화된 기능은 blockstudio.json에서 가져오므로 커밋 훅은 “Enabled features” 아래에 표시되고 githooks.commit가 설정된 경우에만 vendor/bin/blockstudio-githooks sync가 “Commands” 아래에 표시됩니다. 선택한 프리셋은 프리셋 파일의 계층별 내용을 바탕으로 정확성 섹션을 제공합니다:
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 패키지에서도 여기 설명된 명령, 프리셋, 종료 코드는 그대로 제공됩니다. 이 가이드를 작성하면서 두 가지 차이를 확인했습니다. 수정 섹션에서 설명한 것처럼 $a에 더는 주석이 필요하지 않습니다. 생성된 계약에서는 블록 태그 검증을 더 폭넓게 설명하며, 페이지 소스에서 블록에 매핑된 HTML 요소와 태그가 전달할 수 있는 전역 속성을 다룹니다.
다음 단계
- PHPStan 참조: 모든 규칙, 사전 설정 매개변수, 필드 유형 구조, 실시간 렌더링 프로브 및 진단 식별자.
- AI 통합: 프로젝트 계약을 보완하는 코딩 에이전트용 문서 색인.
- Blockstudio을 활용한 바이브 코딩: 코딩 에이전트와 함께 Blockstudio 프로젝트에서 작업하기.
- 필드 패턴 요리책: 그룹과 반복기를 포함해 분석에서 이해하는 템플릿 키가 있는 필드 구조.