Pāriet uz saturu

RPC

RPC (attālās procedūras izsaukums) ļauj definēt PHP funkcijas savā blokā un izsaukt tās no priekšgala. Tā vietā, lai manuāli reģistrētu REST API maršrutus, veidotu kontrollerus un savienotu fetch izsaukumus, ierakstiet funkciju rpc.php un izsauciet to ar bs.fn(). Blockstudio apstrādā galapunktu maršrutēšanu, autentifikāciju, nonce validāciju un JSON serializēšanu.

Šo risinājumu iedvesmojis tRPC: definējiet procedūras servera pusē un izsauciet tās klientā, izmantojot tipizētu palīgfunkciju. Nav jāveido URL un manuāli jāraksta fetch standarta kods.

Kā tas darbojas

  1. Izveidojiet rpc.php sava bloka direktorijā
  2. Tas atgriež asociatīvu masīvu ar nosauktām funkcijām
  3. Blockstudio reģistrē REST galapunktu katrai funkcijai
  4. bs.fn() klients izsauc tās pēc nosaukuma
  5. Parametri tiek nosūtīti, bet tiek saņemta JSON
Kods
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Funkciju definēšana

Katra atgrieztā masīva atslēga ir funkcijas nosaukums. Vienkāršākajā variantā izmantojiet tiešu atzvanes funkciju:

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

Katra funkcija saņem vienu $params masīvu un tai jāatgriež masīvs. Atgrieztā vērtība klientam tiek nosūtīta kā JSON.

Lai iestatītu piekļuves kontroli, izmantojiet izvērsto formātu ar callback un papildu atslēgām:

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

PHP vietējās definīcijas

Ja dodat priekšroku PHP vietējai metadatu sintaksei, nevis ligzdotiem masīviem, rpc.php var atgriezt arī objektu ar atribūtiem apzīmētām metodēm. Masīvi joprojām darbojas tieši tā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];
    }
};

Piezīmes:

  • Pēc noklusējuma metožu nosaukumi tiek pārveidoti par mazajiem burtiem snake case formātā, tāpēc getStatus() kļūst par get_status
  • Izmantojiet name:, lai skaidri norādītu galapunkta nosaukumu
  • Access::Session atbilst iepriekšējai 'public' => true darbībai
  • Access::Open atbilst iepriekšējai 'public' => 'open' darbībai
  • Izlaidiet access:, lai izmantotu noklusēto piekļuvi tikai autentificētiem lietotājiem

Izsaukšana no JavaScript

Blockstudio lapās, kurās ir bloki ar RPC funkcijām, automātiski ievieto bs.fn() palīgfunkciju.

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

Bloka nosaukuma norādīšana

Ja trešais arguments nav norādīts, bs.fn() izmanto document.currentScript atribūtu no data-block kā rezerves vērtību. Blockstudio izvada gan script.js, gan iekļautos skriptus (script-inline.js vai script.inline.js) kā <script type="module"> tagus, bet moduļu skriptiem nav document.currentScript, tāpēc bloka skriptos norādiet bloka nosaukumu kā trešo argumentu:

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

Ja to nenorādīsiet, izsaukums radīs bs.fn: block name required.

Kļūdu apstrāde

bs.fn() atrisina solījumu ar parsētu JSON pamattekstu neatkarīgi no HTTP statusa. Ja funkcija atgriež WP_Error, solījums tiek atrisināts ar objektu, kurā ir tā code, message un data, tāpēc pārbaudiet code:

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

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

Solījums tiek noraidīts tikai tad, ja pats pieprasījums neizdodas vai atbilde nav JSON.

Kopā ar Interactivity API

RPC dabiski papildina WordPress Interactivity API. Jūsu veikala darbības izsauc servera funkcijas un atjaunina reaktīvo stāvokli ar saņemto atbildi. UI tiek atjaunināts automātiski:

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>

Piekļuves kontrole

Pēc noklusējuma funkcijām nepieciešams autentificēts (pieteicies) lietotājs. Tas atbilst WordPress konvencijām, kurās REST galapunkti pēc noklusējuma ir aizsargāti.

Publiskās funkcijas

Atļaujiet piekļuvi bez autentifikācijas, izmantojot CSRF aizsardzību:

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

Kešatmiņā saglabātas lapas

bs.fn() iegūst jaunus akreditācijas datus no kešatmiņā neglabāta tās pašas izcelsmes POST /wp-json/blockstudio/v1/client/credentials galapunkta. Nonces WordPress, kam beidzas derīguma termiņš, un CSRF tokeni Blockstudio netiek saglabāti lapas HTML, tāpēc publiskie izsaukumi turpina darboties, kad ārējā lapu kešatmiņa apkalpo HTML, kas vecāka par 24 stundām.

Atsvaidzināšana notiek pēc vajadzības: ielādējot lapu un neizsaucot API, akreditācijas dati netiek pieprasīti. RPC un datubāzes klienti koplieto atsvaidzināšanu, atjauno akreditācijas datus pēc piecu minūšu lietošanas un vienu reizi mēģina vēlreiz, ja nonce vai CSRF tokens ir beidzies. Iespēju kļūdas un lietojumprogrammas kļūdas netiek mēģinātas vēlreiz. Autentifikācija joprojām balstās uz pašreizējā apmeklētāja WordPress pieteikšanās sīkdatni; akreditācijas datu atsvaidzināšana nepiešķir piekļuvi privātām funkcijām. Akreditācijas datu galapunktam jābūt ārpus jebkādas CDN vai starpniekservera kešatmiņas; tā atbildes ir skaidri atzīmētas kā private, no-store.

Atvērtās funkcijas

Tīmekļa āķiem vai ārējiem API atzvanes izsaukumiem, kam nepieciešama pilnīgi atvērta piekļuve bez tokena:

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

Atļaujas

Ierobežojiet piekļuvi konkrētām WordPress iespējām. Vienai iespējai izmantojiet virkni, bet vairākām — masīvu, kurā lietotājam nepieciešama jebkura viena iespēja:

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 metodes

Pēc noklusējuma funkcijas pieņem tikai POST pieprasījumus. Tas ir drošākais noklusējums darbībām, kas maina stāvokli. Vajadzības gadījumā atļaujiet arī citas metodes:

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

Izsaukumi starp blokiem

No JavaScript

Jebkurš bloks var izsaukt jebkura cita bloka funkcijas, kā trešo argumentu norādot bloka nosaukumu. Tas ļauj veidot bloku kompozīcijas:

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

No PHP

Izmantojiet Rpc::call() izsaukumiem starp blokiem servera pusē. Tas noder, ja vienai RPC funkcijai jākoordinē citu bloku izsaukumi:

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 galapunkts

Fonā katra funkcija tiek sasaistīta ar REST maršrutu:

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

Pieprasījuma pamatteksts: { "params": { ... } }

Atbilde: PHP funkcijas atgrieztā vērtība kā JSON.

Šos galapunktus var izsaukt tieši no jebkura HTTP klienta, taču ieteicams izmantot bs.fn(), jo tas automātiski apstrādā nonce autentifikāciju.

Āķi

Darbības tiek izpildītas pirms un pēc katra RPC izsaukuma gan no REST, gan no PHP. Visi āķi saņem vienu $params masīvu:

Āķis 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.
});

Filtrs

Modificējiet vai pievienojiet funkcijas programmatiski ārpus 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;
});

Kad izmantot RPC, bet kad — datubāzi

db.php automātiski ģenerē CRUD galapunktus no shēmas. Izmantojiet to, ja nepieciešamas standarta izveides, lasīšanas, atjaunināšanas un dzēšanas darbības ar validāciju.

rpc.php ir paredzēts pielāgotai loģikai: e-pasta ziņojumu sūtīšanai, ārējo API izsaukšanai, datu apkopošanai no vairākām shēmām, sarežģītu vaicājumu izpildei un visam, kas neatbilst CRUD modelim.

Abas sistēmas ir neatkarīgas un papildina viena otru. Daudzi bloki izmanto abas: db.php datu modelim un rpc.php biznesa loģikai, kas ar to strādā.