RPC
RPC (Remote Procedure Call) leidžia apibrėžti PHP funkcijas bloke ir iškviesti jas iš išorinės sąsajos. Užuot rankiniu būdu registravę REST API maršrutus, kūrę valdiklius ir sujungę fetch iškvietimus, parašote funkciją faile rpc.php ir iškviečiate ją naudodami bs.fn(). Blockstudio pasirūpina galinių taškų maršrutizavimu, autentifikavimu, nonce patvirtinimu ir JSON serializavimu.
Šis šablonas įkvėptas tRPC: apibrėžkite procedūras serverio pusėje, o iškvieskite jas kliente naudodami tipizuotą pagalbinę funkciją. Nereikia kurti URL ar rankiniu būdu rašyti fetch bazinio kodo.
Kaip tai veikia
- Bloko aplanke sukuriate
rpc.php - Jis grąžina asociatyvų masyvą su pavadintomis funkcijomis
- Blockstudio kiekvienai funkcijai užregistruoja REST galinį tašką
bs.fn()klientas iškviečia jas pagal pavadinimą- Parametrai perduodami, o grąžinamas JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Funkcijų apibrėžimas
Kiekvienas grąžinamo masyvo raktas yra funkcijos pavadinimas. Paprasčiausia forma – tiesioginė atgalinio iškvietimo funkcija:
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];
},
];
Kiekviena funkcija gauna vieną $params masyvą ir turėtų grąžinti masyvą. Grąžinama reikšmė klientui siunčiama kaip JSON.
Norėdami nustatyti prieigos kontrolės parinktis, naudokite išplėstinį formatą su callback ir papildomais raktais:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP savosios apibrėžtys
Jei vietoj įdėtinių masyvų pageidaujate PHP savųjų metaduomenų, rpc.php taip pat gali grąžinti objektą su atributuotais metodais. Masyvai veikia lygiai taip pat.
<?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];
}
};
Pastabos:
- Pagal numatytuosius nustatymus metodų pavadinimai paverčiami mažosiomis raidėmis ir snake case formatu, todėl
getStatus()tampaget_status - Naudokite
name:, kad aiškiai nurodytumėte galinio taško pavadinimą Access::Sessionatitinka ankstesnę'public' => trueveiksenąAccess::Openatitinka ankstesnę'public' => 'open'veikseną- Praleiskite
access:, jei norite numatytojo veikimo, kai prieiga suteikiama tik autentifikuotiems naudotojams
Iškvietimas iš JavaScript
Blockstudio puslapiuose, kuriuose yra blokų su RPC funkcijomis, automatiškai įterpia bs.fn() pagalbinę funkciją.
Signatūra: bs.fn(functionName, params?, blockName?) -> Promise
Bloko pavadinimo perdavimas
bs.fn(), jei praleidžiamas trečias argumentas, naudoja document.currentScript atributą data-block. Blockstudio išveda ir script.js, ir įterptuosius scenarijus (script-inline.js arba script.inline.js) kaip <script type="module"> žymas, o modulių scenarijai neturi document.currentScript. Todėl bloko scenarijuose trečiuoju argumentu perduokite bloko pavadinimą:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Be jo iškvietimas sukelia bs.fn: block name required klaidą.
Klaidų apdorojimas
bs.fn() grąžina išanalizuotą JSON turinį, kad ir koks būtų HTTP būsenos kodas. Kai funkcija grąžina WP_Error, pažadas įvykdomas su objektu, kuriame yra code, message ir data, todėl patikrinkite, ar yra code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Pažadas atmetamas tik tada, kai pati užklausa nepavyksta arba atsakymas nėra JSON.
Su interaktyvumo API
RPC natūraliai dera su WordPress interaktyvumo API. Jūsų saugyklos veiksmai iškviečia serverio funkcijas ir pagal atsakymą atnaujina reaktyviąją būseną. UI atnaujinama automatiškai:
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>
Prieigos kontrolė
Pagal numatytuosius nustatymus funkcijoms reikia autentifikuoto (prisijungusio) naudotojo. Tai atitinka WordPress konvencijas, pagal kurias REST galiniai taškai pagal numatytuosius nustatymus yra apsaugoti.
Viešos funkcijos
Leiskite prieigą neprisijungus, taikydami CSRF apsaugą:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Podėlyje saugomi puslapiai
bs.fn() gauna naujus kredencialus iš tos pačios kilmės nekeshuojamo POST /wp-json/blockstudio/v1/client/credentials galinio taško. Baigiantys galioti WordPress nonce ir Blockstudio CSRF žetonai nesaugomi puslapio HTML, todėl viešieji iškvietimai toliau veikia, kai išorinis puslapio podėlis pateikia senesnį nei 24 valandų HTML.
Atnaujinama prireikus: įkėlus puslapį ir neiškvietus API, kredencialų neprašoma. RPC ir duomenų bazės klientai dalijasi atnaujinimu, po penkių minučių naudojimo atnaujina kredencialus ir vieną kartą pakartoja užklausą, jei nonce arba CSRF žetonas nebegalioja. Galimybių patikros ir programos klaidos užklausų nekartoja. Autentifikavimas ir toliau vykdomas pagal dabartinio lankytojo WordPress prisijungimo slapuką; kredencialų atnaujinimas nesuteikia prieigos prie privačių funkcijų. Kredencialų galinį tašką laikykite už bet kokio CDN ar tarpinio serverio podėlio ribų; jo atsakymai aiškiai pažymėti kaip private, no-store.
Atviros funkcijos
Webhook arba išorinių API atgalinio iškvietimo funkcijų atveju, kai reikia visiškai atviros prieigos be jokio žetono:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Galimybės
Apribokite prieigą konkrečiomis WordPress galimybėmis. Vienai galimybei naudokite eilutę, o jei naudotojui pakanka bet kurios vienos – masyvą:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP metodai
Pagal numatytuosius nustatymus funkcijos priima tik POST užklausas. Tai saugiausia nuostata operacijoms, kurios keičia būseną. Kai reikia, leiskite ir kitus metodus:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Iškvietimai tarp blokų
Iš JavaScript
Bet kuris blokas gali iškviesti kito bloko funkcijas, trečiuoju argumentu perduodamas bloko pavadinimą. Taip galima kurti blokų sąveikas:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Iš PHP
Serverio pusės iškvietimams tarp blokų naudokite Rpc::call(). Tai naudinga, kai viena RPC funkcija turi koordinuoti kitų blokų iškvietimus:
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 galinis taškas
Viduje kiekviena funkcija susiejama su REST maršrutu:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Užklausos turinys: { "params": { ... } }
Atsakymas: funkcijos PHP grąžinama reikšmė kaip JSON.
Šiuos galinius taškus galite tiesiogiai iškviesti iš bet kurio HTTP kliento, tačiau rekomenduojamas būdas yra bs.fn(), nes jis automatiškai tvarko nonce autentifikavimą.
Kabliukai
Veiksmai vykdomi prieš ir po kiekvieno RPC iškvietimo tiek iš REST, tiek iš PHP. Visi kabliukai gauna vieną $params masyvą:
| Kabliukas | Parametrai |
|---|---|
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.
});
Filtras
Programiškai keiskite arba pridėkite funkcijų iš bloko išorės:
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;
});
Kada naudoti RPC, o kada – duomenų bazę
db.php pagal schemą automatiškai generuoja CRUD galinius taškus. Naudokite jį, kai reikia standartinių kūrimo, skaitymo, naujinimo ir šalinimo operacijų su patvirtinimu.
rpc.php skirta pasirinktinei logikai: el. laiškų siuntimui, išorinių API iškvietimui, duomenų iš kelių schemų agregavimui, sudėtingų užklausų vykdymui ar bet kam, kas neatitinka CRUD modelio.
Šios dvi sistemos yra nepriklausomos ir viena kitą papildo. Daugelyje blokų naudojamos abi: db.php duomenų modeliui, o rpc.php – verslo logikai.