Přejít k obsahu

RPC

RPC (Remote Procedure Call) umožňuje definovat funkce PHP v bloku a volat je z frontendu. Místo ruční registrace tras REST API, vytváření kontrolerů a propojování volání fetch napíšete funkci v rpc.php a zavoláte ji pomocí bs.fn(). Blockstudio se postará o směrování endpointů, ověřování, ověření nonce a serializaci JSON.

Tento vzor je inspirován tRPC: procedury definujete na serveru a voláte je z klienta pomocí typovaného pomocníka. Žádné vytváření URL ani ruční základní kód fetch.

Jak to funguje

  1. V adresáři bloku vytvoříte rpc.php
  2. Vrátí asociativní pole pojmenovaných funkcí
  3. Blockstudio zaregistruje endpoint REST pro každou funkci
  4. Klient bs.fn() je volá podle názvu
  5. Předají se parametry a vrátí se JSON
Kód
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definování funkcí

Každý klíč ve vráceném poli představuje název funkce. Nejjednodušší je přímé zpětné volání:

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

Každá funkce dostává jedno pole $params a měla by vrátit pole. Návratová hodnota se klientovi odešle jako JSON.

Pro nastavení řízení přístupu použijte rozšířený formát s callback a dalšími klíči:

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

Definice nativní pro PHP

Pokud místo vnořených polí upřednostňujete metadata nativní pro PHP, rpc.php může také vrátit objekt s metodami opatřenými atributy. Pole fungují stále stejně.

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

Poznámky:

  • Názvy metod se ve výchozím nastavení převádějí na malá písmena ve formátu snake case, takže getStatus() se změní na get_status
  • Pomocí name: můžete výslovně přepsat název endpointu
  • Access::Session odpovídá dřívějšímu chování 'public' => true
  • Access::Open odpovídá dřívějšímu chování 'public' => 'open'
  • Vynecháním access: zachováte výchozí chování, které povoluje pouze ověřené uživatele

Volání z JavaScript

Blockstudio automaticky vloží pomocnou funkci bs.fn() na stránky obsahující bloky s funkcemi RPC.

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

Předání názvu bloku

Pokud vynecháte třetí argument, bs.fn() použije jako náhradní hodnotu atribut data-block v document.currentScript. Blockstudio vypisuje oba script.js i inline skripty (script-inline.js nebo script.inline.js) jako značky <script type="module"> a modulové skripty nemají document.currentScript, proto ve skriptech bloků předejte název bloku jako třetí argument:

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

Bez něj volání vyvolá bs.fn: block name required.

Ošetření chyb

bs.fn() se vyřeší s naparsovaným tělem JSON bez ohledu na stav HTTP. Když funkce vrátí WP_Error, příslib se vyřeší objektem obsahujícím jeho code, message a data, proto kontrolujte code:

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

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

Příslib se zamítne pouze v případě, že samotný požadavek selže nebo odpověď není JSON.

S modulem Interactivity API

RPC přirozeně spolupracuje s WordPress Interactivity API. Akce ve vašem obchodě volají serverové funkce a aktualizují reaktivní stav podle odpovědi. UI se aktualizuje automaticky:

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>

Řízení přístupu

Funkce ve výchozím nastavení vyžadují ověřeného (přihlášeného) uživatele. To odpovídá konvencím WordPress, kde jsou endpointy REST ve výchozím nastavení chráněné.

Veřejné funkce

Povolte přístup bez ověření s ochranou 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
    ],
];

Cachované stránky

bs.fn() získává aktuální přihlašovací údaje z necachovaného endpointu POST /wp-json/blockstudio/v1/client/credentials na stejném originu. Nonce WordPress s omezenou platností a CSRF tokeny Blockstudio se neukládají do HTML stránky, takže veřejná volání fungují dál, i když externí cache stránky poskytuje HTML starší než 24 hodin.

Obnovení probíhá až na vyžádání: načtení stránky bez volání API nevyvolá požadavek na přihlašovací údaje. RPC a databázoví klienti sdílejí proces obnovení, obnovují přihlašovací údaje po pěti minutách používání a při vypršení nonce nebo CSRF tokenu požadavek jednou zopakují. Chyby oprávnění a chyby aplikace se neopakují. Ověření stále probíhá pomocí přihlašovací cookie WordPress aktuálního návštěvníka; obnovení přihlašovacích údajů nezpřístupní soukromé funkce. Endpoint s přihlašovacími údaji umístěte mimo cache CDN i proxy; jeho odpovědi jsou výslovně označené jako private, no-store.

Otevřené funkce

Pro webhooky nebo externí zpětná volání API, která potřebují zcela otevřený přístup bez jakéhokoli ověřovacího tokenu:

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

Oprávnění

Omezte přístup na konkrétní oprávnění WordPress. Pro jedno oprávnění použijte řetězec, nebo pole, pokud uživateli stačí kterékoli z nich:

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

Metody HTTP

Funkce ve výchozím nastavení přijímají pouze požadavky POST. To je nejbezpečnější výchozí nastavení pro operace, které mění stav. Podle potřeby povolte další metody:

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

Volání napříč bloky

Z JavaScript

Každý blok může volat funkce jiného bloku předáním názvu bloku jako třetího argumentu. To umožňuje skládat bloky dohromady:

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

Z PHP

Pro volání napříč bloky na straně serveru použijte Rpc::call(). Hodí se, když jedna funkce RPC potřebuje koordinovat volání dalších bloků:

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

Endpoint REST

Na pozadí se každá funkce mapuje na trasu REST:

Kód
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

Tělo požadavku: { "params": { ... } }

Odpověď: Návratová hodnota funkce PHP jako JSON.

Tyto endpointy můžete volat přímo z libovolného klienta HTTP, doporučený způsob je však bs.fn(), protože automaticky zajišťuje ověření nonce.

Hooky

Akce se spouštějí před každým voláním RPC i po něm, a to z REST i PHP. Všechny hooky dostávají jedno pole $params:

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

Filtr

Programově upravujte nebo přidávejte funkce zvenčí bloku:

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

Kdy použít RPC a kdy databázi

db.php automaticky generuje z definice schématu endpointy CRUD. Použijte ho, pokud potřebujete standardní operace vytvoření, čtení, aktualizace a odstranění s validací.

rpc.php slouží pro vlastní logiku: odesílání e-mailů, volání externích API, agregaci dat napříč schématy, spouštění složitých dotazů nebo cokoli, co neodpovídá vzoru CRUD.

Oba systémy jsou nezávislé a vzájemně se doplňují. Mnoho bloků používá oba: db.php pro datový model a rpc.php pro obchodní logiku nad ním.