Adatbázis
Az adatbázisréteg lehetővé teszi, hogy adatmodellt határozzon meg a blokkhoz egy db.php fájlban. A Blockstudio automatikusan létrehozza a REST CRUD-végpontokat, a séma alapján érvényesíti a bemenetet, kezeli a tárolást, és biztosít egy JavaScript klienst (bs.db()), valamint egy PHP API-t (Db osztály).
Ez a teljes veremű blokkok adatainak gerince. Míg a RPC az egyedi logikát kezeli, az adatbázisréteg a strukturált adatokat kezeli sablonkód nélkül.
Működés
- Hozzon létre
db.php-t a blokk könyvtárában - Ez egy sémát ad vissza: mezőkkel, típusokkal, érvényesítési szabályokkal és hozzáférés-vezérléssel
- A Blockstudio automatikusan létrehozza a tárolót (táblát, fájlt vagy bejegyzésmetaadatot)
- Automatikusan létrejön öt REST-végpont (lista, lekérés, létrehozás, frissítés, törlés)
- A
bs.db()és aDb::get()biztosít hozzáférést a kliens és a szerver számára
Nincs szükség migrációkra, vezérlőkre vagy útvonalak regisztrálására.
Adjon át literális értékeket a REST és PHP API-knak. A meta és post_type háttérrendszerek belsőleg kezelik a WordPress metaadatok escape-elését, megőrizve a fordított perjeleket és az idézőjelek közötti karakterláncokat mind a skalárértékekben, mind a beágyazott objektumokban vagy tömbökben. Ne escape-elje előre az adatbázisrekordok értékeit.
Sémák meghatározása
Egyetlen séma
A legegyszerűbb forma: blokkonként egyetlen adatmodell.
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'],
],
];
PHP-natív builder szintaxis
A db.php egy kis, név szerinti argumentumokra és csak olvasható definíciós objektumokra épülő builder API használatára is képes. A tömbök maradnak az alapértelmezett formátum, de ez egy könnyebben felfedezhető, PHP-natív lehetőséget nyújt, amikor a séma nagyobbra nő.
<?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'),
],
);
Egyetlen sémához használja a Schema::make()-t, több sémát tartalmazó blokkokhoz pedig adjon vissza névvel ellátott Schema::make(...)-hívásokból álló tömböt.
Több séma
Egyetlen blokk több adatmodell tulajdonosa is lehet. Adjon vissza egy névvel ellátott tömböt:
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'],
],
],
];
Minden sémához saját végpontok, tároló és hozzáférés-vezérlés tartozik.
Tárolási módok
Hat tárolási háttér, különböző felhasználási esetekre szabva.
Egyéni tábla (storage: "table")
Minden rekord egy külön MySQL-táblában lévő sor. A Blockstudio automatikusan létrehozza és kezeli a táblát a WordPress dbDelta() függvényével. Ha új mezőket ad a sémához, azok oszlopként a következő oldalbetöltéskor jelennek meg. A meglévő oszlopokat soha nem távolítja el.
Ajánlott: strukturált adatokhoz, lekérdezésekhez és éles alkalmazásokhoz.
SQLite (storage: "sqlite")
Minden séma saját SQLite adatbázisfájlt kap egy db/ almappában. A Blockstudio automatikusan létrehozza a fájlt és a táblát, valamint hozzáadja a hiányzó oszlopokat, ha módosul a séma (hasonlóan a dbDelta működéséhez a MySQL esetében). A párhuzamos olvasási teljesítmény érdekében WAL naplózási módot használ.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Ajánlott: strukturált adatokhoz, amelyekhez valódi SQL-lekérdezések kellenek, de hordozhatónak kell maradniuk. Több ezer rekordot is hatékonyan kezel anélkül, hogy mindet memóriába töltené. Az adatok áthelyezéséhez másolja át a mappát.
JSONC-fájlok (storage: "jsonc")
A rekordok egy-egy JSON-objektumként, soronként tárolódnak egy db/ almappában lévő .jsonc-fájlban. A fájl az első íráskor automatikusan létrejön. Az // karakterekkel kezdődő sorokat megjegyzésként kezeli és megőrzi.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Ajánlott: kis adathalmazokhoz, konfigurációszerű adatokhoz, kezdő rekordokhoz és verziókezelhető példákhoz. A JSONC szándékosan egyetlen fájl a blokk mappájában. Akkor használja, ha azt szeretné, hogy az adatok a kóddal együtt mozogjanak, ne pedig sok párhuzamos írással számol.
Storh-fájlok (storage: "storh")
A Storh minden rekordot külön fájlként tárol a WordPress feltöltések között:
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
A nyilvános rekordazonosítók továbbra is ugyanazok az egész számok, amelyeket a bs.db() többi része is használ. A Blockstudio ezeket az azonosítókat a Storh belső UUIDv7 fájlazonosítóira képezi le, és az egész számú id értéket a rekordadatokban tárolja, így a JavaScript, REST és PHP hívóinak nem kell UUID-kkel foglalkozniuk.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
A Blockstudio a sémából állítja elő a Storh indexeket. Mivel minden deklarált mező használható listaszűrőként, minden deklarált mező indexelve van. Az egész, szám és dátumszerű mezők tartományindexet kapnak; a 'unique' => true vagy 'index' => 'unique' jelölésű mezők egyedi indexet használnak.
Ajánlott: fájlalapú, éles adatokhoz, amelyek biztonságosabb párhuzamos írást, sémából származtatott indexeket és hordozható, uploads szintű tárolást igényelnek, az élő rekordok blokk forrásfájába mentése nélkül.
JSONC migrálása erre: Storh
Ha .jsonc-fájllal kezdte, és ugyanazokat a rekordokat szeretné a Storh tárolóban is elérni, futtassa ezt:
wp bs db migrate my-theme/app subscribers --to=storh
Egyetlen sémát használó blokkok esetén:
wp bs db migrate my-theme/app --to=storh
A migráció beolvassa a meglévő db/{schema}.jsonc-t, a rekordokat a Storh tárolóba írja az egész azonosítók megőrzésével, újraindexel, ellenőrzi a célhelyet, a JSONC fájlt pedig érintetlenül hagyja. A visszaállításhoz csak a séma storage értékét kell visszaállítani erre: "jsonc".
Bejegyzésmetaadat (storage: "meta")
A rekordok JSON-tömbként, WordPress bejegyzésmetaadatként tárolódnak, és a postId segítségével kapcsolódnak egy adott bejegyzéshez.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Ajánlott: egy adott bejegyzéshez vagy oldalhoz tartozó adatokhoz.
Egyéni bejegyzéstípus (storage: "post_type")
Minden rekord egy WordPress-bejegyzés az automatikusan regisztrált egyéni bejegyzéstípusban. A séma minden mezője külön post_meta-bejegyzéssé válik. Így a rekordok lekérdezhetők a WP_Query segítségével, kompatibilisek a REST API bővítményekkel, és olyan eszközökben is láthatók, mint a GraphQL.
Ajánlott: olyan adatokhoz, amelyeknek natívan kell integrálódniuk a WordPress rendszerével. Minden mező külön lekérdezhető és indexelhető.
JavaScript-kliens
A Blockstudio adatbázist használó blokkokat tartalmazó oldalakon bs.db()-t injektál. Egy objektumot ad vissza öt metódussal:
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);
Az első argumentum a blokk neve (/-val), a második a séma neve. Egyetlen sémát használó blokkoknál hagyja el a séma nevét (alapértelmezése: "default").
Gyorsítótár
A bs.cache egy memóriabeli lekérdezési gyorsítótár, amelyet az összes bs.query– és bs.mutate-hívás megoszt. Közvetlenül is használhatja:
// 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();
A gyorsítótár bejegyzései a memóriában tárolódnak, és oldalváltáskor törlődnek. Elsősorban a bs.query és a bs.mutate használja őket belsőleg, de közvetlen hozzáférésük hasznos adatok előzetes feltöltéséhez vagy egyéni műveletek utáni kézi érvénytelenítéshez.
Lekérdezés
A bs.query() gyorsítótárral, deduplikálással és elavuláskezeléssel egészít ki bármilyen aszinkron függvényt. Ha egy kérés folyamatban van, az azonos kulccsal érkező többszöri hívás ugyanazt a promise-t adja vissza (nem történik ismételt lekérés).
// 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 }
);
Az első argumentum egy gyorsítótárkulcs (bármilyen karakterlánc). A második egy promise-t visszaadó függvény. A harmadik egy opcionális beállításobjektum:
| Beállítás | Típus | Leírás |
|---|---|---|
staleTime |
number |
Ennyi ezredmásodperc után tekinti elavultnak a gyorsítótárazott adatot. A 0 (alapértelmezett) mindig újra lekér. |
Ha a gyorsítótárban van adat a kulcshoz, és az staleTime-nél frissebb, a gyorsítótárazott értéket azonnal visszaadja a függvény meghívása nélkül.
Módosítás
A bs.mutate() optimista frissítésekkel és hiba esetén automatikus visszaállítással kezeli az írási műveleteket. Két módja van: automatikus mód az általános CRUD-mintákhoz, valamint kézi mód a teljes körű vezérléshez.
Automatikus mód reaktív állapotobjektummal működik (például Alpine.js $data). Adja meg a state, key, action értékeket, és opcionálisan ezt is: 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),
});
Siker esetén a szerver válasza felváltja az optimista adatokat. Hiba esetén az állapot visszaáll a módosítás előtti pillanatképére. A gyorsítótárkulcs minden sikeres módosítás után automatikusan érvénytelenedik.
A sikertelenség azt jelenti, hogy a fn által visszaadott promise elutasításra kerül. A bs.db() és a bs.fn() validációs hiba, hiányzó rekord vagy sikertelen jogosultság-ellenőrzés esetén a hiba törzsével teljesül, ezért dobjon kivételt, ha ezekben az esetekben is vissza kell vonni a módosításokat: 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)),
});
Létrehozási műveleteknél az optimista elem ideiglenes id-t kap (például __temp_1). Amikor a szerver válaszol, az ideiglenes elemet frissíti a valódi adatokkal, beleértve a szerver által kiosztott id-t is.
A kézi mód teljes körű vezérlést ad a before, onSuccess és onError visszahívásokkal:
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;
},
});
| Beállítás | Típus | Mód | Leírás |
|---|---|---|---|
fn |
function |
Mindkettő | A módosítást végrehajtó aszinkron függvény. Kötelező. |
state |
object |
Automatikus | Reaktív állapotobjektum (e.g., Alpine $data). |
key |
string |
Automatikus | Az állapot azon tulajdonságának neve, amely a tömböt tartalmazza. Gyorsítótárkulcsként is használja. |
action |
string |
Automatikus | A következők egyike: create, update vagy delete. |
id |
any |
Automatikus | Rekordazonosító a update és delete műveletekhez. |
optimistic |
object |
Automatikus | A szerver válasza előtt optimistán alkalmazandó adatok. |
before |
function |
Kézi | A fn előtt hívja meg. A visszatérési értéket onSuccess/onError snapshot-ként kapja meg. |
onSuccess |
function |
Kézi | Siker esetén a (result, snapshot) értékkel hívja meg. |
onError |
function |
Kézi | Hiba esetén a (error, snapshot) értékkel hívja meg. |
invalidate |
string |
Kézi | Siker esetén érvénytelenítendő gyorsítótárkulcs. |
PHP API
A Db osztály ugyanazokat a műveleteket teszi elérhetővé a szerveroldalon. Használja itt: rpc.php, cron.php, sablonokban vagy bármilyen PHP-kódban.
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);
Egyetlen sémát használó blokkok esetén:
$db = Db::get('my-theme/block');
Valós idejű lekérdezés
Adja hozzá a realtime-t a sémához az automatikus lekérdezés engedélyezéséhez. Ha az adatok megváltoznak a szerveren, az UI automatikusan frissül az Interactivity API áruházon keresztül. Nincs szükség a JavaScript módosítására.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
true esetén a Blockstudio 3 másodpercenként kérdez le, és a séma nevét használja az Interactivity API állapotkulcsaként (egysémás blokkoknál: default).
Egyéni beállítás
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Beállítás | Típus | Alapértelmezett | Leírás |
|---|---|---|---|
key |
string |
sémanév | Az state azon tulajdonságának neve, amely az adattömböt tartalmazza |
interval |
number |
3000 |
Lekérdezési időköz ezredmásodpercben |
Működés
- Az oldal betöltésekor a kliens lekéri az aktuális adatok könnyű hashét
- Minden
intervalezredmásodpercben újra lekéri a hash-t - Ha a hash megváltozott, lekéri a teljes adatkészletet
- Az új adatokat a
store()segítségével betölti az Interactivity API áruházba - Az adott állapottulajdonsághoz kötött összes direktíva automatikusan újrarenderelődik
A lekérdezés csak azokon az oldalakon fut, ahol létezik megfelelő data-wp-interactive elem. A böngészőlap rejtett állapotában szünetel, majd láthatóvá válásakor folytatódik.
A hash-végpont (?_hash=1) csak egy md5 ellenőrzőösszeget és a rekordok számát adja vissza, így a lekérdezési kérések kis méretűek maradnak.
Felhasználóhoz kötött adatok
Állítsa be a userScoped: true értékét, hogy minden rekord automatikusan az aktuális felhasználóhoz legyen rendelve. A Blockstudio hozzáad egy user_id oszlopot, létrehozáskor beállítja azt, és minden műveletet az aktuális felhasználó rekordjaira szűr:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Nincs szükség kézi user_id mezőre, before_create horogra vagy szűrésre a RPC kódban. A felhasználók csak a saját rekordjaikat láthatják, szerkeszthetik és törölhetik. Az user_id oszlopot teljes egészében a Blockstudio kezeli.
post_type-tárolás használatakor a userScoped külön user_id oszlop helyett a post_author mezőhöz képezi le az adatokat.
Hozzáférés-vezérlés
Minden CRUD-műveletnek saját jogosultsági szintje van:
| Érték | Működés |
|---|---|
true |
Nyilvános, CSRF-védelemmel (kijelentkezett felhasználók is használhatják, X-BS-Token szükséges) |
'open' |
Teljesen nyilvános, CSRF és hitelesítés nélkül (webhookokhoz és külső API-khoz) |
'edit_posts' |
WordPress jogosultság-ellenőrzés |
['cap_a', 'cap_b'] |
A felhasználónak rendelkeznie kell a felsorolt jogosultságok legalább egyikével |
elhagyva / null |
Hitelesítés szükséges (bejelentkezett felhasználó) |
'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
],
CSRF-védelem
A nyilvános végpontokat (true) egy X-BS-Token fejléc védi. A bs.db() és a bs.fn() friss hitelesítő adatokat kér le egy gyorsítótárazásból kizárt, azonos eredetű végpontról, így nem kerülnek lejáró tokenek az oldal HTML részébe. A hosszú ideig tárolt külső gyorsítótárból kiszolgált oldalak továbbra is működnek. Az érvényes token nélküli névtelen hívások 403 választ kapnak.
A hitelesítő adatokat az első API híváskor kéri le a rendszer, nem minden oldalmegtekintéskor. Mindkét kliens, az adatbázis valós idejű lekérdezéseit is beleértve, ugyanazt a folyamatban lévő hitelesítőadat-frissítést használja. A hitelesítő adatok öt perc használat után frissülnek. Az elutasított WordPress nonce vagy Blockstudio CSRF-token egy frissítést és újrapróbálkozást indít; a szokásos jogosultsági hibákkal nem próbálkozik újra a rendszer. A bejelentkezett kérések továbbra is a látogató munkamenetét, valamint a séma képesség- és rekordtulajdonlási ellenőrzéseit használják.
Tartsa a POST /wp-json/blockstudio/v1/client/credentials végpontot minden proxy- és CDN gyorsítótáron kívül. Cache-Control: private, no-store adatot küld, és azonos eredetű kérést követel meg nem egyszerű fejléccel. A beépített kliensek ezt automatikusan kezelik.
Használja a 'open'-t, ha valóban hitelesítés nélküli, CSRF-védelem nélküli hozzáférésre van szüksége, például külső szolgáltatások bejövő webhookjaihoz.
Mezőtípusok
| Típus | MySQL oszlop | PHP típus | Leírás |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Szöveg, alapértelmezett maxLength: 255 |
integer |
bigint(20) |
int |
Egész számok |
number |
decimal(20,6) |
float |
Tizedes törtek |
boolean |
tinyint(1) |
bool |
Igaz/hamis érték |
text |
longtext |
string |
Hosszabb szöveges tartalom |
Érvényesítés
Minden írást (létrehozást és frissítést) a séma alapján érvényesít a tároló módosítása előtt. Az érvényesítés a szerveren történik, függetlenül attól, hogy a kérés a bs.db(), a REST API vagy a Db::get() felől érkezik.
Beépített szabályok
| Szabály | Példa | Leírás |
|---|---|---|
required |
'required' => true |
Létrehozáskor kötelező megadni a mezőt |
type |
'type' => 'integer' |
Az értéknek meg kell felelnie a megadott típusnak |
enum |
'enum' => ['a', 'b'] |
Az értéknek a felsorolt lehetőségek egyikének kell lennie |
maxLength |
'maxLength' => 100 |
A karakterlánc nem lehet hosszabb ennél |
minLength |
'minLength' => 3 |
A karakterláncnak legalább ilyen hosszúnak kell lennie |
format: "email" |
'format' => 'email' |
Érvényes e-mail-címnek kell lennie |
format: "url" |
'format' => 'url' |
Érvényes URL kell legyen |
Egyéni érvényesítés
Adjon hozzá egy validate visszahívást bármely mezőhöz a beépített szabályokon túlmutató szerveroldali ellenőrzésekhez. Az átengedéshez adja vissza a true értéket, hiba esetén pedig egy karakterláncot a hibaüzenettel:
'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;
},
],
A visszahívás megkapja a mező értékét és a teljes adattömböt, így mezők közötti érvényesítést is végezhet.
Hibaüzenet formátuma
Az érvényesítési hibák 400 állapotkóddal térnek vissza, mezőnkénti hibatömbökkel. Ez a formátum a Zod fieldErrors megoldásából merít, és megkönnyíti a hibák űrlapmezőkhöz rendelését:
{
"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."]
}
}
}
Minden mezőhöz hibaüzenet-karakterláncok tömbje tartozik. Ugyanazon mezőnél több szabály is hibát jelezhet. A kezelőfelületen:
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]);
});
}
REST-végpontok
Minden végpont a blockstudio/v1/db/ névtér alatt található:
/db/{block-name}/{schema-name}
A blokk nevében a / helyére - kerül. Egysémás blokkoknál a séma neve default.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/db/{block}/{schema} |
Rekordok listázása |
POST |
/db/{block}/{schema} |
Rekord létrehozása |
GET |
/db/{block}/{schema}/{id} |
Egyetlen rekord lekérése |
PUT |
/db/{block}/{schema}/{id} |
Rekord frissítése |
DELETE |
/db/{block}/{schema}/{id} |
Rekord törlése |
Lekérdezési paraméterek (lista)
| Paraméter | Leírás |
|---|---|
limit |
Visszaadandó rekordok maximális száma (alapértelmezett: 50, legfeljebb 100) |
offset |
Kihagyandó rekordok száma |
| Bármely mező neve | Szűrés pontos értékegyezés alapján |
Példa: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Űrlap megjelenítése
A mezőkben megadható egy component kulcs, amely egy Blockstudio blokkra hivatkozik. Hívja meg a bs_db_form()-t a sablonban az összes mező űrlapként való megjelenítéséhez, a hozzájuk tartozó komponensblokkok használatával.
'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>
Minden komponens megkapja a teljes meződefiníciót field-ként az attribútumai között, így a komponensek a séma alapján alakíthatják a megjelenítést. Például a $a['field']['name'] adja meg a mező nevét, a $a['field']['type'] a típusát, a $a['field']['required'] pedig azt, hogy kötelező-e stb.
A komponens szerkezete ugyanazt a name, attributes, innerBlocks formátumot követi, mint a WordPress blokkok. A belső blokkok jelennek meg először, tartalmuk pedig $content-ként jut el a szülőhöz.
A PHP használatához visszhangozás nélkül:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hookok
A műveletek minden írási művelet előtt és után lefutnak. Minden hook egyetlen $params tömböt kap. A teljes listát lásd a PHP hookok referenciájában.
Beágyazott hookok
A hookokat közvetlenül a db.php-ban definiálhatja. A rendszer automatikusan ehhez a sémához rendeli őket, így nem kell ellenőriznie a blokk vagy a séma nevét:
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ális hookok
Bárhonnan figyelheti az összes sémát:
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álás a következővel: RPC
A db.php és a rpc.php egymástól független rendszerek. A db.php séma definíciójából CRUD-végpontokat hoz létre. A rpc.php egyéni szerveroldali függvényeket definiál. Mindkettő önállóan is használható.
Akkor használja őket együtt, ha szabványos adatműveletekre és egyéni üzleti logikára is szüksége van:
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',
],
];
Hordozhatóság
A JSONC tárolással az adatok a kód mellett találhatók. Másolja át a blokk mappáját egy másik webhelyre, és minden együtt költözik: a UI, a logika, a hozzáférés-vezérlés és maguk az adatok is.
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
Nincs szükség adatbázis-migrációra vagy exportálási és importálási lépésekre. Csak másolja át a mappát.
A Storh tárolás is hordozható, de a blokk mappája helyett a uploads/blockstudio/db/ alatt található. Így az éles, írható adatok kívül maradnak a forrásfán, miközben minden séma egyszerű fájlalapú tárolót kap, amely külön menthető, másolható vagy migrálható.
Szűrő
Sémák módosítása programozottan, a blokkon kívülről:
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;
});