RPC
RPC (Remote Procedure Call) mahdollistaa PHP-funktioiden määrittämisen lohkossasi ja niiden kutsumisen käyttöliittymästä. Sen sijaan, että rekisteröisit REST API -reitit manuaalisesti, loisit ohjaimia ja kytkisit fetch-kutsut, kirjoitat funktion tiedostoon rpc.php ja kutsut sitä muodossa bs.fn(). Blockstudio huolehtii päätepisteiden reitityksestä, todennuksesta, nonce-tunnuksen tarkistuksesta ja JSON-sarjallistamisesta.
Toteutusmalli on saanut vaikutteita tRPC:stä: määritä proseduurit palvelimella ja kutsu niitä asiakkaalta tyypitetyllä apufunktiolla. Ei URL-konstruktoreita eikä manuaalista fetch-mallikoodia.
Näin se toimii
- Luot
rpc.php-tiedoston lohkohakemistoosi - Se palauttaa assosiatiivisen taulukon nimetyistä funktioista
- Blockstudio rekisteröi kullekin funktiolle REST-päätepisteen
bs.fn()-asiakas kutsuu niitä nimen perusteella- Parametrit lähetetään sisään, ja tuloksena saadaan JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Funktioiden määrittäminen
Jokainen palautetun taulukon avain on funktion nimi. Yksinkertaisin muoto on suora takaisinkutsu:
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];
},
];
Jokainen funktio saa yhden $params-taulukon ja sen pitäisi palauttaa taulukko. Palautusarvo lähetetään asiakkaalle muodossa JSON.
Käyttöoikeuksien hallinnan vaihtoehtoja varten käytä laajennettua muotoa, jossa on callback ja lisäavaimia:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP-natiivimääritykset
Jos haluat PHP-natiivin metatiedon sisäkkäisten taulukoiden sijaan, rpc.php voi palauttaa myös objektin, jolla on attribuuteilla merkityt metodit. Taulukot toimivat edelleen täsmälleen samalla tavalla.
<?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];
}
};
Huomautukset:
- Metodien nimet muunnetaan oletusarvoisesti pienaakkosellisiksi snake_case-nimiksi, joten
getStatus()muuttuu muotoonget_status - Käytä
name:-määritystä päätepisteen nimen asettamiseen erikseen Access::Sessionvastaa vanhaa toimintaa'public' => trueAccess::Openvastaa vanhaa toimintaa'public' => 'open'- Jätä
access:pois, kun haluat käyttää oletusta, jossa vain todennetut käyttäjät pääsevät toimintoihin
Kutsuminen JavaScript-ympäristöstä
Blockstudio lisää automaattisesti bs.fn()-apufunktion sivuille, joilla on lohkoja, joissa on RPC-funktioita.
Allekirjoitus: bs.fn(functionName, params?, blockName?) -> Promise
Lohkon nimen välittäminen
Jos kolmas argumentti jätetään pois, bs.fn() käyttää varalla document.currentScript-määrityksen data-block-attribuuttia. Blockstudio tulostaa sekä script.js-merkinnät että sisäiset skriptit (script-inline.js tai script.inline.js) <script type="module">-tunnisteina, ja moduuliskripteillä ei ole attribuuttia document.currentScript. Siksi lohkon skripteissä lohkon nimi on välitettävä kolmantena argumenttina:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Ilman sitä kutsu aiheuttaa virheen bs.fn: block name required.
Virheenkäsittely
bs.fn() ratkaistuu jäsennetyllä JSON-rungolla HTTP-tilasta riippumatta. Kun funktio palauttaa arvon WP_Error, lupaus ratkaistuu objektilla, joka sisältää arvot code, message ja data, joten tarkista code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Lupaus hylätään vain, jos pyyntö epäonnistuu tai vastaus ei ole JSON.
Yhdessä Interactivity APIin kanssa
RPC toimii luontevasti yhdessä WordPress-Interactivity APIin kanssa. Kaupan toiminnot kutsuvat palvelinfunktioita ja päivittävät reaktiivisen tilan vastauksen perusteella. UI päivittyy automaattisesti:
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>
Käyttöoikeuksien hallinta
Oletusarvoisesti funktiot edellyttävät todennettua eli sisäänkirjautunutta käyttäjää. Tämä vastaa WordPress-käytäntöjä, joissa REST-päätepisteet on suojattu oletusarvoisesti.
Julkiset funktiot
Salli todentamattomien käyttäjien pääsy CSRF-suojauksella:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Välimuistissa olevat sivut
bs.fn() hakee uudet tunnistetiedot välimuistittamattomasta saman alkuperän POST /wp-json/blockstudio/v1/client/credentials-päätepisteestä. Vanhenevia WordPress-nonceja ja Blockstudio CSRF-tunnisteita ei tallenneta sivun HTML-sisältöön, joten julkiset kutsut toimivat edelleen, kun ulkoinen sivuvälimuisti tarjoaa yli 24 tuntia vanhan HTML-sisällön.
Päivitys tehdään tarvittaessa: sivun lataaminen ilman API-kutsua ei lähetä tunnistetietopyyntöä. RPC ja tietokanta-asiakasohjelmat käyttävät samaa päivitystä, uusivat tunnistetiedot viiden minuutin käytön jälkeen ja yrittävät kerran uudelleen vanhentuneen noncen tai CSRF-tunnisteen yhteydessä. Kyvykkyysvirheitä ja sovellusvirheitä ei yritetä uudelleen. Todennus perustuu edelleen nykyisen kävijän WordPress-kirjautumisevästeeseen; tunnistetietojen päivittäminen ei anna pääsyä yksityisiin toimintoihin. Pidä tunnistetietojen päätepiste kaikkien CDN- ja välityspalvelinvälimuistien ulkopuolella; sen vastaukset on merkitty nimenomaisesti private, no-store-tunnisteella.
Avoimet funktiot
Webhookeja tai ulkoisia API-takaisinkutsuja varten, kun pääsyn on oltava täysin avoin ilman tunnusta:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Käyttöoikeudet
Rajoita pääsy tiettyihin WordPress-käyttöoikeuksiin. Käytä merkkijonoa yhdelle käyttöoikeudelle tai taulukkoa, kun käyttäjällä on oltava jokin niistä:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP-metodit
Oletusarvoisesti funktiot hyväksyvät vain POST-pyynnöt. Tämä on turvallisin oletus tilaa muuttaville toiminnoille. Salli tarvittaessa muitakin metodeja:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Lohkojen väliset kutsut
Kutsuminen JavaScript-ympäristöstä
Mikä tahansa lohko voi kutsua toisen lohkon funktioita välittämällä lohkon nimen kolmantena argumenttina. Näin lohkot voidaan yhdistää:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Kutsuminen PHP-ympäristöstä
Käytä Rpc::call()-kutsuja lohkojen välisiin palvelinpuolen kutsuihin. Tämä on hyödyllistä, kun yksi RPC-funktio tarvitsee koordinoida kutsuja muihin lohkoihin:
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-päätepiste
Taustalla kukin funktio yhdistetään REST-reittiin:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Pyynnön runko: { "params": { ... } }
Vastaus: PHP-funktion palautusarvo muodossa JSON.
Voit kutsua näitä päätepisteitä suoraan mistä tahansa HTTP-asiakasohjelmasta, mutta suositeltu tapa on bs.fn(), koska se hoitaa nonce-todennuksen automaattisesti.
Hookit
Toiminnot suoritetaan ennen jokaista RPC-kutsua ja sen jälkeen sekä REST- että PHP-kutsuissa. Kaikki hookit saavat yhden $params-taulukon:
| Hook | Parametrit |
|---|---|
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.
});
Suodatin
Muokkaa funktioita tai lisää niitä ohjelmallisesti lohkon ulkopuolelta:
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;
});
Milloin käyttää RPC-järjestelmää ja milloin tietokantaa
db.php luo CRUD-päätepisteet automaattisesti skeemasta. Käytä sitä, kun tarvitset tavallisia luonti-, luku-, päivitys- ja poistotoimintoja validointeineen.
rpc.php on mukautettua logiikkaa varten: sähköpostien lähettämiseen, ulkoisten API-rajapintojen kutsumiseen, skeemojen datan yhdistämiseen, monimutkaisten kyselyjen suorittamiseen tai muuhun, mikä ei sovi CRUD-malliin.
Nämä kaksi järjestelmää ovat itsenäisiä ja täydentävät toisiaan. Monissa lohkoissa käytetään molempia: db.php-järjestelmää datamalliin ja rpc.php-järjestelmää sen päälle rakentuviin liiketoimintalogiikan toteutuksiin.