RPC
RPC (Remote Procedure Call) umožňuje definovať funkcie PHP vo svojom bloku a volať
ich z frontendu. Namiesto ručnej registrácie trás REST API,
vytvárania radičov a prepájania volaní fetch napíšete funkciu v
rpc.php a zavoláte ju pomocou bs.fn(). Blockstudio sa postará o smerovanie koncových bodov,
overenie, validáciu nonce a serializáciu JSON.
Tento vzor je inšpirovaný tRPC: definujte procedúry
na strane servera a volajte ich z klienta pomocou typovaného pomocného nástroja. Žiadne vytváranie URL,
žiadny ručný pomocný kód fetch.
Ako to funguje
- Vytvoríte
rpc.phpv priečinku svojho bloku - Vráti asociatívne pole pomenovaných funkcií
- Blockstudio zaregistruje koncový bod REST pre každú funkciu
- Klient
bs.fn()ich volá podľa názvu - Odovzdajú sa parametre a vráti sa JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definovanie funkcií
Každý kľúč vo vrátenom poli predstavuje názov funkcie. Najjednoduchšou formou je priame spätné volanie:
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];
},
];
Každá funkcia dostáva jedno pole $params a mala by vrátiť pole.
Návratová hodnota sa klientovi odošle ako JSON.
Ak chcete nastaviť možnosti riadenia prístupu, použite rozšírený formát s callback a
ďalšími kľúčmi:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definície v štýle PHP
Ak uprednostňujete metadáta PHP namiesto vnorených polí, rpc.php môže vrátiť
aj objekt s metódami označenými atribútmi. Polia fungujú naďalej rovnako.
<?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];
}
};
Poznámky:
- Názvy metód sa predvolene normalizujú na malé písmená a formát snake case, takže
getStatus()sa zmení naget_status - Pomocou
name:môžete výslovne nastaviť názov koncového bodu Access::Sessionzodpovedá pôvodnému správaniu'public' => trueAccess::Openzodpovedá pôvodnému správaniu'public' => 'open'- Ak chcete zachovať predvolené správanie, ktoré povoľuje prístup len overeným používateľom, vynechajte
access:
Volanie z JavaScript
Blockstudio automaticky vloží pomocnú funkciu bs.fn() na stránky, ktoré obsahujú bloky s funkciami RPC.
Signatúra: bs.fn(functionName, params?, blockName?) -> Promise
Odovzdanie názvu bloku
Ak vynecháte tretí argument, bs.fn() použije ako náhradnú hodnotu atribút data-block z document.currentScript.
Blockstudio vypisuje script.js aj vložené skripty (script-inline.js alebo script.inline.js) ako
značky <script type="module">. Modulové skripty nemajú atribút document.currentScript, preto v blokových skriptoch odovzdajte názov bloku ako tretí argument:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Bez neho volanie vyvolá bs.fn: block name required.
Spracovanie chýb
bs.fn() sa vyrieši s parsovaným telom JSON bez ohľadu na stav HTTP. Ak funkcia vráti WP_Error, prísľub sa vyrieši objektom obsahujúcim jeho code, message a data, preto kontrolujte code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Prísľub sa zamietne len vtedy, ak samotná požiadavka zlyhá alebo odpoveď nie je JSON.
S Interactivity API
RPC prirodzene spolupracuje s WordPress Interactivity API. Akcie vášho úložiska volajú funkcie servera a aktualizujú reaktívny stav podľa odpovede. UI sa aktualizuje automaticky:
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>
Riadenie prístupu
Funkcie predvolene vyžadujú overeného (prihláseného) používateľa. To zodpovedá konvenciám WordPress, podľa ktorých sú koncové body REST predvolene chránené.
Verejné funkcie
Povoľte prístup bez overenia s ochranou proti CSRF:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Cachované stránky
bs.fn() získava čerstvé prihlasovacie údaje z necachovaného koncového bodu POST /wp-json/blockstudio/v1/client/credentials na rovnakej doméne. Nonce WordPress a CSRF tokeny Blockstudio s obmedzenou platnosťou sa neukladajú do HTML stránky, takže verejné volania naďalej fungujú, keď externá vyrovnávacia pamäť stránky poskytne HTML staršiu ako 24 hodín.
Obnovenie prebieha podľa potreby: načítanie stránky bez volania API nevyvolá požiadavku na prihlasovacie údaje. RPC a databázoví klienti zdieľajú obnovenie, obnovujú prihlasovacie údaje po piatich minútach používania a pri neplatnom nonce alebo CSRF tokene požiadavku raz zopakujú. Chyby oprávnení a chyby aplikácie sa neopakujú. Prihlasovanie sa naďalej riadi súborom cookie WordPress aktuálneho návštevníka; obnovenie prihlasovacích údajov neposkytuje prístup k súkromným funkciám. Koncový bod prihlasovacích údajov ponechajte mimo každej vyrovnávacej pamäte CDN alebo proxy; jeho odpovede sú výslovne označené ako private, no-store.
Otvorené funkcie
Pre webhooky alebo externé spätné volania API, ktoré vyžadujú úplne otvorený prístup bez akéhokoľvek prístupového tokenu:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Oprávnenia
Obmedzte prístup na konkrétne oprávnenia WordPress. Pre jedno oprávnenie použite reťazec, alebo pole, ak používateľ potrebuje ktorékoľvek z nich:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Metódy HTTP
Funkcie predvolene prijímajú iba požiadavky POST. Je to najbezpečnejšia predvolená voľba
pre operácie, ktoré menia stav. Podľa potreby povoľte ďalšie metódy:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Volanie naprieč blokmi
Z JavaScript
Každý blok môže volať funkcie ľubovoľného iného bloku, ak ako tretí argument odovzdá názov bloku. To umožňuje prepájať bloky:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Z PHP
Na volanie medzi blokmi na strane servera použite Rpc::call(). Hodí sa to, keď funkcia RPC potrebuje koordinovať volania iných 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];
},
];
Koncový bod REST
V zákulisí sa každá funkcia mapuje na trasu REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Telo požiadavky: { "params": { ... } }
Odpoveď: Návratová hodnota funkcie PHP vo formáte JSON.
Tieto koncové body môžete volať priamo z ľubovoľného klienta HTTP, odporúčaný spôsob je však bs.fn(), pretože automaticky zabezpečuje overenie nonce.
Háčiky
Akcie sa spúšťajú pred každým volaním RPC aj po ňom, a to z REST aj z PHP. Všetky háčiky
prijímajú jedno pole $params:
| Háčik | Parametre |
|---|---|
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.
});
Filter
Programovo upravujte alebo pridávajte funkcie zvonka bloku:
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;
});
Kedy použiť RPC namiesto databázy
db.php automaticky generuje koncové body CRUD
zo schémy. Použite ho, keď potrebujete štandardné operácie vytvárania, čítania, aktualizácie a odstraňovania
s validáciou.
rpc.php slúži na vlastnú logiku: odosielanie e-mailov, volanie externých API,
agregovanie dát naprieč schémami, spúšťanie zložitých dopytov alebo čokoľvek,
čo nezodpovedá vzoru CRUD.
Tieto dva systémy sú nezávislé a navzájom sa dopĺňajú. Mnohé bloky používajú oba: db.php
pre dátový model a rpc.php pre obchodnú logiku nad ním.