Vai al contenuto

RPC

RPC (Remote Procedure Call) consente di definire funzioni PHP nel blocco e chiamarle dal frontend. Invece di registrare manualmente route REST API, creare controller e configurare chiamate fetch, scrivete una funzione in rpc.php e chiamatela con bs.fn(). Blockstudio gestisce il routing degli endpoint, l’autenticazione, la convalida del nonce e la serializzazione JSON.

Lo schema si ispira a tRPC: definite le procedure lato server e chiamatele dal client con un helper tipizzato. Niente costruzione di URL, niente boilerplate fetch manuale.

Come funziona

  1. Create rpc.php nella directory del blocco
  2. Restituisce un array associativo di funzioni con nome
  3. Blockstudio registra un endpoint REST per ogni funzione
  4. Il client bs.fn() le chiama per nome
  5. Si passano i parametri e si ottiene JSON
Codice
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definizione delle funzioni

Ogni chiave dell’array restituito corrisponde al nome di una funzione. La forma più semplice usa una callback diretta:

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

Ogni funzione riceve un unico array $params e dovrebbe restituire un array. Il valore restituito viene inviato al client come JSON.

Per le opzioni di controllo degli accessi, usate il formato esteso con callback e chiavi aggiuntive:

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

Definizioni native per PHP

Se preferite metadati nativi di PHP invece di array annidati, rpc.php può restituire anche un oggetto con metodi dotati di attributi. Gli array continuano a funzionare nello stesso modo.

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

Note:

  • Per impostazione predefinita, i nomi dei metodi vengono convertiti in minuscolo e nel formato snake case; quindi getStatus() diventa get_status
  • Usate name: per specificare esplicitamente il nome dell’endpoint
  • Access::Session corrisponde al comportamento precedente di 'public' => true
  • Access::Open corrisponde al comportamento precedente di 'public' => 'open'
  • Omettete access: per mantenere il comportamento predefinito, riservato agli utenti autenticati

Chiamate da JavaScript

Blockstudio inserisce automaticamente un helper bs.fn() nelle pagine che contengono blocchi con funzioni RPC.

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

Passaggio del nome del blocco

bs.fn() usa come valore predefinito l’attributo data-block di document.currentScript se omettete il terzo argomento. Blockstudio stampa sia script.js sia gli script inline (script-inline.js o script.inline.js) come tag <script type="module">, mentre gli script modulo non hanno document.currentScript; perciò negli script dei blocchi passate il nome del blocco come terzo argomento:

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

Senza questo, la chiamata genera un’eccezione bs.fn: block name required.

Gestione degli errori

bs.fn() restituisce il corpo JSON analizzato, qualunque sia lo stato HTTP. Se una funzione restituisce un WP_Error, la promise si risolve con un oggetto che contiene code, message e data; controllate quindi code:

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

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

La promise viene rifiutata solo se la richiesta non va a buon fine o la risposta non è JSON.

Con l’API Interattività

RPC si abbina naturalmente all’WordPress Interattività API. Le azioni del vostro store chiamano funzioni server e aggiornano lo stato reattivo con la risposta. L’UI si aggiorna automaticamente:

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>

Controllo degli accessi

Per impostazione predefinita, le funzioni richiedono un utente autenticato (connesso). Questo corrisponde alle convenzioni WordPress, secondo cui gli endpoint REST sono protetti per impostazione predefinita.

Funzioni pubbliche

Consentite l’accesso senza autenticazione con protezione 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
    ],
];

Pagine memorizzate nella cache

bs.fn() recupera credenziali aggiornate dall’endpoint POST /wp-json/blockstudio/v1/client/credentials della stessa origine, escluso dalla cache. I nonce WordPress e i token CSRF Blockstudio in scadenza non vengono memorizzati nel HTML della pagina, quindi le chiamate pubbliche continuano a funzionare quando una cache esterna serve pagine HTML più vecchie di 24 ore.

L’aggiornamento è differito: caricare una pagina senza effettuare una chiamata API non genera una richiesta di credenziali. I client RPC e del database condividono l’aggiornamento, rinnovano le credenziali dopo cinque minuti di utilizzo e riprovano una volta in caso di nonce o token CSRF scaduto. Gli errori di capacità e gli errori dell’applicazione non vengono ritentati. L’autenticazione continua a seguire il cookie di accesso WordPress del visitatore corrente; aggiornare le credenziali non concede l’accesso alle funzioni private. Mantenete l’endpoint delle credenziali fuori da qualsiasi cache CDN o proxy; le relative risposte sono contrassegnate esplicitamente come private, no-store.

Funzioni aperte

Per webhook o callback API esterne che richiedono accesso completamente aperto, senza token:

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

Capacità

Limitate l’accesso a capacità WordPress specifiche. Usate una stringa per una singola capacità oppure un array se l’utente può averne una qualsiasi:

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

Metodi HTTP

Per impostazione predefinita, le funzioni accettano solo richieste POST. È l’impostazione più sicura per le operazioni che modificano lo stato. Se necessario, consentite anche altri metodi:

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

Chiamate tra blocchi

Da JavaScript

Qualsiasi blocco può chiamare funzioni di un altro blocco passando il nome del blocco come terzo argomento. In questo modo è possibile comporre blocchi diversi:

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

Da PHP

Usate Rpc::call() per le chiamate tra blocchi lato server. È utile quando una funzione RPC deve coordinare le chiamate ad altri blocchi:

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

Internamente, ogni funzione corrisponde a una route REST:

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

Corpo della richiesta: { "params": { ... } }

Risposta: il valore restituito dalla funzione PHP in formato JSON.

Potete chiamare direttamente questi endpoint da qualsiasi client HTTP, ma il metodo consigliato è bs.fn(), che gestisce automaticamente l’autenticazione tramite nonce.

Hook

Le azioni vengono eseguite prima e dopo ogni chiamata RPC, sia da REST sia da PHP. Tutti gli hook ricevono un unico array $params:

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

Filtro

Modificate o aggiungete funzioni a livello di codice dall’esterno del blocco:

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

Quando usare RPC o Database

db.php genera automaticamente endpoint CRUD da uno schema. Usatelo quando vi servono operazioni standard di creazione, lettura, aggiornamento ed eliminazione con convalida.

rpc.php serve per la logica personalizzata: inviare email, chiamare API esterne, aggregare dati di più schemi, eseguire query complesse o gestire qualsiasi operazione che non rientri nel modello CRUD.

I due sistemi sono indipendenti e complementari. Molti blocchi li usano entrambi: db.php per il modello dei dati e rpc.php per la logica di business che lo gestisce.