RPC
RPC (Remote Procedure Call) pozwala definiować funkcje PHP w bloku i wywoływać je z poziomu frontendu. Zamiast ręcznie rejestrować trasy REST API, tworzyć kontrolery i konfigurować wywołania fetch, piszesz funkcję w rpc.php i wywołujesz ją za pomocą bs.fn(). Blockstudio obsługuje routing punktów końcowych, uwierzytelnianie, weryfikację nonce i serializację JSON.
Ten wzorzec jest inspirowany przez tRPC: definiujesz procedury po stronie serwera i wywołujesz je z klienta za pomocą typowanego narzędzia pomocniczego. Bez tworzenia URL i ręcznego powielania kodu fetch.
Jak to działa
- Tworzysz
rpc.phpw katalogu bloku - Zwraca on tablicę asocjacyjną z nazwanymi funkcjami
- Blockstudio rejestruje punkt końcowy REST dla każdej funkcji
- Klient
bs.fn()wywołuje je po nazwie - Przekazujesz parametry, otrzymujesz JSON
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definiowanie funkcji
Każdy klucz w zwracanej tablicy jest nazwą funkcji. Najprostsza forma to bezpośrednia funkcja zwrotna:
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];
},
];
Każda funkcja otrzymuje pojedynczą tablicę $params i powinna zwrócić tablicę. Wartość zwracana jest wysyłana do klienta jako JSON.
Aby skonfigurować kontrolę dostępu, użyj rozszerzonego formatu z callback i dodatkowymi kluczami:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definicje natywne PHP
Jeśli zamiast zagnieżdżonych tablic wolisz metadane natywne dla PHP, rpc.php może też zwrócić obiekt z metodami oznaczonymi atrybutami. Tablice nadal działają tak samo.
<?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];
}
};
Uwagi:
- Domyślnie nazwy metod są normalizowane do małych liter i formatu snake_case, więc
getStatus()zmienia się wget_status - Użyj
name:, aby jawnie ustawić nazwę punktu końcowego Access::Sessionodpowiada dotychczasowemu działaniu'public' => trueAccess::Openodpowiada dotychczasowemu działaniu'public' => 'open'- Pomiń
access:, aby zachować domyślne zachowanie wymagające uwierzytelnienia
Wywoływanie z JavaScript
Blockstudio automatycznie dodaje narzędzie pomocnicze bs.fn() na stronach zawierających bloki z funkcjami RPC.
Sygnatura: bs.fn(functionName, params?, blockName?) -> Promise
Przekazywanie nazwy bloku
bs.fn() używa w zastępstwie atrybutu data-block elementu document.currentScript, jeśli pominięto trzeci argument. Blockstudio wyświetla zarówno script.js, jak i skrypty wbudowane (script-inline.js lub script.inline.js) jako znaczniki <script type="module">, a skrypty modułowe nie mają document.currentScript, więc w skryptach bloków podaj nazwę bloku jako trzeci argument:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Bez niego wywołanie zgłosi wyjątek bs.fn: block name required.
Obsługa błędów
bs.fn() zwraca sparsowane ciało odpowiedzi JSON niezależnie od jej statusu HTTP. Gdy funkcja zwróci WP_Error, obietnica zostanie rozwiązana obiektem zawierającym code, message i data, dlatego sprawdź code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
Obietnica zostanie odrzucona tylko wtedy, gdy samo żądanie zakończy się niepowodzeniem lub odpowiedź nie będzie JSON.
Z Interactivity API
RPC dobrze współpracuje z WordPress Interactivity API. Akcje magazynu wywołują funkcje serwera i aktualizują reaktywny stan na podstawie odpowiedzi. UI aktualizuje się automatycznie:
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>
Kontrola dostępu
Domyślnie funkcje wymagają uwierzytelnionego (zalogowanego) użytkownika. Jest to zgodne z konwencjami WordPress, w których punkty końcowe REST są domyślnie chronione.
Funkcje publiczne
Zezwól na dostęp bez uwierzytelnienia z ochroną CSRF:
return [
'get_count' => [
'callback' => function (array $params): array {
return ['count' => wp_count_posts()->publish];
},
'public' => true, // public + CSRF protected via X-BS-Token
],
];
Buforowane strony
bs.fn() pobiera aktualne dane uwierzytelniające z niebuforowanego punktu końcowego POST /wp-json/blockstudio/v1/client/credentials w tym samym źródle. Wygasające nonce WordPress i tokeny CSRF Blockstudio nie są przechowywane w kodzie strony HTML, więc publiczne wywołania nadal działają, gdy zewnętrzna pamięć podręczna serwuje strony HTML starsze niż 24 godziny.
Odświeżanie odbywa się na żądanie: wczytanie strony bez wywołania API nie powoduje żądania danych uwierzytelniających. RPC i klienty bazy danych współdzielą odświeżanie, odnawiają dane uwierzytelniające po pięciu minutach użycia i ponawiają próbę jeden raz w przypadku wygasłego nonce lub tokenu CSRF. Błędy uprawnień i błędy aplikacji nie są ponawiane. Uwierzytelnianie nadal odbywa się za pomocą ciasteczka logowania WordPress bieżącego odwiedzającego; odświeżenie danych uwierzytelniających nie daje dostępu do funkcji prywatnych. Umieść punkt końcowy danych uwierzytelniających poza pamięcią podręczną CDN lub serwera proxy; jego odpowiedzi są jawnie oznaczone jako private, no-store.
Funkcje otwarte
W przypadku webhooków lub zewnętrznych wywołań zwrotnych API, które wymagają całkowicie otwartego dostępu bez tokenu:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Uprawnienia
Ogranicz dostęp do określonych uprawnień WordPress. Użyj ciągu znaków dla pojedynczego uprawnienia lub tablicy, jeśli użytkownik musi mieć dowolne jedno z nich:
return [
'save_draft' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => 'edit_posts',
],
'moderate' => [
'callback' => function (array $params): array { /* ... */ },
'capability' => ['edit_others_posts', 'manage_options'],
],
];
Metody HTTP
Domyślnie funkcje akceptują tylko żądania POST. To najbezpieczniejsze ustawienie domyślne dla operacji zmieniających stan. W razie potrzeby zezwól na dodatkowe metody:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Wywołania między blokami
Z JavaScript
Każdy blok może wywoływać funkcje dowolnego innego bloku, przekazując jego nazwę jako trzeci argument. Umożliwia to łączenie bloków:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
Z PHP
Użyj Rpc::call() do wywołań między blokami po stronie serwera. Przydaje się to, gdy funkcja RPC musi koordynować wywołania innych bloków:
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];
},
];
Punkt końcowy REST
W tle każda funkcja jest mapowana na trasę REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Treść żądania: { "params": { ... } }
Odpowiedź: Wartość zwracana przez funkcję PHP jako JSON.
Możesz wywoływać te punkty końcowe bezpośrednio z dowolnego klienta HTTP, ale zalecanym sposobem jest bs.fn(), ponieważ automatycznie obsługuje uwierzytelnianie nonce.
Hooki
Akcje są wywoływane przed każdym wywołaniem RPC i po nim, zarówno z REST, jak i z PHP. Wszystkie hooki otrzymują pojedynczą tablicę $params:
| Hook | Parametry |
|---|---|
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.
});
Filtr
Modyfikuj lub dodawaj funkcje programowo spoza bloku:
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;
});
Kiedy używać RPC, a kiedy bazy danych
db.php automatycznie generuje punkty końcowe CRUD na podstawie schematu. Użyj tego rozwiązania, gdy potrzebujesz standardowych operacji tworzenia, odczytu, aktualizacji i usuwania z walidacją.
rpc.php służy do niestandardowej logiki: wysyłania wiadomości e-mail, wywoływania zewnętrznych interfejsów API, agregowania danych z wielu schematów, wykonywania złożonych zapytań lub innych zadań, które nie pasują do wzorca CRUD.
Te dwa systemy są niezależne i wzajemnie się uzupełniają. Wiele bloków korzysta z obu: db.php do modelu danych i rpc.php do logiki biznesowej, która go wykorzystuje.