Treci la conținut

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ă

  1. Creați db.php în directorul blocului
  2. Acesta returnează o schemă: câmpuri, tipuri, reguli de validare, controlul accesului
  3. Blockstudio creează stocarea (tabel, fișier sau metadate de articol)
  4. Cinci endpointuri REST sunt generate automat (listare, obținere, creare, actualizare, ștergere)
  5. bs.db() și Db::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.

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

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

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

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.

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

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

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

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

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

Pentru blocuri cu o singură schemă:

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

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

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

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:

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

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

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

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:

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

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

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

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:

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

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

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

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

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

  1. La încărcarea paginii, clientul preia o sumă de control compactă a datelor curente
  2. La fiecare interval milisecunde, preia din nou suma de control
  3. Dacă suma de control s-a schimbat, preia întregul set de date
  4. Noile date sunt trimise în magazinul Interactivity API prin store()
  5. 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:

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

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:

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

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:

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

Fiecare câmp corespunde unui tablou de șiruri de eroare. Mai multe reguli pot eșua pentru același câmp. În partea frontală:

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

Endpointuri REST

Toate endpointurile se află în spațiul de nume blockstudio/v1/db/:

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

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>

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:

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

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-uri globale

Ascultați toate schemele, de oriunde:

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

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

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

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.

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

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