Databáze
Databázová vrstva umožňuje definovat datový model bloku v souboru db.php.
Blockstudio generuje REST CRUD endpointy, ověřuje vstupy podle schématu,
automaticky spravuje úložiště a poskytuje klienta JavaScript
(bs.db()) i PHP API (třídu Db).
Tohle je datová páteř bloků s plným zásobníkem. Zatímco RPC zajišťuje vlastní logiku, databázová vrstva se stará o strukturovaná data bez zbytečného boilerplate kódu.
Jak to funguje
- V adresáři bloku vytvoříte
db.php - Vrátí schéma: pole, typy, pravidla validace a řízení přístupu
- Blockstudio vytvoří úložiště (tabulku, soubor nebo metadata příspěvku)
- Automaticky se vygeneruje pět endpointů REST (seznam, načtení, vytvoření, aktualizace, smazání)
bs.db()aDb::get()poskytují přístup z klienta a serveru
Žádné migrace, controllery ani registrace tras.
Předávejte doslovné hodnoty do API REST a PHP. Backendy meta a post_type zpracují ošetření zpětných lomítek v metadatech WordPress interně, takže zachovají zpětná lomítka i řetězce v uvozovkách ve skalárních hodnotách i vnořených objektech nebo polích. Hodnoty záznamů databáze předem neošetřujte zpětnými lomítky.
Definování schémat
Jedno schéma
Nejjednodušší varianta: jeden datový 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'],
],
];
Syntaxe builderu nativní pro PHP
db.php může používat také jednoduchou syntaxi builderu API založenou na pojmenovaných argumentech a objektech s definicemi pouze pro čtení. Pole zůstávají výchozím formátem, tato možnost nativní pro PHP ale usnadňuje orientaci, když se schéma začne rozrůstat.
<?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'),
],
);
Pro jedno schéma použijte Schema::make(), u bloků s více schématy vraťte pole pojmenovaných volání Schema::make(...).
Více schémat
Jeden blok může obsahovat více datových modelů. Vraťte pojmenované 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í endpointy, úložiště a řízení přístupu.
Režimy úložiště
Šest backendů úložiště, každý vhodný pro jiné použití.
Vlastní tabulka (storage: "table")
Každý záznam je řádkem ve vyhrazené tabulce MySQL. Blockstudio tabulku automaticky vytváří a spravuje pomocí funkce dbDelta() od WordPress. Přidáním nových polí do schématu se při příštím načtení stránky přidají sloupce. Existující sloupce se nikdy neodstraní.
Vhodné pro: strukturovaná data, dotazy a produkční aplikace.
SQLite (storage: "sqlite")
Každé schéma dostane vlastní databázový soubor SQLite v podsložce db/. Blockstudio soubor a tabulku automaticky vytvoří a při změně schématu doplní chybějící sloupce (podobně jako dbDelta pro MySQL). Pro souběžné čtení používá režim žurnálu WAL.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Vhodné pro: strukturovaná data, která vyžadují skutečné dotazy SQL, ale měla by zůstat přenositelná. Efektivně zpracovává tisíce záznamů, aniž by vše načítala do paměti. Data přesunete zkopírováním složky.
Soubory JSONC (storage: "jsonc")
Záznamy se ukládají jako samostatné objekty JSON, jeden na řádek v souboru .jsonc v podsložce db/. Soubor se automaticky vytvoří při prvním zápisu. Řádky začínající na // se považují za komentáře a zachovají se.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Vhodné pro: malé datové sady, konfigurační data, počáteční záznamy a příklady, které lze spravovat ve verzovacím systému. JSONC je záměrně jediný soubor v adresáři bloku. Použijte ho, když chcete, aby data putovala spolu s kódem, ne když očekáváte mnoho souběžných zápisů.
Soubory Storh (storage: "storh")
Storh ukládá každý záznam jako samostatný soubor v nahraných souborech 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
Veřejná ID záznamů zůstávají stejnými celočíselnými ID, která používá zbytek bs.db().
Blockstudio mapuje tato ID na interní ID souborů UUIDv7 v Storh a ukládá celé číslo id do dat záznamu, takže volající JavaScript, REST a PHP nemusejí pracovat s UUID.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio vytváří indexy Storh podle vašeho schématu. Protože každé deklarované pole lze použít jako filtr seznamu, indexují se všechna deklarovaná pole. Pole typu celé číslo, číslo a datum používají rozsahové indexy; pole označená 'unique' => true nebo 'index' => 'unique' používají jedinečné indexy.
Vhodné pro: produkční data uložená v souborech, která vyžadují bezpečnější souběžné zápisy, indexy odvozené ze schématu a přenositelné úložiště na úrovni nahraných souborů, aniž by se živé záznamy ukládaly do zdrojového stromu bloku.
Migrace JSONC na Storh
Pokud jste začali se souborem .jsonc a chcete stejné záznamy v Storh, spusťte:
wp bs db migrate my-theme/app subscribers --to=storh
U bloků s jediným schématem:
wp bs db migrate my-theme/app --to=storh
Migrace přečte existující db/{schema}.jsonc a zapíše záznamy do Storh se zachováním celočíselných ID, znovu vytvoří indexy, ověří cílové úložiště a ponechá soubor JSONC beze změny. Vrácení změny spočívá v přepnutí storage schématu zpět na "jsonc".
Metadata příspěvku (storage: "meta")
Záznamy se ukládají jako pole JSON v metadatech příspěvku WordPress a jsou propojené s konkrétním příspěvkem přes postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Vhodné pro: data patřící ke konkrétnímu příspěvku nebo stránce.
Vlastní typ příspěvku (storage: "post_type")
Každý záznam je příspěvkem WordPress v automaticky registrovaném vlastním typu příspěvku. Každé pole ve schématu se stane samostatnou položkou post_meta. Záznamy tak lze dotazovat pomocí WP_Query, jsou kompatibilní s pluginy REST API a zobrazují se v nástrojích, jako je GraphQL.
Vhodné pro: data, která se mají nativně integrovat s WordPress. Každé pole lze samostatně dotazovat a indexovat.
Klient JavaScript
Blockstudio vkládá na stránky s databázovými bloky bs.db(). Vrací objekt s pěti metodami:
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);
Prvním argumentem je název bloku (s /), druhým název schématu.
U bloků s jediným schématem název schématu vynechte (výchozí hodnota je "default").
Mezipaměť
bs.cache je mezipaměť dotazů v paměti sdílená mezi všemi voláními bs.query a bs.mutate. Můžete ji používat i přímo:
// 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 mezipaměti se ukládají do paměti a při přechodu na jinou stránku se vymažou. Používají je hlavně interně bs.query a bs.mutate, ale přímý přístup se hodí k předběžnému naplnění dat nebo ručnímu zneplatnění po vlastních operacích.
Dotaz
bs.query() obaluje libovolnou asynchronní funkci mezipamětí, deduplikací a řízením zastarávání. Více volání se stejným klíčem během probíhajícího požadavku vrací stejný příslib (nedochází k duplicitnímu načítání).
// 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 }
);
Prvním argumentem je klíč mezipaměti (libovolný řetězec). Druhým je funkce, která vrací příslib. Třetím je volitelný objekt s nastaveními:
| Volba | Typ | Popis |
|---|---|---|
staleTime |
number |
Počet milisekund, po kterém se data v mezipaměti považují za zastaralá. 0 (výchozí) vždy načte data znovu. |
Pokud jsou v mezipaměti pro daný klíč data a jsou novější než staleTime, vrátí se okamžitě jejich uložená hodnota bez volání funkce.
Změna
bs.mutate() zajišťuje zápisové operace s optimistickými aktualizacemi a automatickým vrácením změn při selhání. Má dva režimy: automatický pro běžné vzory CRUD a ruční pro úplnou kontrolu.
Automatický režim pracuje s reaktivním stavovým objektem (například $data Alpine.js). Předejte state, key, action a případně také 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),
});
Při úspěchu se optimistická data nahradí odpovědí serveru. Při selhání se stav vrátí ke snímku pořízenému před změnou. Klíč mezipaměti se po každé úspěšné změně automaticky zneplatní.
Selhání znamená, že příslib vrácený z fn je zamítnut. bs.db() a bs.fn() při chybě validace, chybějícím záznamu nebo neúspěšné kontrole oprávnění chybu vyřeší jako výsledek, takže pokud se mají změny vrátit i v těchto případech, vyvolejte chybu, když výsledek obsahuje code:
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)),
});
Při vytváření se optimistické položce přiřadí dočasné id (například __temp_1). Po odpovědi serveru se dočasná položka aktualizuje skutečnými daty včetně id přiřazeného serverem.
Ruční režim nabízí úplnou kontrolu pomocí callbacků 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;
},
});
| Volba | Typ | Režim | Popis |
|---|---|---|---|
fn |
function |
Oba | Asynchronní funkce, která provádí změnu. Povinné. |
state |
object |
Automatický | Reaktivní stavový objekt (e.g, Alpine $data). |
key |
string |
Automatický | Název vlastnosti stavu, která obsahuje pole. Slouží také jako klíč mezipaměti. |
action |
string |
Automatický | Jedna z možností create, update nebo delete. |
id |
any |
Automatický | ID záznamu pro akce update a delete. |
optimistic |
object |
Automatický | Data, která se optimisticky použijí před odpovědí serveru. |
before |
function |
Ruční | Volá se před fn. Návratová hodnota se předá callbackům onSuccess/onError jako snapshot. |
onSuccess |
function |
Ruční | Volá se při úspěchu s hodnotou (result, snapshot). |
onError |
function |
Ruční | Volá se při selhání s hodnotou (error, snapshot). |
invalidate |
string |
Ruční | Klíč mezipaměti, který se má při úspěchu zneplatnit. |
PHP API
Třída Db poskytuje stejné operace na straně serveru. Použijte ji v rpc.php,
cron.php, šablonách nebo libovolném kódu 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);
U bloků s jediným schématem:
$db = Db::get('my-theme/block');
Průběžné dotazování
Přidejte do schématu realtime a zapněte automatické dotazování. Když se data na serveru změní, UI se automaticky aktualizuje prostřednictvím úložiště API Interactivity. Nejsou potřeba žádné změny JavaScript.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
S nastavením true Blockstudio dotazuje každé 3 sekundy a jako stavový klíč úložiště API Interactivity používá název schématu (default u bloků s jediným schématem).
Vlastní konfigurace
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Volba | Typ | Výchozí | Popis |
|---|---|---|---|
key |
string |
název schématu | Název vlastnosti v state, která obsahuje pole dat |
interval |
number |
3000 |
Interval dotazování v milisekundách |
Jak to funguje
- Při načtení stránky klient načte stručný otisk aktuálních dat
- Každých
intervalmilisekund znovu načte otisk - Pokud se otisk změnil, načte celý soubor dat
- Nová data se přes
store()vloží do úložiště API Interactivity - Direktivy navázané na danou vlastnost stavu se automaticky znovu vykreslí
Dotazování probíhá jen na stránkách, kde existuje odpovídající prvek data-wp-interactive. Pozastaví se při skrytí panelu prohlížeče a obnoví, když je panel viditelný.
Endpoint pro otisk (?_hash=1) vrací pouze kontrolní součet md5 a počet záznamů, takže požadavky na dotazování zůstávají úsporné.
Data omezená na uživatele
Nastavte userScoped: true a všechny záznamy se automaticky omezí na aktuálního uživatele.
Blockstudio přidá sloupec user_id, nastaví ho při vytvoření a ve všech operacích filtruje záznamy tak, aby se týkaly pouze aktuálního uživatele:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Žádné ruční pole user_id, žádný hook before_create ani filtrování v RPC. Uživatelé mohou zobrazit, upravit a smazat pouze své vlastní záznamy. O sloupec user_id se stará výhradně Blockstudio.
Při použití úložiště post_type se userScoped mapuje na post_author místo samostatného sloupce user_id.
Řízení přístupu
Každá operace CRUD má vlastní úroveň oprávnění:
| Hodnota | Chování |
|---|---|
true |
Veřejné s ochranou CSRF (povoleni jsou i odhlášení uživatelé, vyžaduje se X-BS-Token) |
'open' |
Zcela veřejné, bez CSRF a ověřování (pro webhooky a externí API) |
'edit_posts' |
Kontrola oprávnění WordPress |
['cap_a', 'cap_b'] |
Uživatel potřebuje alespoň jedno z uvedených oprávnění |
vynecháno / null |
Vyžaduje ověření (přihlášeného uživatele) |
'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
Veřejné endpointy (true) jsou chráněné hlavičkou X-BS-Token. bs.db() a bs.fn() získávají aktuální přihlašovací údaje z necachovaného endpointu na stejném originu, místo aby vkládaly tokeny s omezenou platností do HTML stránky. Stránky poskytované z dlouhodobých externích cache nadále fungují. Anonymní volání bez platného tokenu obdrží odpověď 403.
Přihlašovací údaje se vyžádají při prvním volání API, nikoli při každém zobrazení stránky. Oba klienti, včetně dotazování na databázové události v reálném čase, sdílejí jeden probíhající proces obnovení přihlašovacích údajů. Ty se obnovují po pěti minutách používání. Při odmítnutí nonce WordPress nebo CSRF tokenu Blockstudio se přihlašovací údaje jednou obnoví a požadavek se zopakuje; běžné chyby oprávnění se neopakují. Požadavky přihlášených uživatelů nadále používají relaci právě přihlášeného uživatele a kontroly oprávnění a vlastnictví záznamů definované schématem.
Umístěte POST /wp-json/blockstudio/v1/client/credentials mimo jakoukoli proxy nebo cache CDN. Odesílá Cache-Control: private, no-store a vyžaduje požadavek ze stejného originu s netriviální hlavičkou. Vestavění klienti to zajišťují automaticky.
Pokud potřebujete skutečně neověřený přístup bez CSRF, použijte 'open', například pro příchozí webhooky z externích služeb.
Typy polí
| Typ | Sloupec MySQL | Typ PHP | Popis |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Text, výchozí hodnota maxLength 255 |
integer |
bigint(20) |
int |
Celá čísla |
number |
decimal(20,6) |
float |
Desetinná čísla |
boolean |
tinyint(1) |
bool |
Pravda/nepravda |
text |
longtext |
string |
Dlouhý textový obsah |
Validace
Všechny zápisy (vytvoření i aktualizace) se před zásahem do úložiště ověřují podle schématu. Validace probíhá na serveru bez ohledu na to, zda požadavek přichází z bs.db(), z REST API, nebo z Db::get().
Vestavěná pravidla
| Pravidlo | Příklad | Popis |
|---|---|---|
required |
'required' => true |
Při vytvoření musí být pole vyplněno |
type |
'type' => 'integer' |
Hodnota musí odpovídat deklarovanému typu |
enum |
'enum' => ['a', 'b'] |
Hodnota musí být jednou z uvedených možností |
maxLength |
'maxLength' => 100 |
Řetězec nesmí překročit tuto délku |
minLength |
'minLength' => 3 |
Řetězec musí mít alespoň tuto délku |
format: "email" |
'format' => 'email' |
Musí jít o platnou e-mailovou adresu |
format: "url" |
'format' => 'url' |
Musí jít o platnou hodnotu URL |
Vlastní validace
Přidejte k libovolnému poli callback validate pro kontroly na straně serveru, které přesahují vestavěná pravidla. Pro úspěšnou validaci vraťte true, nebo vraťte řetězec s chybovou zprá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;
},
],
Callback dostává hodnotu pole a celé datové pole, takže můžete ověřovat vztahy mezi poli.
Formát chybové odpovědi
Validační chyby vracejí stav 400 s poli chyb pro jednotlivé položky. Tento formát vychází z ZodfieldErrors a usnadňuje přiřazení chyb k polím formuláře:
{
"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."]
}
}
}
Každé pole odpovídá poli řetězců s chybami. U jednoho pole může selhat více pravidel. Na frontendu:
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]);
});
}
Endpointy REST
Všechny endpointy jsou v oboru názvů blockstudio/v1/db/:
/db/{block-name}/{schema-name}
V názvu bloku se / nahrazuje hodnotou -. U bloků s jediným schématem je název schématu default.
| Metoda | Endpoint | Popis |
|---|---|---|
GET |
/db/{block}/{schema} |
Vypsat záznamy |
POST |
/db/{block}/{schema} |
Vytvořit záznam |
GET |
/db/{block}/{schema}/{id} |
Načíst jeden záznam |
PUT |
/db/{block}/{schema}/{id} |
Aktualizovat záznam |
DELETE |
/db/{block}/{schema}/{id} |
Smazat záznam |
Parametry dotazu (seznam)
| Parametr | Popis |
|---|---|
limit |
Maximum vrácených záznamů (výchozí hodnota 50, maximum 100) |
offset |
Počet záznamů, které se mají přeskočit |
| Libovolný název pole | Filtrování podle přesné shody hodnot |
Příklad: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Vykreslování formulářů
Pole mohou mít klíč component odkazující na blok Blockstudio. Zavolejte v šabloně bs_db_form() a vykreslete všechna pole jako formulář s použitím jejich komponentových bloků.
'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á komponenta dostává úplnou definici pole jako field ve svých atributech,
takže může přizpůsobit vykreslení podle schématu. Například $a['field']['name'] udává název pole, $a['field']['type'] typ,
$a['field']['required'] informuje, zda je povinné atd.
Struktura komponenty se řídí stejným formátem name, attributes, innerBlocks
jako bloky WordPress. Nejprve se vykreslí vnitřní bloky a předají se rodiči
jako $content.
Pro použití PHP bez vypsání:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hooky
Akce se spouštějí před každou operací zápisu i po ní. Všechny hooky dostávají jedno
pole $params. Úplný seznam najdete v přehledu PHP hooků.
Inline hooky
Definujte hooky přímo v db.php. Automaticky se vztahují pouze k danému schématu,
takže nemusíte kontrolovat název bloku ani schématu:
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ální hooky
Naslouchejte napříč všemi schématy odkudkoli:
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
}
});
Kombinace s RPC
db.php a rpc.php jsou nezávislé systémy. db.php generuje ze schématu definice
CRUD endpointy. rpc.php definuje vlastní serverové funkce.
Každý z nich funguje samostatně.
Použijte je společně, když potřebujete standardní datové operace a 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',
],
];
Přenositelnost
Při použití úložiště JSONC jsou data uložena společně s kódem. Zkopírujte složku bloku na jiný web a vše se přesune společně: UI, logika, řízení přístupu i samotná data.
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
Žádné migrace databáze ani kroky exportu a importu. Stačí zkopírovat složku.
Přenositelné je i úložiště Storh, nachází se však pod uploads/blockstudio/db/
místo ve složce bloku. Díky tomu zůstávají živá data, do kterých lze zapisovat, mimo váš zdrojový
strom a každé schéma má přitom úložiště v podobě běžných souborů, které lze zálohovat,
kopírovat nebo migrovat samostatně.
Filtr
Upravujte schémata programově zvenčí 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;
});