Siirry sisältöön

RPC

RPC (Remote Procedure Call) mahdollistaa PHP-funktioiden määrittämisen lohkossasi ja niiden kutsumisen käyttöliittymästä. Sen sijaan, että rekisteröisit REST API -reitit manuaalisesti, loisit ohjaimia ja kytkisit fetch-kutsut, kirjoitat funktion tiedostoon rpc.php ja kutsut sitä muodossa bs.fn(). Blockstudio huolehtii päätepisteiden reitityksestä, todennuksesta, nonce-tunnuksen tarkistuksesta ja JSON-sarjallistamisesta.

Toteutusmalli on saanut vaikutteita tRPC:stä: määritä proseduurit palvelimella ja kutsu niitä asiakkaalta tyypitetyllä apufunktiolla. Ei URL-konstruktoreita eikä manuaalista fetch-mallikoodia.

Näin se toimii

  1. Luot rpc.php-tiedoston lohkohakemistoosi
  2. Se palauttaa assosiatiivisen taulukon nimetyistä funktioista
  3. Blockstudio rekisteröi kullekin funktiolle REST-päätepisteen
  4. bs.fn()-asiakas kutsuu niitä nimen perusteella
  5. Parametrit lähetetään sisään, ja tuloksena saadaan JSON
Koodi
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Funktioiden määrittäminen

Jokainen palautetun taulukon avain on funktion nimi. Yksinkertaisin muoto on suora takaisinkutsu:

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

Jokainen funktio saa yhden $params-taulukon ja sen pitäisi palauttaa taulukko. Palautusarvo lähetetään asiakkaalle muodossa JSON.

Käyttöoikeuksien hallinnan vaihtoehtoja varten käytä laajennettua muotoa, jossa on callback ja lisäavaimia:

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

PHP-natiivimääritykset

Jos haluat PHP-natiivin metatiedon sisäkkäisten taulukoiden sijaan, rpc.php voi palauttaa myös objektin, jolla on attribuuteilla merkityt metodit. Taulukot toimivat edelleen täsmälleen samalla tavalla.

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

Huomautukset:

  • Metodien nimet muunnetaan oletusarvoisesti pienaakkosellisiksi snake_case-nimiksi, joten getStatus() muuttuu muotoon get_status
  • Käytä name:-määritystä päätepisteen nimen asettamiseen erikseen
  • Access::Session vastaa vanhaa toimintaa 'public' => true
  • Access::Open vastaa vanhaa toimintaa 'public' => 'open'
  • Jätä access: pois, kun haluat käyttää oletusta, jossa vain todennetut käyttäjät pääsevät toimintoihin

Kutsuminen JavaScript-ympäristöstä

Blockstudio lisää automaattisesti bs.fn()-apufunktion sivuille, joilla on lohkoja, joissa on RPC-funktioita.

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

Lohkon nimen välittäminen

Jos kolmas argumentti jätetään pois, bs.fn() käyttää varalla document.currentScript-määrityksen data-block-attribuuttia. Blockstudio tulostaa sekä script.js-merkinnät että sisäiset skriptit (script-inline.js tai script.inline.js) <script type="module">-tunnisteina, ja moduuliskripteillä ei ole attribuuttia document.currentScript. Siksi lohkon skripteissä lohkon nimi on välitettävä kolmantena argumenttina:

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

Ilman sitä kutsu aiheuttaa virheen bs.fn: block name required.

Virheenkäsittely

bs.fn() ratkaistuu jäsennetyllä JSON-rungolla HTTP-tilasta riippumatta. Kun funktio palauttaa arvon WP_Error, lupaus ratkaistuu objektilla, joka sisältää arvot code, message ja data, joten tarkista code:

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

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

Lupaus hylätään vain, jos pyyntö epäonnistuu tai vastaus ei ole JSON.

Yhdessä Interactivity APIin kanssa

RPC toimii luontevasti yhdessä WordPress-Interactivity APIin kanssa. Kaupan toiminnot kutsuvat palvelinfunktioita ja päivittävät reaktiivisen tilan vastauksen perusteella. UI päivittyy automaattisesti:

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>

Käyttöoikeuksien hallinta

Oletusarvoisesti funktiot edellyttävät todennettua eli sisäänkirjautunutta käyttäjää. Tämä vastaa WordPress-käytäntöjä, joissa REST-päätepisteet on suojattu oletusarvoisesti.

Julkiset funktiot

Salli todentamattomien käyttäjien pääsy CSRF-suojauksella:

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

Välimuistissa olevat sivut

bs.fn() hakee uudet tunnistetiedot välimuistittamattomasta saman alkuperän POST /wp-json/blockstudio/v1/client/credentials-päätepisteestä. Vanhenevia WordPress-nonceja ja Blockstudio CSRF-tunnisteita ei tallenneta sivun HTML-sisältöön, joten julkiset kutsut toimivat edelleen, kun ulkoinen sivuvälimuisti tarjoaa yli 24 tuntia vanhan HTML-sisällön.

Päivitys tehdään tarvittaessa: sivun lataaminen ilman API-kutsua ei lähetä tunnistetietopyyntöä. RPC ja tietokanta-asiakasohjelmat käyttävät samaa päivitystä, uusivat tunnistetiedot viiden minuutin käytön jälkeen ja yrittävät kerran uudelleen vanhentuneen noncen tai CSRF-tunnisteen yhteydessä. Kyvykkyysvirheitä ja sovellusvirheitä ei yritetä uudelleen. Todennus perustuu edelleen nykyisen kävijän WordPress-kirjautumisevästeeseen; tunnistetietojen päivittäminen ei anna pääsyä yksityisiin toimintoihin. Pidä tunnistetietojen päätepiste kaikkien CDN- ja välityspalvelinvälimuistien ulkopuolella; sen vastaukset on merkitty nimenomaisesti private, no-store-tunnisteella.

Avoimet funktiot

Webhookeja tai ulkoisia API-takaisinkutsuja varten, kun pääsyn on oltava täysin avoin ilman tunnusta:

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

Käyttöoikeudet

Rajoita pääsy tiettyihin WordPress-käyttöoikeuksiin. Käytä merkkijonoa yhdelle käyttöoikeudelle tai taulukkoa, kun käyttäjällä on oltava jokin niistä:

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-metodit

Oletusarvoisesti funktiot hyväksyvät vain POST-pyynnöt. Tämä on turvallisin oletus tilaa muuttaville toiminnoille. Salli tarvittaessa muitakin metodeja:

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

Lohkojen väliset kutsut

Kutsuminen JavaScript-ympäristöstä

Mikä tahansa lohko voi kutsua toisen lohkon funktioita välittämällä lohkon nimen kolmantena argumenttina. Näin lohkot voidaan yhdistää:

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

Kutsuminen PHP-ympäristöstä

Käytä Rpc::call()-kutsuja lohkojen välisiin palvelinpuolen kutsuihin. Tämä on hyödyllistä, kun yksi RPC-funktio tarvitsee koordinoida kutsuja muihin lohkoihin:

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-päätepiste

Taustalla kukin funktio yhdistetään REST-reittiin:

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

Pyynnön runko: { "params": { ... } }

Vastaus: PHP-funktion palautusarvo muodossa JSON.

Voit kutsua näitä päätepisteitä suoraan mistä tahansa HTTP-asiakasohjelmasta, mutta suositeltu tapa on bs.fn(), koska se hoitaa nonce-todennuksen automaattisesti.

Hookit

Toiminnot suoritetaan ennen jokaista RPC-kutsua ja sen jälkeen sekä REST- että PHP-kutsuissa. Kaikki hookit saavat yhden $params-taulukon:

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

Suodatin

Muokkaa funktioita tai lisää niitä ohjelmallisesti lohkon ulkopuolelta:

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

Milloin käyttää RPC-järjestelmää ja milloin tietokantaa

db.php luo CRUD-päätepisteet automaattisesti skeemasta. Käytä sitä, kun tarvitset tavallisia luonti-, luku-, päivitys- ja poistotoimintoja validointeineen.

rpc.php on mukautettua logiikkaa varten: sähköpostien lähettämiseen, ulkoisten API-rajapintojen kutsumiseen, skeemojen datan yhdistämiseen, monimutkaisten kyselyjen suorittamiseen tai muuhun, mikä ei sovi CRUD-malliin.

Nämä kaksi järjestelmää ovat itsenäisiä ja täydentävät toisiaan. Monissa lohkoissa käytetään molempia: db.php-järjestelmää datamalliin ja rpc.php-järjestelmää sen päälle rakentuviin liiketoimintalogiikan toteutuksiin.