フルスタックブロック
Blockstudioを使うと、ブロックフォルダー内に完全なアプリケーションを構築できます。1つのディレクトリにUI、サーバーロジック、データモデル、スケジュールされたタスク、さらにはデータそのものまで含められます。
このガイドでは、パターンを紹介するために、ユーザーごとのToDoアプリと公開ニュースレター登録フォームという、2つの実際のアプリケーションを構築します。同じファイル構成で、アクセスモデルは異なります。
以下の例では、最も簡潔な配列構文を使いますが、3つのPHP領域にはそれぞれPHPネイティブの代替手段もあります。
db.phpではBlockstudio\\Db\\SchemaとBlockstudio\\Db\\Fieldを使えますrpc.phpでは#[Rpc]メソッドを持つオブジェクトを返せますcron.phpでは#[Cron]メソッドを持つオブジェクトを返せます
ToDoアプリ
ユーザーごとのタスク管理アプリです。ログイン中のユーザーには、自分のToDoだけが表示されます。ユーザーを自動的に分離するuserScoped: true、持ち運びやすいストレージのSQLite、楽観的更新のbs.mutate()、別のタブからの変更を自動的に反映するリアルタイムポーリングを使います。
ファイル構成
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
ブロック定義
{
"$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
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()はすでに現在のユーザーのレコードだけを返します。RPCが必要なのは、切り替えや一括削除など、CRUD以外の操作だけです。
<?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'],
],
];
スケジュールされたクリーンアップ
完了から時間が経ったToDoは自動的に削除されます。
<?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()を使って初期ToDoをサーバー側で読み込みます。これにより、SSRのディレクティブ処理とクライアント側のハイドレーションの両方にデータが渡されます。入力欄の値など、インスタンスごとのUI状態はdata-wp-contextに置きます。
<?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"
>×</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>
主なパターン:
- サーバー由来のデータ(ToDo、件数)には
wp_interactivity_state()を使う - 一時的なUI状態(入力テキスト)には
data-wp-contextを使う data-wp-each--todoを使うと、各反復項目に名前付きコンテキスト(context.todo)を割り当てられるstate.*はグローバルストアを参照し、context.*はインスタンスごとのデータを参照する
クライアントロジック
bs.mutate()はすべての書き込みを処理し、楽観的更新と自動ロールバックを行います。UIは即座に更新されます。サーバー呼び出しが拒否されると、状態は元に戻ります。検証エラーや権限エラーの場合は拒否ではなくエラー本文が返されます。詳しくはMutateを参照してください。
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は即座に更新され、サーバー呼び出しはバックグラウンドで実行されます。失敗すると状態がロールバックされます。 clearDoneにはbs.mutate()の手動モードを使います。before()がスナップショットを取得して変更を適用し、onError()がスナップショットから復元します。- Interactivity APIでの非同期処理には、
yieldを使うジェネレーター関数(*addTodo)を使います。 - 直接のCRUDには
bs.db()、カスタムサーバー関数にはbs.fn()を使います。
スタイル
.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
ブロック定義
{
"$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
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
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
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
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>
クライアントロジック
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;
},
},
});
スタイル
.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
比較
| 項目 | ToDoアプリ | ニュースレター |
|---|---|---|
| 認証モデル | 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、index.php + script.inline.jsでUI、外観にstyle.cssを使います。各ブロックが自己完結したアプリケーションです。