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
Дефиниране на функции
Всеки ключ в върнатия масив е име на функция. Най-простият вариант е директна callback функция:
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, promise се изпълнява успешно с обект, съдържащ code, message и data, затова проверявайте code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Promise се отхвърля само ако самата заявка се провали или отговорът не е 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 със същия произход. Изтичащите WordPress nonce стойности и CSRF токените Blockstudio не се съхраняват в HTML на страницата, затова публичните заявки продължават да работят, когато външен кеш за страници обслужва HTML отпреди повече от 24 часа.
Обновяването е отложено: зареждането на страница без извикване на API не изпраща заявка за идентификационни данни. RPC и клиентите за базата данни споделят обновяването, подновяват идентификационните данни след пет минути употреба и правят един повторен опит при изтекъл nonce или CSRF токен. Грешките с права и грешките на приложението не се повтарят. Удостоверяването продължава да използва бисквитката за влизане в WordPress на текущия посетител; обновяването на идентификационните данни не предоставя достъп до частни функции. Дръжте крайната точка за идентификационни данни извън кеша на CDN или прокси; отговорите ѝ са изрично маркирани като private, no-store.
Отворени функции
За уебхукове или външни callback функции 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. Всички hooks получават един масив $params:
| Hook | Параметри |
|---|---|
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 вместо Database
db.php автоматично генерира CRUD крайни точки от схема. Използвайте го, когато са ви нужни стандартни операции за създаване, четене, актуализиране и изтриване с валидация.
rpc.php е предназначен за персонализирана логика: изпращане на имейли, извикване на външни API, обобщаване на данни от различни схеми, изпълнение на сложни заявки или всяка задача, която не се вписва в модела CRUD.
Двете системи са независими и се допълват. Много блокове използват и двете: db.php за модела на данните и rpc.php за бизнес логиката върху него.