Ugrás a tartalomhoz

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

  1. Hozzon létre db.php-t a blokk könyvtárában
  2. 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
  3. A Blockstudio automatikusan létrehozza a tárolót (táblát, fájlt vagy bejegyzésmetaadatot)
  4. Automatikusan létrejön öt REST-végpont (lista, lekérés, létrehozás, frissítés, törlés)
  5. A bs.db() és a Db::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.

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

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

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

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.

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

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

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

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.

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

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

Egyetlen sémát használó blokkok esetén:

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

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

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

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:

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

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

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

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:

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

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

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

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:

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

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

Egyetlen sémát használó blokkok esetén:

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

PHP
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

PHP
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

  1. Az oldal betöltésekor a kliens lekéri az aktuális adatok könnyű hashét
  2. Minden interval ezredmásodpercben újra lekéri a hash-t
  3. Ha a hash megváltozott, lekéri a teljes adatkészletet
  4. Az új adatokat a store() segítségével betölti az Interactivity API áruházba
  5. 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:

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

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:

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

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:

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

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:

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

REST-végpontok

Minden végpont a blockstudio/v1/db/ névtér alatt található:

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

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>

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:

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

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ális hookok

Bárhonnan figyelheti az összes sémát:

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

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

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.

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

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:

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