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
- Vytvoríte
db.phpv priečinku bloku - Vráti schému: polia, typy, pravidlá validácie a riadenie prístupu
- Blockstudio vytvorí úložisko (tabuľku, súbor alebo metaúdaje príspevku)
- Automaticky sa vygeneruje päť koncových bodov REST (zoznam, získanie, vytvorenie, aktualizácia, odstránenie)
bs.db()aDb::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.
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
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:
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.
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.
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:
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.
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:
wp bs db migrate my-theme/app subscribers --to=storh
Pre bloky s jednou schémou:
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.
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:
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:
// 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í).
// 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:
// 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:
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:
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.
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:
$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é.
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
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
- Pri načítaní stránky klient načíta stručný hash aktuálnych dát
- Každých
intervalmilisekúnd načíta hash znova - Ak sa hash zmenil, načíta celý súbor dát
- Nové dáta sa odošlú do úložiska Interactivity API cez
store() - 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:
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ľ) |
'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:
'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:
{
"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:
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/:
/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.
'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>
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:
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:
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:
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:
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.
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:
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;
});