Liigu sisu juurde

RPC

RPC (Remote Procedure Call) võimaldab määratleda plokis PHP funktsioone ja kutsuda neid kasutajaliidesest. Selle asemel et registreerida käsitsi REST API marsruute, luua kontrollereid ja ühendada fetch kutseid, kirjutate funktsiooni failis rpc.php ja kutsute seda käsuga bs.fn(). Blockstudio haldab lõpp-punktide marsruutimist, autentimist, nonce’i valideerimist ja JSON serialiseerimist.

Muster on inspireeritud teegist tRPC: määratlege protseduurid serveripoolel ja kutsuge neid kliendist tüübistatud abifunktsiooniga. Pole vaja luua URL ega kirjutada käsitsi fetch põhikoodi.

Kuidas see töötab

  1. Loote ploki kausta faili rpc.php
  2. See tagastab nimeliste funktsioonide assotsiatiivse massiivi
  3. Blockstudio registreerib iga funktsiooni jaoks REST lõpp-punkti
  4. bs.fn() klient kutsub neid nime järgi
  5. Sisse antakse parameetrid, välja tuleb JSON
Kood
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Funktsioonide määratlemine

Tagastatud massiivi iga võti on funktsiooni nimi. Lihtsaim variant on otse määratud tagasihelistusfunktsioon:

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

Iga funktsioon saab ühe $params massiivi ja peaks tagastama massiivi. Tagastusväärtus saadetakse kliendile kujul JSON.

Juurdepääsu reguleerimiseks kasutage laiendatud vormingut, kus on callback ja lisavõtmed:

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

PHP-omased määratlused

Kui eelistate pesastatud massiividele PHP-põhiseid metaandmeid, võib rpc.php tagastada ka objektide meetoditega objekti. Massiivid töötavad endiselt täpselt samamoodi.

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

Märkused:

  • Vaikimisi teisendatakse meetodite nimed väiketähtedest koosnevateks snake_case’i nimedeks, nii et getStatus() muutub nimeks get_status
  • Kasutage name:, et lõpp-punkti nime selgesõnaliselt muuta
  • Access::Session vastab vanale käitumisele 'public' => true
  • Access::Open vastab vanale käitumisele 'public' => 'open'
  • Vaikimisi nõutava autentimise säilitamiseks jätke access: välja

Kutsumine kasutajaliidesest JavaScript

Blockstudio lisab automaatselt bs.fn() abifunktsiooni lehtedele, kus on plokke RPC funktsioonidega.

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

Ploki nime edastamine

bs.fn() kasutab kolmanda argumendi puudumisel document.currentScript atribuuti data-block. Blockstudio prindib nii script.js kui ka skriptid (script-inline.js või script.inline.js) <script type="module">-siltidena, moodulskriptidel aga puudub document.currentScript. Seetõttu edastage plokiskriptides kolmanda argumendina ploki nimi:

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

Ilma selleta viskab väljakutse vea bs.fn: block name required.

Vigade käsitlemine

bs.fn() lahendub parsitud JSON kehaga olenemata HTTP olekust. Kui funktsioon tagastab WP_Error, lahendub lubadus objektiga, mis sisaldab selle code, message ja data, seega kontrollige code väärtust:

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

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

Lubadus lükatakse tagasi ainult siis, kui päring ise ebaõnnestub või vastus pole JSON.

Koos Interactivity API-ga

RPC sobib loomulikult kokku Interactivity WordPress-ga API. Poe toimingud kutsuvad serverifunktsioone ja uuendavad vastuse põhjal reaktiivset olekut. UI uueneb automaatselt:

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>

Juurdepääsukontroll

Vaikimisi vajavad funktsioonid autentitud (sisselogitud) kasutajat. See vastab WordPress tavale, mille kohaselt on REST lõpp-punktid vaikimisi kaitstud.

Avalikud funktsioonid

Lubage autentimata juurdepääs CSRF-kaitsega:

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

Vahemällu salvestatud lehed

bs.fn() hangib värsked mandaadid vahemällu salvestamata sama päritoluga lõpp-punktist POST /wp-json/blockstudio/v1/client/credentials. Aeguvaid WordPress nonce’e ja Blockstudio CSRF-tokeneid lehe HTML ei salvestata, seega toimivad avalikud kutsed edasi ka siis, kui väline lehevahemälu serveerib üle 24 tunni vanust HTML.

Värskendamine toimub viivitusega: lehe laadimine ilma API kutsumata ei tekita mandaatide päringut. RPC ja andmebaasi kliendid jagavad värskendust, uuendavad mandaate pärast viit minutit kasutamist ning proovivad aegunud nonce’i või CSRF-tokeni korral korra uuesti. Võimekuse tõrkeid ja rakenduse vigu uuesti ei proovita. Autentimisel kasutatakse endiselt praeguse külastaja WordPress sisselogimisküpsist; mandaatide värskendamine ei anna ligipääsu privaatsetele funktsioonidele. Hoia mandaatide lõpp-punkt väljaspool igasugust CDN või puhverserveri vahemälu; selle vastused on sõnaselgelt märgitud private, no-store.

Avatud funktsioonid

Veebihaakide või väliste API tagasihelistuste jaoks, mis vajavad täiesti avatud juurdepääsu ilma tokenita:

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

Õigused

Piirake juurdepääsu kindlatele WordPress õigustele. Ühe õiguse jaoks kasutage stringi, mitme puhul massiivi, kus kasutajal peab olema neist ükskõik milline:

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 meetodid

Vaikimisi aktsepteerivad funktsioonid ainult POST päringuid. See on olekut muutvate toimingute jaoks kõige turvalisem vaikevalik. Vajaduse korral lubage lisameetodid:

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

Plokkidevahelised kutsed

Plokist JavaScript

Iga plokk saab kutsuda mis tahes teise ploki funktsioone, edastades kolmanda argumendina ploki nime. Nii saab plokke omavahel kombineerida:

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

Plokist PHP

Kasutage serveripoolseteks plokkidevahelisteks kutseteks käsku Rpc::call(). See on kasulik, kui üks RPC funktsioon peab korraldama teiste plokkide kutseid:

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 lõpp-punkt

Kapoti all seostatakse iga funktsioon marsruudiga REST:

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

Päringu sisu: { "params": { ... } }

Vastus: funktsiooni PHP tagastusväärtus kujul JSON.

Neid lõpp-punkte saab kutsuda otse mis tahes HTTP kliendist, kuid soovitatav on kasutada bs.fn(), sest see haldab nonce-autentimist automaatselt.

Hook’id

Toimingud käivituvad enne ja pärast iga RPC kutset nii REST kui ka PHP kaudu. Kõik hook’id saavad ühe $params massiivi:

Hook Parameetrid
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.
});

Filtreeri

Muutke või lisage funktsioone programmiliselt väljastpoolt plokki:

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

Millal kasutada RPC-i ja millal andmebaasi

db.php loob CRUD-lõpp-punktid skeemi põhjal automaatselt. Kasutage seda siis, kui vajate valideerimisega tavalisi loomise, lugemise, uuendamise ja kustutamise toiminguid.

rpc.php on mõeldud kohandatud loogika jaoks: e-kirjade saatmiseks, väliste API-de kutsumiseks, mitme skeemi andmete koondamiseks, keerukate päringute käivitamiseks või muuks, mis CRUD-mustriga ei sobi.

Need kaks süsteemi on sõltumatud ja täiendavad teineteist. Paljud plokid kasutavad mõlemat: db.php andmemudeli jaoks ja rpc.php selle peale ehitatud äriloogika jaoks.