Preskoči na vsebino

RPC

RPC (Remote Procedure Call) omogoča določanje funkcij PHP v bloku in njihovo klicanje iz vmesnika. Namesto ročnega registriranja poti REST API, ustvarjanja krmilnikov in povezovanja klicev fetch napišete funkcijo v rpc.php in jo pokličete z bs.fn(). Blockstudio poskrbi za usmerjanje končnih točk, avtentikacijo, preverjanje nonce in serializacijo JSON.

Vzorec se zgleduje po tRPC: postopke določite na strežniku, v odjemalcu pa jih kličete s tipiziranim pomočnikom. Brez sestavljanja URL, brez ročne odvečne kode za fetch.

Kako deluje

  1. V mapi bloka ustvarite rpc.php
  2. Vrne asociativno polje poimenovanih funkcij
  3. Blockstudio registrira končno točko REST za vsako funkcijo
  4. Odjemalec bs.fn() jih kliče po imenu
  5. Parametri se pošljejo, rezultat JSON pa se vrne
Koda
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Določanje funkcij

Vsak ključ v vrnjenem polju je ime funkcije. Najpreprostejša oblika je neposredni povratni klic:

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

Vsaka funkcija prejme eno samo polje $params in mora vrniti polje. Vrnjena vrednost se odjemalcu pošlje kot JSON.

Za možnosti nadzora dostopa uporabite razširjeno obliko z callback in dodatnimi ključi:

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

Definicije, izvorne za PHP

Če vam bolj ustrezajo metapodatki, značilni za PHP, namesto ugnezdenih polj, lahko rpc.php vrne tudi objekt z metodami z atributi. Polja še vedno delujejo povsem enako.

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

Opombe:

  • Imena metod so privzeto normalizirana v zapis snake case z malimi črkami, zato getStatus() postane get_status
  • Z name: izrecno določite ime končne točke
  • Access::Session ustreza staremu načinu delovanja 'public' => true
  • Access::Open ustreza staremu načinu delovanja 'public' => 'open'
  • Izpustite access: za privzeto vedenje, ki dovoljuje samo preverjene uporabnike

Klicanje iz JavaScript

Blockstudio na straneh z bloki, ki vsebujejo funkcije RPC, samodejno vstavi pomočnika bs.fn().

Podpis: bs.fn(functionName, params?, blockName?) -> Promise

Podajanje imena bloka

Če izpustite tretji argument, bs.fn() uporabi atribut data-block za document.currentScript. Blockstudio izpiše script.js in vgrajene skripte (script-inline.js ali script.inline.js) kot oznake <script type="module">, skripte modula pa nimajo document.currentScript, zato v skriptah bloka kot tretji argument podajte ime bloka:

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

Brez tega klic sproži napako bs.fn: block name required.

Obravnava napak

bs.fn() razreši obljubo z razčlenjenim telesom JSON ne glede na stanje HTTP. Ko funkcija vrne WP_Error, se obljuba razreši z objektom, ki vsebuje njegovo code, message in data, zato preverite vrednost code:

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

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

Obljuba je zavrnjena le, če zahteva sama spodleti ali odgovor ni JSON.

Z Interactivity API

RPC se naravno povezuje z WordPress Interactivity API. Dejanja shrambe kličejo strežniške funkcije in posodobijo reaktivno stanje z odgovorom. UI se posodobi samodejno:

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>

Nadzor dostopa

Funkcije privzeto zahtevajo preverjenega uporabnika (prijavljenega uporabnika). To sledi konvencijam WordPress, po katerih so končne točke REST privzeto zaščitene.

Javne funkcije

Dovolite dostop brez preverjanja pristnosti z zaščito 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
    ],
];

Predpomnjene strani

bs.fn() pridobi sveže poverilnice iz nepredpomnjene končne točke POST /wp-json/blockstudio/v1/client/credentials istega izvora. Žetoni nonce WordPress in žetoni CSRF Blockstudio s časovno omejeno veljavnostjo niso shranjeni v predpomnilniku strani HTML, zato javni klici še naprej delujejo, ko zunanji predpomnilnik strani postreže HTML, starejšo od 24 ur.

Osveževanje je odloženo: nalaganje strani brez klica API ne sproži zahteve za poverilnice. RPC in odjemalci zbirke podatkov uporabljajo isto osvežitev, obnovijo poverilnice po petih minutah uporabe in enkrat ponovijo poskus, če je žeton nonce ali CSRF potekel. Pri napakah zmožnosti in napakah aplikacije se poskus ne ponovi. Preverjanje pristnosti še naprej uporablja prijavni piškotek WordPress trenutnega obiskovalca; osveževanje poverilnic ne omogoča dostopa do zasebnih funkcij. Končno točko za poverilnice hranite zunaj predpomnilnika CDN ali posredniškega strežnika; njeni odgovori so izrecno označeni z private, no-store.

Odprte funkcije

Za spletne kljuke ali povratne klice API od zunaj, ki potrebujejo povsem odprt dostop brez žetona:

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

Zmogljivosti

Dostop omejite na izbrane zmogljivosti WordPress. Za eno zmogljivost uporabite niz, za več pa polje, če uporabnik potrebuje katero koli od njih:

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

Metode HTTP

Funkcije privzeto sprejemajo samo zahteve POST. To je najvarnejša privzeta nastavitev za operacije, ki spreminjajo stanje. Po potrebi dovolite tudi druge metode:

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

Klicanje med bloki

Iz JavaScript

Vsak blok lahko kliče funkcije katerega koli drugega bloka tako, da ime bloka poda kot tretji argument. Tako lahko sestavljate bloke:

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

Iz PHP

Za klice med bloki na strežniku uporabite Rpc::call(). To je uporabno, ko mora funkcija RPC usklajevati klice drugih 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];
    },
];

Končna točka REST

V ozadju je vsaka funkcija povezana s potjo REST:

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

Telo zahteve: { "params": { ... } }

Odgovor: Vrnjena vrednost funkcije PHP v obliki JSON.

Te končne točke lahko pokličete neposredno iz katerega koli odjemalca HTTP, vendar je priporočeni način bs.fn(), saj samodejno poskrbi za avtentikacijo nonce.

Kavlji

Dejanja se sprožijo pred vsakim klicem RPC in po njem, tako iz REST kot iz PHP. Vsi kavlji prejmejo eno samo polje $params:

Kavelj Parametri
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.
});

Filtriranje

Programsko spreminjajte ali dodajajte funkcije od zunaj bloka:

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

Kdaj uporabiti RPC in kdaj podatkovno bazo

db.php samodejno ustvari končne točke CRUD iz sheme. Uporabite ga za standardne operacije ustvarjanja, branja, posodabljanja in brisanja s preverjanjem veljavnosti.

rpc.php je namenjen logiki po meri: pošiljanju e-pošte, klicanju zunanjih API-jev, združevanju podatkov iz več shem, izvajanju zapletenih poizvedb ali vsemu, kar ne sodi v vzorec CRUD.

Sistema sta neodvisna in se dopolnjujeta. Številni bloki uporabljajo oba: db.php za podatkovni model in rpc.php za poslovno logiko, ki temelji na njem.