Database
Il livello database ti consente di definire un modello di dati per il tuo blocco in un file db.php.
Blockstudio genera endpoint CRUD REST, convalida i dati in ingresso rispetto allo schema, gestisce automaticamente l’archiviazione e fornisce sia un client JavaScript (bs.db()) sia una classe PHP API (Db).
Questa è la base dati per i blocchi full-stack. Mentre RPC gestisce la logica personalizzata, il livello database gestisce i dati strutturati senza codice boilerplate.
Come funziona
- Crea
db.phpnella directory del blocco - Restituisce uno schema: campi, tipi, regole di convalida, controllo degli accessi
- Blockstudio crea l’archiviazione (tabella, file o metadati del post)
- Vengono generati automaticamente cinque endpoint REST (elenco, lettura, creazione, aggiornamento, eliminazione)
bs.db()eDb::get()forniscono accesso client e server
Nessuna migrazione, nessun controller, nessuna registrazione delle route.
Passate valori letterali alle API REST e PHP. I backend meta e post_type gestiscono internamente l’escaping dei metadati WordPress, preservando le barre inverse e le stringhe tra virgolette sia nei valori scalari sia negli oggetti o negli array annidati. Non aggiungete preventivamente le barre inverse ai valori dei record del database.
Definizione degli schemi
Schema singolo
La forma più semplice: un solo modello di dati per blocco.
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'],
],
];
Sintassi del builder nativa per PHP
db.php può anche usare una semplice sintassi builder API basata su argomenti denominati e oggetti di definizione in sola lettura. Gli array restano il formato predefinito, ma questa opzione nativa per PHP rende gli schemi più facili da esplorare quando diventano più grandi.
<?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'),
],
);
Usa Schema::make() per un singolo schema oppure restituisci un array di chiamate Schema::make(...) denominate per i blocchi con più schemi.
Schemi multipli
Un singolo blocco può contenere più modelli di dati. Restituisci un array denominato:
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'],
],
],
];
Ogni schema ha i propri endpoint, la propria archiviazione e il proprio controllo degli accessi.
Modalità di archiviazione
Sei backend di archiviazione, ciascuno adatto a casi d’uso diversi.
Tabella personalizzata (storage: "table")
Ogni record è una riga in una tabella MySQL dedicata. Blockstudio crea e gestisce automaticamente la tabella usando la funzione dbDelta() di WordPress. L’aggiunta di nuovi campi allo schema aggiunge colonne al caricamento della pagina successiva. Le colonne esistenti non vengono mai rimosse.
Ideale per: dati strutturati, query e applicazioni di produzione.
SQLite (storage: "sqlite")
Ogni schema ha un proprio file database SQLite in una sottocartella db/. Blockstudio crea automaticamente il file e la tabella e aggiunge le colonne mancanti quando lo schema cambia (come dbDelta per MySQL). Usa la modalità journal WAL per prestazioni di lettura simultanea.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Ideale per: dati strutturati che richiedono vere query SQL ma devono restare portabili. Gestisce migliaia di record in modo efficiente, senza caricare tutto in memoria. Copia la cartella per spostare i dati.
File JSONC (storage: "jsonc")
I record vengono archiviati come un oggetto JSON per riga in un file .jsonc all’interno di una sottocartella db/. Il file viene creato automaticamente alla prima scrittura. Le righe che iniziano con // vengono trattate come commenti e mantenute.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Ideale per: piccoli insiemi di dati, dati simili a configurazioni, record iniziali ed esempi con controllo delle versioni. JSONC è intenzionalmente un unico file nella cartella del blocco. Usalo quando vuoi che i dati viaggino insieme al codice, non quando prevedi molte scritture simultanee.
File Storh (storage: "storh")
Storh archivia ogni record come file individuale in WordPress uploads:
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
Gli ID pubblici dei record restano gli stessi ID interi usati dal resto di bs.db().
Blockstudio associa questi ID agli ID file interni UUIDv7 di Storh e archivia l’intero id nei dati del record, così i chiamanti JavaScript, REST e PHP non devono gestire UUID.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio crea indici Storh dallo schema. Poiché ogni campo dichiarato può essere usato come filtro dell’elenco, ogni campo dichiarato viene indicizzato. I campi interi, numerici e di tipo data usano indici per intervallo; i campi contrassegnati con 'unique' => true o 'index' => 'unique' usano indici univoci.
Ideale per: dati di produzione basati su file che richiedono scritture simultanee più sicure, indici derivati dallo schema e archiviazione portabile a livello di uploads, senza inserire i record attivi nell’albero dei sorgenti del blocco.
Migrazione da JSONC a Storh
Se hai iniziato con un file .jsonc e vuoi gli stessi record in Storh, esegui:
wp bs db migrate my-theme/app subscribers --to=storh
Per i blocchi con schema singolo:
wp bs db migrate my-theme/app --to=storh
La migrazione legge il file db/{schema}.jsonc esistente, scrive i record in Storh mantenendo gli ID interi, reindicizza, verifica l’archivio di destinazione e lascia intatto il file JSONC. Per annullare la migrazione, basta riportare storage dello schema a "jsonc".
Metadati del post (storage: "meta")
I record vengono archiviati come array JSON nei metadati WordPress del post, associati a un post specifico tramite postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Ideale per: dati associati a un post o a una pagina specifici.
Tipo di contenuto personalizzato (storage: "post_type")
Ogni record è un post WordPress in un tipo di contenuto personalizzato registrato automaticamente. Ogni campo dello schema diventa una voce post_meta separata. In questo modo i record sono interrogabili con WP_Query, compatibili con i plugin REST API e visibili a strumenti come GraphQL.
Ideale per: dati da integrare nativamente con WordPress. Ogni campo è interrogabile e indicizzabile in modo indipendente.
Client JavaScript
Blockstudio inserisce bs.db() nelle pagine con blocchi database. Restituisce un oggetto con cinque metodi:
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);
Il primo argomento è il nome del blocco (con /), il secondo è il nome dello schema.
Per i blocchi con schema singolo, ometti il nome dello schema (il valore predefinito è "default").
Cache
bs.cache è una cache di query in memoria condivisa da tutte le chiamate bs.query e bs.mutate. Puoi usarla anche direttamente:
// 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();
Le voci della cache sono archiviate in memoria e cancellate quando si naviga a un’altra pagina. Sono usate principalmente internamente da bs.query e bs.mutate, ma l’accesso diretto è utile per precaricare dati o invalidare manualmente la cache dopo operazioni personalizzate.
Query
bs.query() applica a qualsiasi funzione asincrona caching, deduplicazione e controllo della scadenza. Più chiamate con la stessa chiave mentre una richiesta è in corso restituiscono la stessa promise (nessuna richiesta duplicata).
// 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 }
);
Il primo argomento è una chiave della cache (qualsiasi stringa). Il secondo è una funzione che restituisce una promise. Il terzo è un oggetto opzionale con le opzioni:
| Opzione | Tipo | Descrizione |
|---|---|---|
staleTime |
number |
Millisecondi prima che i dati nella cache siano considerati scaduti. 0 (predefinito) esegue sempre una nuova richiesta. |
Se la cache contiene dati per la chiave e questi sono più recenti di staleTime, il valore memorizzato viene restituito subito senza chiamare la funzione.
Modifica
bs.mutate() gestisce le operazioni di scrittura con aggiornamenti ottimistici e rollback automatico in caso di errore. Ha due modalità: quella automatica per le operazioni CRUD più comuni e quella manuale per il controllo completo.
La modalità automatica funziona con un oggetto di stato reattivo (come Alpine.js $data). Passa state, key, action e, facoltativamente, 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),
});
In caso di successo, i dati ottimistici vengono sostituiti dalla risposta del server. In caso di errore, lo stato viene ripristinato allo snapshot acquisito prima della modifica. La chiave della cache viene invalidata automaticamente dopo ogni modifica riuscita.
Un’operazione non riuscita significa che la promise restituita da fn viene rifiutata. bs.db() e bs.fn() vengono risolte con il corpo dell’errore in caso di errore di convalida, record mancante o controllo dei permessi non superato; quindi genera un’eccezione quando il risultato contiene code se anche questi casi devono causare il rollback:
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)),
});
Per le operazioni di creazione, all’elemento ottimistico viene assegnato un id temporaneo (come __temp_1). Quando il server risponde, l’elemento temporaneo viene aggiornato con i dati reali, incluso l’id assegnato dal server.
La modalità manuale offre il controllo completo con le callback 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;
},
});
| Opzione | Tipo | Modalità | Descrizione |
|---|---|---|---|
fn |
function |
Entrambe | La funzione asincrona che esegue la modifica. Obbligatoria. |
state |
object |
Automatica | Oggetto di stato reattivo (e.g., Alpine $data). |
key |
string |
Automatica | Nome della proprietà nello stato che contiene l’array. Usato anche come chiave della cache. |
action |
string |
Automatica | Uno tra create, update o delete. |
id |
any |
Automatica | ID del record per le azioni update e delete. |
optimistic |
object |
Automatica | Dati da applicare in modo ottimistico prima della risposta del server. |
before |
function |
Manuale | Chiamata prima di fn. Il valore restituito viene passato a onSuccess/onError come snapshot. |
onSuccess |
function |
Manuale | Chiamata con (result, snapshot) in caso di successo. |
onError |
function |
Manuale | Chiamata con (error, snapshot) in caso di errore. |
invalidate |
string |
Manuale | Chiave della cache da invalidare in caso di successo. |
PHP API
La classe Db fornisce le stesse operazioni lato server. Usala in rpc.php, cron.php, nei template o in qualsiasi codice 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);
Per i blocchi con schema singolo:
$db = Db::get('my-theme/block');
Polling in tempo reale
Aggiungi realtime allo schema per abilitare il polling automatico. Quando i dati cambiano sul server, UI si aggiorna automaticamente tramite lo store Interactivity API. Non sono necessarie modifiche a JavaScript.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Con true, Blockstudio esegue il polling ogni 3 secondi usando il nome dello schema come chiave di stato dello store Interactivity API (default per i blocchi con schema singolo).
Configurazione personalizzata
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Opzione | Tipo | Predefinito | Descrizione |
|---|---|---|---|
key |
string |
nome dello schema | Nome della proprietà su state che contiene l’array di dati |
interval |
number |
3000 |
Intervallo di polling in millisecondi |
Come funziona
- Al caricamento della pagina, il client recupera un hash leggero dei dati correnti
- Ogni
intervalmillisecondi, recupera nuovamente l’hash - Se l’hash è cambiato, recupera l’intero insieme di dati
- I nuovi dati vengono inviati allo store Interactivity API tramite
store() - Tutte le direttive associate a quella proprietà di stato vengono renderizzate di nuovo automaticamente
Il polling viene eseguito solo nelle pagine in cui esiste un elemento data-wp-interactive corrispondente. Si interrompe quando la scheda del browser è nascosta e riprende quando è visibile.
L’endpoint hash (?_hash=1) restituisce solo un checksum md5 e il conteggio dei record, mantenendo leggere le richieste di polling.
Dati associati all’utente
Imposta userScoped: true per associare automaticamente tutti i record all’utente corrente.
Blockstudio aggiunge una colonna user_id, la imposta alla creazione e filtra tutte le operazioni in modo da includere solo i record dell’utente corrente:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Nessun campo user_id manuale, nessun hook before_create e nessun filtro in RPC. Gli utenti possono visualizzare, modificare ed eliminare solo i propri record. La colonna user_id è gestita interamente da Blockstudio.
Quando usi l’archiviazione post_type, userScoped viene associato a post_author invece che a una colonna user_id separata.
Controllo degli accessi
Ogni operazione CRUD ha il proprio livello di autorizzazione:
| Valore | Comportamento |
|---|---|
true |
Pubblico con protezione CSRF (utenti non autenticati ammessi, X-BS-Token necessario) |
'open' |
Completamente pubblico, senza CSRF né autenticazione (per webhook e API esterne) |
'edit_posts' |
Verifica della capability WordPress |
['cap_a', 'cap_b'] |
L’utente deve disporre di almeno una delle capability elencate |
omesso / null |
Richiede l’autenticazione (utente con sessione avviata) |
'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
],
Protezione CSRF
Gli endpoint pubblici (true) sono protetti da un’intestazione X-BS-Token. bs.db() e bs.fn() recuperano credenziali aggiornate da un endpoint della stessa origine non memorizzato nella cache, invece di incorporare token in scadenza nel HTML della pagina. Le pagine servite da cache esterne di lunga durata continuano a funzionare. Le chiamate anonime senza un token valido ricevono una risposta 403.
Le credenziali vengono richieste alla prima chiamata API, non a ogni visualizzazione della pagina. Entrambi i client, incluso il polling realtime del database, condividono un unico aggiornamento delle credenziali in corso. Le credenziali vengono aggiornate dopo cinque minuti di utilizzo. Un nonce WordPress o un token CSRF Blockstudio rifiutato attiva un aggiornamento e un nuovo tentativo; gli errori ordinari di autorizzazione non vengono ritentati. Le richieste degli utenti autenticati continuano a usare la sessione dell’utente che visita il sito e i controlli delle capacità e della proprietà dei record definiti nello schema.
Mantenete POST /wp-json/blockstudio/v1/client/credentials fuori da qualsiasi cache proxy o CDN. Invia Cache-Control: private, no-store e richiede una richiesta della stessa origine con un’intestazione non semplice. I client integrati gestiscono tutto automaticamente.
Usa 'open' quando serve un accesso senza autenticazione e senza protezione CSRF, ad esempio per i webhook in ingresso da servizi esterni.
Tipi di campo
| Tipo | Colonna MySQL | Tipo PHP | Descrizione |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Testo, maxLength predefinito 255 |
integer |
bigint(20) |
int |
Numeri interi |
number |
decimal(20,6) |
float |
Numeri decimali |
boolean |
tinyint(1) |
bool |
Vero/falso |
text |
longtext |
string |
Testo di contenuto esteso |
Convalida
Tutte le scritture (creazione e aggiornamento) vengono convalidate rispetto allo schema prima di modificare l’archiviazione. La convalida avviene lato server, indipendentemente dal fatto che la richiesta provenga da bs.db(), dal REST API o da Db::get().
Regole integrate
| Regola | Esempio | Descrizione |
|---|---|---|
required |
'required' => true |
Il campo deve essere presente alla creazione |
type |
'type' => 'integer' |
Il valore deve corrispondere al tipo dichiarato |
enum |
'enum' => ['a', 'b'] |
Il valore deve essere uno di quelli elencati |
maxLength |
'maxLength' => 100 |
La stringa non può superare questa lunghezza |
minLength |
'minLength' => 3 |
La stringa deve essere lunga almeno quanto indicato |
format: "email" |
'format' => 'email' |
Deve essere un indirizzo email valido |
format: "url" |
'format' => 'url' |
Deve essere un URL valido |
Convalida personalizzata
Aggiungi una callback validate a qualsiasi campo per i controlli lato server che vanno oltre le regole integrate. Restituisci true per superare il controllo oppure una stringa con il messaggio di errore:
'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 callback riceve il valore del campo e l’intero array di dati, consentendo la convalida tra campi.
Formato della risposta di errore
Gli errori di convalida restituiscono uno stato 400 con array di errori per ciascun campo. Il formato si ispira a ZodfieldErrors e semplifica l’associazione degli errori ai campi del modulo:
{
"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."]
}
}
}
Ogni campo corrisponde a un array di stringhe di errore. Più regole possono non essere superate per lo stesso campo. Sul 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]);
});
}
Endpoint REST
Tutti gli endpoint si trovano nel namespace blockstudio/v1/db/:
/db/{block-name}/{schema-name}
Il nome del blocco ha / sostituito da -. Per i blocchi con schema singolo, il nome dello schema è default.
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET |
/db/{block}/{schema} |
Elenca i record |
POST |
/db/{block}/{schema} |
Crea un record |
GET |
/db/{block}/{schema}/{id} |
Recupera un singolo record |
PUT |
/db/{block}/{schema}/{id} |
Aggiorna un record |
DELETE |
/db/{block}/{schema}/{id} |
Elimina un record |
Parametri di query (elenco)
| Parametro | Descrizione |
|---|---|
limit |
Numero massimo di record da restituire (predefinito 50, massimo 100) |
offset |
Numero di record da saltare |
| Qualsiasi nome di campo | Filtra in base alla corrispondenza esatta del valore |
Esempio: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Rendering dei moduli
I campi possono definire una chiave component che fa riferimento a un blocco Blockstudio. Chiama bs_db_form() nel template per visualizzare tutti i campi come un modulo usando i relativi blocchi 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>
Ogni componente riceve la definizione completa del campo come field nei propri attributi, così può adattare il rendering in base allo schema. Per esempio, $a['field']['name'] fornisce il nome del campo, $a['field']['type'] il tipo, $a['field']['required'] indica se è obbligatorio e così via.
La struttura dei componenti segue lo stesso formato name, attributes, innerBlocks dei blocchi WordPress. I blocchi interni vengono renderizzati per primi e passati al genitore come $content.
Per usare PHP senza eseguire echo:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hook
Le azioni vengono eseguite prima e dopo ogni operazione di scrittura. Tutti gli hook ricevono un unico array $params. Per l’elenco completo, consultate il riferimento agli hookPHP.
Hook inline
Definite gli hook direttamente in db.php. Vengono associati automaticamente a quello schema, quindi non occorre verificare il nome del blocco o dello schema:
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']);
},
],
];
Hook globali
Ascoltate tutti gli schemi da qualsiasi punto:
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
}
});
Combinazione con RPC
db.php e rpc.php sono sistemi indipendenti. db.php genera endpoint CRUD da una definizione dello schema. rpc.php definisce funzioni server personalizzate. Ognuno funziona autonomamente.
Usateli insieme quando vi servono operazioni standard sui dati e una logica di business personalizzata:
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',
],
];
Portabilità
Con l’archiviazione JSONC, i dati risiedono insieme al codice. Copiate la cartella del blocco in un altro sito e tutto si trasferisce insieme: UI, la logica, i controlli di accesso e i dati stessi.
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
Nessuna migrazione del database, nessuna procedura di esportazione o importazione. Basta copiare la cartella.
Anche l’archiviazione Storh è portabile, ma si trova in uploads/blockstudio/db/ anziché nella cartella del blocco. In questo modo i dati live e modificabili restano fuori dall’albero dei sorgenti, mentre ogni schema dispone di un archivio in file di testo semplice, che può essere sottoposto a backup, copiato o migrato in modo indipendente.
Filtro
Modificate gli schemi a livello di codice dall’esterno del blocco:
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;
});