Pereiti prie turinio

RPC

RPC (Remote Procedure Call) leidžia apibrėžti PHP funkcijas bloke ir iškviesti jas iš išorinės sąsajos. Užuot rankiniu būdu registravę REST API maršrutus, kūrę valdiklius ir sujungę fetch iškvietimus, parašote funkciją faile rpc.php ir iškviečiate ją naudodami bs.fn(). Blockstudio pasirūpina galinių taškų maršrutizavimu, autentifikavimu, nonce patvirtinimu ir JSON serializavimu.

Šis šablonas įkvėptas tRPC: apibrėžkite procedūras serverio pusėje, o iškvieskite jas kliente naudodami tipizuotą pagalbinę funkciją. Nereikia kurti URL ar rankiniu būdu rašyti fetch bazinio kodo.

Kaip tai veikia

  1. Bloko aplanke sukuriate rpc.php
  2. Jis grąžina asociatyvų masyvą su pavadintomis funkcijomis
  3. Blockstudio kiekvienai funkcijai užregistruoja REST galinį tašką
  4. bs.fn() klientas iškviečia jas pagal pavadinimą
  5. Parametrai perduodami, o grąžinamas JSON
Kodas
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Funkcijų apibrėžimas

Kiekvienas grąžinamo masyvo raktas yra funkcijos pavadinimas. Paprasčiausia forma – tiesioginė atgalinio iškvietimo funkcija:

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

Kiekviena funkcija gauna vieną $params masyvą ir turėtų grąžinti masyvą. Grąžinama reikšmė klientui siunčiama kaip JSON.

Norėdami nustatyti prieigos kontrolės parinktis, naudokite išplėstinį formatą su callback ir papildomais raktais:

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

PHP savosios apibrėžtys

Jei vietoj įdėtinių masyvų pageidaujate PHP savųjų metaduomenų, rpc.php taip pat gali grąžinti objektą su atributuotais metodais. Masyvai veikia lygiai taip pat.

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

Pastabos:

  • Pagal numatytuosius nustatymus metodų pavadinimai paverčiami mažosiomis raidėmis ir snake case formatu, todėl getStatus() tampa get_status
  • Naudokite name:, kad aiškiai nurodytumėte galinio taško pavadinimą
  • Access::Session atitinka ankstesnę 'public' => true veikseną
  • Access::Open atitinka ankstesnę 'public' => 'open' veikseną
  • Praleiskite access:, jei norite numatytojo veikimo, kai prieiga suteikiama tik autentifikuotiems naudotojams

Iškvietimas iš JavaScript

Blockstudio puslapiuose, kuriuose yra blokų su RPC funkcijomis, automatiškai įterpia bs.fn() pagalbinę funkciją.

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

Bloko pavadinimo perdavimas

bs.fn(), jei praleidžiamas trečias argumentas, naudoja document.currentScript atributą data-block. Blockstudio išveda ir script.js, ir įterptuosius scenarijus (script-inline.js arba script.inline.js) kaip <script type="module"> žymas, o modulių scenarijai neturi document.currentScript. Todėl bloko scenarijuose trečiuoju argumentu perduokite bloko pavadinimą:

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

Be jo iškvietimas sukelia bs.fn: block name required klaidą.

Klaidų apdorojimas

bs.fn() grąžina išanalizuotą JSON turinį, kad ir koks būtų HTTP būsenos kodas. Kai funkcija grąžina WP_Error, pažadas įvykdomas su objektu, kuriame yra code, message ir data, todėl patikrinkite, ar yra code:

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

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

Pažadas atmetamas tik tada, kai pati užklausa nepavyksta arba atsakymas nėra JSON.

Su interaktyvumo API

RPC natūraliai dera su WordPress interaktyvumo API. Jūsų saugyklos veiksmai iškviečia serverio funkcijas ir pagal atsakymą atnaujina reaktyviąją būseną. UI atnaujinama automatiškai:

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>

Prieigos kontrolė

Pagal numatytuosius nustatymus funkcijoms reikia autentifikuoto (prisijungusio) naudotojo. Tai atitinka WordPress konvencijas, pagal kurias REST galiniai taškai pagal numatytuosius nustatymus yra apsaugoti.

Viešos funkcijos

Leiskite prieigą neprisijungus, taikydami CSRF apsaugą:

PHP
return [
    'get_count' => [
        'callback' => function (array $params): array {
            return ['count' => wp_count_posts()->publish];
        },
        'public' => true,    // public + CSRF protected via X-BS-Token
    ],
];

Podėlyje saugomi puslapiai

bs.fn() gauna naujus kredencialus iš tos pačios kilmės nekeshuojamo POST /wp-json/blockstudio/v1/client/credentials galinio taško. Baigiantys galioti WordPress nonce ir Blockstudio CSRF žetonai nesaugomi puslapio HTML, todėl viešieji iškvietimai toliau veikia, kai išorinis puslapio podėlis pateikia senesnį nei 24 valandų HTML.

Atnaujinama prireikus: įkėlus puslapį ir neiškvietus API, kredencialų neprašoma. RPC ir duomenų bazės klientai dalijasi atnaujinimu, po penkių minučių naudojimo atnaujina kredencialus ir vieną kartą pakartoja užklausą, jei nonce arba CSRF žetonas nebegalioja. Galimybių patikros ir programos klaidos užklausų nekartoja. Autentifikavimas ir toliau vykdomas pagal dabartinio lankytojo WordPress prisijungimo slapuką; kredencialų atnaujinimas nesuteikia prieigos prie privačių funkcijų. Kredencialų galinį tašką laikykite už bet kokio CDN ar tarpinio serverio podėlio ribų; jo atsakymai aiškiai pažymėti kaip private, no-store.

Atviros funkcijos

Webhook arba išorinių API atgalinio iškvietimo funkcijų atveju, kai reikia visiškai atviros prieigos be jokio žetono:

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

Galimybės

Apribokite prieigą konkrečiomis WordPress galimybėmis. Vienai galimybei naudokite eilutę, o jei naudotojui pakanka bet kurios vienos – masyvą:

PHP
return [
    'save_draft' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => 'edit_posts',
    ],
    'moderate' => [
        'callback'   => function (array $params): array { /* ... */ },
        'capability' => ['edit_others_posts', 'manage_options'],
    ],
];

HTTP metodai

Pagal numatytuosius nustatymus funkcijos priima tik POST užklausas. Tai saugiausia nuostata operacijoms, kurios keičia būseną. Kai reikia, leiskite ir kitus metodus:

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

Iškvietimai tarp blokų

Iš JavaScript

Bet kuris blokas gali iškviesti kito bloko funkcijas, trečiuoju argumentu perduodamas bloko pavadinimą. Taip galima kurti blokų sąveikas:

JavaScript
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');

Iš PHP

Serverio pusės iškvietimams tarp blokų naudokite Rpc::call(). Tai naudinga, kai viena RPC funkcija turi koordinuoti kitų blokų iškvietimus:

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

REST galinis taškas

Viduje kiekviena funkcija susiejama su REST maršrutu:

Kodas
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

Užklausos turinys: { "params": { ... } }

Atsakymas: funkcijos PHP grąžinama reikšmė kaip JSON.

Šiuos galinius taškus galite tiesiogiai iškviesti iš bet kurio HTTP kliento, tačiau rekomenduojamas būdas yra bs.fn(), nes jis automatiškai tvarko nonce autentifikavimą.

Kabliukai

Veiksmai vykdomi prieš ir po kiekvieno RPC iškvietimo tiek iš REST, tiek iš PHP. Visi kabliukai gauna vieną $params masyvą:

Kabliukas Parametrai
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.
});

Filtras

Programiškai keiskite arba pridėkite funkcijų iš bloko išorės:

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

Kada naudoti RPC, o kada – duomenų bazę

db.php pagal schemą automatiškai generuoja CRUD galinius taškus. Naudokite jį, kai reikia standartinių kūrimo, skaitymo, naujinimo ir šalinimo operacijų su patvirtinimu.

rpc.php skirta pasirinktinei logikai: el. laiškų siuntimui, išorinių API iškvietimui, duomenų iš kelių schemų agregavimui, sudėtingų užklausų vykdymui ar bet kam, kas neatitinka CRUD modelio.

Šios dvi sistemos yra nepriklausomos ir viena kitą papildo. Daugelyje blokų naudojamos abi: db.php duomenų modeliui, o rpc.php – verslo logikai.