コンテンツへスキップ

RPC

RPC(Remote Procedure Call)を使うと、ブロック内にPHP関数を定義し、フロントエンドから呼び出せます。rpc.phpに関数を記述し、bs.fn()で呼び出せば、Blockstudioがエンドポイントのルーティング、認証、nonce検証、JSONのシリアライズを処理します。RESTAPIルートの手動登録や、コントローラーの作成、fetch呼び出しの接続は不要です。

このパターンはtRPCに着想を得ています。サーバー側でプロシージャを定義し、型付きヘルパーを使ってクライアントから呼び出します。URLの構築や、fetchの定型コードは不要です。

仕組み

  1. ブロックディレクトリにrpc.phpを作成します
  2. 名前付き関数を含む連想配列を返します
  3. Blockstudioが各関数のRESTエンドポイントを登録します
  4. bs.fn()クライアントから関数名で呼び出します
  5. パラメーターを渡すと、JSONが返されます
コード
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

関数の定義

返される配列の各キーが関数名です。最も簡単なのは、コールバックを直接指定する方法です:

PHP
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        // process subscription
        return ['success' => true];
    },
    'load_more' => function (array $params): array {
        $offset = (int) ($params['offset'] ?? 0);
        $posts = get_posts(['offset' => $offset, 'numberposts' => 5]);
        return ['posts' => $posts];
    },
];

各関数は単一の$params配列を受け取り、配列を返します。戻り値はJSONとしてクライアントに送信されます。

アクセス制御オプションを使うには、callbackと追加のキーを含む拡張形式を使用します:

PHP
return [
    'admin_action' => [
        'callback'   => function (array $params): array {
            return ['ok' => true];
        },
        'capability' => 'manage_options',
    ],
];

PHPネイティブの定義

ネストした配列ではなく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 {
        $email = sanitize_email($params['email'] ?? '');
        return ['success' => !empty($email)];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }

    #[Rpc(access: Access::Open)]
    public function webhook(array $params): array {
        return ['received' => true];
    }
};

注意:

  • メソッド名はデフォルトで小文字のスネークケースに正規化されます。そのため、getStatus()はget_statusになります
  • name:を使うと、エンドポイント名を明示的に上書きできます
  • Access::Sessionは従来の'public' => trueの動作に相当します
  • Access::Openは従来の'public' => 'open'の動作に相当します
  • デフォルトの認証済みユーザー限定の動作を使う場合は、access:を省略します

JavaScriptからの呼び出し

Blockstudioは、RPC関数を持つブロックがあるページにbs.fn()ヘルパーを自動挿入します。

シグネチャ: bs.fn(functionName, params?, blockName?) -> Promise

ブロック名の指定

bs.fn() は、3 番目の引数を省略すると document.currentScript の data-block 属性にフォールバックします。 Blockstudio は、script.js とインラインスクリプト(script-inline.js または script.inline.js)の両方を <script type="module"> タグとして出力します。モジュールスクリプトには document.currentScript がないため、ブロックスクリプトでは 3 番目の引数にブロック名を渡してください。

JavaScript
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');

指定しないと、呼び出し時にbs.fn: block name requiredがスローされます。

エラー処理

bs.fn()はHTTPステータスにかかわらず、パース済みのJSON本文で解決します。関数がWP_Errorを返すと、code、message、dataを格納したオブジェクトでPromiseが解決するため、codeを確認してください:

JavaScript
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');

if (result.code) {
  console.error('RPC failed:', result.message);
}

リクエスト自体が失敗した場合、またはレスポンスがJSONでない場合に限り、Promiseは拒否されます。

Interactivity APIとの連携

RPCはWordPressInteractivity APIと自然に連携します。ストアのアクションからサーバー関数を呼び出し、レスポンスでリアクティブな状態を更新できます。UIは自動的に更新されます:

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

store('myTheme/newsletter', {
  actions: {
    subscribe: async () => {
      const ctx = getContext();
      ctx.loading = true;
      ctx.error = '';

      try {
        ctx.result = await bs.fn('subscribe', { email: ctx.email }, 'my-theme/newsletter');
        ctx.success = !ctx.result.code;
      } catch (e) {
        ctx.error = 'Something went wrong.';
      }

      ctx.loading = false;
    },
  },
});
PHP
<div
  data-wp-interactive="myTheme/newsletter"
  data-wp-context='{"email":"","loading":false,"success":false,"error":"","result":null}'
  useBlockProps
>
  <input
    type="email"
    data-wp-bind--value="context.email"
    data-wp-on--input="actions.updateEmail"
  />
  <button
    data-wp-on--click="actions.subscribe"
    data-wp-bind--disabled="context.loading"
  >Subscribe</button>
  <p data-wp-if="context.error" data-wp-text="context.error"></p>
  <p data-wp-if="context.success">Thanks for subscribing!</p>
</div>

アクセス制御

デフォルトでは、関数の呼び出しには認証済み(ログイン済み)ユーザーが必要です。これは、WordPressの慣例と同じく、RESTエンドポイントがデフォルトで保護される動作です。

公開関数

CSRF保護を有効にしたまま、未認証のアクセスを許可します:

PHP
return [
    'get_count' => [
        'callback' => function (array $params): array {
            return ['count' => wp_count_posts()->publish];
        },
        'public' => true,    // public + CSRF protected via X-BS-Token
    ],
];

キャッシュされたページ

bs.fn()は、キャッシュされない同一オリジンのPOST /wp-json/blockstudio/v1/client/credentialsエンドポイントから新しい認証情報を取得します。期限切れになるWordPressnonceとBlockstudioCSRFトークンはページHTMLに保存されないため、外部ページキャッシュが24時間以上前のHTMLを配信した場合も、公開リクエストは引き続き動作します。

更新は必要になった時点で行われます。APIを呼び出さずにページを読み込んでも、認証情報のリクエストは発生しません。RPCとデータベースクライアントは更新を共有し、5分間の使用後に認証情報を更新して、期限切れのnonceまたはCSRFトークンに対して1回だけ再試行します。権限エラーやアプリケーションエラーは再試行されません。認証には引き続き、現在の訪問者のWordPressログインCookieが使用されます。認証情報を更新しても、非公開関数へのアクセス権は付与されません。認証情報エンドポイントは、CDNやプロキシのキャッシュ対象外にしてください。レスポンスにはprivate, no-storeが明示的に設定されています。

オープン関数

トークンなしで完全にオープンなアクセスを必要とするWebhookや外部APIコールバックの場合:

PHP
return [
    'webhook' => [
        'callback' => function (array $params): array {
            // Called by an external service
            return ['received' => true];
        },
        'public' => 'open',  // no CSRF, no auth
    ],
];

権限

特定のWordPress権限に制限します。単一の権限には文字列を、ユーザーにいずれか1つの権限があればよい場合は配列を使います:

PHP
return [
    'save_draft' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => 'edit_posts',
    ],
    'moderate' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => ['edit_others_posts', 'manage_options'],
    ],
];

HTTPメソッド

デフォルトでは、関数はPOSTリクエストのみを受け付けます。これは状態を変更する操作に最も安全な設定です。必要に応じて、ほかのメソッドも許可できます:

PHP
return [
    'get_status' => [
        'callback' => function (array $params): array {
            return ['status' => 'ok'];
        },
        'methods' => ['GET', 'POST'],
    ],
];

ブロック間の呼び出し

JavaScriptから

3つ目の引数にブロック名を渡すと、任意のブロックからほかのブロックの関数を呼び出せます。これにより、ブロック同士を組み合わせられます:

JavaScript
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');

PHPから

サーバー側でブロック間の呼び出しを行うにはRpc::call()を使います。RPC関数からほかのブロックへの呼び出しをまとめて制御する場合に便利です:

PHP
use Blockstudio\Rpc;

return [
    'refresh_dashboard' => function (array $params): array {
        $feed  = Rpc::call('my-theme/blog-feed', 'load_more', ['offset' => 0]);
        $stats = Rpc::call('my-theme/analytics', 'get_summary', []);

        return ['feed' => $feed, 'stats' => $stats];
    },
];

RESTエンドポイント

内部では、各関数がRESTルートに対応します:

コード
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

リクエスト本文: { "params": { ... } }

レスポンス: PHP関数の戻り値をJSONとして返します。

任意のHTTPクライアントからこれらのエンドポイントを直接呼び出せますが、nonce認証を自動的に処理するbs.fn()の使用を推奨します。

フック

アクションは、RESTとPHPのどちらからのRPC呼び出しでも、その前後に実行されます。すべてのフックは単一の$params配列を受け取ります:

フック パラメーター
blockstudio/rpc/before_call block、function、params
blockstudio/rpc/after_call block、function、params、result
PHP
add_action('blockstudio/rpc/after_call', function ($params) {
    // Log every RPC call
    error_log($params['block'] . '::' . $params['function'] . ' called');
});

add_action('blockstudio/rpc/before_call', function ($params) {
    // Rate limiting, audit logging, etc.
});

フィルター

ブロックの外部からプログラムで関数を変更または追加します:

PHP
add_filter('blockstudio/rpc', function (array $functions): array {
    $functions['my-theme/hero']['custom_action'] = [
        'callback' => function (array $params): array {
            return ['ok' => true];
        },
        'public' => false,
    ];
    return $functions;
});

RPCとデータベースの使い分け

db.phpはスキーマからCRUDエンドポイントを自動生成します。検証を伴う標準的な作成、読み取り、更新、削除操作が必要な場合に使用します。

rpc.phpはカスタムロジック向けです。メールの送信、外部APIの呼び出し、複数スキーマのデータ集約、複雑なクエリの実行など、CRUDのパターンに当てはまらない処理に使います。

2つのシステムは独立しており、互いに補完します。多くのブロックは両方を使用します。db.phpでデータモデルを定義し、その上のビジネスロジックにrpc.phpを使います。