RPC
RPC (Remote Procedure Call) consente di definire funzioni PHP nel blocco e chiamarle dal frontend. Invece di registrare manualmente route REST API, creare controller e configurare chiamate fetch, scrivete una funzione in rpc.php e chiamatela con bs.fn(). Blockstudio gestisce il routing degli endpoint, l’autenticazione, la convalida del nonce e la serializzazione JSON.
Lo schema si ispira a tRPC: definite le procedure lato server e chiamatele dal client con un helper tipizzato. Niente costruzione di URL, niente boilerplate fetch manuale.
Come funziona
- Create
rpc.phpnella directory del blocco - Restituisce un array associativo di funzioni con nome
- Blockstudio registra un endpoint REST per ogni funzione
- Il client
bs.fn()le chiama per nome - Si passano i parametri e si ottiene JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definizione delle funzioni
Ogni chiave dell’array restituito corrisponde al nome di una funzione. La forma più semplice usa una callback diretta:
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];
},
];
Ogni funzione riceve un unico array $params e dovrebbe restituire un array. Il valore restituito viene inviato al client come JSON.
Per le opzioni di controllo degli accessi, usate il formato esteso con callback e chiavi aggiuntive:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definizioni native per PHP
Se preferite metadati nativi di PHP invece di array annidati, rpc.php può restituire anche un oggetto con metodi dotati di attributi. Gli array continuano a funzionare nello stesso modo.
<?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:
- Per impostazione predefinita, i nomi dei metodi vengono convertiti in minuscolo e nel formato snake case; quindi
getStatus()diventaget_status - Usate
name:per specificare esplicitamente il nome dell’endpoint Access::Sessioncorrisponde al comportamento precedente di'public' => trueAccess::Opencorrisponde al comportamento precedente di'public' => 'open'- Omettete
access:per mantenere il comportamento predefinito, riservato agli utenti autenticati
Chiamate da JavaScript
Blockstudio inserisce automaticamente un helper bs.fn() nelle pagine che contengono blocchi con funzioni RPC.
Firma: bs.fn(functionName, params?, blockName?) -> Promise
Passaggio del nome del blocco
bs.fn() usa come valore predefinito l’attributo data-block di document.currentScript se omettete il terzo argomento. Blockstudio stampa sia script.js sia gli script inline (script-inline.js o script.inline.js) come tag <script type="module">, mentre gli script modulo non hanno document.currentScript; perciò negli script dei blocchi passate il nome del blocco come terzo argomento:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Senza questo, la chiamata genera un’eccezione bs.fn: block name required.
Gestione degli errori
bs.fn() restituisce il corpo JSON analizzato, qualunque sia lo stato HTTP. Se una funzione restituisce un WP_Error, la promise si risolve con un oggetto che contiene code, message e data; controllate quindi code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
La promise viene rifiutata solo se la richiesta non va a buon fine o la risposta non è JSON.
Con l’API Interattività
RPC si abbina naturalmente all’WordPress Interattività API. Le azioni del vostro store chiamano funzioni server e aggiornano lo stato reattivo con la risposta. L’UI si aggiorna automaticamente:
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>
Controllo degli accessi
Per impostazione predefinita, le funzioni richiedono un utente autenticato (connesso). Questo corrisponde alle convenzioni WordPress, secondo cui gli endpoint REST sono protetti per impostazione predefinita.
Funzioni pubbliche
Consentite l’accesso senza autenticazione con protezione CSRF:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Pagine memorizzate nella cache
bs.fn() recupera credenziali aggiornate dall’endpoint POST /wp-json/blockstudio/v1/client/credentials della stessa origine, escluso dalla cache. I nonce WordPress e i token CSRF Blockstudio in scadenza non vengono memorizzati nel HTML della pagina, quindi le chiamate pubbliche continuano a funzionare quando una cache esterna serve pagine HTML più vecchie di 24 ore.
L’aggiornamento è differito: caricare una pagina senza effettuare una chiamata API non genera una richiesta di credenziali. I client RPC e del database condividono l’aggiornamento, rinnovano le credenziali dopo cinque minuti di utilizzo e riprovano una volta in caso di nonce o token CSRF scaduto. Gli errori di capacità e gli errori dell’applicazione non vengono ritentati. L’autenticazione continua a seguire il cookie di accesso WordPress del visitatore corrente; aggiornare le credenziali non concede l’accesso alle funzioni private. Mantenete l’endpoint delle credenziali fuori da qualsiasi cache CDN o proxy; le relative risposte sono contrassegnate esplicitamente come private, no-store.
Funzioni aperte
Per webhook o callback API esterne che richiedono accesso completamente aperto, senza token:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Capacità
Limitate l’accesso a capacità WordPress specifiche. Usate una stringa per una singola capacità oppure un array se l’utente può averne una qualsiasi:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Metodi HTTP
Per impostazione predefinita, le funzioni accettano solo richieste POST. È l’impostazione più sicura per le operazioni che modificano lo stato. Se necessario, consentite anche altri metodi:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Chiamate tra blocchi
Da JavaScript
Qualsiasi blocco può chiamare funzioni di un altro blocco passando il nome del blocco come terzo argomento. In questo modo è possibile comporre blocchi diversi:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Da PHP
Usate Rpc::call() per le chiamate tra blocchi lato server. È utile quando una funzione RPC deve coordinare le chiamate ad altri blocchi:
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
Internamente, ogni funzione corrisponde a una route REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Corpo della richiesta: { "params": { ... } }
Risposta: il valore restituito dalla funzione PHP in formato JSON.
Potete chiamare direttamente questi endpoint da qualsiasi client HTTP, ma il metodo consigliato è bs.fn(), che gestisce automaticamente l’autenticazione tramite nonce.
Hook
Le azioni vengono eseguite prima e dopo ogni chiamata RPC, sia da REST sia da PHP. Tutti gli hook ricevono un unico 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.
});
Filtro
Modificate o aggiungete funzioni a livello di codice dall’esterno del blocco:
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;
});
Quando usare RPC o Database
db.php genera automaticamente endpoint CRUD da uno schema. Usatelo quando vi servono operazioni standard di creazione, lettura, aggiornamento ed eliminazione con convalida.
rpc.php serve per la logica personalizzata: inviare email, chiamare API esterne, aggregare dati di più schemi, eseguire query complesse o gestire qualsiasi operazione che non rientri nel modello CRUD.
I due sistemi sono indipendenti e complementari. Molti blocchi li usano entrambi: db.php per il modello dei dati e rpc.php per la logica di business che lo gestisce.