RPC
RPC (attālās procedūras izsaukums) ļauj definēt PHP funkcijas savā blokā un izsaukt tās no priekšgala. Tā vietā, lai manuāli reģistrētu REST API maršrutus, veidotu kontrollerus un savienotu fetch izsaukumus, ierakstiet funkciju rpc.php un izsauciet to ar bs.fn(). Blockstudio apstrādā galapunktu maršrutēšanu, autentifikāciju, nonce validāciju un JSON serializēšanu.
Šo risinājumu iedvesmojis tRPC: definējiet procedūras servera pusē un izsauciet tās klientā, izmantojot tipizētu palīgfunkciju. Nav jāveido URL un manuāli jāraksta fetch standarta kods.
Kā tas darbojas
- Izveidojiet
rpc.phpsava bloka direktorijā - Tas atgriež asociatīvu masīvu ar nosauktām funkcijām
- Blockstudio reģistrē REST galapunktu katrai funkcijai
bs.fn()klients izsauc tās pēc nosaukuma- Parametri tiek nosūtīti, bet tiek saņemta JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Funkciju definēšana
Katra atgrieztā masīva atslēga ir funkcijas nosaukums. Vienkāršākajā variantā izmantojiet tiešu atzvanes funkciju:
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];
},
];
Katra funkcija saņem vienu $params masīvu un tai jāatgriež masīvs. Atgrieztā vērtība klientam tiek nosūtīta kā JSON.
Lai iestatītu piekļuves kontroli, izmantojiet izvērsto formātu ar callback un papildu atslēgām:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP vietējās definīcijas
Ja dodat priekšroku PHP vietējai metadatu sintaksei, nevis ligzdotiem masīviem, rpc.php var atgriezt arī objektu ar atribūtiem apzīmētām metodēm. Masīvi joprojām darbojas tieši tāpat.
<?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];
}
};
Piezīmes:
- Pēc noklusējuma metožu nosaukumi tiek pārveidoti par mazajiem burtiem snake case formātā, tāpēc
getStatus()kļūst parget_status - Izmantojiet
name:, lai skaidri norādītu galapunkta nosaukumu Access::Sessionatbilst iepriekšējai'public' => truedarbībaiAccess::Openatbilst iepriekšējai'public' => 'open'darbībai- Izlaidiet
access:, lai izmantotu noklusēto piekļuvi tikai autentificētiem lietotājiem
Izsaukšana no JavaScript
Blockstudio lapās, kurās ir bloki ar RPC funkcijām, automātiski ievieto bs.fn() palīgfunkciju.
Paraksts: bs.fn(functionName, params?, blockName?) -> Promise
Bloka nosaukuma norādīšana
Ja trešais arguments nav norādīts, bs.fn() izmanto document.currentScript atribūtu no data-block kā rezerves vērtību. Blockstudio izvada gan script.js, gan iekļautos skriptus (script-inline.js vai script.inline.js) kā <script type="module"> tagus, bet moduļu skriptiem nav document.currentScript, tāpēc bloka skriptos norādiet bloka nosaukumu kā trešo argumentu:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Ja to nenorādīsiet, izsaukums radīs bs.fn: block name required.
Kļūdu apstrāde
bs.fn() atrisina solījumu ar parsētu JSON pamattekstu neatkarīgi no HTTP statusa. Ja funkcija atgriež WP_Error, solījums tiek atrisināts ar objektu, kurā ir tā code, message un data, tāpēc pārbaudiet code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Solījums tiek noraidīts tikai tad, ja pats pieprasījums neizdodas vai atbilde nav JSON.
Kopā ar Interactivity API
RPC dabiski papildina WordPress Interactivity API. Jūsu veikala darbības izsauc servera funkcijas un atjaunina reaktīvo stāvokli ar saņemto atbildi. UI tiek atjaunināts automātiski:
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>
Piekļuves kontrole
Pēc noklusējuma funkcijām nepieciešams autentificēts (pieteicies) lietotājs. Tas atbilst WordPress konvencijām, kurās REST galapunkti pēc noklusējuma ir aizsargāti.
Publiskās funkcijas
Atļaujiet piekļuvi bez autentifikācijas, izmantojot CSRF aizsardzību:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Kešatmiņā saglabātas lapas
bs.fn() iegūst jaunus akreditācijas datus no kešatmiņā neglabāta tās pašas izcelsmes POST /wp-json/blockstudio/v1/client/credentials galapunkta. Nonces WordPress, kam beidzas derīguma termiņš, un CSRF tokeni Blockstudio netiek saglabāti lapas HTML, tāpēc publiskie izsaukumi turpina darboties, kad ārējā lapu kešatmiņa apkalpo HTML, kas vecāka par 24 stundām.
Atsvaidzināšana notiek pēc vajadzības: ielādējot lapu un neizsaucot API, akreditācijas dati netiek pieprasīti. RPC un datubāzes klienti koplieto atsvaidzināšanu, atjauno akreditācijas datus pēc piecu minūšu lietošanas un vienu reizi mēģina vēlreiz, ja nonce vai CSRF tokens ir beidzies. Iespēju kļūdas un lietojumprogrammas kļūdas netiek mēģinātas vēlreiz. Autentifikācija joprojām balstās uz pašreizējā apmeklētāja WordPress pieteikšanās sīkdatni; akreditācijas datu atsvaidzināšana nepiešķir piekļuvi privātām funkcijām. Akreditācijas datu galapunktam jābūt ārpus jebkādas CDN vai starpniekservera kešatmiņas; tā atbildes ir skaidri atzīmētas kā private, no-store.
Atvērtās funkcijas
Tīmekļa āķiem vai ārējiem API atzvanes izsaukumiem, kam nepieciešama pilnīgi atvērta piekļuve bez tokena:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Atļaujas
Ierobežojiet piekļuvi konkrētām WordPress iespējām. Vienai iespējai izmantojiet virkni, bet vairākām — masīvu, kurā lietotājam nepieciešama jebkura viena iespēja:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP metodes
Pēc noklusējuma funkcijas pieņem tikai POST pieprasījumus. Tas ir drošākais noklusējums darbībām, kas maina stāvokli. Vajadzības gadījumā atļaujiet arī citas metodes:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Izsaukumi starp blokiem
No JavaScript
Jebkurš bloks var izsaukt jebkura cita bloka funkcijas, kā trešo argumentu norādot bloka nosaukumu. Tas ļauj veidot bloku kompozīcijas:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
No PHP
Izmantojiet Rpc::call() izsaukumiem starp blokiem servera pusē. Tas noder, ja vienai RPC funkcijai jākoordinē citu bloku izsaukumi:
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 galapunkts
Fonā katra funkcija tiek sasaistīta ar REST maršrutu:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Pieprasījuma pamatteksts: { "params": { ... } }
Atbilde: PHP funkcijas atgrieztā vērtība kā JSON.
Šos galapunktus var izsaukt tieši no jebkura HTTP klienta, taču ieteicams izmantot bs.fn(), jo tas automātiski apstrādā nonce autentifikāciju.
Āķi
Darbības tiek izpildītas pirms un pēc katra RPC izsaukuma gan no REST, gan no PHP. Visi āķi saņem vienu $params masīvu:
| Āķis | 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.
});
Filtrs
Modificējiet vai pievienojiet funkcijas programmatiski ārpus bloka:
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;
});
Kad izmantot RPC, bet kad — datubāzi
db.php automātiski ģenerē CRUD galapunktus no shēmas. Izmantojiet to, ja nepieciešamas standarta izveides, lasīšanas, atjaunināšanas un dzēšanas darbības ar validāciju.
rpc.php ir paredzēts pielāgotai loģikai: e-pasta ziņojumu sūtīšanai, ārējo API izsaukšanai, datu apkopošanai no vairākām shēmām, sarežģītu vaicājumu izpildei un visam, kas neatbilst CRUD modelim.
Abas sistēmas ir neatkarīgas un papildina viena otru. Daudzi bloki izmanto abas: db.php datu modelim un rpc.php biznesa loģikai, kas ar to strādā.