RPC
RPC (Remote Procedure Call) позволяет определять функции PHP в блоке и вызывать
их из интерфейса. Вместо того чтобы вручную регистрировать маршруты REST API,
создавать контроллеры и настраивать вызовы fetch, вы пишете функцию в
rpc.php и вызываете ее с помощью bs.fn(). Blockstudio берет на себя маршрутизацию конечных точек,
аутентификацию, проверку nonce и сериализацию JSON.
Этот подход вдохновлен tRPC: определяйте процедуры
на сервере, а вызывайте их на клиенте с помощью типизированного помощника. Без создания URL
и шаблонного кода fetch вручную.
Как это работает
- Создайте
rpc.phpв каталоге блока - Он возвращает ассоциативный массив именованных функций
- Blockstudio регистрирует конечную точку REST для каждой функции
- Клиент
bs.fn()вызывает их по имени - На вход подаются параметры, на выходе получается JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Определение функций
Каждый ключ в возвращенном массиве — имя функции. Самый простой вариант — непосредственная функция обратного вызова:
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
и дополнительными ключами:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Определения в стиле PHP
Если вместо вложенных массивов вам удобнее использовать метаданные, нативные для PHP, rpc.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' => trueAccess::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, поэтому в скриптах блока передавайте имя блока третьим аргументом:
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:
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 обновляется автоматически:
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;
},
},
});
<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:
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, которым нужен полностью открытый доступ без токена:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Возможности
Ограничьте доступ определенными возможностями WordPress. Для одной возможности укажите строку, а для доступа при наличии любой из нескольких — массив:
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. Это наиболее безопасное значение для операций, изменяющих состояние. При необходимости разрешите дополнительные методы:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Вызовы между блоками
Из 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 нужно координировать вызовы других блоков:
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 |
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.
});
Фильтрация
Изменяйте или добавляйте функции программно извне блока:
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 для бизнес-логики поверх нее.