RPC
RPC (Remote Procedure Call) laat je PHP-functies definiëren in je blok en aanroepen vanuit de frontend. In plaats van handmatig REST-API-routes te registreren, controllers te maken en fetch-aanroepen in te stellen, schrijf je een functie in rpc.php en roep je die aan met bs.fn(). Blockstudio regelt de routering van eindpunten, authenticatie, nonce-validatie en JSON-serialisatie.
Dit patroon is geïnspireerd op tRPC: definieer procedures aan de serverzijde en roep ze aan vanaf de client met een getypeerde helper. Geen URL-constructie en geen handmatige fetch-standaardcode.
Werking
- Je maakt
rpc.phpin je blokmap - Dit retourneert een associatieve array met benoemde functies
- Blockstudio registreert voor elke functie een REST-eindpunt
- De
bs.fn()-client roept ze op naam aan - Parameters gaan erin, JSON komt eruit
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Functies definiëren
Elke sleutel in de geretourneerde array is een functienaam. De eenvoudigste vorm is een directe callback:
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];
},
];
Elke functie ontvangt één $params-array en moet een array retourneren. De retourwaarde wordt als JSON naar de client verzonden.
Gebruik voor opties voor toegangsbeheer de uitgebreide notatie met callback en aanvullende sleutels:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP-native definities
Als je de voorkeur geeft aan PHP-eigen metadata in plaats van geneste arrays, kan rpc.php ook een object met methoden voorzien van attributen retourneren. Arrays werken nog precies hetzelfde.
<?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];
}
};
Opmerkingen:
- Methodenamen worden standaard genormaliseerd naar kleine letters met snake_case, dus
getStatus()wordtget_status - Gebruik
name:om de naam van het eindpunt expliciet te overschrijven Access::Sessionkomt overeen met het oude gedrag van'public' => trueAccess::Openkomt overeen met het oude gedrag van'public' => 'open'- Laat
access:weg voor het standaardgedrag waarbij alleen geauthenticeerde gebruikers toegang hebben
Aanroepen vanuit JavaScript
Blockstudio voegt automatisch een bs.fn()-helper toe op pagina’s met blokken die RPC-functies hebben.
Signatuur: bs.fn(functionName, params?, blockName?) -> Promise
De bloknaam doorgeven
bs.fn() valt terug op het attribuut data-block van document.currentScript als je het derde argument weglaat. Blockstudio geeft zowel script.js als inline scripts (script-inline.js of script.inline.js) weer als <script type="module">-tags, en modulescripts hebben geen document.currentScript. Geef daarom in blokscripts de bloknaam op als derde argument:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Zonder dit argument geeft de aanroep bs.fn: block name required een fout.
Foutafhandeling
bs.fn() lost op met de geparseerde JSON-body, ongeacht de HTTP-status. Als een functie een WP_Error retourneert, lost de promise op met een object met daarin de code, message en data. Controleer daarom op code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
De promise wordt alleen afgewezen als het verzoek zelf mislukt of als de reactie niet JSON is.
Met de Interactivity API
RPC werkt goed samen met WordPress Interactivity API. De acties in je winkel roepen serverfuncties aan en werken de reactieve status bij met het antwoord. De UI wordt automatisch bijgewerkt:
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>
Toegangsbeheer
Standaard vereisen functies een geauthenticeerde (ingelogde) gebruiker. Dit sluit aan bij de conventies van WordPress, waarbij REST-eindpunten standaard zijn beveiligd.
Openbare functies
Sta niet-geauthenticeerde toegang toe met CSRF-bescherming:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Gecachete pagina’s
bs.fn() haalt actuele inloggegevens op bij het niet-gecachete endpoint van dezelfde oorsprong POST /wp-json/blockstudio/v1/client/credentials. Verlopende WordPress-nonces en Blockstudio-CSRF-tokens worden niet opgeslagen in de paginacache HTML, zodat openbare aanroepen blijven werken wanneer een externe paginacache HTML serveert die ouder is dan 24 uur.
Vernieuwing gebeurt op verzoek: een pagina laden zonder een API aan te roepen, leidt niet tot een aanvraag voor inloggegevens. RPC en databaseclients delen de vernieuwing, vernieuwen inloggegevens na vijf minuten gebruik en proberen het eenmaal opnieuw bij een verlopen nonce of CSRF-token. Bevoegdheidsfouten en toepassingsfouten worden niet opnieuw geprobeerd. Authenticatie blijft de aanmeldcookie van de huidige bezoeker WordPress volgen; het vernieuwen van inloggegevens geeft geen toegang tot privéfuncties. Houd het endpoint voor inloggegevens buiten elke CDN- of proxycache; de reacties zijn expliciet gemarkeerd als private, no-store.
Open functies
Voor webhooks of externe API-callbacks waarvoor volledig open toegang zonder token nodig is:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Machtigingen
Beperk de toegang tot specifieke WordPress-machtigingen. Gebruik een string voor één machtiging of een array als de gebruiker er slechts één nodig heeft:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP-methoden
Standaard accepteren functies alleen POST-verzoeken. Dit is de veiligste standaard voor bewerkingen die de status wijzigen. Sta zo nodig aanvullende methoden toe:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Aanroepen tussen blokken
Vanuit JavaScript
Elk blok kan functies van elk ander blok aanroepen door de bloknaam als derde argument door te geven. Zo kun je blokken combineren:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Vanuit PHP
Gebruik Rpc::call() voor aanroepen tussen blokken aan de serverzijde. Dit is handig wanneer een RPC-functie aanroepen naar andere blokken moet coördineren:
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];
},
];
REST-eindpunt
Achter de schermen wordt elke functie gekoppeld aan een REST-route:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Request-body: { "params": { ... } }
Reactie: De retourwaarde van de PHP-functie als JSON.
Je kunt deze eindpunten rechtstreeks vanuit elke HTTP-client aanroepen, maar bs.fn() is de aanbevolen manier, omdat die nonce-authenticatie automatisch afhandelt.
Hooks
Acties worden uitgevoerd vóór en na elke RPC-aanroep, zowel vanuit REST als vanuit PHP. Alle hooks ontvangen één $params-array:
| Hook | Parameters |
|---|---|
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
Wijzig of voeg programmatisch functies toe van buiten het blok:
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;
});
Wanneer gebruik je RPC en wanneer de database?
db.php genereert automatisch CRUD-eindpunten op basis van een schema. Gebruik dit voor standaardbewerkingen voor maken, lezen, bijwerken en verwijderen, met validatie.
rpc.php is bedoeld voor aangepaste logica: e-mails versturen, externe API’s aanroepen, gegevens uit meerdere schema’s samenvoegen, complexe query’s uitvoeren of andere taken die niet in het CRUD-patroon passen.
De twee systemen zijn onafhankelijk en vullen elkaar aan. Veel blokken gebruiken ze allebei: db.php voor het gegevensmodel en rpc.php voor de bedrijfslogica erbovenop.