Към съдържанието

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

Дефиниране на функции

Всеки ключ в върнатия масив е име на функция. Най-простият вариант е директна callback функция:

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, promise се изпълнява успешно с обект, съдържащ code, message и data, затова проверявайте code:

JavaScript
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 се актуализира автоматично:

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

Обновяването е отложено: зареждането на страница без извикване на API не изпраща заявка за идентификационни данни. RPC и клиентите за базата данни споделят обновяването, подновяват идентификационните данни след пет минути употреба и правят един повторен опит при изтекъл nonce или CSRF токен. Грешките с права и грешките на приложението не се повтарят. Удостоверяването продължава да използва бисквитката за влизане в WordPress на текущия посетител; обновяването на идентификационните данни не предоставя достъп до частни функции. Дръжте крайната точка за идентификационни данни извън кеша на CDN или прокси; отговорите ѝ са изрично маркирани като private, no-store.

Отворени функции

За уебхукове или външни callback функции 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. Всички hooks получават един масив $params:

Hook Параметри
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 вместо Database

db.php автоматично генерира CRUD крайни точки от схема. Използвайте го, когато са ви нужни стандартни операции за създаване, четене, актуализиране и изтриване с валидация.

rpc.php е предназначен за персонализирана логика: изпращане на имейли, извикване на външни API, обобщаване на данни от различни схеми, изпълнение на сложни заявки или всяка задача, която не се вписва в модела CRUD.

Двете системи са независими и се допълват. Много блокове използват и двете: db.php за модела на данните и rpc.php за бизнес логиката върху него.