본문으로 건너뛰기

Dennis · 2026년 4월 10일

Blockstudio 7.2

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
{
  "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 패키지도, 빌드 단계도 필요 없습니다. 명령을 실행하면 블록 소스 코드가 프로젝트에 복사되고, 모든 것을 직접 소유하고 관리할 수 있습니다.

셸
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에서 확인할 수 있습니다.

PHPStan 확장 기능

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

셸
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
<?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
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
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}

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

PHP 네이티브 블록 API 정의

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

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

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
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

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

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

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']]] 같은 템플릿 튜플의 세 번째 요소(자식)를 누락해 빈 컨테이너 블록을 생성했습니다. 이제 중첩된 자식을 보존합니다.