RPC
RPC (Remote Procedure Call) võimaldab määratleda plokis PHP funktsioone ja kutsuda neid kasutajaliidesest. Selle asemel et registreerida käsitsi REST API marsruute, luua kontrollereid ja ühendada fetch kutseid, kirjutate funktsiooni failis rpc.php ja kutsute seda käsuga bs.fn(). Blockstudio haldab lõpp-punktide marsruutimist, autentimist, nonce’i valideerimist ja JSON serialiseerimist.
Muster on inspireeritud teegist tRPC: määratlege protseduurid serveripoolel ja kutsuge neid kliendist tüübistatud abifunktsiooniga. Pole vaja luua URL ega kirjutada käsitsi fetch põhikoodi.
Kuidas see töötab
- Loote ploki kausta faili
rpc.php - See tagastab nimeliste funktsioonide assotsiatiivse massiivi
- Blockstudio registreerib iga funktsiooni jaoks REST lõpp-punkti
bs.fn()klient kutsub neid nime järgi- Sisse antakse parameetrid, välja tuleb JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Funktsioonide määratlemine
Tagastatud massiivi iga võti on funktsiooni nimi. Lihtsaim variant on otse määratud tagasihelistusfunktsioon:
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];
},
];
Iga funktsioon saab ühe $params massiivi ja peaks tagastama massiivi. Tagastusväärtus saadetakse kliendile kujul JSON.
Juurdepääsu reguleerimiseks kasutage laiendatud vormingut, kus on callback ja lisavõtmed:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP-omased määratlused
Kui eelistate pesastatud massiividele PHP-põhiseid metaandmeid, võib rpc.php tagastada ka objektide meetoditega objekti. Massiivid töötavad endiselt täpselt samamoodi.
<?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];
}
};
Märkused:
- Vaikimisi teisendatakse meetodite nimed väiketähtedest koosnevateks snake_case’i nimedeks, nii et
getStatus()muutub nimeksget_status - Kasutage
name:, et lõpp-punkti nime selgesõnaliselt muuta Access::Sessionvastab vanale käitumisele'public' => trueAccess::Openvastab vanale käitumisele'public' => 'open'- Vaikimisi nõutava autentimise säilitamiseks jätke
access:välja
Kutsumine kasutajaliidesest JavaScript
Blockstudio lisab automaatselt bs.fn() abifunktsiooni lehtedele, kus on plokke RPC funktsioonidega.
Signatuur: bs.fn(functionName, params?, blockName?) -> Promise
Ploki nime edastamine
bs.fn() kasutab kolmanda argumendi puudumisel document.currentScript atribuuti data-block. Blockstudio prindib nii script.js kui ka skriptid (script-inline.js või script.inline.js) <script type="module">-siltidena, moodulskriptidel aga puudub document.currentScript. Seetõttu edastage plokiskriptides kolmanda argumendina ploki nimi:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Ilma selleta viskab väljakutse vea bs.fn: block name required.
Vigade käsitlemine
bs.fn() lahendub parsitud JSON kehaga olenemata HTTP olekust. Kui funktsioon tagastab WP_Error, lahendub lubadus objektiga, mis sisaldab selle code, message ja data, seega kontrollige code väärtust:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Lubadus lükatakse tagasi ainult siis, kui päring ise ebaõnnestub või vastus pole JSON.
Koos Interactivity API-ga
RPC sobib loomulikult kokku Interactivity WordPress-ga API. Poe toimingud kutsuvad serverifunktsioone ja uuendavad vastuse põhjal reaktiivset olekut. UI uueneb automaatselt:
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>
Juurdepääsukontroll
Vaikimisi vajavad funktsioonid autentitud (sisselogitud) kasutajat. See vastab WordPress tavale, mille kohaselt on REST lõpp-punktid vaikimisi kaitstud.
Avalikud funktsioonid
Lubage autentimata juurdepääs CSRF-kaitsega:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Vahemällu salvestatud lehed
bs.fn() hangib värsked mandaadid vahemällu salvestamata sama päritoluga lõpp-punktist POST /wp-json/blockstudio/v1/client/credentials. Aeguvaid WordPress nonce’e ja Blockstudio CSRF-tokeneid lehe HTML ei salvestata, seega toimivad avalikud kutsed edasi ka siis, kui väline lehevahemälu serveerib üle 24 tunni vanust HTML.
Värskendamine toimub viivitusega: lehe laadimine ilma API kutsumata ei tekita mandaatide päringut. RPC ja andmebaasi kliendid jagavad värskendust, uuendavad mandaate pärast viit minutit kasutamist ning proovivad aegunud nonce’i või CSRF-tokeni korral korra uuesti. Võimekuse tõrkeid ja rakenduse vigu uuesti ei proovita. Autentimisel kasutatakse endiselt praeguse külastaja WordPress sisselogimisküpsist; mandaatide värskendamine ei anna ligipääsu privaatsetele funktsioonidele. Hoia mandaatide lõpp-punkt väljaspool igasugust CDN või puhverserveri vahemälu; selle vastused on sõnaselgelt märgitud private, no-store.
Avatud funktsioonid
Veebihaakide või väliste API tagasihelistuste jaoks, mis vajavad täiesti avatud juurdepääsu ilma tokenita:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Õigused
Piirake juurdepääsu kindlatele WordPress õigustele. Ühe õiguse jaoks kasutage stringi, mitme puhul massiivi, kus kasutajal peab olema neist ükskõik milline:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP meetodid
Vaikimisi aktsepteerivad funktsioonid ainult POST päringuid. See on olekut muutvate toimingute jaoks kõige turvalisem vaikevalik. Vajaduse korral lubage lisameetodid:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Plokkidevahelised kutsed
Plokist JavaScript
Iga plokk saab kutsuda mis tahes teise ploki funktsioone, edastades kolmanda argumendina ploki nime. Nii saab plokke omavahel kombineerida:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Plokist PHP
Kasutage serveripoolseteks plokkidevahelisteks kutseteks käsku Rpc::call(). See on kasulik, kui üks RPC funktsioon peab korraldama teiste plokkide kutseid:
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 lõpp-punkt
Kapoti all seostatakse iga funktsioon marsruudiga REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Päringu sisu: { "params": { ... } }
Vastus: funktsiooni PHP tagastusväärtus kujul JSON.
Neid lõpp-punkte saab kutsuda otse mis tahes HTTP kliendist, kuid soovitatav on kasutada bs.fn(), sest see haldab nonce-autentimist automaatselt.
Hook’id
Toimingud käivituvad enne ja pärast iga RPC kutset nii REST kui ka PHP kaudu. Kõik hook’id saavad ühe $params massiivi:
| Hook | Parameetrid |
|---|---|
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.
});
Filtreeri
Muutke või lisage funktsioone programmiliselt väljastpoolt plokki:
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;
});
Millal kasutada RPC-i ja millal andmebaasi
db.php loob CRUD-lõpp-punktid skeemi põhjal automaatselt. Kasutage seda siis, kui vajate valideerimisega tavalisi loomise, lugemise, uuendamise ja kustutamise toiminguid.
rpc.php on mõeldud kohandatud loogika jaoks: e-kirjade saatmiseks, väliste API-de kutsumiseks, mitme skeemi andmete koondamiseks, keerukate päringute käivitamiseks või muuks, mis CRUD-mustriga ei sobi.
Need kaks süsteemi on sõltumatud ja täiendavad teineteist. Paljud plokid kasutavad mõlemat: db.php andmemudeli jaoks ja rpc.php selle peale ehitatud äriloogika jaoks.