RPC
RPC (Remote Procedure Call) omogoča določanje funkcij PHP v bloku in njihovo klicanje
iz vmesnika. Namesto ročnega registriranja poti REST API,
ustvarjanja krmilnikov in povezovanja klicev fetch napišete funkcijo v
rpc.php in jo pokličete z bs.fn(). Blockstudio poskrbi za usmerjanje končnih točk,
avtentikacijo, preverjanje nonce in serializacijo JSON.
Vzorec se zgleduje po tRPC: postopke določite
na strežniku, v odjemalcu pa jih kličete s tipiziranim pomočnikom. Brez sestavljanja URL,
brez ročne odvečne kode za fetch.
Kako deluje
- V mapi bloka ustvarite
rpc.php - Vrne asociativno polje poimenovanih funkcij
- Blockstudio registrira končno točko REST za vsako funkcijo
- Odjemalec
bs.fn()jih kliče po imenu - Parametri se pošljejo, rezultat JSON pa se vrne
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Določanje funkcij
Vsak ključ v vrnjenem polju je ime funkcije. Najpreprostejša oblika je neposredni povratni klic:
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];
},
];
Vsaka funkcija prejme eno samo polje $params in mora vrniti polje.
Vrnjena vrednost se odjemalcu pošlje kot JSON.
Za možnosti nadzora dostopa uporabite razširjeno obliko z callback in
dodatnimi ključi:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definicije, izvorne za PHP
Če vam bolj ustrezajo metapodatki, značilni za PHP, namesto ugnezdenih polj, lahko rpc.php vrne tudi
objekt z metodami z atributi. Polja še vedno delujejo povsem enako.
<?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];
}
};
Opombe:
- Imena metod so privzeto normalizirana v zapis snake case z malimi črkami, zato
getStatus()postaneget_status - Z
name:izrecno določite ime končne točke Access::Sessionustreza staremu načinu delovanja'public' => trueAccess::Openustreza staremu načinu delovanja'public' => 'open'- Izpustite
access:za privzeto vedenje, ki dovoljuje samo preverjene uporabnike
Klicanje iz JavaScript
Blockstudio na straneh z bloki, ki vsebujejo funkcije RPC, samodejno vstavi pomočnika bs.fn().
Podpis: bs.fn(functionName, params?, blockName?) -> Promise
Podajanje imena bloka
Če izpustite tretji argument, bs.fn() uporabi atribut data-block za document.currentScript. Blockstudio izpiše script.js in vgrajene skripte (script-inline.js ali script.inline.js) kot oznake <script type="module">, skripte modula pa nimajo document.currentScript, zato v skriptah bloka kot tretji argument podajte ime bloka:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Brez tega klic sproži napako bs.fn: block name required.
Obravnava napak
bs.fn() razreši obljubo z razčlenjenim telesom JSON ne glede na stanje HTTP. Ko funkcija vrne WP_Error, se obljuba razreši z objektom, ki vsebuje njegovo code, message in data, zato preverite vrednost code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Obljuba je zavrnjena le, če zahteva sama spodleti ali odgovor ni JSON.
Z Interactivity API
RPC se naravno povezuje z WordPress Interactivity API. Dejanja shrambe kličejo strežniške funkcije in posodobijo reaktivno stanje z odgovorom. UI se posodobi samodejno:
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>
Nadzor dostopa
Funkcije privzeto zahtevajo preverjenega uporabnika (prijavljenega uporabnika). To sledi konvencijam WordPress, po katerih so končne točke REST privzeto zaščitene.
Javne funkcije
Dovolite dostop brez preverjanja pristnosti z zaščito CSRF:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Predpomnjene strani
bs.fn() pridobi sveže poverilnice iz nepredpomnjene končne točke POST /wp-json/blockstudio/v1/client/credentials istega izvora. Žetoni nonce WordPress in žetoni CSRF Blockstudio s časovno omejeno veljavnostjo niso shranjeni v predpomnilniku strani HTML, zato javni klici še naprej delujejo, ko zunanji predpomnilnik strani postreže HTML, starejšo od 24 ur.
Osveževanje je odloženo: nalaganje strani brez klica API ne sproži zahteve za poverilnice. RPC in odjemalci zbirke podatkov uporabljajo isto osvežitev, obnovijo poverilnice po petih minutah uporabe in enkrat ponovijo poskus, če je žeton nonce ali CSRF potekel. Pri napakah zmožnosti in napakah aplikacije se poskus ne ponovi. Preverjanje pristnosti še naprej uporablja prijavni piškotek WordPress trenutnega obiskovalca; osveževanje poverilnic ne omogoča dostopa do zasebnih funkcij. Končno točko za poverilnice hranite zunaj predpomnilnika CDN ali posredniškega strežnika; njeni odgovori so izrecno označeni z private, no-store.
Odprte funkcije
Za spletne kljuke ali povratne klice API od zunaj, ki potrebujejo povsem odprt dostop brez žetona:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Zmogljivosti
Dostop omejite na izbrane zmogljivosti WordPress. Za eno zmogljivost uporabite niz, za več pa polje, če uporabnik potrebuje katero koli od njih:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Metode HTTP
Funkcije privzeto sprejemajo samo zahteve POST. To je najvarnejša privzeta nastavitev za operacije, ki spreminjajo stanje. Po potrebi dovolite tudi druge metode:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Klicanje med bloki
Iz JavaScript
Vsak blok lahko kliče funkcije katerega koli drugega bloka tako, da ime bloka poda kot tretji argument. Tako lahko sestavljate bloke:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Iz PHP
Za klice med bloki na strežniku uporabite Rpc::call(). To je uporabno, ko mora funkcija RPC usklajevati klice drugih blokov:
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];
},
];
Končna točka REST
V ozadju je vsaka funkcija povezana s potjo REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Telo zahteve: { "params": { ... } }
Odgovor: Vrnjena vrednost funkcije PHP v obliki JSON.
Te končne točke lahko pokličete neposredno iz katerega koli odjemalca HTTP, vendar je priporočeni način bs.fn(), saj samodejno poskrbi za avtentikacijo nonce.
Kavlji
Dejanja se sprožijo pred vsakim klicem RPC in po njem, tako iz REST kot iz PHP. Vsi kavlji prejmejo eno samo polje $params:
| Kavelj | Parametri |
|---|---|
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.
});
Filtriranje
Programsko spreminjajte ali dodajajte funkcije od zunaj bloka:
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;
});
Kdaj uporabiti RPC in kdaj podatkovno bazo
db.php samodejno ustvari končne točke CRUD iz sheme. Uporabite ga za standardne operacije ustvarjanja, branja, posodabljanja in brisanja s preverjanjem veljavnosti.
rpc.php je namenjen logiki po meri: pošiljanju e-pošte, klicanju zunanjih API-jev,
združevanju podatkov iz več shem, izvajanju zapletenih poizvedb ali vsemu, kar ne sodi v vzorec CRUD.
Sistema sta neodvisna in se dopolnjujeta. Številni bloki uporabljajo oba: db.php za podatkovni model in rpc.php za poslovno logiko, ki temelji na njem.