본문으로 건너뛰기

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 및 아일랜드 변수를 템플릿 포함 전에 정의한다는 점을 파악하므로 $a['title'] 같은 직접 읽기를 정의되지 않았을 가능성이 있는 값으로 보고하지 않습니다. 또한 템플릿 옆의 block.json에서 $a의 타입을 가져옵니다. 타입 형태는 범위를 좁혀도 유지되므로 $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.* 오류가 발생합니다. 해당 블록에서는 종속 키 검사를 건너뛰므로 해결되지 않은 정의 하나가 알 수 없는 필드 오류를 추가로 발생시키지 않습니다.

blockstudio/fields PHP 필터를 통해 런타임에만 등록되는 정의는 정적 분석으로 추론할 수 없습니다. 정적으로 검사되는 템플릿 키에 필드가 포함되어야 한다면 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 테마 구성에 PHPStan max, 안전하지 않은 PHP, 출력 이스케이프, Tailwind, JavaScript 및 Interactivity API 검사를 추가합니다.
wordpress-render.neon Extreme 테마에 호출자가 제공하는 실시간 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/**처럼 디렉터리 하나를 지정하는 패턴은 테마 루트 옆뿐 아니라 어디에 있든 해당 디렉터리를 제외합니다. assets/*/docs/**처럼 슬래시가 포함된 패턴은 루트를 기준으로 고정됩니다. 생성된 블록 에셋은 각 블록 안의 _dist 디렉터리에 저장되므로, 디렉터리 하나를 지정하는 형식으로 컴파일된 출력물이 분석되지 않도록 할 수 있습니다.

표준 명령

패키지는 vendor/bin/blockstudio-phpstan을 분석 실행 파일로 설치합니다. 프로젝트가 다른 프리셋을 선택하지 않으면 base 프리셋을 실행하므로, 패키지를 설치하는 것만으로 테마 또는 Extreme 테마 계층이 활성화되지는 않습니다:

셸
vendor/bin/blockstudio-phpstan --root . -- --no-progress

프리셋 자체에 확장 기능이 포함되어 있습니다. 표준 명령을 실행하는 프로젝트에 phpstan/extension-installer을 추가하지 마세요. 설치 프로그램이 있는 상태에서 extension.neon이 두 번 로드되면 PHPStan가 “This file is included multiple times” 오류와 함께 중단되어 아무것도 분석하지 못합니다.

명령은 PHPStan을 1G 메모리 제한으로 설정하므로, Composer에서 관리하는 WordPress 프로젝트에는 일반적인 128M CLI 한도가 적용되지 않습니다. 재정의하려면 -- 뒤에 명시적인 PHPStan 옵션을 전달하세요. 예: -- --memory-limit=512M --no-progress.

기존 프로젝트에서 분석 도입하기

한 번도 분석하지 않은 프로젝트는 첫 실행에서 대개 문제를 보고합니다. 프리셋 수준을 낮추는 대신 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의 공용 디렉터리에 쓰고, core.hooksPath을 관리형 훅 디렉터리로 설정하며, 이전에 구성된 사전 커밋 훅을 안전하게 연결합니다. 반복 동기화는 생성된 파일만 갱신하므로 패키지를 업그레이드해도 결과가 일관됩니다.

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 객체를 출력해야 합니다:

JSON
{"ok":true}

검사 과정에서 특정 오류를 보고할 수 있습니다:

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

0이 아닌 종료 코드, 시간 초과, 형식이 잘못된 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와 함께 제공되므로 고아로 처리되지 않습니다.

진단 식별자

새 프리셋 진단에는 안정적인 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
  • Interactivity: 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를 전달하세요.

코딩 에이전트를 위한 프로젝트 규약

패키지는 세 번째 실행 파일인 vendor/bin/blockstudio-agents을 설치합니다. 이 실행 파일은 실행 중인 프로젝트에 대한 AGENTS.md을 작성합니다. 코딩 에이전트는 무엇을 수정하기 전에 이 문서를 통해 프로젝트가 무엇을 만드는지, 어떤 Blockstudio 기능이 활성화되어 있는지, 분석에서 무엇을 거부하는지, 어떤 명령을 적용할지 알아야 합니다.

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

출력의 어떤 내용도 고정된 템플릿이 아닙니다. 모든 줄은 다음 세 가지 소스 중 하나에서 가져옵니다:

  • 프로젝트 자체 파일. 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은 종료 코드 2와 함께 거부되며, --force을 전달할 때까지 변경되지 않습니다.

다시 생성해도 안전합니다. 파일은 메모 영역으로 끝나며, 해당 표시 사이의 바이트는 다시 생성할 때마다 보존됩니다:

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 호환성 공급자를 자동으로 설치합니다. 따라서 기본 ext-bcmath은 선택 사항이며, 테마 또는 Extreme 프리셋을 통해 JavaScript 검사를 활성화하는 새로 생성된 테마에서도 필요하지 않습니다.