Saltar al contenido

Base de datos

La capa de base de datos permite definir un modelo de datos para el bloque en un archivo db.php. Blockstudio genera endpoints CRUD REST, valida las entradas según el esquema, administra el almacenamiento automáticamente y proporciona tanto un cliente JavaScript (bs.db()) como una clase PHP API (Db).

Esta es la base de datos para bloques de pila completa. Mientras que RPC se encarga de la lógica personalizada, la capa de base de datos gestiona los datos estructurados sin código repetitivo.

Cómo funciona

  1. Cree db.php en el directorio de su bloque
  2. Devuelve un esquema: campos, tipos, reglas de validación y control de acceso
  3. Blockstudio crea el almacenamiento (tabla, archivo o metadatos de publicación)
  4. Se generan automáticamente cinco endpoints REST (listar, obtener, crear, actualizar y eliminar)
  5. bs.db() y Db::get() proporcionan acceso desde el cliente y el servidor

Sin migraciones, controladores ni registro de rutas.

Pase valores literales a las API REST y PHP. Los backends meta y post_type gestionan internamente el escape de barras de WordPress en los metadatos, preservando las barras invertidas y las cadenas entre comillas tanto en valores escalares como en objetos o matrices anidados. No aplique previamente el escape de barras a los valores de los registros de la base de datos.

Definición de esquemas

Esquema único

La forma más sencilla: un modelo de datos por bloque.

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'],
    ],
];

Sintaxis del constructor nativa de PHP

db.php también puede usar una pequeña API de constructor basada en argumentos con nombre y objetos de definición de solo lectura. Los arrays siguen siendo el formato predeterminado, pero esta opción nativa de PHP facilita el descubrimiento cuando el esquema empieza a crecer.

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 un esquema único, o devuelva un array de llamadas Schema::make(...) con nombre para bloques con varios esquemas.

Varios esquemas

Un mismo bloque puede tener varios modelos de datos. Devuelva un array con nombre:

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 obtiene sus propios endpoints, almacenamiento y control de acceso.

Modos de almacenamiento

Seis backends de almacenamiento, cada uno adecuado para distintos casos de uso.

Tabla personalizada (storage: "table")

Cada registro es una fila en una tabla MySQL dedicada. Blockstudio crea y administra la tabla automáticamente con la función dbDelta() de WordPress. Al añadir campos al esquema, se agregan columnas en la siguiente carga de página. Las columnas existentes nunca se eliminan.

Ideal para: datos estructurados, consultas y aplicaciones de producción.

SQLite (storage: "sqlite")

Cada esquema obtiene su propio archivo de base de datos SQLite en una subcarpeta db/. Blockstudio crea automáticamente el archivo y la tabla, y añade las columnas que falten cuando cambia el esquema (como dbDelta para MySQL). Usa el modo de diario WAL para permitir lecturas simultáneas.

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

Ideal para: datos estructurados que necesitan consultas reales de SQL, pero deben seguir siendo portátiles. Gestiona miles de registros de forma eficiente sin cargarlos todos en memoria. Copie la carpeta para trasladar los datos.

Archivos JSONC (storage: "jsonc")

Los registros se almacenan como un objeto JSON por línea en un archivo .jsonc dentro de una subcarpeta db/. El archivo se crea automáticamente al escribir por primera vez. Las líneas que empiezan por // se tratan como comentarios y se conservan.

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

Ideal para: conjuntos de datos pequeños, datos similares a configuraciones, registros iniciales y ejemplos sujetos a control de versiones. JSONC es intencionadamente un único archivo en la carpeta del bloque. Úselo cuando quiera que los datos acompañen al código, no si espera muchas escrituras simultáneas.

Archivos Storh (storage: "storh")

Storh almacena cada registro como un archivo individual en las cargas 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

Los ID públicos de los registros siguen siendo los mismos ID enteros que usa el resto de bs.db(). Blockstudio asigna esos ID a los ID internos de archivo UUIDv7 de Storh y almacena el entero id en los datos del registro, por lo que quienes llaman desde JavaScript, REST y PHP no necesitan gestionar UUID.

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

Blockstudio crea índices Storh a partir del esquema. Como cada campo declarado puede usarse como filtro de lista, todos los campos declarados se indexan. Los campos enteros, numéricos y similares a fechas usan índices de rango; los campos marcados con 'unique' => true o 'index' => 'unique' usan índices únicos.

Ideal para: datos de producción basados en archivos que necesitan escrituras simultáneas más seguras, índices derivados del esquema y almacenamiento portátil a nivel de cargas, sin incluir registros activos en el árbol de código fuente del bloque.

Migrar JSONC a Storh

Si empezó con un archivo .jsonc y quiere los mismos registros en Storh, ejecute:

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

Para bloques con un solo esquema:

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

La migración lee el db/{schema}.jsonc existente y escribe los registros en Storh conservando los ID enteros, vuelve a indexar, verifica el almacén de destino y deja intacto el archivo JSONC. Para revertir, basta con cambiar storage del esquema a "jsonc".

Metadatos de publicación (storage: "meta")

Los registros se almacenan como un array JSON en los metadatos de publicación WordPress, vinculados a una publicación específica mediante postId.

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

Ideal para: datos que pertenecen a una publicación o página específica.

Tipo de publicación personalizado (storage: "post_type")

Cada registro es una publicación WordPress en un tipo de publicación personalizado que se registra automáticamente. Cada campo del esquema se convierte en una entrada post_meta independiente. Así, se pueden consultar los registros con WP_Query, son compatibles con los plugins REST API y son visibles para herramientas como GraphQL.

Ideal para: datos que deben integrarse de forma nativa con WordPress. Cada campo se puede consultar e indexar de forma independiente.

Cliente JavaScript

Blockstudio inyecta bs.db() en las páginas con bloques de base de datos. Devuelve un objeto con 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);

El primer argumento es el nombre del bloque (con /); el segundo, el nombre del esquema. En bloques con un solo esquema, omita el nombre del esquema (el valor predeterminado es "default").

Caché

bs.cache es una caché de consultas en memoria, compartida entre todas las llamadas a bs.query y bs.mutate. También puede usarla directamente:

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();

Las entradas de la caché se almacenan en memoria y se borran al navegar a otra página. Las usan principalmente bs.query y bs.mutate internamente, pero el acceso directo resulta útil para precargar datos o invalidarlos manualmente después de operaciones personalizadas.

Consulta

bs.query() envuelve cualquier función asíncrona con caché, deduplicación y control de antigüedad. Varias llamadas con la misma clave mientras una solicitud está en curso devuelven la misma promesa (sin solicitudes 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 }
);

El primer argumento es una clave de caché (cualquier cadena). El segundo es una función que devuelve una promesa. El tercero es un objeto opcional de opciones:

Opción Tipo Descripción
staleTime number Milisegundos antes de que los datos en caché se consideren obsoletos. 0 (predeterminado) siempre vuelve a obtener los datos.

Si la caché contiene datos para la clave y tienen menos de staleTime, el valor en caché se devuelve inmediatamente sin llamar a la función.

Mutación

bs.mutate() gestiona operaciones de escritura con actualizaciones optimistas y reversión automática en caso de error. Tiene dos modos: automático, para patrones CRUD habituales, y manual, para tener control total.

El modo automático funciona con un objeto de estado reactivo (como Alpine.js $data). Pase state, key, action y, de forma opcional, 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),
});

Si la operación tiene éxito, los datos optimistas se reemplazan por la respuesta del servidor. Si falla, el estado vuelve a una instantánea tomada antes de la mutación. La clave de caché se invalida automáticamente después de cada mutación correcta.

Se considera que hay un error cuando se rechaza la promesa devuelta por fn. bs.db() y bs.fn() se resuelven con el cuerpo del error si falla la validación, no se encuentra un registro o se deniega un permiso. Para que esos casos también provoquen una reversión, lance una excepción cuando el resultado incluya code:

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)),
});

En las operaciones de creación, se asigna un id temporal (como __temp_1) al elemento optimista. Cuando responde el servidor, el elemento temporal se actualiza con los datos reales, incluido el id asignado por el servidor.

El modo manual le da control total mediante las funciones de retorno before, onSuccess y 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;
  },
});
Opción Tipo Modo Descripción
fn function Ambos Función asíncrona que realiza la mutación. Obligatoria.
state object Automático Objeto de estado reactivo (e.g., Alpine $data).
key string Automático Nombre de la propiedad del estado que contiene el array. También se usa como clave de caché.
action string Automático Uno de create, update o delete.
id any Automático ID del registro para las acciones update y delete.
optimistic object Automático Datos que se aplican de forma optimista antes de que responda el servidor.
before function Manual Se llama antes de fn. El valor devuelto se pasa a onSuccess/onError como snapshot.
onSuccess function Manual Se llama con (result, snapshot) si la operación tiene éxito.
onError function Manual Se llama con (error, snapshot) si falla.
invalidate string Manual Clave de caché que se invalidará si la operación tiene éxito.

PHP API

La clase Db proporciona las mismas operaciones en el servidor. Úsela en rpc.php, cron.php, plantillas o cualquier 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 bloques con un solo esquema:

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

Sondeo en tiempo real

Añada realtime al esquema para activar el sondeo automático. Cuando cambian los datos en el servidor, el UI se actualiza automáticamente mediante el almacén de Interactivity API. No es necesario cambiar JavaScript.

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

Con true, Blockstudio sondea cada 3 segundos usando el nombre del esquema como clave de estado del almacén de Interactivity API (default en bloques con un solo esquema).

Configuración personalizada

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Opción Tipo Valor predeterminado Descripción
key string nombre del esquema Nombre de la propiedad de state que contiene el array de datos
interval number 3000 Intervalo de sondeo en milisegundos

Cómo funciona

  1. Al cargar la página, el cliente obtiene un hash ligero de los datos actuales
  2. Cada interval milisegundos, vuelve a obtener el hash
  3. Si el hash ha cambiado, obtiene el conjunto de datos completo
  4. Los datos nuevos se envían al almacén de Interactivity API mediante store()
  5. Las directivas vinculadas a esa propiedad de estado se vuelven a renderizar automáticamente

El sondeo solo se ejecuta en páginas donde existe un elemento data-wp-interactive correspondiente. Se pausa cuando la pestaña del navegador está oculta y se reanuda al volver a mostrarse.

El endpoint de hash (?_hash=1) solo devuelve una suma de comprobación md5 y el número de registros, para que las solicitudes de sondeo sean ligeras.

Datos vinculados al usuario

Configure userScoped: true para limitar automáticamente todos los registros al usuario actual. Blockstudio añade una columna user_id, la establece al crear registros y limita todas las operaciones a los registros del usuario actual:

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

Sin campo manual user_id, sin hook before_create ni filtrado en RPC. Los usuarios solo pueden ver, editar y eliminar sus propios registros. La columna user_id está gestionada íntegramente por Blockstudio.

Al usar el almacenamiento post_type, userScoped se asigna a post_author en lugar de a una columna user_id independiente.

Control de acceso

Cada operación CRUD tiene su propio nivel de permisos:

Valor Comportamiento
true Público con protección CSRF (se permiten usuarios sin sesión; se requiere X-BS-Token)
'open' Público de verdad, sin CSRF ni autenticación (para webhooks y API externas)
'edit_posts' Comprobación de capacidad WordPress
['cap_a', 'cap_b'] El usuario necesita una de las capacidades indicadas
omitido / null Requiere autenticación (usuario con sesión iniciada)
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
],

Protección CSRF

Los endpoints públicos (true) están protegidos por un encabezado X-BS-Token. bs.db() y bs.fn() obtienen credenciales nuevas de un endpoint del mismo origen sin caché, en lugar de insertar tokens que caducan en el HTML de la página. Las páginas servidas desde cachés externos de larga duración siguen funcionando. Las llamadas anónimas sin un token válido reciben una respuesta 403.

Las credenciales se solicitan en la primera llamada API, no en cada visita a la página. Ambos clientes, incluido el sondeo en tiempo real de la base de datos, comparten una única actualización de credenciales en curso. Las credenciales se actualizan tras cinco minutos de uso. Si se rechaza un nonce WordPress o un token CSRF Blockstudio, se actualizan las credenciales y se reintenta una vez; los errores de permisos ordinarios no se reintentan. Las solicitudes de usuarios que han iniciado sesión siguen usando la sesión del usuario visitante y las comprobaciones de capacidades y propiedad de registros del esquema.

Mantén POST /wp-json/blockstudio/v1/client/credentials fuera de cualquier caché de proxy o CDN. Envía Cache-Control: private, no-store y requiere una solicitud del mismo origen con un encabezado no simple. Los clientes integrados se encargan de esto automáticamente.

Use 'open' cuando necesite acceso sin autenticación ni protección CSRF, por ejemplo, para recibir webhooks de servicios externos.

Tipos de campo

Tipo Columna MySQL Tipo PHP Descripción
string varchar(maxLength) string Texto, longitud máxima predeterminada 255
integer bigint(20) int Números enteros
number decimal(20,6) float Números decimales
boolean tinyint(1) bool Verdadero/falso
text longtext string Contenido de texto largo

Validación

Todas las escrituras (creación y actualización) se validan según el esquema antes de modificar el almacenamiento. La validación se realiza en el servidor, independientemente de si la solicitud proviene de bs.db(), del REST API o de Db::get().

Reglas integradas

Regla Ejemplo Descripción
required 'required' => true El campo debe estar presente al crear
type 'type' => 'integer' El valor debe coincidir con el tipo declarado
enum 'enum' => ['a', 'b'] El valor debe ser una de las opciones indicadas
maxLength 'maxLength' => 100 La cadena no puede superar esta longitud
minLength 'minLength' => 3 La cadena debe tener al menos esta longitud
format: "email" 'format' => 'email' Debe ser una dirección de correo válida
format: "url" 'format' => 'url' Debe ser un URL válido

Validación personalizada

Añada una función de retorno validate a cualquier campo para realizar comprobaciones en el servidor que vayan más allá de las reglas integradas. Devuelva true para validar el campo o una cadena con el mensaje de error:

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;
    },
],

La función de retorno recibe el valor del campo y el array de datos completo, por lo que permite validar varios campos relacionados.

Formato de respuesta de error

Los errores de validación devuelven un estado 400 con matrices de errores por campo. Este formato está inspirado en Zod fieldErrors y facilita asociar los errores con los campos del formulario:

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 se asocia a un array de cadenas de error. Pueden fallar varias reglas para el mismo campo. En el 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 los endpoints están en el espacio de nombres blockstudio/v1/db/:

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

En el nombre del bloque, / se reemplaza por -. En los bloques con un solo esquema, el nombre del esquema es default.

Método Endpoint Descripción
GET /db/{block}/{schema} Listar registros
POST /db/{block}/{schema} Crear un registro
GET /db/{block}/{schema}/{id} Obtener un registro
PUT /db/{block}/{schema}/{id} Actualizar un registro
DELETE /db/{block}/{schema}/{id} Eliminar un registro

Parámetros de consulta (lista)

Parámetro Descripción
limit Máximo de registros que se devolverán (predeterminado: 50; máximo: 100)
offset Número de registros que se omitirán
Cualquier nombre de campo Filtrar por coincidencia exacta del valor

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

Renderizado de formularios

Los campos pueden definir una clave component que haga referencia a un bloque Blockstudio. Llame a bs_db_form() en la plantilla para mostrar todos los campos como un formulario que usa sus bloques de componentes.

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 recibe la definición completa del campo como field en sus atributos, para que pueda adaptar su representación según el esquema. Por ejemplo, $a['field']['name'] indica el nombre del campo, $a['field']['type'] el tipo, $a['field']['required'] si es obligatorio, etc.

La estructura del componente sigue el mismo formato name, attributes, innerBlocks que los bloques WordPress. Los bloques internos se representan primero y se pasan como $content al bloque principal.

Para usar PHP sin imprimirlo:

PHP
use Blockstudio\Db;

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

Hooks

Las acciones se ejecutan antes y después de cada operación de escritura. Todos los hooks reciben un único array $params. Consulta la referencia de hooksPHP para ver la lista completa.

Hooks en línea

Define los hooks directamente en db.php. Se aplican automáticamente a ese esquema, así que no necesitas comprobar el nombre del bloque o del 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 globales

Escucha los eventos de todos los esquemas desde cualquier 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
    }
});

Combinación con RPC

db.php y rpc.php son sistemas independientes. db.php genera endpoints CRUD a partir de una definición de esquema. rpc.php define funciones de servidor personalizadas. Cada uno funciona por separado.

Úsalos juntos cuando necesites operaciones de datos estándar y lógica de negocio 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',
    ],
];

Portabilidad

Con el almacenamiento JSONC, los datos se guardan junto al código. Copia la carpeta del bloque a otro sitio y todo se traslada con ella: UI, la lógica, el control de acceso y los propios datos.

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

Sin migraciones de base de datos ni pasos de exportación e importación. Solo tienes que copiar la carpeta.

El almacenamiento Storh también es portable, pero se encuentra en uploads/blockstudio/db/ en lugar de la carpeta del bloque. Así, los datos activos y modificables quedan fuera del árbol de código fuente, y cada esquema conserva un almacén de archivos sencillo que puedes respaldar, copiar o migrar de forma independiente.

Filtro

Modifica esquemas mediante programación desde fuera del bloque:

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;
});