Перейти к содержимому

RPC

RPC (Remote Procedure Call) позволяет определять функции PHP в блоке и вызывать их из интерфейса. Вместо того чтобы вручную регистрировать маршруты REST API, создавать контроллеры и настраивать вызовы fetch, вы пишете функцию в rpc.php и вызываете ее с помощью bs.fn(). Blockstudio берет на себя маршрутизацию конечных точек, аутентификацию, проверку nonce и сериализацию JSON.

Этот подход вдохновлен 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];
    }
};

Примечания:

  • По умолчанию имена методов приводятся к нижнему регистру и формату snake_case, поэтому getStatus() становится get_status
  • Используйте name:, чтобы явно задать имя конечной точки
  • Access::Session соответствует прежнему поведению 'public' => true
  • Access::Open соответствует прежнему поведению 'public' => 'open'
  • Не указывайте access:, чтобы оставить поведение по умолчанию — только для аутентифицированных пользователей

Вызов из JavaScript

Blockstudio автоматически добавляет помощник bs.fn() на страницы, где есть блоки с функциями RPC.

Сигнатура: bs.fn(functionName, params?, blockName?) -> Promise

Передача имени блока

Если опустить третий аргумент, bs.fn() использует значение атрибута data-block объекта document.currentScript. Blockstudio выводит и script.js, и встроенные скрипты (script-inline.js или script.inline.js) как теги <script type="module">, а у модульных скриптов нет document.currentScript, поэтому в скриптах блока передавайте имя блока третьим аргументом:

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

Без него вызов выбрасывает bs.fn: block name required.

Обработка ошибок

bs.fn() возвращает разобранное тело JSON независимо от статуса HTTP. Если функция возвращает WP_Error, промис разрешается объектом с его code, message и data, поэтому проверяйте code:

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

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

Промис отклоняется, только если сам запрос завершается ошибкой или ответ не является JSON.

С Interactivity API

RPC хорошо сочетается с WordPress Interactivity 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 того же источника. Истекающие nonce WordPress и токены CSRF Blockstudio не сохраняются в HTML страницы, поэтому публичные вызовы продолжают работать, даже когда внешний кэш страниц отдаёт HTML старше 24 часов.

Обновление выполняется по требованию: загрузка страницы без вызова API не приводит к запросу учетных данных. RPC и клиенты базы данных используют общий запрос на обновление, обновляют учетные данные после пяти минут использования и один раз повторяют запрос при истекшем nonce или токене CSRF. Ошибки разрешений и приложения не приводят к повторным попыткам. Аутентификация по-прежнему использует cookie входа WordPress текущего посетителя; обновление учетных данных не предоставляет доступ к приватным функциям. Разместите конечную точку учетных данных вне кэша CDN или прокси; для её ответов явно задан заголовок private, no-store.

Открытые функции

Для вебхуков или внешних обратных вызовов API, которым нужен полностью открытый доступ без токена:

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

Возможности

Ограничьте доступ определенными возможностями WordPress. Для одной возможности укажите строку, а для доступа при наличии любой из нескольких — массив:

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

Любой блок может вызывать функции другого блока, передав имя блока третьим аргументом. Так можно объединять блоки:

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, но рекомендуется использовать bs.fn(), поскольку он автоматически обрабатывает аутентификацию с nonce.

Хуки

Действия выполняются до и после каждого вызова RPC, как из REST, так и из PHP. Все хуки получают один массив $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.

Эти две системы независимы и дополняют друг друга. Во многих блоках используются обе: db.php для модели данных и rpc.php для бизнес-логики поверх нее.