Перейти до вмісту

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.

З API Interactivity API

RPC природно поєднується з WordPress Інтерактивністю 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 прострочено. Помилки перевірки можливостей і помилки застосунку не спричиняють повторних спроб. Автентифікація й далі використовує поточну WordPress cookie входу відвідувача; оновлення облікових даних не надає доступу до приватних функцій. Розмістіть кінцеву точку облікових даних поза кешем проксі або 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 для бізнес-логіки поверх неї.