RPC
RPC (Remote Procedure Call) låter dig definiera PHP-funktioner i ditt block och anropa
dem från frontend. I stället för att manuellt registrera REST-API-rutter,
skapa styrenheter och koppla ihop fetch-anrop skriver du en funktion i
rpc.php och anropar den med bs.fn(). Blockstudio hanterar routningen av slutpunkter,
autentisering, nonce-validering och JSON-serialisering.
Mönstret är inspirerat av tRPC: definiera procedurerna
på serversidan och anropa dem från klienten med en typad hjälpfunktion. Ingen konstruktion av URL,
inget manuellt fetch-standardarbete.
Så fungerar det
- Du skapar
rpc.phpi blockkatalogen - Den returnerar en associativ array med namngivna funktioner
- Blockstudio registrerar en REST-slutpunkt för varje funktion
bs.fn()-klienten anropar dem med namn- Parametrar skickas in, JSON kommer ut
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definiera funktioner
Varje nyckel i den returnerade arrayen är ett funktionsnamn. Den enklaste formen är en direkt återanropsfunktion:
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];
},
];
Varje funktion får en enda $params-array och ska returnera en array.
Returvärdet skickas till klienten som JSON.
Använd det utökade formatet med callback
och ytterligare nycklar för åtkomstkontroll:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definitioner för PHP
Om du föredrar PHP-inbyggd metadata framför nästlade arrayer kan rpc.php också returnera
ett objekt med attributförsedda metoder. Arrayer fungerar fortfarande på samma sätt.
<?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];
}
};
Observera:
- Metodnamn normaliseras som standard till gemener med snake case, så
getStatus()blirget_status - Använd
name:för att uttryckligen ange slutpunktens namn Access::Sessionmotsvarar det gamla beteendet för'public' => trueAccess::Openmotsvarar det gamla beteendet för'public' => 'open'- Utelämna
access:för standardbeteendet, där endast autentiserade användare tillåts
Anropa från JavaScript
Blockstudio lägger automatiskt till en hjälpfunktion för bs.fn() på sidor med block som har RPC-funktioner.
Signatur: bs.fn(functionName, params?, blockName?) -> Promise
Ange blockets namn
bs.fn() använder attributet data-block för document.currentScript
om det tredje argumentet utelämnas. Blockstudio skriver ut både script.js och
inline-skript (script-inline.js eller script.inline.js) som
<script type="module">-taggar, och modulskript saknar document.currentScript. Ange därför blockets namn som tredje
argument i blockskript:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Utan det ger anropet felet bs.fn: block name required.
Felhantering
bs.fn() löses med den parsade svarskroppen i JSON oavsett HTTP-status. När
en funktion returnerar ett WP_Error löses löftet med ett objekt som innehåller dess
code, message och data. Kontrollera därför code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Löftet avvisas bara när själva begäran misslyckas eller svaret inte är JSON.
Med Interactivity API
RPC passar naturligt ihop med WordPress Interactivity API. Åtgärder i din lagring anropar serverfunktioner och uppdaterar reaktivt tillstånd med svaret. UI uppdateras automatiskt:
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>
Åtkomstkontroll
Som standard kräver funktioner en autentiserad (inloggad) användare. Det följer WordPress-konventioner, där REST-slutpunkter skyddas som standard.
Publika funktioner
Tillåt åtkomst utan autentisering med CSRF-skydd:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Cachade sidor
bs.fn() hämtar nya inloggningsuppgifter från slutpunkten POST /wp-json/blockstudio/v1/client/credentials med samma ursprung, som inte cachas. Utgående WordPress-nonce och Blockstudio CSRF-token lagras inte i sidans HTML, så offentliga anrop fortsätter att fungera när en extern sidcache visar HTML som är äldre än 24 timmar.
Uppdateringen sker vid behov: om du laddar en sida utan att anropa en API görs ingen förfrågan om inloggningsuppgifter. RPC och databasklienterna delar på uppdateringen, förnyar uppgifterna efter fem minuters användning och gör ett nytt försök vid utgången nonce eller CSRF-token. Behörighetsfel och programfel leder inte till nya försök. Autentiseringen följer fortfarande den aktuella besökarens inloggningscookie för WordPress. Att uppgifterna uppdateras ger inte åtkomst till privata funktioner. Placera slutpunkten för inloggningsuppgifter utanför alla cachelagringar för CDN eller proxyservrar. Svaren är uttryckligen märkta private, no-store.
Öppna funktioner
För webhookar eller externa API-återanrop som behöver helt öppen åtkomst utan någon token:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Behörigheter
Begränsa till specifika WordPress-behörigheter. Använd en sträng för en enda behörighet eller en array om användaren behöver ha minst en av dem:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Metoder för HTTP
Som standard accepterar funktioner bara POST-begäranden. Det är det säkraste standardvalet
för åtgärder som ändrar tillstånd. Tillåt ytterligare metoder vid behov:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Anrop mellan block
Från JavaScript
Alla block kan anropa funktioner i andra block genom att ange blockets namn som ett tredje argument. Det gör att block kan samverka:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Från PHP
Använd Rpc::call() för anrop mellan block på serversidan. Det är användbart när en
RPC-funktion behöver samordna anrop till andra block:
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-slutpunkt
I bakgrunden mappas varje funktion till en REST-rutt:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Begärandekropp: { "params": { ... } }
Svar: Returvärdet från funktionen PHP som JSON.
Du kan anropa dessa slutpunkter direkt från valfri HTTP-klient, men bs.fn() rekommenderas eftersom den hanterar nonce-autentisering automatiskt.
Hooks
Åtgärder körs före och efter varje RPC-anrop, både från REST och PHP. Alla hooks
får en enda $params-array:
| Hook | Parametrar |
|---|---|
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
Ändra eller lägg till funktioner programmatiskt utifrån blocket:
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;
});
När du ska använda RPC respektive databas
db.php genererar automatiskt CRUD-slutpunkter
från ett schema. Använd det när du behöver standardoperationer för att skapa, läsa, uppdatera och ta bort
med validering.
rpc.php är till för anpassad logik: skicka e-post, anropa externa API:er,
sammanställa data från flera scheman, köra komplexa frågor eller hantera sådant som
inte passar CRUD-mönstret.
Systemen är oberoende och kompletterar varandra. Många block använder båda: db.php
för datamodellen och rpc.php för affärslogiken ovanpå den.