RPC
RPC (Remote Procedure Call) permite definir funções PHP no bloco e chamá-las pelo frontend. Em vez de registrar manualmente rotas REST API, criar controladores e conectar chamadas fetch, você escreve uma função em rpc.php e a chama com bs.fn(). Blockstudio cuida do roteamento de endpoints, da autenticação, da validação de nonce e da serialização JSON.
O padrão é inspirado em tRPC: defina procedimentos no servidor e chame-os no cliente com um helper tipado. Sem criar URL, sem código boilerplate manual de fetch.
Como funciona
- Você cria
rpc.phpno diretório do bloco - Ele retorna um array associativo de funções nomeadas
- Blockstudio registra um endpoint REST para cada função
- O cliente
bs.fn()as chama pelo nome - Os parâmetros são enviados e JSON é retornado
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← your server functions live here
├── script-inline.js ← call them from here
└── style.css
Definindo funções
Cada chave no array retornado é o nome de uma função. A forma mais simples é um callback direto:
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 função recebe um único array $params e deve retornar um array. O valor de retorno é enviado ao cliente como JSON.
Para definir opções de controle de acesso, use o formato expandido com callback e chaves adicionais:
return [
'admin_action' => [
'callback' => function (array $params): array {
return ['ok' => true];
},
'capability' => 'manage_options',
],
];
Definições nativas de PHP
Se preferir metadados nativos de PHP em vez de arrays aninhados, rpc.php também pode retornar um objeto com métodos anotados. Os arrays continuam funcionando exatamente da mesma forma.
<?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];
}
};
Observações:
- Por padrão, os nomes dos métodos são normalizados para snake case em minúsculas, então
getStatus()se tornaget_status - Use
name:para substituir explicitamente o nome do endpoint Access::Sessioncorresponde ao comportamento antigo de'public' => trueAccess::Opencorresponde ao comportamento antigo de'public' => 'open'- Omita
access:para usar o comportamento padrão, que exige autenticação
Chamando de JavaScript
Blockstudio injeta automaticamente um helper bs.fn() nas páginas que têm blocos com funções RPC.
Assinatura: bs.fn(functionName, params?, blockName?) -> Promise
Passando o nome do bloco
Quando você omite o terceiro argumento, bs.fn() usa como alternativa o atributo data-block de document.currentScript. Blockstudio imprime tanto script.js quanto scripts em linha (script-inline.js ou script.inline.js) como tags <script type="module">, e scripts de módulo não têm document.currentScript. Portanto, nos scripts de bloco, passe o nome do bloco como terceiro argumento:
const posts = await bs.fn('load_more', { offset: 10 }, 'my-theme/blog-feed');
Sem ele, a chamada lança bs.fn: block name required.
Tratamento de erros
bs.fn() é resolvida com o corpo JSON analisado, qualquer que seja o status HTTP. Quando uma função retorna um WP_Error, a promise é resolvida com um objeto que contém seu code, message e data, então verifique code:
const result = await bs.fn('subscribe', { email }, 'my-theme/newsletter');
if (result.code) {
console.error('RPC failed:', result.message);
}
A promise é rejeitada somente quando a própria solicitação falha ou a resposta não é JSON.
Com o API Interactivity
RPC combina naturalmente com o WordPress Interactivity API. As ações do seu armazenamento chamam funções do servidor e atualizam o estado reativo com a resposta. O UI é atualizado automaticamente:
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>
Controle de acesso
Por padrão, as funções exigem um usuário autenticado (com sessão iniciada). Isso corresponde às convenções de WordPress, segundo as quais os endpoints REST são protegidos por padrão.
Funções públicas
Permita acesso sem autenticação com proteção contra 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 em cache
bs.fn() busca credenciais atualizadas no endpoint POST /wp-json/blockstudio/v1/client/credentials da mesma origem, sem cache. Nonces WordPress e tokens CSRF Blockstudio com prazo de validade não são armazenados no HTML da página, então as chamadas públicas continuam funcionando quando um cache externo serve HTML com mais de 24 horas.
A atualização é sob demanda: carregar uma página sem chamar um API não gera uma solicitação de credenciais. RPC e os clientes de banco de dados compartilham a atualização, renovam as credenciais após cinco minutos de uso e fazem uma única nova tentativa em caso de nonce ou token CSRF expirado. Falhas de capacidade e erros da aplicação não geram novas tentativas. A autenticação continua usando o cookie de login WordPress do visitante atual; atualizar as credenciais não concede acesso a funções privadas. Mantenha o endpoint de credenciais fora de qualquer cache CDN ou de proxy; as respostas são marcadas explicitamente como private, no-store.
Funções abertas
Para webhooks ou callbacks API externos que precisam de acesso realmente aberto, sem nenhum token:
return [
'webhook' => [
'callback' => function (array $params): array {
// Called by an external service
return ['received' => true];
},
'public' => 'open', // no CSRF, no auth
],
];
Capacidades
Restrinja o acesso a capacidades WordPress específicas. Use uma string para uma única capacidade ou um array quando o usuário puder ter qualquer uma delas:
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
Por padrão, as funções aceitam apenas solicitações POST. Essa é a opção mais segura para operações que alteram o estado. Permita métodos adicionais quando necessário:
return [
'get_status' => [
'callback' => function (array $params): array {
return ['status' => 'ok'];
},
'methods' => ['GET', 'POST'],
],
];
Chamadas entre blocos
De JavaScript
Qualquer bloco pode chamar funções de qualquer outro bloco passando o nome do bloco como terceiro argumento. Isso permite compor blocos:
// Block A calling a function defined in Block B
const result = await bs.fn('load_more', { offset: 0 }, 'my-theme/blog-feed');
De PHP
Use Rpc::call() para fazer chamadas entre blocos no servidor. Isso é útil quando uma função RPC precisa orquestrar chamadas a outros blocos:
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 função corresponde a uma rota REST:
POST /wp-json/blockstudio/v1/fn/{namespace}/{block}/{function}
Corpo da solicitação: { "params": { ... } }
Resposta: o valor de retorno da função PHP como JSON.
Você pode chamar esses endpoints diretamente de qualquer cliente HTTP, mas bs.fn() é a forma recomendada, pois gerencia automaticamente a autenticação por nonce.
Hooks
As ações são disparadas antes e depois de cada chamada RPC, tanto de REST quanto de PHP. Todos os hooks recebem um ú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
Modifique ou adicione funções programaticamente de fora do bloco:
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 usar RPC ou Database
db.php gera automaticamente endpoints CRUD a partir de um esquema. Use quando precisar de operações padrão de criação, leitura, atualização e exclusão com validação.
rpc.php serve para lógica personalizada: enviar e-mails, chamar APIs externas, agregar dados de vários esquemas, executar consultas complexas ou qualquer outra coisa que não se encaixe no padrão CRUD.
Os dois sistemas são independentes e complementares. Muitos blocos usam ambos: db.php para o modelo de dados e rpc.php para a lógica de negócios baseada nele.