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
- Creas
rpc.phpen el directorio del bloque - Devuelve un array asociativo de funciones con nombre
- Blockstudio registra un endpoint REST para cada función
- El cliente
bs.fn()las llama por nombre - Se envían parámetros y se recibe JSON
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:
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:
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
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 enget_status - Usa
name:para indicar explícitamente otro nombre de endpoint Access::Sessionreproduce el comportamiento anterior de'public' => trueAccess::Openreproduce 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:
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:
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:
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;
},
},
});
<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:
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:
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:
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:
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:
// 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:
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:
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 |
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:
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.