본문으로 건너뛰기

데이터베이스

데이터베이스 계층에서는 db.php 파일에 블록의 데이터 모델을 정의할 수 있습니다. Blockstudio는 REST CRUD 엔드포인트를 생성하고, 스키마에 따라 입력을 검증하며, 저장소를 자동으로 관리하고, JavaScript 클라이언트(bs.db())와 PHP API(Db 클래스)를 모두 제공합니다.

이는 풀스택 블록의 데이터 기반입니다. RPC에서 사용자 지정 로직을 처리한다면, 데이터베이스 계층은 상용구 코드 없이 구조화된 데이터를 처리합니다.

작동 방식

  1. 블록 디렉터리에 db.php를 만듭니다
  2. 필드, 유형, 유효성 검사 규칙, 액세스 제어가 포함된 스키마가 반환됩니다
  3. Blockstudio가 저장소(테이블, 파일 또는 게시물 메타)를 생성합니다
  4. REST 엔드포인트 5개(목록, 조회, 생성, 업데이트, 삭제)가 자동으로 생성됩니다
  5. bs.db() 및 Db::get()에서 클라이언트 및 서버 액세스를 제공합니다

마이그레이션도, 컨트롤러도, 경로 등록도 필요하지 않습니다.

REST 및 PHP API에는 리터럴 값을 전달하세요. meta 및 post_type 백엔드는 WordPress 메타 슬래시 처리를 내부적으로 수행하므로, 스칼라 값과 중첩된 객체 또는 배열에서 백슬래시와 따옴표로 묶인 문자열이 그대로 유지됩니다. 데이터베이스 레코드 값에 미리 슬래시를 추가하지 마세요.

스키마 정의

단일 스키마

가장 간단한 형식으로, 블록당 데이터 모델 하나를 사용합니다.

PHP
return [
    'storage'    => 'table',
    'capability' => [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    'fields' => [
        'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
        'name'  => ['type' => 'string', 'maxLength' => 100],
        'plan'  => ['type' => 'string', 'enum' => ['free', 'pro'], 'default' => 'free'],
    ],
];

PHP 네이티브 빌더 구문

db.php에서는 명명된 인수와 읽기 전용 정의 객체를 기반으로 하는 간단한 빌더 API도 사용할 수 있습니다. 배열이 기본 형식으로 유지되지만, 스키마가 커지기 시작할 때 더 쉽게 찾아 쓸 수 있는 PHP 네이티브 옵션을 제공합니다.

PHP
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    capability: [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'name'  => Field::string(maxLength: 100),
        'plan'  => Field::string(enum: ['free', 'pro'], default: 'free'),
    ],
);

단일 스키마에는 Schema::make()을 사용하고, 여러 스키마를 사용하는 블록에는 이름이 지정된 Schema::make(...) 호출의 배열을 반환하세요.

여러 스키마

블록 하나에 여러 데이터 모델을 둘 수 있습니다. 이름이 지정된 배열을 반환하세요:

PHP
return [
    'subscribers' => [
        'storage' => 'table',
        'fields'  => [
            'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
            'plan'  => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
    'activity_log' => [
        'storage' => 'jsonc',
        'fields'  => [
            'action'  => ['type' => 'string', 'required' => true],
            'details' => ['type' => 'string'],
        ],
    ],
];

각 스키마에는 자체 엔드포인트, 저장소, 액세스 제어가 지정됩니다.

저장소 모드

여섯 가지 저장소 백엔드가 있으며, 각각 용도가 다릅니다.

사용자 지정 테이블 (storage: "table")

각 레코드는 전용 MySQL 테이블의 행으로 저장됩니다. Blockstudio는 WordPress의 dbDelta() 함수를 사용해 테이블을 자동으로 생성하고 관리합니다. 스키마에 필드를 추가하면 다음 페이지 로드 시 열이 추가됩니다. 기존 열은 삭제되지 않습니다.

적합한 용도: 구조화된 데이터, 쿼리, 프로덕션 애플리케이션.

SQLite (storage: "sqlite")

각 스키마에는 db/ 하위 폴더에 자체 SQLite 데이터베이스 파일이 만들어집니다. Blockstudio는 파일과 테이블을 자동으로 생성하고, 스키마가 변경되면 누락된 열을 추가합니다(MySQL용 dbDelta과 유사). 동시 읽기 성능을 위해 WAL 저널 모드를 사용합니다.

코드
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

적합한 용도: 실제 SQL 쿼리가 필요하지만 이식성을 유지해야 하는 구조화된 데이터. 모든 데이터를 메모리에 올리지 않고도 수천 개의 레코드를 효율적으로 처리합니다. 폴더를 복사해 데이터를 옮길 수 있습니다.

JSONC 파일 (storage: "jsonc")

레코드는 db/ 하위 폴더의 .jsonc 파일에 한 줄당 JSON 객체 하나씩 저장됩니다. 파일은 처음 쓸 때 자동으로 생성됩니다. //로 시작하는 줄은 주석으로 처리되어 보존됩니다.

코드
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

적합한 용도: 소규모 데이터 세트, 설정과 유사한 데이터, 초기 레코드, 버전 관리가 가능한 예시입니다. JSONC는 블록 폴더에 단일 파일로 저장하도록 설계되었습니다. 데이터가 코드와 함께 이동해야 할 때 사용하고, 동시 쓰기가 많을 것으로 예상될 때는 사용하지 마세요.

Storh 파일 (storage: "storh")

Storh는 각 레코드를 WordPress uploads 아래의 개별 파일로 저장합니다:

코드
wp-content/uploads/blockstudio/db/
└── my-theme-my-block/
    └── subscribers/
        ├── data/
        │   └── 00/
        │       ├── 00000000-0000-7000-8000-000000000001.jsonc
        │       └── 00000000-0000-7000-8000-000000000002.jsonc
        ├── .storh/
        │   └── indexes/
        └── .blockstudio/
            └── sequence.json

공개 레코드 ID는 나머지 bs.db()에서 사용하는 것과 동일한 정수 ID로 유지됩니다. Blockstudio는 해당 ID를 Storh의 내부 UUIDv7 파일 ID에 매핑하고, 정수 id를 레코드 데이터에 저장하므로 JavaScript, REST, PHP 호출자는 UUID를 처리할 필요가 없습니다.

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Blockstudio는 스키마에서 Storh 인덱스를 생성합니다. 선언된 모든 필드를 목록 필터로 사용할 수 있으므로 모든 필드에 인덱스가 생성됩니다. 정수, 숫자, 날짜형 필드에는 범위 인덱스가 사용되고, 'unique' => true 또는 'index' => 'unique'으로 표시된 필드에는 고유 인덱스가 사용됩니다.

적합한 용도: 더 안전한 동시 쓰기, 스키마에서 파생된 인덱스, 라이브 레코드를 블록 소스 트리에 커밋하지 않는 이식 가능한 uploads 수준의 저장소가 필요한 파일 기반 프로덕션 데이터입니다.

JSONC에서 Storh(으)로 마이그레이션

.jsonc 파일로 시작했고 동일한 레코드를 Storh에 저장하려면 다음 명령을 실행하세요:

셸
wp bs db migrate my-theme/app subscribers --to=storh

단일 스키마 블록의 경우:

셸
wp bs db migrate my-theme/app --to=storh

마이그레이션은 기존 db/{schema}.jsonc를 읽고 정수 ID를 유지하면서 레코드를 Storh에 씁니다. 대상 저장소의 인덱스를 다시 만들고 확인하며 JSONC 파일은 그대로 둡니다. 롤백하려면 스키마의 storage를 다시 "jsonc"로 변경하면 됩니다.

게시물 메타 (storage: "meta")

레코드는 WordPress 게시물 메타의 JSON 배열로 저장되며, postId를 통해 특정 게시물에 연결됩니다.

PHP
return [
    'storage' => 'meta',
    'postId'  => 42,
    'fields'  => [ /* ... */ ],
];

적합한 용도: 특정 글이나 페이지에 속하는 데이터.

사용자 지정 게시물 유형 (storage: "post_type")

각 레코드는 자동으로 등록되는 사용자 지정 게시물 유형의 WordPress 게시물이며, 스키마의 각 필드는 별도의 post_meta 항목이 됩니다. 따라서 WP_Query로 레코드를 쿼리할 수 있고, REST API 플러그인과 호환되며, GraphQL 같은 도구에도 표시됩니다.

적합한 용도: WordPress와 기본적으로 통합되어야 하는 데이터. 각 필드를 개별적으로 쿼리하고 색인화할 수 있습니다.

JavaScript 클라이언트

Blockstudio는 데이터베이스 블록이 있는 페이지에 bs.db()를 삽입합니다. 다섯 가지 메서드가 있는 객체를 반환합니다:

JavaScript
const db = bs.db('my-theme/block', 'subscribers');

// Create a record
const record = await db.create({ email: 'a@b.com', plan: 'pro' });

// List all records (with optional filters)
const all = await db.list();
const pros = await db.list({ plan: 'pro', limit: 10, offset: 0 });

// Get a single record
const one = await db.get(record.id);

// Update specific fields
const updated = await db.update(record.id, { plan: 'enterprise' });

// Delete a record
await db.delete(record.id);

첫 번째 인수는 블록 이름(/ 포함)이고, 두 번째 인수는 스키마 이름입니다. 단일 스키마 블록에서는 스키마 이름을 생략할 수 있으며, 기본값은 "default"입니다.

캐시

bs.cache는 모든 bs.query 및 bs.mutate 호출에서 공유하는 메모리 내 쿼리 캐시입니다. 직접 사용할 수도 있습니다:

JavaScript
// Read a cached value
const data = bs.cache.get('my-key');

// Write to the cache
bs.cache.set('my-key', { items: [...] });

// Invalidate a single key
bs.cache.invalidate('my-key');

// Clear all cached entries
bs.cache.clear();

캐시 항목은 메모리에 저장되며 페이지 이동 시 지워집니다. 주로 bs.query 및 bs.mutate에서 내부적으로 사용하지만, 데이터를 미리 채우거나 사용자 지정 작업 후 수동으로 무효화할 때 직접 액세스하면 유용합니다.

쿼리

bs.query()는 모든 비동기 함수를 캐싱, 중복 제거, 오래된 데이터 제어 기능으로 감쌉니다. 요청이 진행 중일 때 동일한 키로 여러 번 호출하면 같은 프라미스를 반환하므로 중복으로 가져오지 않습니다.

JavaScript
// Basic cached fetch
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list()
);

// With staleTime: skip the fetch if cached data is younger than 30 seconds
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list(),
  { staleTime: 30000 }
);

첫 번째 인수는 캐시 키(모든 문자열 가능)입니다. 두 번째는 프라미스를 반환하는 함수이며, 세 번째는 선택적 옵션 객체입니다:

옵션 유형 설명
staleTime number 캐시된 데이터가 오래된 것으로 간주되기까지의 시간(밀리초)입니다. 0(기본값)은 항상 다시 가져옵니다.

캐시에 해당 키의 데이터가 있고 그 데이터가 staleTime보다 오래되지 않았다면 함수를 호출하지 않고 캐시된 값을 즉시 반환합니다.

변경

bs.mutate()는 낙관적 업데이트와 실패 시 자동 롤백으로 쓰기 작업을 처리합니다. 일반적인 CRUD 패턴에 맞춘 자동 모드와 모든 작업을 직접 제어하는 수동 모드를 제공합니다.

자동 모드는 반응형 상태 객체(예: Alpine.js $data)와 함께 작동합니다. state, key, action와 필요한 경우 optimistic를 전달하세요:

JavaScript
// Optimistic create: item appears instantly, gets real ID on success
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'create',
  optimistic: { text: 'New todo', done: false },
  fn: () =>
    bs.db('my-theme/app', 'todos').create({ text: 'New todo', done: false }),
});

// Optimistic update: field changes instantly, reverts on failure
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'update',
  id: todoId,
  optimistic: { done: true },
  fn: () => bs.db('my-theme/app', 'todos').update(todoId, { done: true }),
});

// Delete: item removed from the array immediately
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => bs.db('my-theme/app', 'todos').delete(todoId),
});

성공하면 낙관적으로 적용한 데이터가 서버 응답으로 대체됩니다. 실패하면 변경 전에 저장한 스냅샷으로 상태를 되돌립니다. 성공적으로 변경할 때마다 캐시 키가 자동으로 무효화됩니다.

fn이 반환한 프라미스가 거부되면 실패로 간주합니다. 유효성 검사 오류, 레코드 누락 또는 권한 확인 실패 시 bs.db() 및 bs.fn()는 오류 본문과 함께 정상적으로 완료되므로, 이런 경우에도 롤백하려면 결과에 code가 있을 때 예외를 발생시키세요:

JavaScript
const ok = (request) =>
  request.then((result) => {
    if (result?.code) {
      throw result;
    }
    return result;
  });

await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => ok(bs.db('my-theme/app', 'todos').delete(todoId)),
});

생성 작업에서는 임시 id(예: __temp_1)가 낙관적으로 추가한 항목에 할당됩니다. 서버가 응답하면 서버에서 할당한 실제 id를 포함해 임시 항목이 실제 데이터로 갱신됩니다.

수동 모드에서는 before, onSuccess, onError 콜백으로 모든 작업을 직접 제어할 수 있습니다:

JavaScript
await bs.mutate({
  fn: () => bs.db('my-theme/app', 'todos').create({ text: 'New' }),
  invalidate: 'todos',
  before: () => {
    // Take a snapshot, return it for use in onError
    const snapshot = [...$data.todos];
    $data.todos.push({ id: '__temp', text: 'New' });
    return snapshot;
  },
  onSuccess: (result, snapshot) => {
    // Replace temp item with server response
  },
  onError: (error, snapshot) => {
    // Restore from snapshot
    $data.todos = snapshot;
  },
});
옵션 유형 모드 설명
fn function Both 변경을 수행하는 비동기 함수입니다. 필수 항목입니다.
state object Auto 반응형 상태 객체(e.g., Alpine $data)입니다.
key string Auto 배열을 보유한 상태의 속성 이름입니다. 캐시 키로도 사용됩니다.
action string Auto create, update 또는 delete 중 하나입니다.
id any Auto update 및 delete 작업의 레코드 ID입니다.
optimistic object Auto 서버 응답 전에 낙관적으로 적용할 데이터입니다.
before function Manual fn 전에 호출됩니다. 반환값은 snapshot로 onSuccess/onError에 전달됩니다.
onSuccess function Manual 성공 시 (result, snapshot)와 함께 호출됩니다.
onError function Manual 실패 시 (error, snapshot)와 함께 호출됩니다.
invalidate string Manual 성공 시 무효화할 캐시 키입니다.

PHP API

Db 클래스는 서버 측에서도 동일한 작업을 제공합니다. rpc.php, cron.php, 템플릿 또는 모든 PHP 코드에서 사용하세요.

PHP
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');

// Create
$record = $db->create(['email' => 'a@b.com', 'plan' => 'pro']);

// List with filters
$all  = $db->list();
$pros = $db->list(['plan' => 'pro'], limit: 10, offset: 0);

// Count and paginate
$count = $db->count(['plan' => 'pro']);
$page  = $db->paginate(['plan' => 'pro'], limit: 10, offset: 20);

// Get by ID
$one = $db->get_record(1);

// Update
$db->update(1, ['plan' => 'enterprise']);

// Delete
$db->delete(1);

단일 스키마 블록의 경우:

PHP
$db = Db::get('my-theme/block');

실시간 폴링

스키마에 realtime을 추가하면 자동 폴링을 사용할 수 있습니다. 서버의 데이터가 변경되면 Interactivity API 저장소를 통해 UI가 자동으로 업데이트됩니다. JavaScript는 변경할 필요가 없습니다.

PHP
return [
    'storage'  => 'table',
    'realtime' => true,
    'fields'   => [ /* ... */ ],
];

true를 사용하면 Blockstudio는 3초마다 스키마 이름을 Interactivity API 상태 키로 사용해 폴링합니다(단일 스키마 블록에서는 default).

사용자 지정 구성

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
옵션 유형 기본값 설명
key string 스키마 이름 데이터 배열을 보유한 state의 속성 이름
interval number 3000 폴링 간격(밀리초)

작동 방식

  1. 페이지가 로드되면 클라이언트가 현재 데이터의 경량 해시를 가져옵니다
  2. interval밀리초마다 해시를 다시 가져옵니다
  3. 해시가 변경되면 전체 데이터 세트를 가져옵니다
  4. 새 데이터가 store()를 통해 Interactivity API 저장소로 전달됩니다
  5. 해당 상태 속성에 바인딩된 지시문이 자동으로 다시 렌더링됩니다

일치하는 data-wp-interactive 요소가 있는 페이지에서만 폴링이 실행됩니다. 브라우저 탭이 숨겨지면 일시 중지되고 다시 표시되면 재개됩니다.

해시 엔드포인트(?_hash=1)는 md5 체크섬과 레코드 수만 반환해 폴링 요청의 데이터 크기를 줄입니다.

사용자 범위 데이터

userScoped: true를 설정하면 모든 레코드가 자동으로 현재 사용자에게 한정됩니다. Blockstudio는 user_id 열을 추가하고 생성 시 값을 설정하며, 모든 작업을 현재 사용자의 레코드만 대상으로 제한합니다:

PHP
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [
        'text' => ['type' => 'string', 'required' => true],
        'done' => ['type' => 'boolean', 'default' => false],
    ],
];

수동 user_id 필드도, before_create 훅도, RPC에서의 필터링도 필요하지 않습니다. 사용자는 자신의 레코드만 조회, 수정, 삭제할 수 있습니다. user_id 열은 Blockstudio에서 전적으로 관리합니다.

post_type 저장소를 사용하면 userScoped는 별도의 user_id 열 대신 post_author에 매핑됩니다.

액세스 제어

각 CRUD 작업에는 고유한 권한 수준이 있습니다:

값 동작
true CSRF 보호가 적용된 공개 액세스(로그아웃 사용자 허용, X-BS-Token 필수)
'open' 완전 공개, CSRF 및 인증 없음(웹훅과 외부 API용)
'edit_posts' WordPress 권한 확인
['cap_a', 'cap_b'] 사용자에게 목록에 있는 권한 중 하나 이상이 필요합니다
생략 / null 인증 필요(로그인한 사용자)
PHP
'capability' => [
    'create' => true,                               // public + CSRF protected
    'read'   => 'open',                             // truly open, no protection
    'update' => 'edit_posts',                       // editors and above
    'delete' => ['delete_posts', 'manage_options'], // either capability works
],

CSRF 보호

공개 엔드포인트(true)는 X-BS-Token 헤더로 보호됩니다. bs.db()와 bs.fn()는 만료되는 토큰을 페이지 HTML에 삽입하는 대신, 캐시되지 않은 동일 출처 엔드포인트에서 새 인증 정보를 가져옵니다. 장기간 유지되는 외부 캐시에서 제공되는 페이지도 계속 작동합니다. 유효한 토큰 없이 익명으로 호출하면 403 응답이 반환됩니다.

인증 정보는 페이지를 볼 때마다가 아니라 첫 번째 API 호출 시 요청됩니다. 데이터베이스 실시간 폴링을 포함한 두 클라이언트는 진행 중인 인증 정보 갱신 요청 하나를 공유합니다. 인증 정보는 5분간 사용한 후 갱신됩니다. 거부된 WordPress nonce 또는 Blockstudio CSRF 토큰은 한 번 갱신한 뒤 재시도합니다. 일반 권한 오류는 재시도하지 않습니다. 로그인한 요청에는 방문자 사용자의 세션과 스키마의 기능 및 레코드 소유권 검사가 계속 적용됩니다.

POST /wp-json/blockstudio/v1/client/credentials를 프록시 또는 CDN 캐시에서 제외하세요. Cache-Control: private, no-store를 전송하며, 단순 헤더가 아닌 헤더를 사용하는 동일 출처 요청이 필요합니다. 내장 클라이언트가 이를 자동으로 처리합니다.

외부 서비스의 수신 웹훅처럼 인증 없이 완전히 공개된 액세스가 필요한 경우 'open'을 사용하세요.

필드 유형

유형 MySQL 열 PHP 유형 설명
string varchar(maxLength) string 텍스트, 기본 maxLength 255
integer bigint(20) int 정수
number decimal(20,6) float 소수
boolean tinyint(1) bool 참/거짓
text longtext string 긴 텍스트 콘텐츠

유효성 검사

모든 쓰기 작업(생성 및 업데이트)은 저장소에 반영되기 전에 스키마에 따라 검증됩니다. 요청이 bs.db(), REST API, Db::get() 중 어디에서 오든 서버 측에서 유효성을 검사합니다.

기본 제공 규칙

규칙 예시 설명
required 'required' => true 생성 시 필드가 있어야 합니다
type 'type' => 'integer' 값이 선언된 유형과 일치해야 합니다
enum 'enum' => ['a', 'b'] 값은 목록에 있는 옵션 중 하나여야 합니다
maxLength 'maxLength' => 100 문자열은 이 길이를 초과할 수 없습니다
minLength 'minLength' => 3 문자열은 최소한 이 길이여야 합니다
format: "email" 'format' => 'email' 유효한 이메일 주소여야 합니다
format: "url" 'format' => 'url' 유효한 URL여야 합니다

사용자 지정 유효성 검사

기본 제공 규칙으로 처리할 수 없는 서버 측 검사를 위해 각 필드에 validate 콜백을 추가하세요. 통과하려면 true를 반환하고, 오류 메시지가 있으면 문자열을 반환합니다:

PHP
'email' => [
    'type'     => 'string',
    'format'   => 'email',
    'required' => true,
    'validate' => function ($value, $data) {
        if (str_ends_with($value, '@disposable.com')) {
            return 'Disposable email addresses are not allowed.';
        }
        return true;
    },
],

콜백에는 필드 값과 전체 데이터 배열이 전달되므로 필드 간 유효성 검사도 수행할 수 있습니다.

오류 응답 형식

유효성 검사 오류는 필드별 오류 배열이 포함된 400 상태를 반환합니다. 이 형식은 Zod의 fieldErrors에서 영감을 얻었으며, 오류를 양식 필드에 쉽게 연결할 수 있습니다:

JSON
{
  "code": "blockstudio_db_validation",
  "message": "Validation failed.",
  "data": {
    "status": 400,
    "errors": {
      "email": [
        "Must be a valid email address.",
        "Disposable email addresses are not allowed."
      ],
      "plan": ["Must be one of: free, pro."]
    }
  }
}

각 필드에는 오류 문자열 배열이 연결됩니다. 같은 필드에서 여러 규칙이 실패할 수 있습니다. 프런트엔드에서는 다음과 같이 처리합니다:

JavaScript
const result = await db.create({ email: 'bad', plan: 'invalid' });

if (result.data?.errors) {
  // { email: ["Must be a valid email address."], plan: ["Must be one of: free, pro."] }
  Object.entries(result.data.errors).forEach(([field, messages]) => {
    showFieldError(field, messages[0]);
  });
}

REST 엔드포인트

모든 엔드포인트는 blockstudio/v1/db/ 네임스페이스 아래에 있습니다:

코드
/db/{block-name}/{schema-name}

블록 이름에서 /는 -로 대체됩니다. 단일 스키마 블록에서 스키마 이름은 default입니다.

메서드 엔드포인트 설명
GET /db/{block}/{schema} 레코드 목록 조회
POST /db/{block}/{schema} 레코드 생성
GET /db/{block}/{schema}/{id} 단일 레코드 조회
PUT /db/{block}/{schema}/{id} 레코드 업데이트
DELETE /db/{block}/{schema}/{id} 레코드 삭제

쿼리 매개변수(목록)

매개변수 설명
limit 반환할 최대 레코드 수(기본값 50, 최대 100)
offset 건너뛸 레코드 수
필드 이름 정확히 일치하는 값으로 필터링

예시: GET /db/my-theme-app/subscribers?plan=pro&limit=10

폼 렌더링

필드에 Blockstudio 블록을 참조하는 component 키를 정의할 수 있습니다. 템플릿에서 bs_db_form()을 호출하면 각 필드를 해당 컴포넌트 블록으로 폼에 렌더링합니다.

PHP
'fields' => [
    'email' => [
        'type'     => 'string',
        'format'   => 'email',
        'required' => true,
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Email', 'type' => 'email'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/input',
                    'attributes' => ['placeholder' => 'Enter your email'],
                ],
            ],
        ],
    ],
    'plan' => [
        'type' => 'string',
        'enum' => ['free', 'pro'],
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Plan'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/select',
                    'attributes' => ['options' => ['free', 'pro']],
                ],
            ],
        ],
    ],
],
PHP
<form>
  <?php bs_db_form('my-theme/app', 'subscribers'); ?>
  <button type="submit">Subscribe</button>
</form>

각 컴포넌트는 전체 필드 정의를 속성의 field로 받으므로, 스키마에 따라 렌더링 방식을 조정할 수 있습니다. 예를 들어 $a['field']['name']은 필드 이름을, $a['field']['type']는 유형을, $a['field']['required']는 필수 여부를 나타내는 식입니다.

컴포넌트 구조는 WordPress 블록과 동일한 name, attributes, innerBlocks 형식을 따릅니다. 내부 블록이 먼저 렌더링되고 $content로 부모에 전달됩니다.

에코 출력 없이 PHP을 사용하려면:

PHP
use Blockstudio\Db;

$db   = Db::get('my-theme/app', 'subscribers');
$html = $db->form();

훅

액션은 모든 쓰기 작업 전후에 실행됩니다. 모든 훅은 단일 $params 배열을 받습니다. 전체 목록은 PHP 훅 참조 문서를 확인하세요.

인라인 훅

훅을 db.php에 직접 정의하세요. 해당 스키마에 자동으로 범위가 지정되므로 블록/스키마 이름을 확인할 필요가 없습니다.

PHP
return [
    'storage' => 'table',
    'fields'  => [ /* ... */ ],
    'hooks' => [
        'after_create' => function ($params) {
            // $params['record'] is the created record
            wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
        },
        'before_delete' => function ($params) {
            // $params['id'] is the record being deleted
            error_log('Deleting subscriber ' . $params['id']);
        },
    ],
];

전역 훅

어디서든 모든 스키마의 변경을 감지할 수 있습니다:

PHP
add_action('blockstudio/db/after_create', function ($params) {
    // $params['block'] and $params['schema'] identify the source
    if ('my-theme/app' === $params['block'] && 'subscribers' === $params['schema']) {
        // sync to external CRM
    }
});

RPC와 함께 사용하기

db.php와 rpc.php는 서로 독립적인 시스템입니다. db.php는 스키마 정의에서 CRUD 엔드포인트를 생성합니다. rpc.php는 사용자 지정 서버 함수를 정의합니다. 각각 단독으로 사용할 수 있습니다.

표준 데이터 작업과 사용자 지정 비즈니스 로직이 모두 필요할 때 함께 사용하세요:

PHP
use Blockstudio\Db;

return [
    'export' => [
        'callback'   => function (array $params): array {
            $db   = Db::get('my-theme/app', 'subscribers');
            $rows = $db->list(['plan' => 'pro']);
            // custom CSV generation, email sending, etc.
            return ['exported' => count($rows)];
        },
        'capability' => 'manage_options',
    ],
];

이식성

JSONC 저장소를 사용하면 데이터가 코드와 함께 저장됩니다. 블록 폴더를 다른 사이트로 복사하면 UI, 로직, 접근 제어, 데이터까지 모두 함께 옮겨집니다.

코드
my-app/
├── block.json
├── index.twig
├── style.css
├── rpc.php        ← custom endpoints
├── db.php         ← data schema
├── cron.php       ← scheduled tasks
└── db/
    └── entries.jsonc  ← the actual data

데이터베이스 마이그레이션이나 내보내기/가져오기 과정이 필요 없습니다. 폴더만 복사하면 됩니다.

Storh 저장소도 이식할 수 있지만, 블록 폴더가 아닌 uploads/blockstudio/db/ 아래에 저장됩니다. 따라서 변경 가능한 운영 데이터는 소스 트리 밖에 두면서도 각 스키마에 일반 파일 저장소를 제공하므로, 별도로 백업하거나 복사하거나 마이그레이션할 수 있습니다.

필터

블록 외부에서 프로그래밍 방식으로 스키마를 수정합니다:

PHP
add_filter('blockstudio/database', function (array $schemas): array {
    // Add a field to an existing schema
    $schemas['my-theme/app:subscribers']['fields']['source'] = [
        'type'    => 'string',
        'default' => 'website',
    ];
    return $schemas;
});