Ga naar de inhoud

RPC

RPC (Remote Procedure Call) laat je PHP-functies definiëren in je blok en aanroepen vanuit de frontend. In plaats van handmatig REST-API-routes te registreren, controllers te maken en fetch-aanroepen in te stellen, schrijf je een functie in rpc.php en roep je die aan met bs.fn(). Blockstudio regelt de routering van eindpunten, authenticatie, nonce-validatie en JSON-serialisatie.

Dit patroon is geïnspireerd op tRPC: definieer procedures aan de serverzijde en roep ze aan vanaf de client met een getypeerde helper. Geen URL-constructie en geen handmatige fetch-standaardcode.

Werking

  1. Je maakt rpc.php in je blokmap
  2. Dit retourneert een associatieve array met benoemde functies
  3. Blockstudio registreert voor elke functie een REST-eindpunt
  4. De bs.fn()-client roept ze op naam aan
  5. Parameters gaan erin, JSON komt eruit
Code
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Functies definiëren

Elke sleutel in de geretourneerde array is een functienaam. De eenvoudigste vorm is een directe callback:

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

Elke functie ontvangt één $params-array en moet een array retourneren. De retourwaarde wordt als JSON naar de client verzonden.

Gebruik voor opties voor toegangsbeheer de uitgebreide notatie met callback en aanvullende sleutels:

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

PHP-native definities

Als je de voorkeur geeft aan PHP-eigen metadata in plaats van geneste arrays, kan rpc.php ook een object met methoden voorzien van attributen retourneren. Arrays werken nog precies hetzelfde.

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

Opmerkingen:

  • Methodenamen worden standaard genormaliseerd naar kleine letters met snake_case, dus getStatus() wordt get_status
  • Gebruik name: om de naam van het eindpunt expliciet te overschrijven
  • Access::Session komt overeen met het oude gedrag van 'public' => true
  • Access::Open komt overeen met het oude gedrag van 'public' => 'open'
  • Laat access: weg voor het standaardgedrag waarbij alleen geauthenticeerde gebruikers toegang hebben

Aanroepen vanuit JavaScript

Blockstudio voegt automatisch een bs.fn()-helper toe op pagina’s met blokken die RPC-functies hebben.

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

De bloknaam doorgeven

bs.fn() valt terug op het attribuut data-block van document.currentScript als je het derde argument weglaat. Blockstudio geeft zowel script.js als inline scripts (script-inline.js of script.inline.js) weer als <script type="module">-tags, en modulescripts hebben geen document.currentScript. Geef daarom in blokscripts de bloknaam op als derde argument:

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

Zonder dit argument geeft de aanroep bs.fn: block name required een fout.

Foutafhandeling

bs.fn() lost op met de geparseerde JSON-body, ongeacht de HTTP-status. Als een functie een WP_Error retourneert, lost de promise op met een object met daarin de code, message en data. Controleer daarom op code:

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

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

De promise wordt alleen afgewezen als het verzoek zelf mislukt of als de reactie niet JSON is.

Met de Interactivity API

RPC werkt goed samen met WordPress Interactivity API. De acties in je winkel roepen serverfuncties aan en werken de reactieve status bij met het antwoord. De UI wordt automatisch bijgewerkt:

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>

Toegangsbeheer

Standaard vereisen functies een geauthenticeerde (ingelogde) gebruiker. Dit sluit aan bij de conventies van WordPress, waarbij REST-eindpunten standaard zijn beveiligd.

Openbare functies

Sta niet-geauthenticeerde toegang toe met CSRF-bescherming:

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

Gecachete pagina’s

bs.fn() haalt actuele inloggegevens op bij het niet-gecachete endpoint van dezelfde oorsprong POST /wp-json/blockstudio/v1/client/credentials. Verlopende WordPress-nonces en Blockstudio-CSRF-tokens worden niet opgeslagen in de paginacache HTML, zodat openbare aanroepen blijven werken wanneer een externe paginacache HTML serveert die ouder is dan 24 uur.

Vernieuwing gebeurt op verzoek: een pagina laden zonder een API aan te roepen, leidt niet tot een aanvraag voor inloggegevens. RPC en databaseclients delen de vernieuwing, vernieuwen inloggegevens na vijf minuten gebruik en proberen het eenmaal opnieuw bij een verlopen nonce of CSRF-token. Bevoegdheidsfouten en toepassingsfouten worden niet opnieuw geprobeerd. Authenticatie blijft de aanmeldcookie van de huidige bezoeker WordPress volgen; het vernieuwen van inloggegevens geeft geen toegang tot privéfuncties. Houd het endpoint voor inloggegevens buiten elke CDN- of proxycache; de reacties zijn expliciet gemarkeerd als private, no-store.

Open functies

Voor webhooks of externe API-callbacks waarvoor volledig open toegang zonder token nodig is:

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

Machtigingen

Beperk de toegang tot specifieke WordPress-machtigingen. Gebruik een string voor één machtiging of een array als de gebruiker er slechts één nodig heeft:

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

Standaard accepteren functies alleen POST-verzoeken. Dit is de veiligste standaard voor bewerkingen die de status wijzigen. Sta zo nodig aanvullende methoden toe:

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

Aanroepen tussen blokken

Vanuit JavaScript

Elk blok kan functies van elk ander blok aanroepen door de bloknaam als derde argument door te geven. Zo kun je blokken combineren:

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

Vanuit PHP

Gebruik Rpc::call() voor aanroepen tussen blokken aan de serverzijde. Dit is handig wanneer een RPC-functie aanroepen naar andere blokken moet coördineren:

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

Achter de schermen wordt elke functie gekoppeld aan een REST-route:

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

Request-body: { "params": { ... } }

Reactie: De retourwaarde van de PHP-functie als JSON.

Je kunt deze eindpunten rechtstreeks vanuit elke HTTP-client aanroepen, maar bs.fn() is de aanbevolen manier, omdat die nonce-authenticatie automatisch afhandelt.

Hooks

Acties worden uitgevoerd vóór en na elke RPC-aanroep, zowel vanuit REST als vanuit PHP. Alle hooks ontvangen één $params-array:

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

Filter

Wijzig of voeg programmatisch functies toe van buiten het blok:

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

Wanneer gebruik je RPC en wanneer de database?

db.php genereert automatisch CRUD-eindpunten op basis van een schema. Gebruik dit voor standaardbewerkingen voor maken, lezen, bijwerken en verwijderen, met validatie.

rpc.php is bedoeld voor aangepaste logica: e-mails versturen, externe API’s aanroepen, gegevens uit meerdere schema’s samenvoegen, complexe query’s uitvoeren of andere taken die niet in het CRUD-patroon passen.

De twee systemen zijn onafhankelijk en vullen elkaar aan. Veel blokken gebruiken ze allebei: db.php voor het gegevensmodel en rpc.php voor de bedrijfslogica erbovenop.