
Blockstudio 7.2에서는 프레임워크를 두 방향으로 확장합니다.

첫 번째 방향은 단일 프로젝트 내의 **가시성과 워크플로우**입니다. 새로운 관리자 개요, 데이터베이스 브라우저, 관리자 레지스트리 브라우저, 공유 Sass 설정을 위한 SCSS 프렐류드가 추가됩니다.

두 번째 방향은 **Blockstudio를 둘러싼 생태계**입니다. 블록 배포를 위한 레지스트리 CLI(WordPress용 shadcn과 같은 방식)와 TypeScript 스타일의 형식 안전성을 템플릿, 블록 태그, `db.php`, `rpc.php`, `cron.php` 및 관련 스키마 파일에 적용하는 PHPStan 확장 기능입니다.

두 방향의 목표는 같습니다. 규모가 큰 Blockstudio 프로젝트를 더 쉽게 이해하고, 확장하고, 공유할 수 있게 하는 것입니다.

## 관리자 환경

두 가지 기능이 추가되어 wp-admin에서 규모가 큰 프로젝트를 더 쉽게 탐색할 수 있습니다.

### 관리자 개요

이제 Blockstudio에는 **도구 > Blockstudio** 아래에 관리자 화면이 포함됩니다. 파일 시스템에서 시스템이 등록한 항목을 한곳에서 확인할 수 있습니다.

개요 화면에는 다음 전용 탭이 있습니다:

- 블록
- 확장 기능
- 필드
- 페이지
- 스키마

개요 화면과 함께 관리자 영역에 **데이터베이스** 전용 섹션이 추가됩니다. 등록된 모든 `Blockstudio\Db` 스키마를 나열하고 wp-admin에서 실제 레코드를 바로 확인할 수 있습니다.

사용자 지정 패널 그리드를 만드는 대신, 이 화면은 기본 WordPress DataViews 테이블을 사용합니다. 따라서 UI가 wp-admin과 일관된 모양을 유지하며, 등록 항목이 수십 개 또는 수백 개로 늘어난 프로젝트에서도 실용적으로 사용할 수 있습니다.

소규모 설치에서는 실행 상태를 머릿속으로 파악할 수 있습니다. 코드베이스가 커지면 더 이상 그럴 수 없습니다. 다음과 같은 질문이 생깁니다:

- 현재 실제로 등록된 블록은 무엇인가요?
- 어떤 확장 기능이 `core/*`를 대상으로 하고, 어떤 기능이 개별 블록을 대상으로 하나요?
- 동기화된 페이지는 무엇이며 어떤 게시물 유형에 속하나요?
- 이 프로젝트에 있는 재사용 가능한 필드는 무엇인가요?
- 어떤 스키마가 등록되어 있고 각각 어떤 저장소 백엔드를 사용하나요?

지금까지는 폴더를 살펴보고 JSON 파일을 열고 PHP을 추적하는 방식으로 답을 찾아야 했습니다. 이제 개요 화면에서 관리자 인터페이스를 통해 바로 확인할 수 있습니다.

각 탭은 서로 다른 질문에 답하도록 설계되었습니다:

- **블록**에는 등록된 블록 유형, 렌더링 모드, API 버전, 속성 수가 표시됩니다.
- **확장 기능**에는 대상 블록과 우선순위, 렌더링 세부 정보가 표시됩니다.
- **필드**에서는 재사용 가능한 사용자 지정 필드 정의를 빠르게 확인할 수 있습니다.
- **페이지**에는 게시물 유형, 상태, 템플릿 엔진, 동기화 상태와 함께 동기화된 파일 기반 페이지가 표시됩니다.
- **스키마**에는 백엔드, 필드 수, 권한 범위와 함께 등록된 저장소 스키마가 표시됩니다.

데이터베이스 브라우저는 초기 개요 페이로드와 의도적으로 분리되어 있습니다. 페이지를 불러올 때 모든 행을 직렬화하는 대신, 먼저 사용 가능한 스키마만 현지화하고 데이터베이스 탭을 열 때 필요에 따라 레코드를 가져옵니다. 덕분에 `db.php` 뒤에 대규모 데이터 세트가 있는 프로젝트에서도 관리자 화면을 유용하게 사용할 수 있습니다.

첫 버전은 스키마 기반 등록에만 의도적으로 초점을 맞췄습니다. 설정 페이지가 아니라 검사 페이지입니다.

아예 원하지 않는다면 완전히 비활성화하세요:

```php
add_filter('blockstudio/admin/enabled', '__return_false');
```

### 관리자 레지스트리 브라우저

개요 옆에 두 번째 탭인 **Registry**가 있습니다. 테마의 `blocks.json`에 구성된 원격 블록 레지스트리를 탐색하고, WordPress 관리자 화면에서 CLI을 건드리지 않고도 블록을 바로 가져올 수 있습니다.

```json title="blocks.json"
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

브라우저는 구성된 각 레지스트리에서 데이터를 가져와 사용 가능한 모든 블록을 나열하고, 로컬에 이미 설치되어 있는지 또는 가져올 수 있는지 표시합니다. 각 행에는 블록 파일을 테마에서 구성한 디렉터리로 다운로드하는 Import 버튼이 있습니다. 이미 설치된 블록에는 대신 Reimport 버튼이 표시됩니다.

`headers`를 포함한 객체 형식으로 인증이 필요한 레지스트리도 지원하며, `${ENV_VAR}` 보간을 사용하므로 토큰이 버전 관리에 포함되지 않습니다.

덕분에 레지스트리를 탐색하고 사용하는 과정이 단순한 CLI 워크플로우가 아닌, 관리자 화면의 핵심 기능으로 자리 잡습니다.

## 레지스트리 CLI

레지스트리 기능의 나머지 한 축은 독립 실행형 CLI인 `blockstudio/registry`입니다.

WordPress 블록을 위한 shadcn 스타일 도구입니다. npm 패키지도, 빌드 단계도 필요 없습니다. 명령을 실행하면 블록 소스 코드가 프로젝트에 복사되고, 모든 것을 직접 소유하고 관리할 수 있습니다.

```bash
npx blockstudio init
npx blockstudio add ui/tabs
```

CLI은 어떤 블록 유형과도 함께 사용할 수 있습니다. Blockstudio 블록, `@wordpress/create-block` 출력, 일반 PHP 블록을 지원합니다. 레지스트리는 폴더 안에 무엇이 있는지 신경 쓰지 않습니다. `registry.json`에서 파일 목록을 읽고 해당 파일만 정확히 복사합니다.

블록 작성자는 메타데이터, 종속성, 파일 목록과 함께 사용 가능한 블록을 나열하는 `registry.json`을 어느 URL에나 게시할 수 있습니다(GitHub 원시 콘텐츠, S3, 사용자 지정 서버 등). 사용자는 URL를 `blocks.json`에 추가하고 이름으로 블록을 가져옵니다.

CLI에서 지원하는 기능:

- **종속성 해결**: 블록은 다른 블록에 대한 종속성을 선언할 수 있으며, 순환 감지를 통해 자동으로 해결됩니다.
- **여러 레지스트리 간 충돌 처리**: 같은 블록 이름이 여러 레지스트리에 있으면 CLI에서 하나를 선택하라는 메시지가 표시됩니다.
- **인증 레지스트리**: 환경 변수 보간을 지원하는 bearer 토큰, 기본 인증, 사용자 지정 헤더
- **대화형 TUI**: 스피너, 선택 프롬프트, 진행률 표시기가 포함된 Ink 기반 인터페이스
- **비대화형 모드**: `--yes` 플래그 및 자동 CI/파이프 입력 대체 동작
- **검색 및 목록**: 명령줄에서 레지스트리 탐색

패키지에는 스키마, 종속성 해결, HTTP 가져오기, 파일 쓰기, 모든 명령 흐름, 대화형 Ink UI을 다루는 130 테스트가 포함되어 있습니다.

전체 문서는 [blockstudio.dev/registry](https://blockstudio.dev/ko/registry/)에서 확인할 수 있습니다.

## PHPStan 확장 기능

또 다른 주요 추가 기능은 `blockstudio/phpstan`입니다. PHPStan 확장 기능으로, Blockstudio 사용자에게 TypeScript 개발자가 기대하는 수준의 타입 안전성을 제공합니다.

```bash
composer require --dev blockstudio/phpstan
```

이 확장 기능은 분석 시 프로젝트의 실제 스키마를 읽고, 그 결과 타입을 PHPStan에 전달합니다. 이제 PHP 템플릿, Twig, Blade, 블록 태그, 타입이 지정된 데이터베이스 레코드, 설정 경로, 훅 이름, 그리고 `block.json`, `field.json`, 확장 기능 JSON, `page.json`, `db.php`, `rpc.php`, `cron.php`, `blockstudio.json` 전반의 스키마 검증을 지원합니다.

### 타입 안전성이 보장되는 블록 템플릿

`$a`에 대한 필드 접근은 인접한 `block.json`에 정의된 내용과 대조해 검증됩니다:

```php title="blockstudio/hero/index.php"
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
```

### 타입이 지정된 데이터베이스 레코드

`Db::get()`은 `db.php` 스키마를 바탕으로 타입이 지정된 인스턴스를 반환합니다. 레코드 구조는 실제 필드로 구성됩니다:

```php title="db.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']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
```

### 스키마 검증

잘못된 스키마 파일은 분석 시점에 감지됩니다: `block.json`, `field.json`, 확장 기능 JSON, `page.json`, `db.php`, `rpc.php`, `cron.php`, `blockstudio.json`. 이름 누락, 잘못된 필드 유형, 형식이 잘못된 정의, 더 이상 권장되지 않는 축약형 불리언(중첩 객체 대신 `"tailwind": true`)을 모두 원본 파일의 정확한 줄 번호와 함께 보고합니다.

### 설정 경로 검증

`Settings::get()` 호출은 알려진 설정 스키마와 대조해 검증됩니다:

```php
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
```

### 훅 이름 검증

필터 및 액션 훅 이름도 같은 방식으로 검증됩니다:

```php
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
```

확장 기능에는 전체 Blockstudio 공개 API의 스텁도 포함됩니다: `Db`, `Settings`, `Field_Registry`, `Build` 및 전역 헬퍼가 제공됩니다. 개발 환경에 플러그인 소스가 없어도 모든 Blockstudio API의 자동 완성과 타입 검사를 사용할 수 있습니다.

## 작성 편의 기능

두 가지 소소한 작성 편의 기능이 이번 릴리스를 마무리합니다.

### 전역 SCSS 프리루드

Blockstudio은 이미 SCSS 컴파일을 지원했지만, 한 가지 불편한 지점이 있었습니다. 공통 Sass 설정이 필요했습니다.

공통 변수, 함수 또는 믹스인에 접근하려면 모든 SCSS 파일에서 직접 가져와야 했습니다. 특히 대규모 디자인 시스템이나 Bootstrap 같은 Sass 툴킷을 사용할 때 금세 반복 작업이 됩니다.

7.2에서는 바로 이 문제를 해결하는 프리루드 훅을 추가했습니다:

```php
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

기존 `blockstudio/assets/process/scss/import_paths` 필터와 함께 사용하면 공통 Sass 환경을 한 번 정의하고 모든 컴파일 파일에서 사용할 수 있습니다.

블록 스타일시트에는 필요한 스타일만 집중해서 작성할 수 있습니다:

```scss title="style.scss"
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}
```

각 블록 에셋에서 가져오기를 반복할 필요가 없습니다. 이는 특별한 모드로 제공되는 "Bootstrap 지원"이 아닙니다. Bootstrap에서 제공되든 내부 툴킷에서 제공되든, 프로젝트 전반에서 공통 Sass을 사용할 수 있게 하는 범용 훅입니다.

### PHP 네이티브 블록 API 정의

7.2에서는 풀스택 블록 API에 사용할 수 있는 PHP 네이티브 문법도 선택 기능으로 추가했습니다. 배열은 기본 형식으로 계속 완전히 지원되며, 대체된 기능은 없습니다. 중첩된 설정 배열보다 이름이 지정된 인수, 열거형, 속성을 선호한다면 이제 해당 스타일을 선택해 사용할 수 있습니다.

`rpc.php`에서는 속성이 지정된 메서드가 포함된 객체를 반환합니다:

```php title="rpc.php"
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};
```

`cron.php`에서는 `#[Cron]`를 사용해 같은 방식으로 구현할 수 있습니다:

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};
```

`db.php`에는 이제 간단한 빌더 레이어가 제공됩니다:

```php title="db.php"
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);
```

이 방식은 규모가 큰 코드베이스에 더 적합합니다. 필요할 때는 배열 형식의 간결함을 유지하고, 블록에 필드나 엔드포인트가 몇 개 이상 생기면 더 쉽게 탐색할 수 있는 PHP 인터페이스로 전환할 수 있습니다.

## 이 기능들을 함께 출시한 이유

관리자 개요, 레지스트리 브라우저, 레지스트리 CLI, PHPStan 확장 기능은 모두 같은 질문에 답합니다. Blockstudio 프로젝트가 커져도 어떻게 이해하기 쉽게 유지할 수 있을까요?

관리자 도구는 프로젝트 수준에서 이 질문에 답합니다. 등록된 항목을 확인하고, 레지스트리에서 블록을 가져올 수 있어 추측할 일이 줄어듭니다.

CLI은 생태계 수준에서 답을 제시합니다. 블록을 npm 패키지에 묶거나 빌드 시스템과 씨름하지 않고도 프로젝트와 팀 간에 공유할 방법을 제공합니다.

PHPStan 확장 기능은 코드 수준에서 답을 제시합니다. 잘못된 필드 접근, 스키마 오타, 손상된 훅 콜백을 런타임에 도달하기 전에 감지합니다.

전반적으로 7.2가 나아가는 방향은 추측과 반복을 줄이고, 가시성을 높이며, 실제 타입 안전성을 제공하는 것입니다.

## 버그 수정

- **Classes 필드**: 사용자가 입력한 사용자 지정 클래스 이름이 포커스를 잃을 때 조용히 삭제되었습니다. 검증기가 미리 정의된 Tailwind/설정 목록의 클래스만 허용했기 때문입니다. 이제 비어 있지 않은 문자열은 무엇이든 허용합니다.
- **Attributes 필드**: 속성 쌍을 제거해도 저장된 데이터에 `null` 항목이 남았습니다. 배열 요소를 null 처리하는 lodash `unset()` 대신 항목을 제거하는 `splice()`를 사용하도록 변경했습니다.
- **CSS 축소기**: TailwindPHP 축소기가 `calc()` 및 `clamp()` 안의 `+` 주변 공백을 제거해 `calc(1rem+0.5vw)` 같은 잘못된 CSS을 생성했습니다. 괄호 깊이가 0일 때 선택자 결합자 주변의 공백만 제거하도록 깊이를 인식하는 문자 순회 방식을 사용해 TailwindPHP v1.3.1에서 수정했습니다.
- **Block Inserter 미리보기**: 렌더링 캐시 해시 키에 렌더링 모드가 포함되지 않아 Block Inserter 미리보기에서 `$isPreview`이 항상 `false`였습니다. 이제 편집기와 미리보기 렌더링이 별도의 캐시 항목을 사용합니다.
- **InnerBlocks 중첩 템플릿**: `<InnerBlocks template="..."/>` 구성 요소가 `['core/group', {}, [['core/paragraph']]]` 같은 템플릿 튜플의 세 번째 요소(자식)를 누락해 빈 컨테이너 블록을 생성했습니다. 이제 중첩된 자식을 보존합니다.
