Zum Inhalt springen

RPC

Mit RPC (Remote Procedure Call) kannst du PHP-Funktionen in deinem Block definieren und vom Frontend aus aufrufen. Statt REST-API-Routen manuell zu registrieren, Controller zu erstellen und fetch-Aufrufe zu verbinden, schreibst du eine Funktion in rpc.php und rufst sie mit bs.fn() auf. Blockstudio übernimmt das Routing der Endpunkte, die Authentifizierung, die Nonce-Validierung und die JSON-Serialisierung.

Das Muster ist von tRPC inspiriert: Definiere deine Prozeduren serverseitig und rufe sie clientseitig mit einem typisierten Helper auf. Kein Erstellen von URL, kein manuelles fetch-Boilerplate.

So funktioniert es

  1. Du erstellst rpc.php in deinem Blockverzeichnis
  2. Es gibt ein assoziatives Array benannter Funktionen zurück
  3. Blockstudio registriert für jede Funktion einen REST-Endpunkt
  4. Der bs.fn()-Client ruft sie anhand ihres Namens auf
  5. Parameter hinein, JSON heraus
Code
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Funktionen definieren

Jeder Schlüssel im zurückgegebenen Array ist ein Funktionsname. Die einfachste Form ist ein direkter 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];
    },
];

Jede Funktion erhält ein einzelnes $params-Array und sollte ein Array zurückgeben. Der Rückgabewert wird als JSON an den Client gesendet.

Für Optionen zur Zugriffskontrolle verwendest du das erweiterte Format mit callback und zusätzlichen Schlüsseln:

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

PHP-native Definitionen

Wenn du PHP-native Metadaten statt verschachtelter Arrays bevorzugst, kann rpc.php auch ein Objekt mit Attributmethoden zurückgeben. Arrays funktionieren weiterhin genauso.

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

Hinweise:

  • Methodennamen werden standardmäßig in kleingeschriebene Snake-Case-Namen umgewandelt, daher wird getStatus() zu get_status
  • Mit name: kannst du den Endpunktnamen explizit überschreiben
  • Access::Session entspricht dem bisherigen Verhalten von 'public' => true
  • Access::Open entspricht dem bisherigen Verhalten von 'public' => 'open'
  • Lass access: weg, um das Standardverhalten „nur authentifizierte Benutzer“ zu verwenden

Aufruf von JavaScript

Blockstudio fügt auf Seiten mit Blöcken, die RPC-Funktionen enthalten, automatisch einen bs.fn()-Helper ein.

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

Blockname übergeben

Wenn du das dritte Argument weglässt, greift bs.fn() auf das Attribut data-block von document.currentScript zurück. Blockstudio gibt sowohl script.js als auch Inline-Skripte (script-inline.js oder script.inline.js) als <script type="module">-Tags aus. Modulscripts haben kein document.currentScript. Gib in Block-Skripten daher den Blocknamen als drittes Argument an:

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

Ohne diese Angabe löst der Aufruf bs.fn: block name required aus.

Fehlerbehandlung

bs.fn() wird mit dem geparsten JSON-Body aufgelöst, unabhängig vom HTTP-Status. Wenn eine Funktion ein WP_Error zurückgibt, wird das Promise mit einem Objekt aufgelöst, das code, message und data enthält. Prüfe daher auf code:

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

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

Das Promise wird nur abgelehnt, wenn die Anfrage selbst fehlschlägt oder die Antwort nicht JSON ist.

Mit der Interaktivitäts-API

RPC passt gut zur Interaktivitäts-WordPress von API. Deine Store-Aktionen rufen Serverfunktionen auf und aktualisieren den reaktiven Status mit der Antwort. Das UI aktualisiert sich automatisch:

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>

Zugriffskontrolle

Standardmäßig benötigen Funktionen einen authentifizierten (angemeldeten) Benutzer. Das entspricht den WordPress-Konventionen, nach denen REST-Endpunkte standardmäßig geschützt sind.

Öffentliche Funktionen

Erlaube nicht authentifizierten Zugriff mit CSRF-Schutz:

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

Zwischengespeicherte Seiten

bs.fn() ruft frische Zugangsdaten vom nicht zwischengespeicherten Same-Origin-POST /wp-json/blockstudio/v1/client/credentials-Endpunkt ab. Ablaufende WordPress-Nonces und Blockstudio-CSRF-Tokens werden nicht im Seiten-HTML gespeichert. Daher funktionieren öffentliche Aufrufe weiterhin, wenn ein externer Seiten-Cache HTML bereitstellt, das älter als 24 Stunden ist.

Die Erneuerung erfolgt bei Bedarf: Wenn du eine Seite lädst, ohne API aufzurufen, werden keine Zugangsdaten angefordert. RPC und Datenbank-Clients teilen sich die Erneuerung, aktualisieren die Zugangsdaten nach fünf Minuten Nutzung und wiederholen den Aufruf einmalig, wenn eine Nonce oder ein CSRF-Token abgelaufen ist. Berechtigungsfehler und Anwendungsfehler führen nicht zu einem erneuten Versuch. Die Authentifizierung folgt weiterhin dem WordPress-Login-Cookie des aktuellen Besuchers; durch die Erneuerung der Zugangsdaten erhältst du keinen Zugriff auf private Funktionen. Halte den Zugangsdaten-Endpunkt von jedem CDN- oder Proxy-Cache fern; seine Antworten sind ausdrücklich als private, no-store gekennzeichnet.

Offene Funktionen

Für Webhooks oder externe API-Callbacks, die wirklich offenen Zugriff ohne Token benötigen:

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

Berechtigungen

Beschränke den Zugriff auf bestimmte WordPress-Berechtigungen. Verwende einen String für eine einzelne Berechtigung oder ein Array, wenn der Benutzer eine davon benötigt:

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

Standardmäßig akzeptieren Funktionen nur POST-Anfragen. Das ist die sicherste Vorgabe für Vorgänge, die den Status ändern. Erlaube bei Bedarf weitere Methoden:

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

Aufrufe zwischen Blöcken

Von JavaScript

Jeder Block kann Funktionen eines anderen Blocks aufrufen, indem er den Blocknamen als drittes Argument übergibt. So lassen sich Blöcke miteinander kombinieren:

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

Von PHP

Verwende Rpc::call() für blockübergreifende Aufrufe auf der Serverseite. Das ist nützlich, wenn eine RPC-Funktion Aufrufe an andere Blöcke koordinieren muss:

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

Im Hintergrund wird jede Funktion einer REST-Route zugeordnet:

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

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

Antwort: Der Rückgabewert der PHP-Funktion als JSON.

Du kannst diese Endpunkte direkt von jedem HTTP-Client aus aufrufen. Empfohlen wird jedoch bs.fn(), da es die Nonce-Authentifizierung automatisch übernimmt.

Hooks

Aktionen werden vor und nach jedem RPC-Aufruf ausgelöst, sowohl von REST als auch von PHP aus. Alle Hooks erhalten ein einzelnes $params-Array:

Hook Parameter
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

Ändere oder ergänze Funktionen programmatisch von außerhalb des Blocks:

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

RPC oder Datenbank verwenden

db.php erzeugt CRUD-Endpunkte automatisch aus einem Schema. Verwende es, wenn du standardisierte Erstellen-, Lesen-, Aktualisieren- und Löschen-Vorgänge mit Validierung brauchst.

rpc.php ist für benutzerdefinierte Logik gedacht: E-Mails versenden, externe APIs aufrufen, Daten über mehrere Schemas hinweg zusammenführen, komplexe Abfragen ausführen oder andere Aufgaben, die nicht zum CRUD-Muster passen.

Die beiden Systeme sind unabhängig und ergänzen sich. Viele Blöcke verwenden beide: db.php für das Datenmodell und rpc.php für darauf aufbauende Geschäftslogik.