Przejdź do treści

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

  1. Tworzysz rpc.php w katalogu bloku
  2. Zwraca on tablicę asocjacyjną z nazwanymi funkcjami
  3. Blockstudio rejestruje punkt końcowy REST dla każdej funkcji
  4. Klient bs.fn() wywołuje je po nazwie
  5. Przekazujesz parametry, otrzymujesz JSON
Kod
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:

PHP
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:

PHP
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
<?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ę w get_status
  • Użyj name:, aby jawnie ustawić nazwę punktu końcowego
  • Access::Session odpowiada dotychczasowemu działaniu 'public' => true
  • Access::Open odpowiada 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:

JavaScript
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:

JavaScript
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:

JavaScript
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;
    },
  },
});
PHP
<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:

PHP
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:

PHP
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:

PHP
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:

PHP
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:

JavaScript
// 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:

PHP
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:

Kod
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
PHP
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:

PHP
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.