コンテンツへスキップ

データベース

データベース層では、db.phpファイルでブロックのデータモデルを定義できます。BlockstudioはRESTCRUDエンドポイントを生成し、スキーマに照らして入力を検証し、ストレージを自動管理します。また、JavaScriptクライアント(bs.db())とPHPAPI(Dbクラス)の両方を提供します。

これはフルスタックブロックのデータ基盤です。RPCが独自のロジックを扱う一方、データベース層はボイラープレートなしで構造化データを扱います。

仕組み

  1. ブロックディレクトリにdb.phpを作成します
  2. スキーマとして、フィールド、型、検証ルール、アクセス制御を返します
  3. Blockstudioがストレージ(テーブル、ファイル、または投稿メタ)を作成します
  4. 5つのRESTエンドポイント(一覧、取得、作成、更新、削除)が自動生成されます
  5. bs.db()とDb::get()がクライアント側とサーバー側のアクセスを提供します

マイグレーションもコントローラーも、ルート登録も不要です。

REST API と PHP API には値をそのまま渡してください。metaバックエンドとpost_typeバックエンドはWordPressメタデータのスラッシュ処理を内部で行い、スカラー値とネストされたオブジェクトや配列の両方で、バックスラッシュと引用符付き文字列を保持します。データベースレコードの値にあらかじめスラッシュを追加しないでください。

スキーマの定義

単一スキーマ

最もシンプルな形式で、ブロックごとに1つのデータモデルを定義します。

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(...)呼び出しの配列を返します。

複数スキーマ

1つのブロックで複数のデータモデルを管理できます。名前付き配列を返します。

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'],
        ],
    ],
];

各スキーマには、それぞれ独自のエンドポイント、ストレージ、アクセス制御が割り当てられます。

ストレージモード

用途に応じて選べる6種類のストレージバックエンドがあります。

カスタムテーブル(storage: "table")

各レコードは専用のMySQLテーブルの行として保存されます。BlockstudioはWordPressのdbDelta()関数を使ってテーブルを自動作成し、管理します。スキーマにフィールドを追加すると、次回のページ読み込み時に列が追加されます。既存の列は削除されません。

最適な用途:構造化データ、クエリ、本番アプリケーション。

SQLite (storage: "sqlite")

各スキーマ専用のSQLiteデータベースファイルが、db/サブフォルダーに作成されます。Blockstudioがファイルとテーブルを自動作成し、スキーマ変更時には不足している列を追加します(MySQLのdbDeltaと同様)。同時読み取りのパフォーマンス向上のため、WALジャーナルモードを使用します。

コード
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

最適な用途:実際のSQLクエリが必要で、データの移植性も保ちたい構造化データです。すべてをメモリに読み込まずに数千件のレコードを効率よく処理できます。フォルダーをコピーするだけでデータを移動できます。

JSONCファイル(storage: "jsonc")

レコードはdb/サブフォルダー内の.jsoncファイルに、1行につき1つのJSONオブジェクトとして保存されます。ファイルは初回書き込み時に自動作成されます。//で始まる行はコメントとして扱われ、保持されます。

コード
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

最適な用途:小規模なデータセット、設定のようなデータ、シードレコード、バージョン管理できるサンプルです。JSONCは意図的にブロックフォルダー内の単一ファイルとして保存されます。データをコードと一緒に持ち運びたい場合に使い、同時書き込みが多い用途には使わないでください。

Storhファイル(storage: "storh")

Storhは各レコードをWordPressuploads内の個別ファイルとして保存します。

コード
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でレコードをクエリでき、RESTAPIプラグインと互換性を持ち、GraphQLなどのツールからも確認できます。

最適な用途:WordPressにネイティブに統合するデータです。各フィールドを個別にクエリ、インデックス化できます。

JavaScriptクライアント

データベースブロックを含むページでは、Blockstudioがbs.db()を挿入します。次の5つのメソッドを持つオブジェクトを返します。

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);

最初の引数はブロック名(/を含む)、2番目はスキーマ名です。単一スキーマのブロックでは、スキーマ名を省略できます(デフォルトは"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()は任意の非同期関数をキャッシュ、重複排除、鮮度管理でラップします。リクエストの処理中に同じキーで複数回呼び出すと、同じPromiseが返されます(重複した取得は発生しません)。

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 }
);

最初の引数はキャッシュキー(任意の文字列)、2番目はPromiseを返す関数、3番目は省略可能なオプションオブジェクトです。

オプション 型 説明
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が返すPromiseがrejectされることです。検証エラー、レコード不在、権限チェック失敗の場合、bs.db()とbs.fn()はエラーボディを伴ってresolveされます。これらの場合もロールバックするには、結果にcodeが含まれていたらthrowしてください。

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 両方 ミューテーションを実行する非同期関数。必須。
state object 自動 リアクティブな状態オブジェクト(e.g、Alpine $data)。
key string 自動 配列を保持する状態上のプロパティ名。キャッシュキーとしても使われます。
action string 自動 create、update、deleteのいずれか。
id any 自動 updateおよびdeleteアクションのレコードID。
optimistic object 自動 サーバー応答前に楽観的に適用するデータ。
before function 手動 fnの前に呼び出されます。戻り値はsnapshotとしてonSuccess/onErrorに渡されます。
onSuccess function 手動 成功時に(result, snapshot)とともに呼び出されます。
onError function 手動 失敗時に(error, snapshot)とともに呼び出されます。
invalidate string 手動 成功時に無効化するキャッシュキー。

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も認証も不要(webhookや外部API向け)
'edit_posts' WordPress権限チェック
['cap_a', 'cap_b'] ユーザーは一覧の権限のいずれか1つを持つ必要があります
省略 / 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分間使用した後に更新されます。無効なWordPressnonceまたはBlockstudioCSRFトークンが拒否されると、1回だけ更新して再試行します。通常の権限エラーは再試行されません。ログイン中のリクエストでは引き続き、訪問ユーザーのセッションとスキーマの権限およびレコード所有権のチェックが適用されます。

POST /wp-json/blockstudio/v1/client/credentialsは、プロキシやCDNキャッシュの対象外にしてください。Cache-Control: private, no-storeを送信し、同一オリジンからのリクエストと、シンプルではないヘッダーを必要とします。組み込みクライアントがこれらを自動的に処理します。

外部サービスからの受信webhookなど、CSRF保護なしで完全に未認証のアクセスを許可する場合は、'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()、RESTAPI、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;
});