Saltar al contenido

RPC

RPC (llamada a procedimiento remoto) permite definir funciones PHP en el bloque y llamarlas desde el frontend. En lugar de registrar manualmente rutas REST API, crear controladores y conectar llamadas fetch, escribes una función en rpc.php y la llamas con bs.fn(). Blockstudio se ocupa del enrutamiento de endpoints, la autenticación, la validación de nonce y la serialización JSON.

El patrón está inspirado en tRPC: define procedimientos en el servidor y llámalos desde el cliente con una función auxiliar tipada. Sin construir URL ni escribir código repetitivo de fetch a mano.

Cómo funciona

  1. Creas rpc.php en el directorio del bloque
  2. Devuelve un array asociativo de funciones con nombre
  3. Blockstudio registra un endpoint REST para cada función
  4. El cliente bs.fn() las llama por nombre
  5. Se envían parámetros y se recibe JSON
Código
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php             ← your server functions live here
├── script-inline.js    ← call them from here
└── style.css

Definición de funciones

Cada clave del array devuelto es el nombre de una función. La forma más sencilla es usar una función de retorno de llamada directamente:

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

Cada función recibe un único array $params y debe devolver un array. El valor devuelto se envía al cliente como JSON.

Para configurar las opciones de control de acceso, usa el formato ampliado con callback y claves adicionales:

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

Definiciones nativas de PHP

Si prefieres los metadatos nativos de PHP en lugar de los arrays anidados, rpc.php también puede devolver un objeto con métodos anotados. Los arrays siguen funcionando exactamente igual.

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

Notas:

  • De forma predeterminada, los nombres de método se normalizan a minúsculas con snake case, por lo que getStatus() se convierte en get_status
  • Usa name: para indicar explícitamente otro nombre de endpoint
  • Access::Session reproduce el comportamiento anterior de 'public' => true
  • Access::Open reproduce el comportamiento anterior de 'public' => 'open'
  • Omite access: para permitir únicamente el acceso autenticado de forma predeterminada

Llamadas desde JavaScript

Blockstudio inyecta automáticamente una función auxiliar bs.fn() en las páginas que contienen bloques con funciones RPC.

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

Indicar el nombre del bloque

bs.fn() recurre al atributo data-block de document.currentScript si omites el tercer argumento. Blockstudio imprime tanto script.js como los scripts en línea (script-inline.js o script.inline.js) como etiquetas <script type="module">, y los scripts de módulo no tienen document.currentScript; por eso, en los scripts de bloque, pasa el nombre del bloque como tercer argumento:

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

Si no lo incluyes, la llamada genera bs.fn: block name required.

Gestión de errores

bs.fn() se resuelve con el cuerpo JSON analizado, sea cual sea el estado HTTP. Cuando una función devuelve un WP_Error, la promesa se resuelve con un objeto que contiene su code, message y data; por eso, comprueba code:

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

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

La promesa solo se rechaza si falla la solicitud o si la respuesta no es JSON.

Con la API de interactividad API

RPC combina de forma natural con WordPress Interactivity API. Las acciones de tu tienda llaman a funciones del servidor y actualizan el estado reactivo con la respuesta. UI se actualiza automáticamente:

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>

Control de acceso

De forma predeterminada, las funciones requieren un usuario autenticado (con la sesión iniciada). Esto coincide con las convenciones de WordPress, donde los endpoints REST están protegidos de forma predeterminada.

Funciones públicas

Permite el acceso sin autenticación con protección 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
    ],
];

Páginas en caché

bs.fn() obtiene credenciales nuevas del endpoint POST /wp-json/blockstudio/v1/client/credentials del mismo origen, sin caché. Los nonces WordPress y los tokens CSRF Blockstudio que caducan no se guardan en el HTML de la página, por lo que las llamadas públicas siguen funcionando cuando una caché externa sirve un HTML de más de 24 horas.

La actualización es diferida: cargar una página sin llamar a API no genera una solicitud de credenciales. RPC y los clientes de base de datos comparten la actualización, renuevan las credenciales tras cinco minutos de uso y reintentan una vez si caduca un nonce o un token CSRF. Los errores de capacidad y de la aplicación no se reintentan. La autenticación sigue usando la cookie de inicio de sesión WordPress del visitante actual; actualizar las credenciales no concede acceso a funciones privadas. Mantén el endpoint de credenciales fuera de cualquier caché CDN o de proxy; sus respuestas llevan explícitamente la marca private, no-store.

Funciones abiertas

Para webhooks o devoluciones de llamada API externas que necesiten acceso totalmente abierto, sin token:

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

Capacidades

Restringe el acceso a capacidades WordPress específicas. Usa una cadena para una sola capacidad o un array si el usuario necesita cualquiera de ellas:

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

Métodos HTTP

De forma predeterminada, las funciones solo aceptan solicitudes POST. Es la opción más segura para las operaciones que modifican el estado. Permite otros métodos cuando sea necesario:

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

Llamadas entre bloques

Desde JavaScript

Cualquier bloque puede llamar a funciones de otro bloque si se pasa el nombre de este como tercer argumento. Así se pueden combinar bloques:

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

Desde PHP

Usa Rpc::call() para hacer llamadas entre bloques desde el servidor. Resulta útil cuando una función RPC necesita coordinar llamadas a otros bloques:

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, cada función corresponde a una ruta REST:

Código
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}

Cuerpo de la solicitud: { "params": { ... } }

Respuesta: valor devuelto por la función PHP como JSON.

Puedes llamar a estos endpoints directamente desde cualquier cliente HTTP, pero se recomienda bs.fn() porque gestiona la autenticación con nonce automáticamente.

Hooks

Las acciones se ejecutan antes y después de cada llamada RPC, tanto desde REST como desde PHP. Todos los hooks reciben un único array $params:

Hook Parámetros
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

Modifica o añade funciones mediante programación desde fuera del bloque:

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

Cuándo usar RPC o una base de datos

db.php genera endpoints CRUD automáticamente a partir de un esquema. Úsalo cuando necesites operaciones estándar de creación, lectura, actualización y eliminación con validación.

rpc.php sirve para la lógica personalizada: enviar correos electrónicos, llamar a API externas, agregar datos de varios esquemas, ejecutar consultas complejas o cualquier otra tarea que no encaje en el patrón CRUD.

Los dos sistemas son independientes y complementarios. Muchos bloques usan ambos: db.php para el modelo de datos y rpc.php para la lógica de negocio que se aplica a este.