Preskočiť na obsah

Databáza

Databázová vrstva umožňuje definovať dátový model bloku v súbore db.php. Blockstudio generuje koncové body CRUD REST, overuje vstup podľa schémy, automaticky spravuje úložisko a poskytuje klienta JavaScript (bs.db()) aj PHP API (triedu Db).

Toto je dátová základňa blokov s plným zásobníkom. Kým RPC rieši vlastnú logiku, databázová vrstva spracúva štruktúrované dáta bez zbytočného pomocného kódu.

Ako to funguje

  1. Vytvoríte db.php v priečinku bloku
  2. Vráti schému: polia, typy, pravidlá validácie a riadenie prístupu
  3. Blockstudio vytvorí úložisko (tabuľku, súbor alebo metaúdaje príspevku)
  4. Automaticky sa vygeneruje päť koncových bodov REST (zoznam, získanie, vytvorenie, aktualizácia, odstránenie)
  5. bs.db() a Db::get() poskytujú prístup z klienta a servera

Žiadne migrácie, žiadne kontroléry, žiadna registrácia trás.

Do rozhraní API REST a PHP odovzdávajte doslovné hodnoty. Backendy meta a post_type sa interne postarajú o escapovanie lomiek v metadátach WordPress, pričom zachovajú spätné lomky aj reťazce v úvodzovkách v skalárnych hodnotách aj vnorených objektoch či poliach. Hodnoty databázových záznamov vopred neescapujte.

Definovanie schém

Jedna schéma

Najjednoduchšia forma: jeden dátový model na blok.

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

Syntax tvorcu natívna pre PHP

db.php môže používať aj malý tvorca API založený na pomenovaných argumentoch a objektoch definície iba na čítanie. Predvoleným formátom zostávajú polia, no táto možnosť ponúka prehľadnejšiu alternatívu natívnu pre PHP, keď sa schéma začne zväčšovať.

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

Pre jednu schému použite Schema::make() alebo pre bloky s viacerými schémami vráťte pole pomenovaných volaní Schema::make(...).

Viaceré schémy

Jeden blok môže spravovať viacero dátových modelov. Vráťte pomenované pole:

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

Každá schéma má vlastné koncové body, úložisko a riadenie prístupu.

Režimy úložiska

Šesť úložísk, každé vhodné na iné použitie.

Vlastná tabuľka (storage: "table")

Každý záznam je riadkom vo vyhradenej tabuľke MySQL. Blockstudio vytvára a spravuje tabuľku automaticky pomocou funkcie dbDelta() v WordPress. Pridaním nových polí do schémy sa pri ďalšom načítaní stránky pridajú stĺpce. Existujúce stĺpce sa nikdy neodstránia.

Vhodné na: štruktúrované dáta, dopyty a produkčné aplikácie.

SQLite (storage: "sqlite")

Každá schéma má vlastný databázový súbor SQLite v podpriečinku db/. Blockstudio automaticky vytvorí súbor a tabuľku a pri zmene schémy doplní chýbajúce stĺpce (podobne ako dbDelta pre MySQL). Používa režim žurnálu WAL na zvýšenie výkonu súbežného čítania.

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

Vhodné na: štruktúrované dáta, ktoré vyžadujú skutočné dopyty SQL, no majú zostať prenosné. Efektívne spracúva tisíce záznamov bez načítania všetkých do pamäte. Na presun dát stačí skopírovať priečinok.

Súbory JSONC (storage: "jsonc")

Záznamy sa ukladajú ako jeden objekt JSON na riadok v súbore .jsonc v podpriečinku db/. Súbor sa vytvorí automaticky pri prvom zápise. Riadky začínajúce sa na // sa považujú za komentáre a zachovajú sa.

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

Vhodné na: malé súbory dát, konfiguračné dáta, počiatočné záznamy a príklady vhodné na správu verzií. JSONC je zámerne jediným súborom v priečinku bloku. Použite ho, ak chcete mať dáta spolu s kódom, nie ak očakávate veľa súbežných zápisov.

Súbory Storh (storage: "storh")

Storh ukladá každý záznam ako samostatný súbor v priečinku nahratých súborov WordPress:

Kód
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

Verejné ID záznamov zostávajú rovnakými celočíselnými ID, aké používa zvyšok bs.db(). Blockstudio mapuje tieto ID na interné ID súborov UUIDv7 v Storh a ukladá celé číslo id do dát záznamu, takže volajúci JavaScript, REST a PHP nemusia pracovať s UUID.

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

Blockstudio vytvára indexy Storh podľa vašej schémy. Keďže každé deklarované pole možno použiť ako filter zoznamu, indexuje sa každé takéto pole. Polia typu celé číslo, číslo a dátum používajú rozsahové indexy; polia označené ako 'unique' => true alebo 'index' => 'unique' používajú jedinečné indexy.

Vhodné na: produkčné dáta ukladané do súborov, ktoré vyžadujú bezpečnejšie súbežné zápisy, indexy odvodené zo schémy a prenosné úložisko na úrovni nahratých súborov bez ukladania živých záznamov do zdrojového stromu bloku.

Migrácia z JSONC na Storh

Ak ste začali so súborom .jsonc a chcete mať rovnaké záznamy v Storh, spustite:

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

Pre bloky s jednou schémou:

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

Migrácia načíta existujúce db/{schema}.jsonc, zapíše záznamy do Storh so zachovaním celočíselných ID, obnoví indexy, overí cieľové úložisko a ponechá súbor JSONC nedotknutý. Návrat späť spočíva iba v zmene storage schémy na "jsonc".

Metaúdaje príspevku (storage: "meta")

Záznamy sa ukladajú ako pole JSON v metaúdajoch príspevku WordPress a pomocou postId sa priraďujú ku konkrétnemu príspevku.

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

Vhodné na: dáta priradené ku konkrétnemu príspevku alebo stránke.

Vlastný typ príspevku (storage: "post_type")

Každý záznam je príspevkom WordPress vo vlastnom type príspevku, ktorý sa registruje automaticky. Každé pole v schéme sa stane samostatnou položkou post_meta. Vďaka tomu možno záznamy vyhľadávať pomocou WP_Query, sú kompatibilné s doplnkami REST API a viditeľné v nástrojoch, ako je GraphQL.

Vhodné na: dáta, ktoré sa majú natívne integrovať s WordPress. Každé pole možno samostatne vyhľadávať a indexovať.

Klient JavaScript

Blockstudio vkladá bs.db() na stránky s databázovými blokmi. Vráti objekt s piatimi metódami:

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

Prvým argumentom je názov bloku (s /), druhým názov schémy. Pri blokoch s jednou schémou názov schémy možno vynechať (predvolená hodnota je "default").

Vyrovnávacia pamäť

bs.cache je vyrovnávacia pamäť dopytov v pamäti zdieľaná medzi všetkými volaniami bs.query a bs.mutate. Môžete ju použiť aj priamo:

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

Položky vyrovnávacej pamäte sa ukladajú do pamäte a pri prechode na inú stránku sa vymažú. Používajú ich najmä interne bs.query a bs.mutate, no priamy prístup sa hodí na predbežné naplnenie dát alebo manuálne zneplatnenie po vlastných operáciách.

Dopyt

bs.query() obalí ľubovoľnú asynchrónnu funkciu a pridá ukladanie do vyrovnávacej pamäte, deduplikáciu a riadenie zastaranosti. Viaceré volania s rovnakým kľúčom počas prebiehajúcej požiadavky vrátia rovnaký prísľub (bez duplicitných načítaní).

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

Prvým argumentom je kľúč vyrovnávacej pamäte (ľubovoľný reťazec). Druhým je funkcia vracajúca prísľub. Tretím je voliteľný objekt možností:

Možnosť Typ Opis
staleTime number Počet milisekúnd, po ktorom sa údaje vo vyrovnávacej pamäti považujú za zastarané. 0 (predvolené) vždy načíta údaje znova.

Ak vyrovnávacia pamäť obsahuje dáta pre daný kľúč a sú mladšie než staleTime, uložená hodnota sa vráti okamžite bez volania funkcie.

Zmena dát

bs.mutate() spracúva operácie zápisu pomocou optimistických aktualizácií a pri zlyhaní automatického návratu zmien. Podporuje dva režimy: automatický režim pre bežné vzory CRUD a manuálny režim na úplnú kontrolu.

Automatický režim pracuje s reaktívnym stavovým objektom (napríklad Alpine.js $data). Zadajte state, key, action a prípadne aj 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),
});

Pri úspechu sa optimistické dáta nahradia odpoveďou servera. Pri zlyhaní sa stav vráti na snímku vytvorenú pred zmenou. Kľúč vyrovnávacej pamäte sa automaticky zneplatní po každej úspešnej zmene.

Za zlyhanie sa považuje zamietnutie prísľubu vráteného funkciou fn. Funkcie bs.db() a bs.fn() pri chybe validácie, chýbajúcom zázname alebo neúspešnej kontrole oprávnení vrátia telo chyby ako splnený prísľub. Ak sa majú zmeny vrátiť aj v týchto prípadoch, pri výsledku obsahujúcom code vyvolajte výnimku:

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

Pri vytváraní sa optimistickej položke priradí dočasné id (napríklad __temp_1). Po odpovedi servera sa dočasná položka aktualizuje skutočnými dátami vrátane ID id prideleného serverom.

Manuálny režim vám poskytuje úplnú kontrolu pomocou funkcií spätného volania before, onSuccess a 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;
  },
});
Možnosť Typ Režim Opis
fn function Oba Asynchrónna funkcia vykonávajúca zmenu. Povinné.
state object Automatický Reaktívny stavový objekt (e.g., Alpine $data).
key string Automatický Názov vlastnosti stavu, v ktorej je uložené pole. Používa sa aj ako kľúč vyrovnávacej pamäte.
action string Automatický Jedna z možností create, update alebo delete.
id any Automatický ID záznamu pre akcie update a delete.
optimistic object Automatický Dáta, ktoré sa optimisticky použijú pred odpoveďou servera.
before function Manuálny Volá sa pred fn. Návratová hodnota sa odovzdá do onSuccess/onError ako snapshot.
onSuccess function Manuálny Volá sa s (result, snapshot) pri úspechu.
onError function Manuálny Volá sa s (error, snapshot) pri zlyhaní.
invalidate string Manuálny Kľúč vyrovnávacej pamäte, ktorý sa pri úspechu zneplatní.

PHP API

Trieda Db poskytuje rovnaké operácie na strane servera. Použite ju v rpc.php, cron.php, šablónach alebo ľubovoľnom kóde 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);

Pre bloky s jednou schémou:

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

Priebežné zisťovanie zmien

Pridajte do schémy realtime, aby sa zaplo automatické pravidelné načítavanie. Keď sa dáta na serveri zmenia, UI sa automaticky aktualizuje prostredníctvom úložiska Interactivity API. Zmeny v JavaScript nie sú potrebné.

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

Pri použití true kontroluje Blockstudio zmeny každé 3 sekundy a ako stavový kľúč Interactivity API používa názov schémy (pri blokoch s jednou schémou sa použije default).

Vlastné nastavenia

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Možnosť Typ Predvolená hodnota Opis
key string názov schémy Názov vlastnosti v state, ktorá obsahuje pole dát
interval number 3000 Interval načítavania v milisekundách

Ako to funguje

  1. Pri načítaní stránky klient načíta stručný hash aktuálnych dát
  2. Každých interval milisekúnd načíta hash znova
  3. Ak sa hash zmenil, načíta celý súbor dát
  4. Nové dáta sa odošlú do úložiska Interactivity API cez store()
  5. Všetky direktívy naviazané na túto stavovú vlastnosť sa automaticky vykreslia znova

Pravidelné načítavanie prebieha iba na stránkach, na ktorých existuje zodpovedajúci prvok data-wp-interactive. Pozastaví sa, keď je karta prehliadača skrytá, a obnoví sa, keď sa znova zobrazí.

Koncový bod hash ?_hash=1 vracia iba kontrolný súčet md5 a počet záznamov, takže požiadavky na kontrolu zmien zostávajú nenáročné.

Dáta viazané na používateľa

Nastavením userScoped: true sa všetky záznamy automaticky obmedzia na aktuálneho používateľa. Blockstudio pridá stĺpec user_id, nastaví ho pri vytvorení a obmedzí všetky operácie na záznamy aktuálneho používateľa:

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

Netreba manuálne pole user_id, hák before_create ani filtrovanie v RPC. Používatelia môžu zobrazovať, upravovať a odstraňovať iba vlastné záznamy. Stĺpec user_id spravuje výhradne Blockstudio.

Pri použití úložiska post_type sa userScoped mapuje na post_author namiesto samostatného stĺpca user_id.

Riadenie prístupu

Každá operácia CRUD má vlastnú úroveň oprávnení:

Hodnota Správanie
true Verejný prístup s ochranou CSRF (odhlásení používatelia majú prístup, vyžaduje sa X-BS-Token)
'open' Úplne verejný prístup, bez CSRF a overenia (pre webhooky a externé API)
'edit_posts' Kontrola oprávnenia WordPress
['cap_a', 'cap_b'] Používateľ potrebuje aspoň jedno z uvedených oprávnení
vynechané / null Vyžaduje overenie (prihlásený používateľ)
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
],

Ochrana CSRF

Verejné koncové body (true) sú chránené hlavičkou X-BS-Token. bs.db() a bs.fn() získavajú čerstvé prihlasovacie údaje z necachovaného koncového bodu na rovnakej doméne, namiesto vkladania tokenov s obmedzenou platnosťou do HTML stránky. Stránky poskytované z externých vyrovnávacích pamätí s dlhou životnosťou naďalej fungujú. Anonymné volania bez platného tokenu dostanú odpoveď 403.

Prihlasovacie údaje sa vyžiadajú pri prvom volaní API, nie pri každom zobrazení stránky. Oba klienty vrátane priebežného zisťovania zmien v databáze zdieľajú jedno prebiehajúce obnovenie prihlasovacích údajov. Obnovenie sa vykoná po piatich minútach používania. Pri odmietnutom nonce WordPress alebo CSRF tokene Blockstudio sa prihlasovacie údaje raz obnovia a požiadavka sa zopakuje; bežné chyby oprávnení sa neopakujú. Prihlásené požiadavky naďalej používajú reláciu aktuálneho používateľa a kontroly oprávnení a vlastníctva záznamu podľa schémy.

POST /wp-json/blockstudio/v1/client/credentials ponechajte mimo každej proxy alebo vyrovnávacej pamäte CDN. Odosiela Cache-Control: private, no-store a vyžaduje požiadavku z rovnakej domény s nejednoduchou hlavičkou. Vstavaní klienti to vybavia automaticky.

Použite 'open', keď potrebujete úplne neoverený prístup bez CSRF, napríklad pre prichádzajúce webhooky z externých služieb.

Typy polí

Typ Stĺpec MySQL Typ PHP Opis
string varchar(maxLength) string Text, predvolené maxLength 255
integer bigint(20) int Celé čísla
number decimal(20,6) float Desatinné čísla
boolean tinyint(1) bool Pravda/nepravda
text longtext string Dlhší textový obsah

Validácia

Všetky zápisy (vytvorenie a aktualizácia) sa pred prístupom k úložisku overujú podľa schémy. Validácia prebieha na strane servera bez ohľadu na to, či požiadavka prichádza z bs.db(), z REST API alebo z Db::get().

Vstavané pravidlá

Pravidlo Príklad Opis
required 'required' => true Pole musí byť uvedené pri vytvorení
type 'type' => 'integer' Hodnota musí zodpovedať deklarovanému typu
enum 'enum' => ['a', 'b'] Hodnota musí byť jednou z uvedených možností
maxLength 'maxLength' => 100 Dĺžka reťazca nesmie prekročiť túto hodnotu
minLength 'minLength' => 3 Reťazec musí mať aspoň túto dĺžku
format: "email" 'format' => 'email' Musí ísť o platnú e-mailovú adresu
format: "url" 'format' => 'url' Musí ísť o platný URL

Vlastná validácia

Pridajte ku ktorémukoľvek poľu funkciu spätného volania validate na kontroly na strane servera, ktoré presahujú vstavané pravidlá. Na úspešné overenie vráťte true alebo reťazec s chybovou správou:

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

Funkcia spätného volania dostáva hodnotu poľa aj celé pole dát, takže môžete overovať vzťahy medzi poľami.

Formát odpovede s chybami

Chyby validácie vracajú stav 400 a polia chýb pre jednotlivé polia. Tento formát vychádza z Zod, konkrétne z fieldErrors, a uľahčuje priradenie chýb k poliam formulára:

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

Ku každému poľu patrí pole chybových reťazcov. Pri rovnakom poli môže zlyhať viacero pravidiel. Vo frontendovej časti:

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

Koncové body REST

Všetky koncové body patria do priestoru názvov blockstudio/v1/db/:

Kód
/db/{block-name}/{schema-name}

Názov bloku má / nahradené za -. Pri blokoch s jednou schémou je názov schémy default.

Metóda Koncový bod Opis
GET /db/{block}/{schema} Zoznam záznamov
POST /db/{block}/{schema} Vytvorenie záznamu
GET /db/{block}/{schema}/{id} Získanie jedného záznamu
PUT /db/{block}/{schema}/{id} Aktualizácia záznamu
DELETE /db/{block}/{schema}/{id} Odstránenie záznamu

Parametre dopytu (zoznam)

Parameter Opis
limit Maximálny počet vracaných záznamov (predvolene 50, maximum 100)
offset Počet záznamov, ktoré sa majú preskočiť
Názov ľubovoľného poľa Filtrovanie podľa presnej zhody hodnoty

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

Vykresľovanie formulárov

Polia môžu definovať kľúč component, ktorý odkazuje na blok Blockstudio. Zavolajte bs_db_form() vo svojej šablóne a vykreslite všetky polia ako formulár pomocou ich komponentových blokov.

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>

Každý komponent dostáva v atribútoch úplnú definíciu poľa ako field, takže môže prispôsobiť vykresľovanie podľa schémy. Napríklad $a['field']['name'] poskytuje názov poľa, $a['field']['type'] jeho typ, $a['field']['required'] informáciu, či je povinné, a podobne.

Štruktúra komponentov používa rovnaký formát name, attributes, innerBlocks ako bloky WordPress. Vnorené bloky sa vykreslia ako prvé a rodičovi sa odovzdajú ako $content.

Pre použitie PHP bez výpisu:

PHP
use Blockstudio\Db;

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

Háčiky

Akcie sa spúšťajú pred každou operáciou zápisu aj po nej. Všetky háčiky dostávajú jedno pole $params. Úplný zoznam nájdete v referencii PHP háčikov.

Vložené háčiky

Definujte háčiky priamo v db.php. Automaticky sa obmedzia na danú schému, takže nemusíte kontrolovať názov bloku ani schémy:

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

Globálne háčiky

Počúvajte naprieč všetkými schémami odkiaľkoľvek:

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

Kombinácia s RPC

db.php a rpc.php sú nezávislé systémy. db.php generuje koncové body CRUD z definície schémy. rpc.php definuje vlastné funkcie servera. Každý z nich funguje samostatne.

Použite ich spolu, keď potrebujete štandardné operácie s dátami aj vlastnú obchodnú logiku:

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

Prenositeľnosť

Pri úložisku JSONC sa dáta nachádzajú spolu s kódom. Skopírujte priečinok bloku na inú stránku a všetko sa presunie spolu s ním: UI, logika, riadenie prístupu a samotné dáta.

Kód
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

Žiadne migrácie databázy ani kroky exportu a importu. Stačí skopírovať priečinok.

Aj úložisko Storh je prenositeľné, ale nachádza sa v priečinku uploads/blockstudio/db/, namiesto priečinka bloku. Vďaka tomu zostávajú živé, zapisovateľné dáta mimo zdrojového stromu, pričom každá schéma má úložisko v obyčajných súboroch, ktoré možno zálohovať, skopírovať alebo migrovať samostatne.

Filter

Programovo upravujte schémy zvonka bloku:

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