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
- Crie
db.phpno diretório do seu bloco - Ele retorna um esquema: campos, tipos, regras de validação e controle de acesso
- Blockstudio cria o armazenamento (tabela, arquivo ou metadados do post)
- Cinco endpoints REST são gerados automaticamente (listar, obter, criar, atualizar, excluir)
bs.db()eDb::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.
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
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:
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.
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.
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:
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.
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:
wp bs db migrate my-theme/app subscribers --to=storh
Para blocos com um único esquema:
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.
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:
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:
// 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).
// 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:
// 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:
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:
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.
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:
$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.
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
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
- Ao carregar a página, o cliente busca um hash leve dos dados atuais
- A cada
intervalmilissegundos, busca o hash novamente - Se o hash mudar, busca o conjunto de dados completo
- Os novos dados são enviados ao armazenamento API de Interactivity por meio de
store() - 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:
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) |
'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:
'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:
{
"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:
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/:
/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.
'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']],
],
],
],
],
],
<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:
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:
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:
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:
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.
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:
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;
});