Bază de date
Stratul bazei de date vă permite să definiți un model de date pentru blocul dvs. într-un fișier db.php. Blockstudio generează endpointuri CRUD REST, validează datele de intrare conform schemei, gestionează automat stocarea și oferă atât un client JavaScript (bs.db()), cât și un API PHP (clasa Db).
Acesta este fundamentul de date pentru blocurile full-stack. În timp ce RPC gestionează logica personalizată, stratul bazei de date gestionează date structurate fără cod redundant.
Cum funcționează
- Creați
db.phpîn directorul blocului - Acesta returnează o schemă: câmpuri, tipuri, reguli de validare, controlul accesului
- Blockstudio creează stocarea (tabel, fișier sau metadate de articol)
- Cinci endpointuri REST sunt generate automat (listare, obținere, creare, actualizare, ștergere)
bs.db()șiDb::get()oferă acces de client și de server
Fără migrări, controlere sau înregistrarea rutelor.
Transmiteți valori literale API-urilor REST și PHP. Backendurile meta și post_type gestionează intern eliminarea caracterelor de escape din metadatele WordPress, păstrând barele oblice inverse și șirurile între ghilimele atât în valorile scalare, cât și în obiectele sau tablourile imbricate. Nu adăugați manual caractere de escape valorilor din înregistrările bazei de date.
Definirea schemelor
O singură schemă
Cea mai simplă formă: un singur model de date pentru fiecare bloc.
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'],
],
];
Sintaxa builderului nativ PHP
db.php poate folosi și un mic builder API, bazat pe argumente denumite și obiecte de definiție readonly. Tablourile rămân formatul implicit, dar această opțiune nativă pentru PHP oferă o structură mai clară când schema începe să devină mai amplă.
<?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'),
],
);
Folosiți Schema::make() pentru o singură schemă sau returnați un tablou cu apeluri Schema::make(...) denumite pentru blocurile cu mai multe scheme.
Mai multe scheme
Un singur bloc poate avea mai multe modele de date. Returnați un tablou asociativ:
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'],
],
],
];
Fiecare schemă primește propriile endpointuri, propria stocare și propriul control al accesului.
Moduri de stocare
Șase backenduri de stocare, fiecare potrivit pentru cazuri de utilizare diferite.
Tabel personalizat (storage: "table")
Fiecare înregistrare este un rând într-un tabel MySQL dedicat. Blockstudio creează și gestionează automat tabelul folosind funcția dbDelta() din WordPress. Câmpurile noi adăugate în schemă devin coloane la următoarea încărcare a paginii. Coloanele existente nu sunt niciodată eliminate.
Recomandat pentru: date structurate, interogări și aplicații de producție.
SQLite (storage: "sqlite")
Fiecare schemă primește propriul fișier de bază de date SQLite într-un subdirector db/. Blockstudio creează automat fișierul și tabelul și adaugă coloanele lipsă atunci când se modifică schema (precum dbDelta pentru MySQL). Folosește modul de jurnal WAL pentru performanță la citiri concurente.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Recomandat pentru: date structurate care necesită interogări SQL reale, dar trebuie să rămână portabile. Gestionează eficient mii de înregistrări fără să le încarce pe toate în memorie. Copiați folderul pentru a muta datele.
Fișiere JSONC (storage: "jsonc")
Înregistrările sunt stocate ca obiecte JSON, câte unul pe linie, într-un fișier .jsonc dintr-un subdirector db/. Fișierul este creat automat la prima scriere. Liniile care încep cu // sunt tratate ca comentarii și păstrate.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Recomandat pentru: seturi mici de date, date de tip configurare, înregistrări inițiale și exemple care pot fi gestionate în controlul versiunilor. JSONC este conceput intenționat ca un singur fișier în folderul blocului. Folosiți-l când doriți ca datele să călătorească împreună cu codul, nu când vă așteptați la multe scrieri concurente.
Fișiere Storh (storage: "storh")
Storh stochează fiecare înregistrare într-un fișier individual din 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
ID-urile publice ale înregistrărilor rămân aceleași ID-uri întregi folosite în restul bs.db(). Blockstudio asociază aceste ID-uri cu ID-urile interne ale fișierelor UUIDv7 din Storh și stochează numărul întreg id în datele înregistrării, astfel încât apelanții JavaScript, REST și PHP să nu fie nevoiți să gestioneze UUID-uri.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio generează indexuri Storh din schema dvs. Deoarece fiecare câmp declarat poate fi folosit ca filtru de listă, toate câmpurile declarate sunt indexate. Câmpurile întregi, numerice și de tip dată folosesc indexuri de interval; câmpurile marcate cu 'unique' => true sau 'index' => 'unique' folosesc indexuri unice.
Recomandat pentru: date de producție bazate pe fișiere, care necesită scrieri concurente mai sigure, indexuri derivate din schemă și stocare portabilă la nivelul încărcărilor, fără a include înregistrările active în arborele sursă al blocului.
Migrarea de la JSONC la Storh
Dacă ați început cu un fișier .jsonc și doriți aceleași înregistrări în Storh, rulați:
wp bs db migrate my-theme/app subscribers --to=storh
Pentru blocuri cu o singură schemă:
wp bs db migrate my-theme/app --to=storh
Migrarea citește fișierul db/{schema}.jsonc existent, scrie înregistrările în Storh păstrând ID-urile întregi, reconstruiește indexurile, verifică stocarea țintă și lasă fișierul JSONC neatins. Pentru revenire, schimbați pur și simplu storage din schemă înapoi la "jsonc".
Metadate de articol (storage: "meta")
Înregistrările sunt stocate ca un tablou JSON în metadatele articolului WordPress, asociate unui anumit articol prin postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Recomandat pentru: date care aparțin unui anumit articol sau unei anumite pagini.
Tip de conținut personalizat (storage: "post_type")
Fiecare înregistrare este un articol WordPress într-un tip de conținut personalizat înregistrat automat. Fiecare câmp din schemă devine o intrare post_meta separată. Astfel, înregistrările pot fi interogate cu WP_Query, sunt compatibile cu pluginurile REST API și sunt vizibile în instrumente precum GraphQL.
Recomandat pentru: date care trebuie să se integreze nativ cu WordPress. Fiecare câmp poate fi interogat și indexat independent.
Clientul JavaScript
Blockstudio injectează bs.db() pe paginile cu blocuri de bază de date. Returnează un obiect cu cinci metode:
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);
Primul argument este numele blocului (cu /), iar al doilea este numele schemei. Pentru blocurile cu o singură schemă, omiteți numele schemei (implicit este "default").
Cache
bs.cache este un cache de interogări în memorie, partajat între toate apelurile bs.query și bs.mutate. Îl puteți folosi și direct:
// 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();
Intrările din cache sunt stocate în memorie și șterse la navigarea între pagini. Sunt folosite în principal intern de bs.query și bs.mutate, dar accesul direct este util pentru prepopularea datelor sau invalidarea manuală după operațiuni personalizate.
Interogare
bs.query() încapsulează orice funcție async cu memorare în cache, deduplicare și controlul vechimii. Apelurile multiple cu aceeași cheie, cât timp o solicitare este în curs, returnează aceeași promisiune (fără solicitări duplicate).
// 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 }
);
Primul argument este o cheie de cache (orice șir). Al doilea este o funcție care returnează o promisiune. Al treilea este un obiect opțional cu opțiuni:
| Opțiune | Tip | Descriere |
|---|---|---|
staleTime |
number |
Milisecunde până când datele din cache sunt considerate învechite. 0 (implicit) preia întotdeauna din nou. |
Dacă cache-ul conține date pentru această cheie și acestea sunt mai noi decât staleTime, valoarea din cache este returnată imediat, fără apelarea funcției.
Modificare
bs.mutate() gestionează operațiunile de scriere cu actualizări optimiste și revenire automată la starea anterioară în caz de eșec. Are două moduri: modul automat pentru tipare CRUD obișnuite și modul manual pentru control complet.
Modul automat funcționează cu un obiect de stare reactivă (precum Alpine.js $data). Transmiteți state, key, action și, opțional, 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),
});
La succes, datele optimiste sunt înlocuite cu răspunsul serverului. La eșec, starea revine la o copie instantanee realizată înaintea modificării. Cheia din cache este invalidată automat după fiecare modificare reușită.
Un eșec înseamnă că promisiunea returnată de fn este respinsă. bs.db() și bs.fn() se rezolvă cu corpul erorii în cazul unei erori de validare, al lipsei unei înregistrări sau al unui eșec la verificarea permisiunilor. Așadar, aruncați o eroare când rezultatul conține code dacă doriți ca și aceste situații să declanșeze revenirea la starea anterioară:
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)),
});
Pentru operațiunile de creare, elementului optimist i se atribuie un id temporar (precum __temp_1). Când răspunde serverul, elementul temporar este actualizat cu datele reale, inclusiv cu id atribuit de server.
Modul manual vă oferă control complet prin callbackurile before, onSuccess și 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țiune | Tip | Mod | Descriere |
|---|---|---|---|
fn |
function |
Ambele | Funcția async care efectuează modificarea. Obligatorie. |
state |
object |
Automat | Obiect de stare reactivă (e.g., Alpine $data). |
key |
string |
Automat | Numele proprietății din stare care conține tabloul. Folosită și ca cheie de cache. |
action |
string |
Automat | Una dintre valorile create, update sau delete. |
id |
any |
Automat | ID-ul înregistrării pentru acțiunile update și delete. |
optimistic |
object |
Automat | Datele aplicate optimist înainte de răspunsul serverului. |
before |
function |
Manual | Apelată înainte de fn. Valoarea returnată este transmisă către onSuccess/onError ca snapshot. |
onSuccess |
function |
Manual | Apelată cu (result, snapshot) la succes. |
onError |
function |
Manual | Apelată cu (error, snapshot) la eșec. |
invalidate |
string |
Manual | Cheia de cache care trebuie invalidată la succes. |
PHP API
Clasa Db oferă aceleași operațiuni pe server. Folosiți-o în rpc.php, cron.php, șabloane sau orice cod 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);
Pentru blocuri cu o singură schemă:
$db = Db::get('my-theme/block');
Interogare periodică în timp real
Adăugați realtime în schema dvs. pentru a activa interogarea periodică automată. Când datele se modifică pe server, UI se actualizează automat prin magazinul Interactivity API. Nu sunt necesare modificări ale JavaScript.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Cu true, Blockstudio interoghează la fiecare 3 secunde, folosind numele schemei drept cheie de stare în magazinul Interactivity API (default pentru blocurile cu o singură schemă).
Configurare personalizată
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Opțiune | Tip | Valoare implicită | Descriere |
|---|---|---|---|
key |
string |
numele schemei | Numele proprietății din state care conține tabloul de date |
interval |
number |
3000 |
Intervalul interogărilor periodice, în milisecunde |
Cum funcționează
- La încărcarea paginii, clientul preia o sumă de control compactă a datelor curente
- La fiecare
intervalmilisecunde, preia din nou suma de control - Dacă suma de control s-a schimbat, preia întregul set de date
- Noile date sunt trimise în magazinul Interactivity API prin
store() - Directivele asociate acelei proprietăți de stare redau automat conținutul
Interogarea periodică rulează numai pe paginile care conțin un element data-wp-interactive corespunzător. Se suspendă când fila browserului este ascunsă și se reia când devine vizibilă.
Endpointul pentru suma de control (?_hash=1) returnează doar o sumă de control md5 și numărul de înregistrări, menținând solicitările periodice compacte.
Date asociate utilizatorului
Setați userScoped: true pentru a asocia automat toate înregistrările cu utilizatorul curent. Blockstudio adaugă o coloană user_id, o setează la creare și filtrează toate operațiunile astfel încât să includă numai înregistrările utilizatorului curent:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Fără câmpul manual user_id, fără hook-ul before_create și fără filtrare în RPC. Utilizatorii pot vedea, modifica și șterge numai propriile înregistrări. Coloana user_id este gestionată în întregime de Blockstudio.
Când folosiți stocarea post_type, userScoped este asociat cu post_author în locul unei coloane user_id separate.
Controlul accesului
Fiecare operațiune CRUD are propriul nivel de permisiune:
| Valoare | Comportament |
|---|---|
true |
Publică, cu protecție CSRF (utilizatorii deconectați sunt acceptați; este necesar X-BS-Token) |
'open' |
Complet publică, fără CSRF și fără autentificare (pentru webhookuri și API-uri externe) |
'edit_posts' |
Verificarea capabilității WordPress |
['cap_a', 'cap_b'] |
Utilizatorul trebuie să aibă cel puțin una dintre capabilitățile enumerate |
omis / null |
Necesită autentificare (utilizator conectat) |
'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
],
Protecție CSRF
Punctele finale publice (true) sunt protejate printr-un antet X-BS-Token. bs.db() și bs.fn() obțin acreditări noi de la un punct final de aceeași origine, necache-uit, în loc să includă tokenuri cu expirare în HTML paginii. Paginile servite din cache-uri externe cu durată lungă continuă să funcționeze. Apelurile anonime fără un token valid primesc un răspuns 403.
Acreditările sunt solicitate la primul apel API, nu la fiecare vizualizare a paginii. Ambii clienți, inclusiv interogarea periodică în timp real a bazei de date, folosesc împreună aceeași reîmprospătare a acreditărilor aflată în curs. Acreditările sunt reîmprospătate după cinci minute de utilizare. Un nonce WordPress sau un token CSRF Blockstudio respins declanșează o reîmprospătare și o reîncercare; erorile obișnuite de permisiune nu sunt reîncercate. Solicitările utilizatorilor autentificați folosesc în continuare sesiunea utilizatorului care vizitează site-ul și verificările de capabilități și de proprietate asupra înregistrărilor definite de schemă.
Păstrați POST /wp-json/blockstudio/v1/client/credentials în afara oricărui cache de proxy sau CDN. Acesta trimite Cache-Control: private, no-store și necesită o solicitare de aceeași origine cu un antet non-simplu. Clienții integrați gestionează automat acest lucru.
Folosiți 'open' când aveți nevoie de acces complet neautentificat, fără CSRF, de exemplu pentru webhookuri primite de la servicii externe.
Tipuri de câmpuri
| Tip | Coloană MySQL | Tip PHP | Descriere |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Text, maxLength implicit 255 |
integer |
bigint(20) |
int |
Numere întregi |
number |
decimal(20,6) |
float |
Numere zecimale |
boolean |
tinyint(1) |
bool |
Adevărat/fals |
text |
longtext |
string |
Conținut textual amplu |
Validare
Toate scrierile (creare și actualizare) sunt validate conform schemei înainte de a modifica stocarea. Validarea are loc pe server, indiferent dacă solicitarea provine din bs.db(), din REST API sau din Db::get().
Reguli integrate
| Regulă | Exemplu | Descriere |
|---|---|---|
required |
'required' => true |
Câmpul trebuie să fie prezent la creare |
type |
'type' => 'integer' |
Valoarea trebuie să corespundă tipului declarat |
enum |
'enum' => ['a', 'b'] |
Valoarea trebuie să fie una dintre opțiunile enumerate |
maxLength |
'maxLength' => 100 |
Șirul nu poate depăși această lungime |
minLength |
'minLength' => 3 |
Șirul trebuie să aibă cel puțin această lungime |
format: "email" |
'format' => 'email' |
Trebuie să fie o adresă de e-mail validă |
format: "url" |
'format' => 'url' |
Trebuie să fie un URL valid |
Validare personalizată
Adăugați un callback validate oricărui câmp pentru verificări pe server care depășesc regulile integrate. Returnați true pentru validare sau un șir cu mesajul de eroare:
'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;
},
],
Callbackul primește valoarea câmpului și întregul tablou de date, astfel încât puteți efectua validări între câmpuri.
Formatul răspunsului de eroare
Erorile de validare returnează un statut 400 cu tablouri de erori pentru fiecare câmp. Formatul este inspirat de ZodfieldErrors și facilitează asocierea erorilor cu câmpurile formularului:
{
"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."]
}
}
}
Fiecare câmp corespunde unui tablou de șiruri de eroare. Mai multe reguli pot eșua pentru același câmp. În partea frontală:
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]);
});
}
Endpointuri REST
Toate endpointurile se află în spațiul de nume blockstudio/v1/db/:
/db/{block-name}/{schema-name}
În numele blocului, / este înlocuit cu -. Pentru blocurile cu o singură schemă, numele schemei este default.
| Metodă | Endpoint | Descriere |
|---|---|---|
GET |
/db/{block}/{schema} |
Listează înregistrările |
POST |
/db/{block}/{schema} |
Creează o înregistrare |
GET |
/db/{block}/{schema}/{id} |
Obține o singură înregistrare |
PUT |
/db/{block}/{schema}/{id} |
Actualizează o înregistrare |
DELETE |
/db/{block}/{schema}/{id} |
Șterge o înregistrare |
Parametri de interogare (listă)
| Parametru | Descriere |
|---|---|
limit |
Numărul maxim de înregistrări returnate (implicit 50, maxim 100) |
offset |
Numărul de înregistrări de omis |
| Orice nume de câmp | Filtrare după potrivirea exactă a valorii |
Exemplu: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Randarea formularelor
Câmpurile pot defini o cheie component care face referire la un bloc Blockstudio. Apelați bs_db_form() în șablon pentru a reda toate câmpurile ca formular folosind blocurile lor 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>
Fiecare componentă primește definiția completă a câmpului ca field în atributele sale,
așa că componentele își pot adapta randarea în funcție de schemă. De exemplu,
$a['field']['name'] oferă numele câmpului, $a['field']['type'] tipul,
$a['field']['required'] dacă este obligatoriu etc.
Structura componentelor urmează același format name, attributes, innerBlocks
ca blocurile WordPress. Blocurile interioare sunt randate primele și transmise
părintelui ca $content.
Pentru utilizarea PHP fără afișare:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hook-uri
Acțiunile sunt declanșate înainte și după fiecare operațiune de scriere. Toate hook-urile primesc un singur
array $params. Consultați referința PHP Hook-uri
pentru lista completă.
Hook-uri inline
Definiți hook-uri direct în db.php. Acestea sunt asociate automat cu schema,
așa că nu trebuie să verificați numele blocului/schemei:
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-uri globale
Ascultați toate schemele, de oriunde:
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
}
});
Combinarea cu RPC
db.php și rpc.php sunt sisteme independente. db.php generează endpoint-uri CRUD
pe baza unei definiții de schemă. rpc.php definește funcții personalizate pe server.
Fiecare poate funcționa independent.
Folosiți-le împreună când aveți nevoie de operațiuni standard asupra datelor și de logică de business personalizată:
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',
],
];
Portabilitate
Cu stocarea JSONC, datele sunt păstrate alături de cod. Copiați folderul blocului pe alt site și totul se mută împreună: UI, logica, controlul accesului și datele propriu-zise.
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
Fără migrări de baze de date, fără pași de export/import. Doar copiați folderul.
Și stocarea Storh este portabilă, dar se află în uploads/blockstudio/db/,
în locul folderului blocului. Astfel, datele active, inscriptibile, rămân în afara arborelui
sursă, iar fiecare schemă are în continuare o stocare în fișiere obișnuite, care poate fi salvată,
copiată sau migrată independent.
Filtrare
Modificați schemele programatic din afara blocului:
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;
});