RPC
A RPC (Remote Procedure Call, távoli eljáráshívás) segítségével PHP függvényeket definiálhat a blokkjában, és meghívhatja őket a frontendről. A REST API útvonalak kézi regisztrálása, vezérlők létrehozása és a fetch hívások összekötése helyett írjon egy függvényt a rpc.php-ben, majd hívja meg a bs.fn() segítségével. A Blockstudio kezeli a végpontok útvonalát, a hitelesítést, a nonce-ellenőrzést és a JSON szerializálását.
A minta a tRPC megoldásából ered: definiálja az eljárásokat a szerveren, majd egy típusos segédfüggvénnyel hívja meg őket a kliensről. Nincs szükség URL létrehozására vagy kézi fetch sablonkódra.
Működés
- Hozzon létre
rpc.php-t a blokk könyvtárában - Ez névvel ellátott függvények asszociatív tömbjét adja vissza
- A Blockstudio minden függvényhez regisztrál egy REST végpontot
- A
bs.fn()kliens név szerint hívja meg őket - A paraméterek bemenetként érkeznek, JSON pedig kimenetként tér vissza
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Függvények definiálása
A visszaadott tömb minden kulcsa egy függvény neve. A legegyszerűbb forma a közvetlen visszahívási függvény:
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];
},
];
Minden függvény egyetlen $params tömböt kap, és egy tömböt kell visszaadnia. A visszatérési értéket a rendszer JSON formájában küldi el a kliensnek.
A hozzáférés-vezérlési beállításokhoz használja a kibővített formátumot a callback elemmel és további kulcsokkal:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
PHP-natív definíciók
Ha a beágyazott tömbök helyett a PHP natív metaadatait részesíti előnyben, a rpc.php attribútumokkal ellátott metódusokat tartalmazó objektumot is visszaadhat. A tömbök továbbra is ugyanúgy működnek.
<?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];
}
};
Megjegyzések:
- A metódusnevek alapértelmezés szerint kisbetűs snake case formára normalizálódnak, ezért a
getStatus()névbőlget_statuslesz - A
name:segítségével felülírhatja a végpont nevét - A
Access::Sessiona régi'public' => trueműködésének felel meg - A
Access::Opena régi'public' => 'open'működésének felel meg - Hagyja ki a
access:elemet az alapértelmezett, csak hitelesített felhasználóknak szóló működéshez
Hívás JavaScript-ből
A Blockstudio automatikusan beilleszt egy bs.fn() segédfüggvényt azokra az oldalakra, amelyeken RPC függvényeket tartalmazó blokkok vannak.
Aláírás: bs.fn(functionName, params?, blockName?) -> Promise
A blokk nevének megadása
Ha kihagyja a harmadik argumentumot, a bs.fn() a document.currentScript data-block attribútumára vált vissza. A Blockstudio a script.js értékét és a beágyazott szkripteket (script-inline.js vagy script.inline.js) is <script type="module"> címkékként jeleníti meg, a modulszkripteknek pedig nincs document.currentScript attribútumuk. Ezért a blokkszkriptekben harmadik argumentumként adja meg a blokk nevét:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Enélkül a hívás bs.fn: block name required hibát dob.
Hibakezelés
A bs.fn() a feldolgozott JSON törzzsel teljesül, függetlenül a HTTP állapotától. Ha egy függvény WP_Error értéket ad vissza, az ígéret egy olyan objektummal teljesül, amely tartalmazza annak code, message és data értékét, ezért ellenőrizze a code értéket:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Az ígéret csak akkor utasítódik el, ha maga a kérés sikertelen, vagy a válasz nem JSON.
Az Interactivity API használatával
A RPC természetesen együttműködik az WordPress Interactivity API megoldással. Az áruház műveletei szerverfüggvényeket hívnak, és a válasz alapján frissítik a reaktív állapotot. A UI automatikusan frissül:
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>
Hozzáférés-vezérlés
Alapértelmezés szerint a függvények hitelesített (bejelentkezett) felhasználót igényelnek. Ez megfelel a WordPress konvencióinak, amelyek szerint a REST végpontok alapértelmezés szerint védettek.
Nyilvános függvények
Névtelen hozzáférés engedélyezése CSRF-védelemmel:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Gyorsítótárazott oldalak
A bs.fn() friss hitelesítő adatokat kér le a gyorsítótárazásból kizárt, azonos eredetű POST /wp-json/blockstudio/v1/client/credentials végpontról. A lejáró WordPress nonce-okat és Blockstudio CSRF-tokeneket a rendszer nem tárolja az oldal HTML részében, így a nyilvános hívások akkor is működnek, ha egy külső oldalgyorsítótár 24 óránál régebbi HTML adatot szolgál ki.
A frissítés igény szerinti: ha egy oldal betöltésekor nem történik API hívás, a rendszer nem kér hitelesítő adatokat. A RPC és az adatbázis-kliensek közösen végzik a frissítést, öt perc használat után megújítják a hitelesítő adatokat, és lejárt nonce vagy CSRF-token esetén egyszer újrapróbálkoznak. A képességellenőrzési hibákkal és az alkalmazáshibákkal nem próbálkoznak újra. A hitelesítés továbbra is a látogató aktuális WordPress bejelentkezési sütijét követi; a hitelesítő adatok frissítése nem biztosít hozzáférést a privát függvényekhez. Tartsa a hitelesítőadat-végpontot minden CDN vagy proxy gyorsítótárán kívül; a válaszai kifejezetten private, no-store jelölést kapnak.
Nyitott függvények
Webhookokhoz vagy külső API visszahívásokhoz, amelyeknek token nélkül, teljesen nyitott hozzáférésre van szükségük:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Képességek
Korlátozza a hozzáférést bizonyos WordPress képességekre. Egyetlen képességhez használjon szöveget, vagy olyan tömböt, amelyben a felhasználónak bármelyik képességre szüksége van:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
HTTP metódusok
Alapértelmezés szerint a függvények csak POST kéréseket fogadnak. Ez a legbiztonságosabb alapértelmezés az állapotot módosító műveletekhez. Szükség esetén további metódusokat is engedélyezhet:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Hívások blokkok között
Hívás JavaScript-ből
Bármelyik blokk meghívhatja egy másik blokk függvényeit, ha harmadik argumentumként megadja annak nevét. Ez lehetővé teszi a blokkok összekapcsolását:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Hívás PHP-ből
Blokkok közötti szerveroldali hívásokhoz használja a Rpc::call()-t. Ez akkor hasznos, ha egy RPC függvénynek más blokkok hívásait kell összehangolnia:
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 végpont
A háttérben minden függvény egy REST útvonalhoz van rendelve:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Kérés törzse: { "params": { ... } }
Válasz: A PHP függvény visszatérési értéke JSON formátumban.
Ezeket a végpontokat közvetlenül bármelyik HTTP kliensből meghívhatja, de a bs.fn() használata ajánlott, mert automatikusan kezeli a nonce-hitelesítést.
Hookok
A műveletek minden RPC hívás előtt és után lefutnak, mind a REST, mind a PHP esetén. Minden hook egyetlen $params tömböt kap:
| Hook | Paraméterek |
|---|---|
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.
});
Szűrő
Függvények módosítása vagy hozzáadása programozottan, a blokkon kívülről:
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;
});
Mikor használja a RPC-t és mikor az adatbázist?
A db.php automatikusan CRUD-végpontokat hoz létre a sémából. Akkor használja, ha szabványos létrehozási, olvasási, frissítési és törlési műveletekre van szüksége érvényesítéssel.
A rpc.php egyéni logikához való: e-mailek küldéséhez, külső API-k hívásához, sémák közötti adatok összesítéséhez, összetett lekérdezések futtatásához vagy bármihez, ami nem illik a CRUD-mintába.
A két rendszer egymástól független, mégis kiegészíti egymást. Sok blokk mindkettőt használja: a db.php-t az adatmodellhez, a rpc.php-t pedig az arra épülő üzleti logikához.