RPC
RPC (Remote Procedure Call) umožňuje definovat funkce PHP v bloku a volat je z frontendu. Místo ruční registrace tras REST API, vytváření kontrolerů a propojování volání fetch napíšete funkci v rpc.php a zavoláte ji pomocí bs.fn(). Blockstudio se postará o směrování endpointů, ověřování, ověření nonce a serializaci JSON.
Tento vzor je inspirován tRPC: procedury definujete na serveru
a voláte je z klienta pomocí typovaného pomocníka. Žádné vytváření URL
ani ruční základní kód fetch.
Jak to funguje
- V adresáři bloku vytvoříte
rpc.php - Vrátí asociativní pole pojmenovaných funkcí
- Blockstudio zaregistruje endpoint REST pro každou funkci
- Klient
bs.fn()je volá podle názvu - Předají se parametry a vrátí se JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definování funkcí
Každý klíč ve vráceném poli představuje název funkce. Nejjednodušší je přímé zpětné volání:
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á funkce dostává jedno pole $params a měla by vrátit pole.
Návratová hodnota se klientovi odešle jako JSON.
Pro nastavení řízení přístupu použijte rozšířený formát s callback
a dalšími klíči:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definice nativní pro PHP
Pokud místo vnořených polí upřednostňujete metadata nativní pro PHP, rpc.php může také vrátit
objekt s metodami opatřenými atributy. Pole fungují stále stejně.
<?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 metod se ve výchozím nastavení převádějí na malá písmena ve formátu snake case, takže
getStatus()se změní naget_status - Pomocí
name:můžete výslovně přepsat název endpointu Access::Sessionodpovídá dřívějšímu chování'public' => trueAccess::Openodpovídá dřívějšímu chování'public' => 'open'- Vynecháním
access:zachováte výchozí chování, které povoluje pouze ověřené uživatele
Volání z JavaScript
Blockstudio automaticky vloží pomocnou funkci bs.fn() na stránky obsahující bloky s funkcemi RPC.
Signatura: bs.fn(functionName, params?, blockName?) -> Promise
Předání názvu bloku
Pokud vynecháte třetí argument, bs.fn() použije jako náhradní hodnotu atribut data-block v document.currentScript.
Blockstudio vypisuje oba script.js i inline skripty (script-inline.js nebo script.inline.js) jako
značky <script type="module"> a modulové skripty nemají document.currentScript, proto ve skriptech bloků předejte název bloku jako třetí argument:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Bez něj volání vyvolá bs.fn: block name required.
Ošetření chyb
bs.fn() se vyřeší s naparsovaným tělem JSON bez ohledu na stav HTTP. Když funkce vrátí WP_Error, příslib se vyřeší objektem obsahujícím jeho code, message a data, proto kontrolujte code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Příslib se zamítne pouze v případě, že samotný požadavek selže nebo odpověď není JSON.
S modulem Interactivity API
RPC přirozeně spolupracuje s WordPress Interactivity API. Akce ve vašem obchodě volají serverové funkce a aktualizují reaktivní stav podle odpovědi. UI se 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>
Řízení přístupu
Funkce ve výchozím nastavení vyžadují ověřeného (přihlášeného) uživatele. To odpovídá konvencím WordPress, kde jsou endpointy REST ve výchozím nastavení chráněné.
Veřejné funkce
Povolte přístup bez ověření s ochranou 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ískává aktuální přihlašovací údaje z necachovaného endpointu POST /wp-json/blockstudio/v1/client/credentials na stejném originu. Nonce WordPress s omezenou platností a CSRF tokeny Blockstudio se neukládají do HTML stránky, takže veřejná volání fungují dál, i když externí cache stránky poskytuje HTML starší než 24 hodin.
Obnovení probíhá až na vyžádání: načtení stránky bez volání API nevyvolá požadavek na přihlašovací údaje. RPC a databázoví klienti sdílejí proces obnovení, obnovují přihlašovací údaje po pěti minutách používání a při vypršení nonce nebo CSRF tokenu požadavek jednou zopakují. Chyby oprávnění a chyby aplikace se neopakují. Ověření stále probíhá pomocí přihlašovací cookie WordPress aktuálního návštěvníka; obnovení přihlašovacích údajů nezpřístupní soukromé funkce. Endpoint s přihlašovacími údaji umístěte mimo cache CDN i proxy; jeho odpovědi jsou výslovně označené jako private, no-store.
Otevřené funkce
Pro webhooky nebo externí zpětná volání API, která potřebují zcela otevřený přístup bez jakéhokoli ověřovacího tokenu:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Oprávnění
Omezte přístup na konkrétní oprávnění WordPress. Pro jedno oprávnění použijte řetězec, nebo pole, pokud uživateli stačí kterékoli 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'],
],
];
Metody HTTP
Funkce ve výchozím nastavení přijímají pouze požadavky POST. To je nejbezpečnější výchozí nastavení
pro operace, které mění stav. Podle potřeby povolte další metody:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Volání napříč bloky
Z JavaScript
Každý blok může volat funkce jiného bloku předáním názvu bloku jako třetího argumentu. To umožňuje skládat bloky dohromady:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Z PHP
Pro volání napříč bloky na straně serveru použijte Rpc::call(). Hodí se, když jedna
funkce RPC potřebuje koordinovat volání dalších bloků:
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];
},
];
Endpoint REST
Na pozadí se každá funkce mapuje na trasu REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Tělo požadavku: { "params": { ... } }
Odpověď: Návratová hodnota funkce PHP jako JSON.
Tyto endpointy můžete volat přímo z libovolného klienta HTTP, doporučený způsob je však bs.fn(), protože automaticky zajišťuje ověření nonce.
Hooky
Akce se spouštějí před každým voláním RPC i po něm, a to z REST i PHP. Všechny hooky
dostávají jedno pole $params:
| Hook | Parametry |
|---|---|
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.
});
Filtr
Programově upravujte nebo přidávejte funkce zvenčí 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;
});
Kdy použít RPC a kdy databázi
db.php automaticky generuje z definice schématu endpointy CRUD. Použijte ho, pokud potřebujete standardní operace vytvoření, čtení, aktualizace a odstranění s validací.
rpc.php slouží pro vlastní logiku: odesílání e-mailů, volání externích API,
agregaci dat napříč schématy, spouštění složitých dotazů nebo cokoli, co
neodpovídá vzoru CRUD.
Oba systémy jsou nezávislé a vzájemně se doplňují. Mnoho bloků používá oba: db.php
pro datový model a rpc.php pro obchodní logiku nad ním.