Pular para o conteúdo

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

  1. Você cria rpc.php no diretório do bloco
  2. Ele retorna um array associativo de funções nomeadas
  3. Blockstudio registra um endpoint REST para cada função
  4. O cliente bs.fn() as chama pelo nome
  5. Os parâmetros são enviados e JSON é retornado
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

Definindo funções

Cada chave no array retornado é o nome de uma função. A forma mais simples é um callback direto:

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

PHP
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
<?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 torna get_status
  • Use name: para substituir explicitamente o nome do endpoint
  • Access::Session corresponde ao comportamento antigo de 'public' => true
  • Access::Open corresponde 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:

JavaScript
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:

JavaScript
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:

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>

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:

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

PHP
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:

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

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:

PHP
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:

JavaScript
// 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:

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 função corresponde a uma rota REST:

Código
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
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

Modifique ou adicione funções programaticamente de fora do bloco:

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