Duomenų bazė
Duomenų bazės sluoksnyje galite apibrėžti bloko duomenų modelį faile db.php.
Blockstudio automatiškai sukuria REST CRUD galinius taškus, tikrina įvestį pagal schemą,
automatiškai tvarko saugyklą ir pateikia tiek JavaScript klientą
(bs.db()), tiek PHP API (Db klasę).
Tai yra viso steko blokų duomenų pagrindas. RPC tvarko tinkintą logiką, o duomenų bazės sluoksnis be papildomo paruošiamojo kodo tvarko struktūruotus duomenis.
Kaip tai veikia
- Bloko kataloge sukuriate
db.php - Ji pateikia schemą: laukus, tipus, tikrinimo taisykles ir prieigos kontrolę
- Blockstudio automatiškai sukuria saugyklą (lentelę, failą arba įrašo meta duomenis)
- Automatiškai sugeneruojami penki REST galiniai taškai (sąrašo, gavimo, kūrimo, atnaujinimo ir trynimo)
bs.db()irDb::get()suteikia prieigą klientui ir serveriui
Nereikia migracijų, valdiklių ar registruoti maršrutų.
Perduokite pažodines reikšmes į REST ir PHP API. meta ir post_type posistemės pačios apdoroja WordPress metaduomenų apsaugą nuo pasvirųjų brūkšnių, išsaugodamos pasviruosius brūkšnius ir kabutėse esančias eilutes tiek skaliarinėse reikšmėse, tiek įdėtuose objektuose ar masyvuose. Iš anksto nepridėkite pasvirųjų brūkšnių prie duomenų bazės įrašų reikšmių.
Schemos apibrėžimas
Viena schema
Paprasčiausias variantas: po vieną duomenų modelį kiekvienam blokui.
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 būdinga kūrimo sintaksė
db.php taip pat gali naudoti nedidelį kūrimo priemonės API, pagrįstą pavadintais argumentais ir tik skaitomais apibrėžimo objektais. Masyvai lieka numatytuoju formatu, tačiau ši parinktis suteikia aiškesnę PHP būdingą sintaksę, kai schema tampa didesnė.
<?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'),
],
);
Naudokite Schema::make() vienai schemai arba grąžinkite pavadintų Schema::make(...) iškvietimų masyvą blokams su keliomis schemomis.
Kelios schemos
Viename bloke gali būti keli duomenų modeliai. Grąžinkite pavadintą masyvą:
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'],
],
],
];
Kiekviena schema gauna savo galinius taškus, saugyklą ir prieigos kontrolę.
Saugyklos režimai
Šešios saugyklų sistemos, pritaikytos skirtingiems naudojimo atvejams.
Tinkinta lentelė (storage: "table")
Kiekvienas įrašas saugomas kaip eilutė atskiroje MySQL lentelėje. Blockstudio automatiškai sukuria ir tvarko lentelę naudodama funkciją dbDelta() iš WordPress. Pridėjus į schemą naujų laukų, kito puslapio įkėlimo metu pridedami stulpeliai. Esami stulpeliai niekada nepašalinami.
Geriausiai tinka struktūruotiems duomenims, užklausoms ir gamybinėms programoms.
SQLite (storage: "sqlite")
Kiekviena schema saugoma atskirame SQLite duomenų bazės faile, db/ poaplankyje. Blockstudio automatiškai sukuria failą ir lentelę bei prideda trūkstamus stulpelius pasikeitus schemai (kaip dbDelta skirtoje MySQL). Naudojamas WAL žurnalo režimas, kad būtų našiau vykdomos lygiagrečios skaitymo operacijos.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Geriausiai tinka struktūruotiems duomenims, kuriems reikia tikrų SQL užklausų, bet kuriuos norite išlaikyti perkeliamus. Tūkstančiai įrašų apdorojami efektyviai, neįkeliant visų į atmintį. Norėdami perkelti duomenis, nukopijuokite aplanką.
JSONC failai (storage: "jsonc")
Įrašai saugomi po vieną JSON objektą eilutėje .jsonc faile, esančiame db/ poaplankyje. Failas automatiškai sukuriamas pirmą kartą įrašant duomenis. Eilutės, prasidedančios //, laikomos komentarais ir išsaugomos.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Geriausiai tinka mažiems duomenų rinkiniams, konfigūracijos tipo duomenims, pradiniams įrašams ir pavyzdžiams, kurių versijas galima sekti. JSONC sąmoningai yra vienas failas bloko aplanke. Naudokite jį, kai norite, kad duomenys keliautų kartu su kodu, o ne kai tikitės daug lygiagrečių įrašymo operacijų.
Storh failai (storage: "storh")
Storh saugo kiekvieną įrašą kaip atskirą failą WordPress įkeltų failų aplanke:
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
Viešieji įrašų ID išlieka tokie patys sveikieji skaičiai kaip ir kitur bs.db().
Blockstudio susieja šiuos ID su vidiniais UUIDv7 failų ID sistemoje Storh ir įrašo sveikąjį skaičių id įrašo duomenyse, todėl JavaScript, REST ir PHP iškvietėjams nereikia tvarkyti UUID.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio pagal jūsų schemą sukuria Storh indeksus. Kadangi kiekvieną deklaruotą lauką galima naudoti kaip sąrašo filtrą, indeksuojami visi deklaruoti laukai. Sveikųjų skaičių, skaičių ir datų tipo laukams naudojami intervalų indeksai, o laukuose, pažymėtuose 'unique' => true arba 'index' => 'unique', naudojami unikalumo indeksai.
Geriausiai tinka gamybiniams duomenims, saugomiems failuose, kai reikia saugesnio lygiagretaus įrašymo, pagal schemą sudaromų indeksų ir perkeliamų duomenų saugyklos įkeltų failų lygmenyje, neįtraukiant aktyvių įrašų į bloko šaltinio medį.
Migravimas iš JSONC į Storh
Jei pradėjote nuo .jsonc failo ir norite perkelti tuos pačius įrašus į Storh, vykdykite:
wp bs db migrate my-theme/app subscribers --to=storh
Blokams su viena schema:
wp bs db migrate my-theme/app --to=storh
Migravimo metu nuskaitomas esamas db/{schema}.jsonc, įrašai perkeliami į Storh išsaugant sveikųjų skaičių ID, atnaujinami indeksai, patikrinama paskirties saugykla, o JSONC failas paliekamas nepakeistas. Norėdami grąžinti ankstesnę būseną, tiesiog pakeiskite schemos storage atgal į "jsonc".
Įrašo meta duomenys (storage: "meta")
Įrašai saugomi kaip JSON masyvas WordPress įrašo meta duomenyse ir susiejami su konkrečiu įrašu per postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Geriausiai tinka duomenims, susijusiems su konkrečiu įrašu ar puslapiu.
Tinkintas įrašo tipas (storage: "post_type")
Kiekvienas įrašas yra WordPress įrašas automatiškai užregistruotame tinkintame įrašo tipe. Kiekvienas schemos laukas tampa atskiru post_meta įrašu. Todėl įrašus galima užklausti naudojant WP_Query, jie suderinami su REST API papildiniais ir matomi tokiems įrankiams kaip GraphQL.
Geriausiai tinka duomenims, kuriuos reikia natūraliai integruoti su WordPress. Kiekvieną lauką galima atskirai užklausti ir indeksuoti.
JavaScript klientas
Blockstudio įterpia bs.db() puslapiuose su duomenų bazės blokais. Grąžinamas objektas su penkiais metodais:
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);
Pirmasis argumentas yra bloko pavadinimas (su /), antrasis – schemos pavadinimas.
Blokuose su viena schema schemos pavadinimą galima praleisti (numatytoji reikšmė – "default").
Spartinančioji atmintinė
bs.cache yra atmintyje esanti užklausų spartinančioji atmintinė, bendra visiems bs.query ir bs.mutate iškvietimams. Galite ją naudoti ir tiesiogiai:
// 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();
Spartinančiosios atmintinės įrašai saugomi atmintyje ir išvalomi pereinant į kitą puslapį. Juos daugiausia viduje naudoja bs.query ir bs.mutate, tačiau tiesioginė prieiga naudinga iš anksto įkeliant duomenis arba rankiniu būdu panaikinant jų galiojimą po tinkintų operacijų.
Užklausa
bs.query() apgaubia bet kurią asinchroninę funkciją spartinimu, pasikartojančių užklausų sujungimu ir duomenų pasenimo valdymu. Jei užklausa dar vykdoma ir kelis kartus kviečiama tuo pačiu raktu, visi iškvietimai grąžina tą patį promise objektą (nedubliuoja duomenų gavimo).
// 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 }
);
Pirmasis argumentas yra spartinančiosios atmintinės raktas (bet kokia eilutė). Antrasis – funkcija, grąžinanti promise objektą. Trečiasis – pasirenkamas parinkčių objektas:
| Parinktis | Tipas | Aprašymas |
|---|---|---|
staleTime |
number |
Milisekundės, po kurių spartinamosios atmintinės duomenys laikomi pasenusiais. 0 (numatytoji reikšmė) visada iš naujo gauna duomenis. |
Jei spartinančiojoje atmintinėje yra rakto duomenų ir jie yra naujesni nei staleTime, iškart grąžinama spartinama reikšmė, nekviečiant funkcijos.
Keitimas
bs.mutate() tvarko įrašymo operacijas, atlikdamas optimistinius atnaujinimus ir nesėkmės atveju automatiškai atkūręs ankstesnę būseną. Galimi du režimai: automatinis režimas įprastiems CRUD šablonams ir rankinis režimas, kai reikia visiškos kontrolės.
Automatinis režimas veikia su reaktyviosios būsenos objektu (pvz., Alpine.js $data). Perduokite state, key, action ir, pasirinktinai, 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),
});
Sėkmės atveju optimistiniai duomenys pakeičiami serverio atsakymu. Nesėkmės atveju būsena atkuriama pagal prieš pakeitimą padarytą kopiją. Po kiekvieno sėkmingo pakeitimo spartinančiosios atmintinės raktas automatiškai panaikinamas.
Nesėkme laikoma situacija, kai fn grąžintas promise objektas atmetamas. bs.db() ir bs.fn() klaidos atveju grąžina klaidos turinį, jei nepavyksta tikrinti duomenų, nerandamas įrašas arba nepavyksta leidimų patikra. Todėl iškvieskite klaidą, kai rezultate yra code, jei ir tokiais atvejais turėtų būti atkuriama ankstesnė būsena:
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)),
});
Kuriant įrašą, optimistiniam elementui priskiriamas laikinas id (pvz., __temp_1). Serveriui atsakius, laikinas elementas atnaujinamas tikrais duomenimis, įskaitant serverio priskirtą id.
Rankinis režimas suteikia visišką kontrolę naudojant before, onSuccess ir onError atgalinio iškvietimo funkcijas:
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;
},
});
| Parinktis | Tipas | Režimas | Aprašymas |
|---|---|---|---|
fn |
function |
Abu | Asinchroninė funkcija, atliekanti pakeitimą. Privaloma. |
state |
object |
Automatinis | Reaktyviosios būsenos objektas (e.g, Alpine $data). |
key |
string |
Automatinis | Būsenos savybės pavadinimas, kuriame laikomas masyvas. Taip pat naudojamas kaip spartinančiosios atmintinės raktas. |
action |
string |
Automatinis | Vienas iš create, update arba delete. |
id |
any |
Automatinis | Įrašo ID veiksmams update ir delete. |
optimistic |
object |
Automatinis | Duomenys, pritaikomi optimistiškai prieš gaunant serverio atsakymą. |
before |
function |
Rankinis | Iškviečiama prieš fn. Grąžinama reikšmė perduodama onSuccess/onError kaip snapshot. |
onSuccess |
function |
Rankinis | Iškviečiama su (result, snapshot) sėkmės atveju. |
onError |
function |
Rankinis | Iškviečiama su (error, snapshot) nesėkmės atveju. |
invalidate |
string |
Rankinis | Spartinančiosios atmintinės raktas, kurio galiojimas panaikinamas sėkmės atveju. |
PHP API
Db klasė serverio pusėje teikia tas pačias operacijas. Naudokite ją faile rpc.php, cron.php, šablonuose arba bet kuriame PHP kode.
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);
Blokams su viena schema:
$db = Db::get('my-theme/block');
Duomenų tikrinimas realiuoju laiku
Įtraukite realtime į schemą, kad būtų įjungtas automatinis duomenų tikrinimas nustatytais intervalais. Pasikeitus duomenims serveryje, UI automatiškai atnaujinama per Interactivity API saugyklą. JavaScript pakeitimų nereikia.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Naudojant true, Blockstudio kas 3 sekundes siunčia užklausą, schemos pavadinimą naudodama kaip Interactivity API būsenos raktą (default blokams su viena schema).
Tinkinta konfigūracija
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Parinktis | Tipas | Numatytoji reikšmė | Aprašymas |
|---|---|---|---|
key |
string |
schemos pavadinimas | Ypatybės pavadinimas state, kurioje saugomas duomenų masyvas |
interval |
number |
3000 |
Tikrinimo užklausų intervalas milisekundėmis |
Kaip tai veikia
- Įkėlus puslapį, klientas gauna lengvą dabartinių duomenų maišą
- Kas
intervalmilisekundžių maiša gaunama iš naujo - Pasikeitus maišai, gaunamas visas duomenų rinkinys
- Nauji duomenys per
store()perduodami į Interactivity API saugyklą - Visos su šia būsenos savybe susietos direktyvos automatiškai atvaizduojamos iš naujo
Duomenų tikrinimas intervalais vykdomas tik puslapiuose, kuriuose yra atitinkamas data-wp-interactive elementas. Jis pristabdomas, kai naršyklės skirtukas paslepiamas, ir tęsiamas, kai vėl tampa matomas.
Maišos galinis taškas (?_hash=1) grąžina tik md5 kontrolinę sumą ir įrašų skaičių, todėl periodinės užklausos lieka nedidelės.
Naudotojo duomenys
Nustatykite userScoped: true, kad visi įrašai būtų automatiškai apriboti iki dabartinio naudotojo. Blockstudio prideda stulpelį user_id, nustato jo reikšmę kuriant įrašą ir filtruoja visas operacijas, kad jos apimtų tik dabartinio naudotojo įrašus:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Nereikia rankiniu būdu nurodyti lauko user_id, before_create kablio ar filtruoti faile RPC. Naudotojai gali matyti, redaguoti ir ištrinti tik savo įrašus. Stulpelį user_id visiškai tvarko Blockstudio.
Naudojant post_type saugyklą, userScoped susiejamas su post_author, o ne atskiru stulpeliu user_id.
Prieigos kontrolė
Kiekvienai CRUD operacijai nustatomas atskiras leidimų lygis:
| Reikšmė | Veikimas |
|---|---|
true |
Vieša su CSRF apsauga (atsijungę naudotojai gali naudotis, būtinas X-BS-Token) |
'open' |
Visiškai vieša, be CSRF ir autentifikavimo (skirta internetinėms sąsajoms ir išorinėms API) |
'edit_posts' |
WordPress galimybės patikra |
['cap_a', 'cap_b'] |
Naudotojui reikia bet kurios vienos iš išvardytų galimybių |
praleista / null |
Reikalingas autentifikavimas (prisijungęs naudotojas) |
'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 apsauga
Viešieji galiniai taškai (true) apsaugoti X-BS-Token antrašte. bs.db() ir bs.fn() gauna naujus kredencialus iš tos pačios kilmės nekeshuojamo galinio taško, užuot įterpę baigiančius galioti prieigos žetonus į puslapio HTML. Puslapiai, pateikiami iš ilgai veikiančių išorinių podėlių, toliau veikia. Anoniminėms užklausoms be galiojančio žetono pateikiamas 403 atsakymas.
Kredencialų prašoma pirmą kartą iškvietus API, o ne kaskart peržiūrint puslapį. Abu klientai, įskaitant duomenų bazės apklausas realiuoju laiku, dalijasi vienu vykdomu kredencialų atnaujinimu. Panaudojus kredencialus penkias minutes, jie atnaujinami. Atmetus WordPress nonce arba Blockstudio CSRF žetoną, kredencialai vieną kartą atnaujinami ir užklausa pakartojama; įprastos leidimų klaidos užklausos nekartoja. Prisijungusių naudotojų užklausoms ir toliau naudojama apsilankančio naudotojo sesija, schemos galimybių ir įrašo nuosavybės patikros.
POST /wp-json/blockstudio/v1/client/credentials laikykite už bet kokio tarpinio serverio ar CDN podėlio ribų. Jis siunčia Cache-Control: private, no-store ir reikalauja tos pačios kilmės užklausos su nestandartine antrašte. Integruoti klientai tai atlieka automatiškai.
Naudokite 'open', kai reikia visiškai neautentifikuotos prieigos be CSRF, pavyzdžiui, priimant išorinių paslaugų siunčiamus žiniatinklio kablius.
Laukų tipai
| Tipas | MySQL stulpelis | PHP tipas | Aprašymas |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Tekstas, numatytasis maxLength 255 |
integer |
bigint(20) |
int |
Sveikieji skaičiai |
number |
decimal(20,6) |
float |
Dešimtainiai skaičiai |
boolean |
tinyint(1) |
bool |
Tiesa / netiesa |
text |
longtext |
string |
Ilgas tekstinis turinys |
Tikrinimas
Visi įrašymo veiksmai (kūrimas ir atnaujinimas) prieš saugant duomenis tikrinami pagal schemą. Tikrinimas atliekamas serverio pusėje, nesvarbu, ar užklausa siunčiama iš bs.db(), REST API, ar iš Db::get().
Integruotos taisyklės
| Taisyklė | Pavyzdys | Aprašymas |
|---|---|---|
required |
'required' => true |
Kuriant įrašą, laukas turi būti nurodytas |
type |
'type' => 'integer' |
Reikšmė turi atitikti deklaruotą tipą |
enum |
'enum' => ['a', 'b'] |
Reikšmė turi būti viena iš nurodytų parinkčių |
maxLength |
'maxLength' => 100 |
Eilutė negali viršyti šio ilgio |
minLength |
'minLength' => 3 |
Eilutė turi būti bent tokio ilgio |
format: "email" |
'format' => 'email' |
Turi būti galiojantis el. pašto adresas |
format: "url" |
'format' => 'url' |
Turi būti galiojantis URL |
Tinkintas tikrinimas
Pridėkite validate atgalinio iškvietimo funkciją prie bet kurio lauko, kad atliktumėte serverio pusės patikras, kurių neapima integruotos taisyklės. Grąžinkite true, jei patikra sėkminga, arba klaidos pranešimo eilutę:
'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;
},
],
Atgalinio iškvietimo funkcija gauna lauko reikšmę ir visą duomenų masyvą, todėl galite tikrinti kelių laukų tarpusavio priklausomybes.
Klaidų atsakymo formatas
Tikrinimo klaidos grąžina būseną 400 ir kiekvieno lauko klaidų masyvus. Formatas pagrįstas ZodfieldErrors ir leidžia lengvai susieti klaidas su formos laukais:
{
"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."]
}
}
}
Kiekvienam laukui priskiriamas klaidų eilučių masyvas. Tame pačiame lauke gali nepavykti patikrinti pagal kelias taisykles. Sąsajos pusėje:
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 galiniai taškai
Visi galiniai taškai yra vardų srityje blockstudio/v1/db/:
/db/{block-name}/{schema-name}
Bloko pavadinime / pakeičiama į -. Blokuose su viena schema schemos
pavadinimas yra default.
| Metodas | Galinis taškas | Aprašymas |
|---|---|---|
GET |
/db/{block}/{schema} |
Išvardyti įrašus |
POST |
/db/{block}/{schema} |
Sukurti įrašą |
GET |
/db/{block}/{schema}/{id} |
Gauti vieną įrašą |
PUT |
/db/{block}/{schema}/{id} |
Atnaujinti įrašą |
DELETE |
/db/{block}/{schema}/{id} |
Ištrinti įrašą |
Užklausos parametrai (sąrašas)
| Parametras | Aprašymas |
|---|---|
limit |
Didžiausias grąžinamų įrašų skaičius (numatytoji reikšmė – 50, maks. 100) |
offset |
Praleidžiamų įrašų skaičius |
| Bet kuris lauko pavadinimas | Filtruoti pagal tikslią reikšmę |
Pavyzdys: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Formos atvaizdavimas
Laukuose galima apibrėžti component raktą, nurodantį į Blockstudio bloką. Šablone iškvieskite bs_db_form(), kad visi laukai būtų atvaizduoti kaip forma naudojant jų komponentų blokus.
'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>
Kiekvienas komponentas savo atributuose gauna visą lauko apibrėžtį kaip field, todėl gali pritaikyti atvaizdavimą pagal schemą. Pavyzdžiui, $a['field']['name'] nurodo lauko pavadinimą, $a['field']['type'] – tipą, $a['field']['required'] – ar jis privalomas ir t. t.
Komponento struktūra atitinka tą patį name, attributes, innerBlocks formatą kaip WordPress blokai. Vidiniai blokai atvaizduojami pirmiausia ir perduodami kaip $content tėviniam blokui.
Naudojant PHP be išvedimo:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Kabliukai
Veiksmai vykdomi prieš kiekvieną rašymo operaciją ir po jos. Visi kabliukai gauna vieną $params masyvą. Visą sąrašą rasite PHPKabliukų nuorodoje.
Įterptieji kabliukai
Kabliukus apibrėžkite tiesiogiai faile db.php. Jie automatiškai taikomi tik tai schemai, todėl nereikia tikrinti bloko ar schemos pavadinimo:
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']);
},
],
];
Globalūs kabliukai
Klausykitės įvykių visose schemose iš bet kurios vietos:
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
}
});
Derinimas su RPC
db.php ir rpc.php yra nepriklausomos sistemos. db.php pagal schemos apibrėžtį generuoja CRUD galinius taškus. rpc.php apibrėžia pasirinktines serverio funkcijas. Kiekviena sistema veikia ir atskirai.
Naudokite jas kartu, kai reikia standartinių duomenų operacijų ir pasirinktinės verslo logikos:
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',
],
];
Perkeliamumas
Naudojant JSONC saugyklą, duomenys laikomi kartu su kodu. Nukopijuokite bloko aplanką į kitą svetainę – persikels viskas: UI, logika, prieigos kontrolė ir patys duomenys.
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
Nereikia duomenų bazės migracijų ar eksportavimo ir importavimo. Tiesiog nukopijuokite aplanką.
Storh saugykla taip pat yra perkeliama, tačiau ji laikoma uploads/blockstudio/db/, o ne bloko aplanke. Taip aktyvūs, įrašomi duomenys lieka už jūsų šaltinio medžio ribų, o kiekviena schema vis tiek turi paprastų failų saugyklą, kurią galima kurti atsarginę kopiją, kopijuoti arba perkelti atskirai.
Filtras
Programiškai keiskite schemas iš bloko išorės:
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;
});