Pular para o conteúdo

Banco de dados

A camada de banco de dados permite definir um modelo de dados para seu bloco em um arquivo db.php. Blockstudio gera endpoints CRUD REST, valida as entradas de acordo com o esquema, gerencia o armazenamento automaticamente e fornece um cliente JavaScript (bs.db()) e uma API PHP (classe Db).

Essa é a base de dados dos blocos full-stack. Enquanto RPC cuida da lógica personalizada, a camada de banco de dados cuida de dados estruturados sem código repetitivo.

Como funciona

  1. Crie db.php no diretório do seu bloco
  2. Ele retorna um esquema: campos, tipos, regras de validação e controle de acesso
  3. Blockstudio cria o armazenamento (tabela, arquivo ou metadados do post)
  4. Cinco endpoints REST são gerados automaticamente (listar, obter, criar, atualizar, excluir)
  5. bs.db() e Db::get() fornecem acesso pelo cliente e pelo servidor

Sem migrações, controladores ou registro de rotas.

Passe valores literais às APIs REST e PHP. Os backends meta e post_type tratam internamente o escape de barras invertidas dos metadados de WordPress, preservando barras invertidas e strings entre aspas tanto em valores escalares quanto em objetos ou arrays aninhados. Não aplique escape previamente aos valores dos registros do banco de dados.

Definição de esquemas

Esquema único

A forma mais simples: um único modelo de dados por bloco.

PHP
return [
    'storage'    => 'table',
    'capability' => [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    'fields' => [
        'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
        'name'  => ['type' => 'string', 'maxLength' => 100],
        'plan'  => ['type' => 'string', 'enum' => ['free', 'pro'], 'default' => 'free'],
    ],
];

Sintaxe de criação nativa do PHP

db.php também pode usar uma pequena API de criação baseada em argumentos nomeados e objetos de definição somente leitura. Os arrays continuam sendo o formato padrão, mas essa opção nativa do PHP facilita a descoberta quando o esquema começa a ficar maior.

PHP
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    capability: [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'name'  => Field::string(maxLength: 100),
        'plan'  => Field::string(enum: ['free', 'pro'], default: 'free'),
    ],
);

Use Schema::make() para um único esquema ou retorne um array de chamadas Schema::make(...) nomeadas para blocos com vários esquemas.

Vários esquemas

Um único bloco pode ter vários modelos de dados. Retorne um array nomeado:

PHP
return [
    'subscribers' => [
        'storage' => 'table',
        'fields'  => [
            'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
            'plan'  => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
    'activity_log' => [
        'storage' => 'jsonc',
        'fields'  => [
            'action'  => ['type' => 'string', 'required' => true],
            'details' => ['type' => 'string'],
        ],
    ],
];

Cada esquema tem seus próprios endpoints, armazenamento e controle de acesso.

Modos de armazenamento

Seis backends de armazenamento, cada um adequado a diferentes casos de uso.

Tabela personalizada (storage: "table")

Cada registro é uma linha em uma tabela MySQL dedicada. Blockstudio cria e gerencia a tabela automaticamente usando a função dbDelta() de WordPress. A adição de novos campos ao esquema acrescenta colunas no próximo carregamento da página. As colunas existentes nunca são removidas.

Ideal para: dados estruturados, consultas e aplicativos em produção.

SQLite (storage: "sqlite")

Cada esquema tem seu próprio arquivo de banco de dados SQLite em uma subpasta db/. Blockstudio cria o arquivo e a tabela automaticamente e adiciona as colunas ausentes quando o esquema muda (como dbDelta para MySQL). Usa o modo de diário WAL para melhorar o desempenho de leituras simultâneas.

Código
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

Ideal para: dados estruturados que precisam de consultas SQL reais, mas devem continuar portáteis. Processa milhares de registros com eficiência sem carregar tudo na memória. Copie a pasta para mover os dados.

Arquivos JSONC (storage: "jsonc")

Os registros são armazenados como um objeto JSON por linha em um arquivo .jsonc dentro de uma subpasta db/. O arquivo é criado automaticamente na primeira gravação. Linhas iniciadas por // são tratadas como comentários e preservadas.

Código
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

Ideal para: conjuntos de dados pequenos, dados semelhantes a configurações, registros iniciais e exemplos com controle de versão. JSONC é intencionalmente um único arquivo na pasta do seu bloco. Use-o quando quiser que os dados acompanhem o código, não quando esperar muitas gravações simultâneas.

Arquivos Storh (storage: "storh")

Storh armazena cada registro como um arquivo individual em uploads de WordPress:

Código
wp-content/uploads/blockstudio/db/
└── my-theme-my-block/
    └── subscribers/
        ├── data/
        │   └── 00/
        │       ├── 00000000-0000-7000-8000-000000000001.jsonc
        │       └── 00000000-0000-7000-8000-000000000002.jsonc
        ├── .storh/
        │   └── indexes/
        └── .blockstudio/
            └── sequence.json

Os IDs públicos dos registros continuam sendo os mesmos IDs inteiros usados pelo restante do bs.db(). Blockstudio associa esses IDs aos IDs de arquivo internos UUIDv7 de Storh e armazena o id inteiro nos dados do registro, para que os clientes de JavaScript, REST e PHP não precisem lidar com UUIDs.

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Blockstudio cria índices Storh a partir do seu esquema. Como todo campo declarado pode ser usado como filtro de lista, todos os campos declarados são indexados. Campos inteiros, numéricos e do tipo data usam índices de intervalo; campos marcados com 'unique' => true ou 'index' => 'unique' usam índices exclusivos.

Ideal para: dados de produção baseados em arquivos que precisam de gravações simultâneas mais seguras, índices derivados do esquema e armazenamento portátil no nível de uploads, sem incluir registros ativos na árvore de código-fonte do bloco.

Migrar JSONC para Storh

Se você começou com um arquivo .jsonc e quer os mesmos registros em Storh, execute:

Shell
wp bs db migrate my-theme/app subscribers --to=storh

Para blocos com um único esquema:

Shell
wp bs db migrate my-theme/app --to=storh

A migração lê o db/{schema}.jsonc existente, grava os registros em Storh preservando os IDs inteiros, reindexa, verifica o armazenamento de destino e mantém intacto o arquivo JSONC. Para reverter, basta alterar storage do esquema de volta para "jsonc".

Metadados do post (storage: "meta")

Os registros são armazenados como um array JSON nos metadados do post WordPress, associados a um post específico por meio de postId.

PHP
return [
    'storage' => 'meta',
    'postId'  => 42,
    'fields'  => [ /* ... */ ],
];

Ideal para: dados que pertencem a um post ou página específicos.

Tipo de post personalizado (storage: "post_type")

Cada registro é um post WordPress em um tipo de post personalizado registrado automaticamente. Cada campo do esquema se torna uma entrada post_meta separada. Assim, é possível consultar os registros com WP_Query, eles são compatíveis com plugins REST API e ficam visíveis para ferramentas como GraphQL.

Ideal para: dados que devem se integrar nativamente ao WordPress. Cada campo pode ser consultado e indexado de forma independente.

Cliente JavaScript

Blockstudio injeta bs.db() nas páginas com blocos de banco de dados. Ele retorna um objeto com cinco métodos:

JavaScript
const db = bs.db('my-theme/block', 'subscribers');

// Create a record
const record = await db.create({ email: 'a@b.com', plan: 'pro' });

// List all records (with optional filters)
const all = await db.list();
const pros = await db.list({ plan: 'pro', limit: 10, offset: 0 });

// Get a single record
const one = await db.get(record.id);

// Update specific fields
const updated = await db.update(record.id, { plan: 'enterprise' });

// Delete a record
await db.delete(record.id);

O primeiro argumento é o nome do bloco (com /), e o segundo é o nome do esquema. Para blocos com um único esquema, omita o nome do esquema (o padrão é "default").

Cache

bs.cache é um cache de consultas em memória, compartilhado entre todas as chamadas a bs.query e bs.mutate. Também é possível usá-lo diretamente:

JavaScript
// Read a cached value
const data = bs.cache.get('my-key');

// Write to the cache
bs.cache.set('my-key', { items: [...] });

// Invalidate a single key
bs.cache.invalidate('my-key');

// Clear all cached entries
bs.cache.clear();

As entradas de cache ficam armazenadas na memória e são apagadas ao navegar para outra página. Elas são usadas principalmente internamente por bs.query e bs.mutate, mas o acesso direto é útil para pré-carregar dados ou invalidar manualmente o cache após operações personalizadas.

Consulta

bs.query() envolve qualquer função assíncrona com cache, deduplicação e controle de obsolescência. Várias chamadas com a mesma chave enquanto uma solicitação está em andamento retornam a mesma promessa (sem buscas duplicadas).

JavaScript
// Basic cached fetch
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list()
);

// With staleTime: skip the fetch if cached data is younger than 30 seconds
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list(),
  { staleTime: 30000 }
);

O primeiro argumento é uma chave de cache (qualquer string). O segundo é uma função que retorna uma promessa. O terceiro é um objeto de opções opcional:

Opção Tipo Descrição
staleTime number Milissegundos até que os dados em cache sejam considerados desatualizados. 0 (padrão) sempre busca novamente.

Se o cache tiver dados para a chave e eles tiverem menos tempo que staleTime, o valor em cache será retornado imediatamente sem chamar a função.

Mutação

bs.mutate() gerencia operações de gravação com atualizações otimistas e reversão automática em caso de falha. Há dois modos: automático, para padrões CRUD comuns, e manual, para controle total.

O modo automático funciona com um objeto de estado reativo (como Alpine.js $data). Passe state, key, action e, opcionalmente, optimistic:

JavaScript
// Optimistic create: item appears instantly, gets real ID on success
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'create',
  optimistic: { text: 'New todo', done: false },
  fn: () =>
    bs.db('my-theme/app', 'todos').create({ text: 'New todo', done: false }),
});

// Optimistic update: field changes instantly, reverts on failure
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'update',
  id: todoId,
  optimistic: { done: true },
  fn: () => bs.db('my-theme/app', 'todos').update(todoId, { done: true }),
});

// Delete: item removed from the array immediately
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => bs.db('my-theme/app', 'todos').delete(todoId),
});

Em caso de sucesso, os dados otimistas são substituídos pela resposta do servidor. Em caso de falha, o estado volta a um instantâneo capturado antes da mutação. A chave de cache é invalidada automaticamente após cada mutação bem-sucedida.

Falha significa que a promessa retornada por fn é rejeitada. bs.db() e bs.fn() resolvem com o corpo do erro em caso de erro de validação, registro ausente ou falha na verificação de permissões. Portanto, lance uma exceção quando o resultado contiver um code se esses casos também devem acionar a reversão:

JavaScript
const ok = (request) =>
  request.then((result) => {
    if (result?.code) {
      throw result;
    }
    return result;
  });

await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => ok(bs.db('my-theme/app', 'todos').delete(todoId)),
});

Nas operações de criação, é atribuído ao item otimista um id temporário (como __temp_1). Quando o servidor responde, o item temporário é atualizado com os dados reais, incluindo o id atribuído pelo servidor.

O modo manual dá controle total com os callbacks before, onSuccess e onError:

JavaScript
await bs.mutate({
  fn: () => bs.db('my-theme/app', 'todos').create({ text: 'New' }),
  invalidate: 'todos',
  before: () => {
    // Take a snapshot, return it for use in onError
    const snapshot = [...$data.todos];
    $data.todos.push({ id: '__temp', text: 'New' });
    return snapshot;
  },
  onSuccess: (result, snapshot) => {
    // Replace temp item with server response
  },
  onError: (error, snapshot) => {
    // Restore from snapshot
    $data.todos = snapshot;
  },
});
Opção Tipo Modo Descrição
fn function Ambos Função assíncrona que executa a mutação. Obrigatória.
state object Automático Objeto de estado reativo (e.g., Alpine $data).
key string Automático Nome da propriedade do estado que contém o array. Também usado como chave de cache.
action string Automático Um entre create, update ou delete.
id any Automático ID do registro para as ações update e delete.
optimistic object Automático Dados a aplicar de forma otimista antes da resposta do servidor.
before function Manual Chamado antes de fn. O valor de retorno é passado a onSuccess/onError como snapshot.
onSuccess function Manual Chamado com (result, snapshot) em caso de sucesso.
onError function Manual Chamado com (error, snapshot) em caso de falha.
invalidate string Manual Chave de cache a invalidar em caso de sucesso.

PHP API

A classe Db fornece as mesmas operações no servidor. Use-a em rpc.php, cron.php, templates ou qualquer código PHP.

PHP
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');

// Create
$record = $db->create(['email' => 'a@b.com', 'plan' => 'pro']);

// List with filters
$all  = $db->list();
$pros = $db->list(['plan' => 'pro'], limit: 10, offset: 0);

// Count and paginate
$count = $db->count(['plan' => 'pro']);
$page  = $db->paginate(['plan' => 'pro'], limit: 10, offset: 20);

// Get by ID
$one = $db->get_record(1);

// Update
$db->update(1, ['plan' => 'enterprise']);

// Delete
$db->delete(1);

Para blocos com um único esquema:

PHP
$db = Db::get('my-theme/block');

Consulta periódica em tempo real

Adicione realtime ao seu esquema para ativar a consulta periódica automática. Quando os dados mudam no servidor, UI é atualizado automaticamente por meio do armazenamento API de Interactivity. Não são necessárias alterações em JavaScript.

PHP
return [
    'storage'  => 'table',
    'realtime' => true,
    'fields'   => [ /* ... */ ],
];

Com true, Blockstudio faz consultas a cada 3 segundos, usando o nome do esquema como chave de estado do armazenamento de Interactivity API (default para blocos com um único esquema).

Configuração personalizada

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Opção Tipo Padrão Descrição
key string nome do esquema Nome da propriedade em state que contém o array de dados
interval number 3000 Intervalo da consulta periódica em milissegundos

Como funciona

  1. Ao carregar a página, o cliente busca um hash leve dos dados atuais
  2. A cada interval milissegundos, busca o hash novamente
  3. Se o hash mudar, busca o conjunto de dados completo
  4. Os novos dados são enviados ao armazenamento API de Interactivity por meio de store()
  5. Quaisquer diretivas vinculadas a essa propriedade de estado são renderizadas novamente automaticamente

A consulta periódica só é executada em páginas onde existe um elemento data-wp-interactive correspondente. Ela é pausada quando a aba do navegador fica oculta e retomada quando volta a ficar visível.

O endpoint de hash (?_hash=1) retorna apenas um checksum md5 e a contagem de registros, mantendo leves as solicitações periódicas.

Dados associados ao usuário

Defina userScoped: true para associar automaticamente todos os registros ao usuário atual. Blockstudio adiciona uma coluna user_id, define seu valor na criação e filtra todas as operações para incluir apenas os registros do usuário atual:

PHP
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [
        'text' => ['type' => 'string', 'required' => true],
        'done' => ['type' => 'boolean', 'default' => false],
    ],
];

Sem campo user_id manual, hook before_create ou filtragem em RPC. Os usuários só podem ver, editar e excluir os próprios registros. A coluna user_id é totalmente gerenciada por Blockstudio.

Ao usar o armazenamento post_type, userScoped é associado a post_author em vez de uma coluna user_id separada.

Controle de acesso

Cada operação CRUD tem seu próprio nível de permissão:

Valor Comportamento
true Público com proteção CSRF (usuários desconectados são permitidos; X-BS-Token é obrigatório)
'open' Verdadeiramente público, sem CSRF nem autenticação (para webhooks e APIs externas)
'edit_posts' Verificação de capacidade WordPress
['cap_a', 'cap_b'] O usuário precisa ter pelo menos uma das capacidades listadas
omitido / null Exige autenticação (usuário conectado)
PHP
'capability' => [
    'create' => true,                               // public + CSRF protected
    'read'   => 'open',                             // truly open, no protection
    'update' => 'edit_posts',                       // editors and above
    'delete' => ['delete_posts', 'manage_options'], // either capability works
],

Proteção CSRF

Os endpoints públicos (true) são protegidos por um cabeçalho X-BS-Token. bs.db() e bs.fn() buscam credenciais atualizadas em um endpoint da mesma origem sem cache, em vez de incorporar tokens com prazo de validade no HTML da página. Páginas servidas por caches externos de longa duração continuam funcionando. Chamadas anônimas sem um token válido recebem uma resposta 403.

As credenciais são solicitadas na primeira chamada API, e não a cada visualização de página. Os dois clientes, incluindo a consulta periódica de atualizações em tempo real do banco de dados, compartilham uma única atualização de credenciais em andamento. As credenciais são renovadas após cinco minutos de uso. Um nonce WordPress ou token CSRF Blockstudio rejeitado aciona uma atualização e uma nova tentativa; erros comuns de permissão não geram novas tentativas. As solicitações de usuários conectados continuam usando a sessão do visitante e as verificações de capacidades e propriedade de registros do esquema.

Mantenha POST /wp-json/blockstudio/v1/client/credentials fora de qualquer cache de proxy ou CDN. Ele envia Cache-Control: private, no-store e exige uma solicitação da mesma origem com um cabeçalho não simples. Os clientes integrados fazem isso automaticamente.

Use 'open' quando precisar de acesso realmente não autenticado e sem CSRF, por exemplo, para receber webhooks de serviços externos.

Tipos de campo

Tipo Coluna MySQL Tipo PHP Descrição
string varchar(maxLength) string Texto, maxLength padrão 255
integer bigint(20) int Números inteiros
number decimal(20,6) float Números decimais
boolean tinyint(1) bool Verdadeiro/falso
text longtext string Conteúdo de texto longo

Validação

Todas as gravações (criação e atualização) são validadas de acordo com o esquema antes de acessar o armazenamento. A validação ocorre no servidor, independentemente de a solicitação vir de bs.db(), do REST API ou de Db::get().

Regras integradas

Regra Exemplo Descrição
required 'required' => true O campo deve estar presente na criação
type 'type' => 'integer' O valor deve corresponder ao tipo declarado
enum 'enum' => ['a', 'b'] O valor deve ser uma das opções listadas
maxLength 'maxLength' => 100 A string não pode exceder este comprimento
minLength 'minLength' => 3 A string deve ter pelo menos este comprimento
format: "email" 'format' => 'email' Deve ser um endereço de e-mail válido
format: "url" 'format' => 'url' Deve ser um URL válido

Validação personalizada

Adicione um callback validate a qualquer campo para realizar verificações no servidor que vão além das regras integradas. Retorne true para aprovar ou uma string com a mensagem de erro:

PHP
'email' => [
    'type'     => 'string',
    'format'   => 'email',
    'required' => true,
    'validate' => function ($value, $data) {
        if (str_ends_with($value, '@disposable.com')) {
            return 'Disposable email addresses are not allowed.';
        }
        return true;
    },
],

O callback recebe o valor do campo e o array de dados completo, permitindo validar vários campos em conjunto.

Formato da resposta de erro

Os erros de validação retornam um status 400 com arrays de erros por campo. Esse formato é inspirado em ZodfieldErrors e facilita a associação dos erros aos campos do formulário:

JSON
{
  "code": "blockstudio_db_validation",
  "message": "Validation failed.",
  "data": {
    "status": 400,
    "errors": {
      "email": [
        "Must be a valid email address.",
        "Disposable email addresses are not allowed."
      ],
      "plan": ["Must be one of: free, pro."]
    }
  }
}

Cada campo corresponde a um array de strings de erro. Várias regras podem falhar no mesmo campo. No frontend:

JavaScript
const result = await db.create({ email: 'bad', plan: 'invalid' });

if (result.data?.errors) {
  // { email: ["Must be a valid email address."], plan: ["Must be one of: free, pro."] }
  Object.entries(result.data.errors).forEach(([field, messages]) => {
    showFieldError(field, messages[0]);
  });
}

Endpoints REST

Todos os endpoints estão no namespace blockstudio/v1/db/:

Código
/db/{block-name}/{schema-name}

O nome do bloco tem / substituído por -. Para blocos com um único esquema, o nome do esquema é default.

Método Endpoint Descrição
GET /db/{block}/{schema} Listar registros
POST /db/{block}/{schema} Criar um registro
GET /db/{block}/{schema}/{id} Obter um único registro
PUT /db/{block}/{schema}/{id} Atualizar um registro
DELETE /db/{block}/{schema}/{id} Excluir um registro

Parâmetros de consulta (lista)

Parâmetro Descrição
limit Número máximo de registros a retornar (padrão 50, máximo 100)
offset Número de registros a ignorar
Qualquer nome de campo Filtrar por correspondência exata de valor

Exemplo: GET /db/my-theme-app/subscribers?plan=pro&limit=10

Renderização de formulários

Os campos podem definir uma chave component que referencia um bloco Blockstudio. Chame bs_db_form() no seu template para renderizar todos os campos em um formulário usando os respectivos blocos de componente.

PHP
'fields' => [
    'email' => [
        'type'     => 'string',
        'format'   => 'email',
        'required' => true,
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Email', 'type' => 'email'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/input',
                    'attributes' => ['placeholder' => 'Enter your email'],
                ],
            ],
        ],
    ],
    'plan' => [
        'type' => 'string',
        'enum' => ['free', 'pro'],
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Plan'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/select',
                    'attributes' => ['options' => ['free', 'pro']],
                ],
            ],
        ],
    ],
],
PHP
<form>
  <?php bs_db_form('my-theme/app', 'subscribers'); ?>
  <button type="submit">Subscribe</button>
</form>

Cada componente recebe a definição completa do campo como field em seus atributos, para que os componentes possam adaptar a renderização com base no esquema. Por exemplo, $a['field']['name'] informa o nome do campo, $a['field']['type'] o tipo, $a['field']['required'] se é obrigatório etc.

A estrutura do componente segue o mesmo formato name, attributes, innerBlocks dos blocos WordPress. Os blocos internos são renderizados primeiro e passados como $content ao componente pai.

Para usar PHP sem ecoar:

PHP
use Blockstudio\Db;

$db   = Db::get('my-theme/app', 'subscribers');
$html = $db->form();

Hooks

As ações são disparadas antes e depois de cada operação de gravação. Todos os hooks recebem um único array $params. Consulte a referência de HooksPHP para ver a lista completa.

Hooks em linha

Defina hooks diretamente em db.php. Eles são automaticamente associados a esse esquema, então você não precisa verificar o nome do bloco/esquema:

PHP
return [
    'storage' => 'table',
    'fields'  => [ /* ... */ ],
    'hooks' => [
        'after_create' => function ($params) {
            // $params['record'] is the created record
            wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
        },
        'before_delete' => function ($params) {
            // $params['id'] is the record being deleted
            error_log('Deleting subscriber ' . $params['id']);
        },
    ],
];

Hooks globais

Monitore todos os esquemas de qualquer lugar:

PHP
add_action('blockstudio/db/after_create', function ($params) {
    // $params['block'] and $params['schema'] identify the source
    if ('my-theme/app' === $params['block'] && 'subscribers' === $params['schema']) {
        // sync to external CRM
    }
});

Combinando com RPC

db.php e rpc.php são sistemas independentes. db.php gera endpoints CRUD a partir de uma definição de esquema. rpc.php define funções personalizadas no servidor. Cada um funciona por conta própria.

Use os dois em conjunto quando precisar de operações de dados padrão e lógica de negócios personalizada:

PHP
use Blockstudio\Db;

return [
    'export' => [
        'callback'   => function (array $params): array {
            $db   = Db::get('my-theme/app', 'subscribers');
            $rows = $db->list(['plan' => 'pro']);
            // custom CSV generation, email sending, etc.
            return ['exported' => count($rows)];
        },
        'capability' => 'manage_options',
    ],
];

Portabilidade

Com o armazenamento JSONC, os dados ficam junto ao código. Copie a pasta do bloco para outro site e tudo vai junto: o UI, a lógica, o controle de acesso e os próprios dados.

Código
my-app/
├── block.json
├── index.twig
├── style.css
├── rpc.php        ← custom endpoints
├── db.php         ← data schema
├── cron.php       ← scheduled tasks
└── db/
    └── entries.jsonc  ← the actual data

Sem migrações de banco de dados nem etapas de exportação/importação. Basta copiar a pasta.

O armazenamento Storh também é portátil, mas fica em uploads/blockstudio/db/ em vez de na pasta do bloco. Assim, os dados ativos e graváveis ficam fora da árvore de código-fonte, enquanto cada esquema ainda tem um armazenamento em arquivos simples que pode ser copiado, incluído em um backup ou migrado de forma independente.

Filtro

Modifique esquemas programaticamente de fora do bloco:

PHP
add_filter('blockstudio/database', function (array $schemas): array {
    // Add a field to an existing schema
    $schemas['my-theme/app:subscribers']['fields']['source'] = [
        'type'    => 'string',
        'default' => 'website',
    ];
    return $schemas;
});