Vai al contenuto

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

  1. Crea db.php nella directory del blocco
  2. Restituisce uno schema: campi, tipi, regole di convalida, controllo degli accessi
  3. Blockstudio crea l’archiviazione (tabella, file o metadati del post)
  4. Vengono generati automaticamente cinque endpoint REST (elenco, lettura, creazione, aggiornamento, eliminazione)
  5. bs.db() e Db::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.

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

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
<?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:

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

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.

Codice
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.

Codice
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:

Codice
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.

PHP
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:

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

Per i blocchi con schema singolo:

Shell
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.

PHP
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:

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

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:

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

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).

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

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:

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

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:

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

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:

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

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:

PHP
$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.

PHP
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

PHP
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

  1. Al caricamento della pagina, il client recupera un hash leggero dei dati correnti
  2. Ogni interval millisecondi, recupera nuovamente l’hash
  3. Se l’hash è cambiato, recupera l’intero insieme di dati
  4. I nuovi dati vengono inviati allo store Interactivity API tramite store()
  5. 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:

PHP
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)
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
],

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:

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

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."]
    }
  }
}

Ogni campo corrisponde a un array di stringhe di errore. Più regole possono non essere superate per lo stesso campo. Sul 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]);
  });
}

Endpoint REST

Tutti gli endpoint si trovano nel namespace blockstudio/v1/db/:

Codice
/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.

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>

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:

PHP
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:

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

Hook globali

Ascoltate tutti gli schemi da qualsiasi punto:

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

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:

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

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.

Codice
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:

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