Preskočiť na obsah

RPC

RPC (Remote Procedure Call) umožňuje definovať funkcie PHP vo svojom bloku a volať ich z frontendu. Namiesto ručnej registrácie trás REST API, vytvárania radičov a prepájania volaní fetch napíšete funkciu v rpc.php a zavoláte ju pomocou bs.fn(). Blockstudio sa postará o smerovanie koncových bodov, overenie, validáciu nonce a serializáciu JSON.

Tento vzor je inšpirovaný tRPC: definujte procedúry na strane servera a volajte ich z klienta pomocou typovaného pomocného nástroja. Žiadne vytváranie URL, žiadny ručný pomocný kód fetch.

Ako to funguje

  1. Vytvoríte rpc.php v priečinku svojho bloku
  2. Vráti asociatívne pole pomenovaných funkcií
  3. Blockstudio zaregistruje koncový bod REST pre každú funkciu
  4. Klient bs.fn() ich volá podľa názvu
  5. Odovzdajú sa parametre a vráti sa JSON
Kód
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definovanie funkcií

Každý kľúč vo vrátenom poli predstavuje názov funkcie. Najjednoduchšou formou je priame spätné volanie:

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ždá funkcia dostáva jedno pole $params a mala by vrátiť pole. Návratová hodnota sa klientovi odošle ako JSON.

Ak chcete nastaviť možnosti riadenia prístupu, použite rozšírený formát s callback a ďalšími kľúčmi:

PHP
return [
    'admin_action' => [
        'callback'   => function (array $params): array {
            return ['ok' => true];
        },
        'capability' => 'manage_options',
    ],
];

Definície v štýle PHP

Ak uprednostňujete metadáta PHP namiesto vnorených polí, rpc.php môže vrátiť aj objekt s metódami označenými atribútmi. Polia fungujú naďalej rovnako.

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];
    }
};

Poznámky:

  • Názvy metód sa predvolene normalizujú na malé písmená a formát snake case, takže getStatus() sa zmení na get_status
  • Pomocou name: môžete výslovne nastaviť názov koncového bodu
  • Access::Session zodpovedá pôvodnému správaniu 'public' => true
  • Access::Open zodpovedá pôvodnému správaniu 'public' => 'open'
  • Ak chcete zachovať predvolené správanie, ktoré povoľuje prístup len overeným používateľom, vynechajte access:

Volanie z JavaScript

Blockstudio automaticky vloží pomocnú funkciu bs.fn() na stránky, ktoré obsahujú bloky s funkciami RPC.

Signatúra: bs.fn(functionName, params?, blockName?) -> Promise

Odovzdanie názvu bloku

Ak vynecháte tretí argument, bs.fn() použije ako náhradnú hodnotu atribút data-block z document.currentScript. Blockstudio vypisuje script.js aj vložené skripty (script-inline.js alebo script.inline.js) ako značky <script type="module">. Modulové skripty nemajú atribút document.currentScript, preto v blokových skriptoch odovzdajte názov bloku ako tretí argument:

JavaScript
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');

Bez neho volanie vyvolá bs.fn: block name required.

Spracovanie chýb

bs.fn() sa vyrieši s parsovaným telom JSON bez ohľadu na stav HTTP. Ak funkcia vráti WP_Error, prísľub sa vyrieši objektom obsahujúcim jeho code, message a data, preto kontrolujte code:

JavaScript
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');

if (result.code) {
  console.error('RPC failed:', result.message);
}

Prísľub sa zamietne len vtedy, ak samotná požiadavka zlyhá alebo odpoveď nie je JSON.

S Interactivity API

RPC prirodzene spolupracuje s WordPress Interactivity API. Akcie vášho úložiska volajú funkcie servera a aktualizujú reaktívny stav podľa odpovede. UI sa aktualizuje automaticky:

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>

Riadenie prístupu

Funkcie predvolene vyžadujú overeného (prihláseného) používateľa. To zodpovedá konvenciám WordPress, podľa ktorých sú koncové body REST predvolene chránené.

Verejné funkcie

Povoľte prístup bez overenia s ochranou proti 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
    ],
];

Cachované stránky

bs.fn() získava čerstvé prihlasovacie údaje z necachovaného koncového bodu POST /wp-json/blockstudio/v1/client/credentials na rovnakej doméne. Nonce WordPress a CSRF tokeny Blockstudio s obmedzenou platnosťou sa neukladajú do HTML stránky, takže verejné volania naďalej fungujú, keď externá vyrovnávacia pamäť stránky poskytne HTML staršiu ako 24 hodín.

Obnovenie prebieha podľa potreby: načítanie stránky bez volania API nevyvolá požiadavku na prihlasovacie údaje. RPC a databázoví klienti zdieľajú obnovenie, obnovujú prihlasovacie údaje po piatich minútach používania a pri neplatnom nonce alebo CSRF tokene požiadavku raz zopakujú. Chyby oprávnení a chyby aplikácie sa neopakujú. Prihlasovanie sa naďalej riadi súborom cookie WordPress aktuálneho návštevníka; obnovenie prihlasovacích údajov neposkytuje prístup k súkromným funkciám. Koncový bod prihlasovacích údajov ponechajte mimo každej vyrovnávacej pamäte CDN alebo proxy; jeho odpovede sú výslovne označené ako private, no-store.

Otvorené funkcie

Pre webhooky alebo externé spätné volania API, ktoré vyžadujú úplne otvorený prístup bez akéhokoľvek prístupového tokenu:

PHP
return [
    'webhook' => [
        'callback' => function (array $params): array {
            // Called by an external service
            return ['received' => true];
        },
        'public' => 'open',  // no CSRF, no auth
    ],
];

Oprávnenia

Obmedzte prístup na konkrétne oprávnenia WordPress. Pre jedno oprávnenie použite reťazec, alebo pole, ak používateľ potrebuje ktorékoľvek 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'],
    ],
];

Metódy HTTP

Funkcie predvolene prijímajú iba požiadavky POST. Je to najbezpečnejšia predvolená voľba pre operácie, ktoré menia stav. Podľa potreby povoľte ďalšie metódy:

PHP
return [
    'get_status' => [
        'callback' => function (array $params): array {
            return ['status' => 'ok'];
        },
        'methods' => ['GET', 'POST'],
    ],
];

Volanie naprieč blokmi

Z JavaScript

Každý blok môže volať funkcie ľubovoľného iného bloku, ak ako tretí argument odovzdá názov bloku. To umožňuje prepájať bloky:

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

Na volanie medzi blokmi na strane servera použite Rpc::call(). Hodí sa to, keď funkcia RPC potrebuje koordinovať volania iných blokov:

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];
    },
];

Koncový bod REST

V zákulisí sa každá funkcia mapuje na trasu REST:

Kód
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

Telo požiadavky: { "params": { ... } }

Odpoveď: Návratová hodnota funkcie PHP vo formáte JSON.

Tieto koncové body môžete volať priamo z ľubovoľného klienta HTTP, odporúčaný spôsob je však bs.fn(), pretože automaticky zabezpečuje overenie nonce.

Háčiky

Akcie sa spúšťajú pred každým volaním RPC aj po ňom, a to z REST aj z PHP. Všetky háčiky prijímajú jedno pole $params:

Háčik Parametre
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.
});

Filter

Programovo upravujte alebo pridávajte funkcie zvonka 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;
});

Kedy použiť RPC namiesto databázy

db.php automaticky generuje koncové body CRUD zo schémy. Použite ho, keď potrebujete štandardné operácie vytvárania, čítania, aktualizácie a odstraňovania s validáciou.

rpc.php slúži na vlastnú logiku: odosielanie e-mailov, volanie externých API, agregovanie dát naprieč schémami, spúšťanie zložitých dopytov alebo čokoľvek, čo nezodpovedá vzoru CRUD.

Tieto dva systémy sú nezávislé a navzájom sa dopĺňajú. Mnohé bloky používajú oba: db.php pre dátový model a rpc.php pre obchodnú logiku nad ním.