RPC
RPC (Remote Procedure Call) vă permite să definiți funcții PHP în bloc și să le apelați
din frontend. În loc să înregistrați manual rute REST API,
să creați controlere și să conectați apeluri fetch, scrieți o funcție în
rpc.php și o apelați cu bs.fn(). Blockstudio gestionează rutarea endpoint-urilor,
autentificarea, validarea nonce și serializarea JSON.
Modelul este inspirat de tRPC: definiți procedurile pe server,
apoi le apelați din client cu un ajutor tipizat. Fără construirea URL,
fără cod boilerplate fetch scris manual.
Cum funcționează
- Creați
rpc.phpîn directorul blocului - Returnează un array asociativ cu funcții denumite
- Blockstudio înregistrează un endpoint REST pentru fiecare funcție
- Clientul
bs.fn()le apelează după nume - Parametrii intră, iar JSON iese
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definirea funcțiilor
Fiecare cheie din array-ul returnat este numele unei funcții. Cea mai simplă formă este un callback direct:
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];
},
];
Fiecare funcție primește un singur array $params și ar trebui să returneze un array.
Valoarea returnată este trimisă clientului ca JSON.
Pentru opțiunile de control al accesului, folosiți formatul extins cu callback și
chei suplimentare:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definiții native pentru PHP
Dacă preferați metadatele native PHP în locul array-urilor imbricate, rpc.php poate returna
și un obiect cu metode adnotate. Array-urile funcționează în continuare exact la fel.
<?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];
}
};
Note:
- Numele metodelor sunt normalizate implicit la litere mici și format snake case, astfel că
getStatus()devineget_status - Folosiți
name:pentru a suprascrie explicit numele endpoint-ului Access::Sessioncorespunde comportamentului vechi'public' => trueAccess::Opencorespunde comportamentului vechi'public' => 'open'- Omiteți
access:pentru comportamentul implicit, doar cu autentificare
Apelarea din JavaScript
Blockstudio injectează automat un ajutor bs.fn() în paginile care au blocuri cu funcții RPC.
Semnătură: bs.fn(functionName, params?, blockName?) -> Promise
Transmiterea numelui blocului
bs.fn() folosește ca valoare de rezervă atributul data-block al document.currentScript
când omiteți al treilea argument. Blockstudio afișează atât script.js, cât și
scripturile inline (script-inline.js sau script.inline.js) ca etichete
<script type="module">, iar scripturile modul nu au document.currentScript, așa că în scripturile blocurilor transmiteți numele blocului ca al treilea
argument:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Fără acesta, apelul generează bs.fn: block name required.
Tratarea erorilor
bs.fn() se rezolvă cu corpul JSON analizat, indiferent de starea HTTP. Când
o funcție returnează un WP_Error, promisiunea se rezolvă cu un obiect care conține
code, message și data, așa că verificați code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Promisiunea este respinsă doar când cererea eșuează sau răspunsul nu este JSON.
Cu API Interactivity
RPC se combină în mod natural cu WordPress Interactivity API. Acțiunile din magazinul vostru apelează funcții de pe server și actualizează starea reactivă cu răspunsul. UI se actualizează automat:
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>
Controlul accesului
Implicit, funcțiile necesită un utilizator autentificat (conectat). Acest lucru corespunde convențiilor WordPress, conform cărora endpoint-urile REST sunt protejate implicit.
Funcții publice
Permiteți accesul neautentificat cu protecție CSRF:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Pagini cache-uite
bs.fn() obține acreditări noi de la punctul final POST /wp-json/blockstudio/v1/client/credentials de aceeași origine, necache-uit. Nonce-urile WordPress cu expirare și tokenurile CSRF Blockstudio nu sunt stocate în HTML paginii, astfel încât apelurile publice continuă să funcționeze când un cache extern servește HTML mai vechi de 24 de ore.
Reîmprospătarea este întârziată: încărcarea unei pagini fără apelarea unui API nu declanșează o solicitare de acreditări. RPC și clienții bazei de date folosesc împreună reîmprospătarea, reînnoiesc acreditările după cinci minute de utilizare și reîncearcă o singură dată în cazul unui nonce sau token CSRF expirat. Erorile de capabilitate și erorile aplicației nu sunt reîncercate. Autentificarea folosește în continuare cookie-ul de conectare WordPress al vizitatorului curent; reîmprospătarea acreditărilor nu acordă acces la funcții private. Păstrați punctul final pentru acreditări în afara oricărui cache CDN sau de proxy; răspunsurile sale sunt marcate explicit private, no-store.
Funcții deschise
Pentru webhook-uri sau callback-uri API externe care au nevoie de acces cu adevărat deschis, fără niciun token:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Capabilități
Restricționați accesul la anumite capabilități WordPress. Folosiți un șir pentru o singură capabilitate sau un array dacă utilizatorul poate avea nevoie de oricare dintre ele:
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
Implicit, funcțiile acceptă doar cereri POST. Acesta este cel mai sigur comportament implicit
pentru operațiunile care modifică starea. Permiteți și alte metode când este necesar:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Apeluri între blocuri
Din JavaScript
Orice bloc poate apela funcții din oricare alt bloc, transmițând numele blocului ca al treilea argument. Astfel se pot compune blocuri:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Din PHP
Folosiți Rpc::call() pentru apeluri între blocuri pe server. Acest lucru este util când o funcție RPC
trebuie să coordoneze apeluri către alte blocuri:
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-ul REST
În culise, fiecare funcție este asociată unei rute REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Corpul cererii: { "params": { ... } }
Răspuns: Valoarea returnată de funcția PHP, ca JSON.
Puteți apela direct aceste endpoint-uri din orice client HTTP, dar bs.fn() este
metoda recomandată, deoarece gestionează automat autentificarea cu nonce.
Hook-uri
Acțiunile sunt declanșate înainte și după fiecare apel RPC, atât din REST, cât și din PHP. Toate hook-urile
primesc un singur array $params:
| Hook | 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.
});
Filtrare
Modificați sau adăugați funcții programatic din afara blocului:
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;
});
Când să folosiți RPC în loc de Database
db.php generează automat endpoint-uri CRUD
pe baza unei scheme. Folosiți-l când aveți nevoie de operațiuni standard de creare/citire/actualizare/ștergere,
cu validare.
rpc.php este destinat logicii personalizate: trimiterea de e-mailuri, apelarea API-urilor externe,
agregarea datelor între scheme, rularea de interogări complexe sau orice altceva care
nu se încadrează în modelul CRUD.
Cele două sisteme sunt independente și complementare. Multe blocuri le folosesc pe amândouă: db.php
pentru modelul de date și rpc.php pentru logica de business construită pe baza acestuia.