RPC
RPC (Remote Procedure Call) lader dig definere PHP-funktioner i din blok og kalde dem fra frontend. I stedet for manuelt at registrere REST-API-ruter, oprette controllere og koble fetch-kald sammen skriver du en funktion i rpc.php og kalder den med bs.fn(). Blockstudio håndterer rutetildeling til endpoints, godkendelse, nonce-validering og JSON-serialisering.
Mønstret er inspireret af tRPC: Definér procedurer på serversiden, og kald dem fra klienten med en typet hjælper. Ingen opbygning af URL og intet manuelt fetch-standardkode.
Sådan fungerer det
- Du opretter
rpc.phpi din blokmappe - Den returnerer et associativt array med navngivne funktioner
- Blockstudio registrerer et REST-endpoint for hver funktion
bs.fn()-klienten kalder dem ved navn- Parametre sendes ind, og JSON kommer ud
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definition af funktioner
Hver nøgle i det returnerede array er et funktionsnavn. Den enkleste form er et direkte 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];
},
];
Hver funktion modtager ét $params-array og bør returnere et array. Returværdien sendes til klienten som JSON.
Brug den udvidede form med callback og flere nøgler til adgangskontrol:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP-native definitioner
Hvis du foretrækker metadata, der er native i PHP, frem for indlejrede arrays, kan rpc.php også returnere et objekt med metoder forsynet med attributter. Arrays fungerer stadig præcis som før.
<?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];
}
};
Bemærk:
- Metodenavne normaliseres som standard til små bogstaver og snake case, så
getStatus()bliver tilget_status - Brug
name:til eksplicit at tilsidesætte endpoint-navnet Access::Sessionsvarer til den gamle'public' => true-adfærdAccess::Opensvarer til den gamle'public' => 'open'-adfærd- Udelad
access:for standardadfærden, hvor kun godkendte brugere har adgang
Kald fra JavaScript
Blockstudio indsætter automatisk en bs.fn()-helper på sider med blokke, der har RPC-funktioner.
Signatur: bs.fn(functionName, params?, blockName?) -> Promise
Angivelse af bloknavnet
bs.fn() bruger værdien af attributten data-block i document.currentScript som reserve, når det tredje argument udelades. Blockstudio udskriver både script.js og inline-scripts (script-inline.js eller script.inline.js) som <script type="module">-tags, og modul-scripts har ingen document.currentScript. Angiv derfor bloknavnet som det tredje argument i blok-scripts:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Uden det kaster kaldet bs.fn: block name required.
Fejlhåndtering
bs.fn() løses med den fortolkede JSON-body uanset HTTP-status. Når en funktion returnerer en WP_Error, løses promise med et objekt, der indeholder dens code, message og data. Kontrollér derfor code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Promise afvises kun, når selve anmodningen mislykkes, eller svaret ikke er JSON.
Med Interactivity-API
RPC passer naturligt sammen med WordPress Interactivity-API. Dine store-handlinger kalder serverfunktioner og opdaterer reaktiv tilstand med svaret. UI opdateres automatisk:
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>
Adgangskontrol
Som standard kræver funktioner en godkendt (indlogget) bruger. Det følger WordPress-konventionerne, hvor REST-endpoints som standard er beskyttet.
Offentlige funktioner
Tillad adgang uden godkendelse med CSRF-beskyttelse:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Cachelagrede sider
bs.fn() henter friske legitimationsoplysninger fra det ikke-cachelagrede
POST /wp-json/blockstudio/v1/client/credentials-endpoint med samme oprindelse. WordPress-nonces og Blockstudio-CSRF-tokens, der udløber,
gemmes ikke i sidens HTML, så offentlige kald fortsat fungerer, når en ekstern sidecache viser HTML, der er ældre end 24 timer.
Opdateringen sker efter behov: Indlæsning af en side uden et API-kald udløser ikke en anmodning om legitimationsoplysninger. RPC- og databaseklienter deler opdateringen, fornyer legitimationsoplysninger efter fem minutters brug og forsøger én gang til ved en udløbet nonce eller et udløbet CSRF-token. Fejl med rettigheder og programfejl forsøges ikke igen. Godkendelse følger stadig den aktuelle besøgendes login-cookie fra WordPress; opdatering af legitimationsoplysninger giver ikke adgang til private funktioner. Hold endpointet til legitimationsoplysninger uden for enhver CDN- eller proxycache; dets svar er eksplicit markeret som private, no-store.
Åbne funktioner
Til webhooks eller eksterne API-callbacks, der kræver helt åben adgang uden token:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Tilladelser
Begræns adgangen til bestemte WordPress-tilladelser. Brug en streng til en enkelt tilladelse eller et array, hvis brugeren skal have en hvilken som helst af dem:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP-metoder
Som standard accepterer funktioner kun POST-anmodninger. Det er den sikreste standard for handlinger, der ændrer tilstand. Tillad flere metoder efter behov:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Kald på tværs af blokke
Fra JavaScript
Alle blokke kan kalde funktioner i andre blokke ved at angive bloknavnet som det tredje argument. Det gør det muligt at kombinere blokke:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Fra PHP
Brug Rpc::call() til kald mellem blokke på serversiden. Det er nyttigt, når en RPC-funktion skal koordinere kald til andre blokke:
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-endpoint
Bag kulisserne knyttes hver funktion til en REST-rute:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Anmodningsbody: { "params": { ... } }
Svar: Returværdien fra funktionen PHP som JSON.
Du kan kalde disse endpoints direkte fra enhver HTTP-klient, men bs.fn() er den anbefalede metode, da den automatisk håndterer nonce-godkendelse.
Hooks
Handlinger udløses før og efter hvert RPC-kald, både fra REST og PHP. Alle hooks modtager ét $params-array:
| Hook | Parametre |
|---|---|
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.
});
Filtrering
Redigér eller tilføj funktioner programmatisk uden for blokken:
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;
});
Hvornår skal du bruge RPC eller Database?
db.php genererer automatisk CRUD-endpoints ud fra et skema. Brug det, når du har brug for standardhandlinger til oprettelse, læsning, opdatering og sletning med validering.
rpc.php bruges til brugerdefineret logik: afsendelse af e-mails, kald til eksterne API’er, sammenlægning af data på tværs af skemaer, kørsel af komplekse forespørgsler eller alt, der ikke passer til CRUD-mønstret.
De to systemer er uafhængige og supplerer hinanden. Mange blokke bruger begge: db.php til datamodellen og rpc.php til forretningslogikken oven på den.