
# 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](https://trpc.io): 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

```
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 title="rpc.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 title="rpc.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 title="rpc.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:

```js title="script.inline.js"
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`:

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

```js title="script-inline.js"
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 title="index.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 title="rpc.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 title="rpc.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 title="rpc.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 title="rpc.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:

```js
// 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 title="rpc.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:

```
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`](https://blockstudio.dev/pt/docs/blocks/block-api/database/) 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.
