본문으로 건너뛰기

풀스택 블록

Blockstudio를 사용하면 블록 폴더 안에서 완전한 애플리케이션을 만들 수 있습니다. 하나의 디렉터리에 UI, 서버 로직, 데이터 모델, 예약 작업은 물론 데이터 자체까지 담을 수 있습니다.

이 가이드에서는 패턴을 보여 주기 위해 실제 애플리케이션 두 가지를 만듭니다. 사용자별 할 일 앱과 공개 뉴스레터 구독 양식입니다. 파일 구조는 같지만 액세스 모델은 다릅니다.

아래 예제에서는 가장 간결한 배열 구문을 사용하지만, 세 가지 PHP 표면 모두 PHP에 맞는 대안도 제공합니다:

  • db.php는 Blockstudio\\Db\\Schema와 Blockstudio\\Db\\Field를 사용할 수 있습니다.
  • rpc.php는 #[Rpc] 메서드가 포함된 객체를 반환할 수 있습니다.
  • cron.php는 #[Cron] 메서드가 포함된 객체를 반환할 수 있습니다.

할 일 앱

사용자별 작업 관리 앱입니다. 로그인한 사용자는 자신의 할 일만 볼 수 있습니다. 자동 사용자 분리에 userScoped: true, 이동 가능한 저장소에 SQLite, 낙관적 업데이트에 bs.mutate()를 사용하며, 실시간 폴링으로 다른 탭의 변경 사항도 자동으로 표시합니다.

파일 구조

코드
blockstudio/
  todo/
    block.json
    index.php
    script.inline.js
    style.css
    db.php
    rpc.php
    cron.php

블록 정의

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/todo",
  "title": "Todo App",
  "category": "widgets",
  "icon": "editor-ul",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

supports.interactivity는 WordPress의 지시문 처리(data-wp-each, data-wp-bind 등의 SSR)를 활성화합니다. interactivity.enqueue는 프런트엔드에서 @wordpress/interactivity 모듈을 불러옵니다.

데이터 모델

userScoped: true는 user_id 열을 자동으로 추가하고 생성 시 값을 설정하며 모든 쿼리를 현재 사용자로 필터링합니다. realtime를 사용하면 자동 폴링이 활성화되어 페이지를 새로고침하지 않아도 다른 탭이나 기기의 변경 사항이 표시됩니다.

PHP
<?php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'realtime'   => [
        'key'      => 'todos',
        'interval' => 3000,
    ],
    'capability' => [
        'create' => true,
        'read'   => true,
        'update' => true,
        'delete' => true,
    ],
    'fields' => [
        'text' => [
            'type'      => 'string',
            'required'  => true,
            'minLength' => 1,
            'maxLength' => 500,
        ],
        'done' => [
            'type'    => 'boolean',
            'default' => false,
        ],
    ],
];

SQLite 저장소에서는 데이터베이스 파일이 todo/db/default.sqlite에 저장됩니다. 블록 폴더를 다른 사이트에 복사하면 데이터도 함께 이동합니다.

realtime 구성은 가벼운 해시 비교를 사용해 클라이언트가 3초마다 변경 사항을 확인하도록 합니다. 데이터가 바뀌면 state.todos가 업데이트되고 UI가 자동으로 다시 렌더링됩니다.

사용자 지정 서버 로직

userScoped가 현재 사용자에 맞춰 자동으로 필터링하므로 기본 제공 bs.db().list()는 이미 현재 사용자의 레코드만 반환합니다. 토글 및 일괄 삭제처럼 CRUD를 넘어서는 작업에만 RPC가 필요합니다.

PHP
<?php
use Blockstudio\Db;

return [
    'toggle' => [
        'callback' => function (array $params) {
            $id = (int) ($params['id'] ?? 0);

            if (!$id) {
                return new \WP_Error('missing_id', 'ID is required.', ['status' => 400]);
            }

            $db   = Db::get('my-theme/todo');
            $todo = $db->get_record($id);

            if (!$todo) {
                return new \WP_Error('not_found', 'Not found.', ['status' => 404]);
            }

            return $db->update($id, ['done' => !$todo['done']]);
        },
        'public'  => true,
        'methods' => ['POST'],
    ],
    'clear_done' => [
        'callback' => function () {
            $db    = Db::get('my-theme/todo');
            $todos = $db->list();
            $count = 0;

            foreach ($todos as $todo) {
                if (!empty($todo['done'])) {
                    $db->delete((int) $todo['id']);
                    ++$count;
                }
            }

            return ['deleted' => $count];
        },
        'public'  => true,
        'methods' => ['POST'],
    ],
];

예약 정리

완료된 지 오래된 할 일은 자동으로 정리됩니다.

PHP
<?php
use Blockstudio\Db;

return [
    'cleanup_old_todos' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db    = Db::get('my-theme/todo');
            $todos = $db->list();

            foreach ($todos as $todo) {
                $is_done = $todo['done'];
                $is_old  = strtotime($todo['updated_at']) < strtotime('-30 days');

                if ($is_done && $is_old) {
                    $db->delete((int) $todo['id']);
                }
            }
        },
    ],
];

템플릿

PHP는 wp_interactivity_state()를 통해 초기 할 일을 서버 측에서 불러옵니다. 불러온 데이터는 SSR 지시문 처리와 클라이언트 측 하이드레이션에 모두 제공됩니다. 입력 필드 값과 같은 인스턴스별 UI 상태는 data-wp-context에 저장합니다.

PHP
<?php
$db         = \Blockstudio\Db::get('my-theme/todo');
$todos      = $db ? $db->list() : [];
$items_left = count(array_filter($todos, fn($t) => empty($t['done'])));

wp_interactivity_state('my-theme/todo', [
    'todos'     => array_values($todos),
    'hasTodos'  => !empty($todos),
    'hasDone'   => count($todos) !== $items_left,
    'itemsLeft' => $items_left . ($items_left === 1 ? ' item left' : ' items left'),
]);
?>
<div
    data-wp-interactive="my-theme/todo"
    data-wp-context='<?php echo esc_attr(wp_json_encode(['newText' => ''])); ?>'
    useBlockProps
    class="todo-app"
>
    <h2>Todos</h2>

    <div class="todo-input">
        <input
            type="text"
            placeholder="What needs to be done?"
            data-wp-bind--value="context.newText"
            data-wp-on--input="my-theme/todo::actions.updateNewText"
            data-wp-on--keydown="my-theme/todo::actions.handleKeyDown"
        />
        <button
            data-wp-on--click="my-theme/todo::actions.addTodo"
            data-wp-bind--disabled="!state.canAdd"
        >Add</button>
    </div>

    <ul class="todo-list">
        <template data-wp-each--todo="state.todos" data-wp-each-key="context.todo.id">
            <li>
                <label>
                    <input
                        type="checkbox"
                        data-wp-bind--checked="context.todo.done"
                        data-wp-on--change="actions.toggleTodo"
                    />
                    <span
                        data-wp-text="context.todo.text"
                        data-wp-class--done="context.todo.done"
                    ></span>
                </label>
                <button
                    class="todo-delete"
                    data-wp-on--click="actions.deleteTodo"
                >&times;</button>
            </li>
        </template>
    </ul>

    <div class="todo-footer" data-wp-bind--hidden="!state.hasTodos">
        <span data-wp-text="state.itemsLeft"></span>
        <button
            data-wp-on--click="my-theme/todo::actions.clearDone"
            data-wp-bind--hidden="!state.hasDone"
        >Clear done</button>
    </div>
</div>

주요 패턴:

  • 서버에서 가져온 데이터(할 일, 개수)에는 wp_interactivity_state()를 사용합니다.
  • 일시적인 UI 상태(입력 텍스트)에는 data-wp-context를 사용합니다.
  • data-wp-each--todo는 각 반복 항목에 이름이 지정된 컨텍스트(context.todo)를 제공합니다.
  • state.*는 전역 스토어를 참조하고 context.*는 인스턴스별 데이터를 참조합니다.

클라이언트 로직

bs.mutate()는 모든 쓰기 작업을 낙관적 업데이트와 자동 롤백으로 처리합니다. UI는 즉시 업데이트되며, 서버 호출이 거부되면 상태가 되돌아갑니다. 검증 또는 권한 오류가 발생하면 거부되는 대신 오류 본문으로 응답합니다. 자세한 내용은 변경을 참조하세요.

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const { state } = store('my-theme/todo', {
    state: {
        get canAdd() {
            return getContext().newText.trim() !== '';
        },
        get hasTodos() {
            return state.todos.length > 0;
        },
        get hasDone() {
            return state.todos.some(t => t.done);
        },
        get itemsLeft() {
            const count = state.todos.filter(t => !t.done).length;
            return count + (count === 1 ? ' item left' : ' items left');
        },
    },
    actions: {
        updateNewText(event) {
            getContext().newText = event.target.value;
        },
        handleKeyDown(event) {
            if (event.key === 'Enter') {
                event.preventDefault();
                store('my-theme/todo').actions.addTodo();
            }
        },
        *addTodo() {
            const ctx = getContext();
            const text = ctx.newText.trim();
            if (!text) return;
            ctx.newText = '';

            yield bs.mutate({
                fn: () => bs.db('my-theme/todo').create({ text, done: false }),
                state, key: 'todos', action: 'create',
                optimistic: { text, done: false },
            });
        },
        *toggleTodo() {
            const todo = getContext().todo;

            yield bs.mutate({
                fn: () => bs.fn('toggle', { id: todo.id }, 'my-theme/todo'),
                state, key: 'todos', action: 'update', id: todo.id,
                optimistic: { ...todo, done: !todo.done },
            });
        },
        *deleteTodo() {
            const todo = getContext().todo;

            yield bs.mutate({
                fn: () => bs.db('my-theme/todo').delete(todo.id),
                state, key: 'todos', action: 'delete', id: todo.id,
            });
        },
        *clearDone() {
            yield bs.mutate({
                fn: () => bs.fn('clear_done', {}, 'my-theme/todo'),
                before() {
                    const snap = state.todos.slice();
                    state.todos = state.todos.filter(t => !t.done);
                    return snap;
                },
                onError(err, snap) { state.todos = snap; },
                invalidate: 'todos',
            });
        },
    },
});

주요 패턴:

  • bs.mutate() 생성/업데이트/삭제에는 자동 모드를 사용합니다. state, key, action 및 optimistic 데이터를 전달합니다. UI가 즉시 업데이트되고 서버 호출은 백그라운드에서 진행되며 실패하면 상태가 롤백됩니다.
  • bs.mutate() clearDone에는 수동 모드를 사용합니다. before()가 스냅샷을 저장하고 변경 사항을 적용하며 onError()가 스냅샷에서 복원합니다.
  • Interactivity API의 비동기 작업에는 yield를 사용하는 생성기 함수(*addTodo)를 사용합니다.
  • 직접 CRUD에는 bs.db()를, 사용자 지정 서버 함수에는 bs.fn()를 사용합니다.

스타일

CSS
.todo-app {
    max-width: 500px;
    margin: 0 auto;
    font-family: system-ui, sans-serif;
}

.todo-input {
    display: flex;
    gap: 0.5rem;
    margin-bottom: 1rem;
}

.todo-input input {
    flex: 1;
    padding: 0.5rem 0.75rem;
    border: 1px solid #d1d5db;
    border-radius: 0.375rem;
}

.todo-input button {
    padding: 0.5rem 1rem;
    background: #3b82f6;
    color: white;
    border: none;
    border-radius: 0.375rem;
    cursor: pointer;
}

.todo-list {
    list-style: none;
    padding: 0;
}

.todo-list li {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 0.75rem 0;
    border-bottom: 1px solid #f3f4f6;
}

.todo-list label {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    flex: 1;
    cursor: pointer;
}

.todo-list .done {
    text-decoration: line-through;
    color: #9ca3af;
}

.todo-delete {
    background: none;
    border: none;
    color: #ef4444;
    font-size: 1.25rem;
    cursor: pointer;
    opacity: 0;
    transition: opacity 0.15s;
}

.todo-list li:hover .todo-delete {
    opacity: 1;
}

.todo-footer {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 0.75rem 0;
    font-size: 0.875rem;
    color: #6b7280;
}

.todo-footer button {
    background: none;
    border: none;
    color: #6b7280;
    cursor: pointer;
    text-decoration: underline;
}

CLI

셸
wp bs db list my-theme/todo
wp bs db create my-theme/todo --text="Buy milk" --user_id=1
wp bs cron run my-theme/todo cleanup_old_todos
wp bs rpc call my-theme/todo toggle --id=1

뉴스레터 구독

공개 구독 양식입니다. 누구나 구독할 수 있지만 구독자 정보를 보고 관리할 수 있는 사람은 관리자뿐입니다. userScoped가 없으며 주요 작업에 인증이 필요하지 않습니다. 실제 운영 환경에서는 MySQL 테이블 저장소를 사용합니다.

파일 구조

코드
blockstudio/
  newsletter/
    block.json
    index.php
    style.css
    script.inline.js
    db.php
    rpc.php
    cron.php

블록 정의

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/newsletter",
  "title": "Newsletter Signup",
  "category": "widgets",
  "icon": "email",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

데이터 모델

CSRF 보호 기능이 적용된 공개 생성 방식입니다. 사용자 지정 유효성 검사로 일회용 이메일 주소를 차단합니다. 읽기 및 삭제는 관리자만 할 수 있습니다.

PHP
<?php
return [
    'storage'    => 'table',
    'capability' => [
        'create' => true,
        'read'   => 'manage_options',
        'update' => 'manage_options',
        'delete' => 'manage_options',
    ],
    'fields' => [
        'email' => [
            'type'     => 'string',
            'format'   => 'email',
            'required' => true,
            'validate' => function ($value) {
                $blocked = ['mailinator.com', 'tempmail.com', 'throwaway.email'];
                $domain  = substr($value, strpos($value, '@') + 1);
                if (in_array($domain, $blocked, true)) {
                    return 'Please use a permanent email address.';
                }
                return true;
            },
        ],
        'name' => [
            'type'      => 'string',
            'maxLength' => 100,
        ],
        'status' => [
            'type'    => 'string',
            'enum'    => ['active', 'unsubscribed'],
            'default' => 'active',
        ],
    ],
    'hooks' => [
        'after_create' => function ($params) {
            $name = $params['record']['name'];
            wp_mail(
                $params['record']['email'],
                'Welcome!',
                'Thanks for subscribing' . ($name ? ", $name" : '') . '.'
            );
        },
    ],
];

사용자 지정 로직

로그인 없이 이메일 링크에서 사용할 수 있는 공개 구독 취소 엔드포인트와 관리자 전용 통계를 제공합니다:

PHP
<?php
use Blockstudio\Db;

return [
    'unsubscribe' => [
        'callback' => function (array $params): array {
            $email = sanitize_email($params['email'] ?? '');
            $db    = Db::get('my-theme/newsletter');
            $subs  = $db->list(['email' => $email]);

            if (empty($subs)) {
                return ['error' => 'Email not found.'];
            }

            $db->update((int) $subs[0]['id'], ['status' => 'unsubscribed']);

            return ['success' => true];
        },
        'public' => true,
    ],
    'stats' => [
        'callback'   => function (array $params): array {
            $db = Db::get('my-theme/newsletter');
            return [
                'total'  => count($db->list()),
                'active' => count($db->list(['status' => 'active'])),
            ];
        },
        'capability' => 'manage_options',
    ],
];

예약 정리

PHP
<?php
use Blockstudio\Db;

return [
    'cleanup' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db    = Db::get('my-theme/newsletter');
            $unsub = $db->list(['status' => 'unsubscribed']);

            foreach ($unsub as $row) {
                if (strtotime($row['updated_at']) < strtotime('-90 days')) {
                    $db->delete((int) $row['id']);
                }
            }
        },
    ],
];

템플릿

PHP
<?php
wp_interactivity_state('my-theme/newsletter', [
    'submitted' => false,
]);
?>
<div
    data-wp-interactive="my-theme/newsletter"
    data-wp-context='<?php echo esc_attr(wp_json_encode([
        'email'   => '',
        'name'    => '',
        'loading' => false,
        'error'   => '',
    ])); ?>'
    useBlockProps
    class="newsletter"
>
    <div data-wp-bind--hidden="state.submitted">
        <h3>Stay in the loop</h3>
        <div class="newsletter-form">
            <input
                type="text"
                placeholder="Name (optional)"
                data-wp-bind--value="context.name"
                data-wp-on--input="actions.setName"
            />
            <input
                type="email"
                placeholder="Email address"
                data-wp-bind--value="context.email"
                data-wp-on--input="actions.setEmail"
                data-wp-on--keydown="actions.handleKeydown"
            />
            <button
                data-wp-on--click="actions.subscribe"
                data-wp-bind--disabled="context.loading"
            >
                <span data-wp-text="context.loading ? 'Subscribing...' : 'Subscribe'"></span>
            </button>
        </div>
        <p data-wp-bind--hidden="!context.error" class="newsletter-error" data-wp-text="context.error"></p>
    </div>
    <div data-wp-bind--hidden="!state.submitted">
        <p class="newsletter-success">You're in! Check your email.</p>
    </div>
</div>

클라이언트 로직

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const { state } = store('my-theme/newsletter', {
    actions: {
        setName(event) {
            getContext().name = event.target.value;
        },
        setEmail(event) {
            getContext().email = event.target.value;
        },
        handleKeydown(event) {
            if (event.key === 'Enter') {
                store('my-theme/newsletter').actions.subscribe();
            }
        },
        *subscribe() {
            const ctx = getContext();
            const email = ctx.email.trim();
            if (!email) return;

            ctx.loading = true;
            ctx.error = '';

            const result = yield bs.db('my-theme/newsletter').create({
                email,
                name: ctx.name.trim(),
            });

            if (result.data?.errors) {
                ctx.error = Object.values(result.data.errors)[0][0];
                ctx.loading = false;
                return;
            }

            if (result.code) {
                ctx.error = result.message || 'Something went wrong.';
                ctx.loading = false;
                return;
            }

            state.submitted = true;
            ctx.loading = false;
        },
    },
});

스타일

CSS
.newsletter {
    max-width: 480px;
    margin: 0 auto;
    padding: 2rem;
    text-align: center;
}

.newsletter h3 {
    margin: 0 0 1rem;
}

.newsletter-form {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
}

.newsletter-form input {
    padding: 0.625rem 0.75rem;
    border: 1px solid #d1d5db;
    border-radius: 0.375rem;
    font-size: 1rem;
}

.newsletter-form button {
    padding: 0.625rem 1rem;
    background: #3b82f6;
    color: white;
    border: none;
    border-radius: 0.375rem;
    font-size: 1rem;
    cursor: pointer;
}

.newsletter-form button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
}

.newsletter-error {
    color: #ef4444;
    font-size: 0.875rem;
    margin: 0.5rem 0 0;
}

.newsletter-success {
    color: #10b981;
    font-size: 1.125rem;
}

CLI

셸
wp bs db list my-theme/newsletter --format=table
wp bs rpc call my-theme/newsletter stats
wp bs rpc call my-theme/newsletter unsubscribe --email=user@example.com
wp bs cron run my-theme/newsletter cleanup

나란히 비교

항목 할 일 앱 뉴스레터
인증 모델 userScoped: true 공개 생성, 관리자 읽기
저장소 SQLite (이동 가능) MySQL 테이블 (실제 운영 환경)
사용자 필터링 자동 필요 없음
CSRF X-BS-Token를 통해 X-BS-Token를 통해
사용자 지정 RPC 완료 상태 전환, 완료 항목 지우기 구독 취소, 통계
Cron 오래된 완료 항목 삭제 구독 취소자 제거
유효성 검사 길이 제한 이메일 형식 및 도메인 차단
실시간 업데이트 3초 폴링 필요 없음
낙관적 UI bs.mutate() 자동 모드 직접 bs.db().create()
상태 wp_interactivity_state() wp_interactivity_state() + 컨텍스트

패턴은 같고 액세스 모델은 다릅니다. 구성 요소는 동일합니다: 데이터 모델용 db.php, 비즈니스 로직용 rpc.php, 백그라운드 작업용 cron.php, UI용 index.php + script.inline.js, 그리고 모양을 위한 style.css입니다. 각 블록은 독립적으로 작동하는 애플리케이션입니다.