Andmebaas
Andmebaasikiht võimaldab määratleda ploki andmemudeli failis db.php.
Blockstudio loob automaatselt CRUD-lõpp-punktid REST, valideerib sisendi skeemi alusel,
haldab salvestust automaatselt ning pakub nii JavaScript klienti
(bs.db()) kui ka PHP API (Db klassi).
See on täisvirnaplokkide andmete selgroog. Kui RPC tegeleb kohandatud loogikaga, siis andmebaasikiht haldab struktureeritud andmeid ilma korduva algkoodita.
Kuidas see töötab
- Loo oma ploki kataloogis
db.php - See tagastab skeemi: väljad, tüübid, valideerimisreeglid ja juurdepääsukontroll
- Blockstudio loob salvestuskoha (tabeli, faili või post meta)
- Automaatselt luuakse viis REST lõpp-punkti (loendamine, hankimine, loomine, uuendamine, kustutamine)
bs.db()jaDb::get()pakuvad kliendi- ja serveripoolset juurdepääsu
Pole vaja migratsioone, kontrollereid ega marsruutide registreerimist.
Edastage API-dele REST ja PHP sõnasõnalised väärtused. Taustsüsteemid meta ja post_type käsitlevad WordPress metaandmete kaldkriipsude lisamist sisemiselt, säilitades kaldkriipsud ja jutumärkides stringid nii skalaarväärtustes kui ka pesastatud objektides või massiivides. Ärge lisage andmebaasikirjete väärtustele eelnevalt kaldkriipse.
Skeemide määratlemine
Üks skeem
Lihtsaim variant: üks andmemudel ploki kohta.
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-i natiivne koostajasüntaks
db.php saab kasutada ka väikest koostaja API, mis põhineb nimega argumentidel ja kirjutuskaitstud definitsiooniobjektidel. Massiivid jäävad vaikevorminguks, kuid see annab PHP-i natiivse ja paremini avastatava võimaluse, kui skeem muutub suuremaks.
<?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'),
],
);
Kasuta ühe skeemi jaoks Schema::make() või tagasta mitme skeemiga plokkide puhul nimega Schema::make(...)-kutsete massiiv.
Mitu skeemi
Ühel plokil võib olla mitu andmemudelit. Tagasta nimega massiiv:
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'],
],
],
];
Iga skeem saab oma lõpp-punktid, salvestuskoha ja juurdepääsukontrolli.
Salvestusrežiimid
Kuus salvestustausta, millest igaüks sobib eri kasutusjuhtudeks.
Kohandatud tabel (storage: "table")
Iga kirje on eraldi MySQL tabeli rida. Blockstudio loob tabeli automaatselt ja haldab seda, kasutades WordPress funktsiooni dbDelta(). Uute väljade lisamine skeemi lisab järgmise lehelaadimise ajal veerud. Olemasolevaid veerge ei eemaldata kunagi.
Sobib kõige paremini: struktureeritud andmete, päringute ja tootmisrakenduste jaoks.
SQLite (storage: "sqlite")
Iga skeem saab oma SQLite andmebaasifaili alamkaustas db/. Blockstudio loob faili ja tabeli automaatselt ning lisab skeemi muutumisel puuduvad veerud (nagu dbDelta MySQL jaoks). Kasutab WAL-päevikurežiimi samaaegsete lugemiste jõudluse parandamiseks.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Sobib kõige paremini: struktureeritud andmete jaoks, mis vajavad päris SQL-päringuid, kuid peavad jääma teisaldatavaks. Tõhusalt saab hallata tuhandeid kirjeid ilma kõike mällu laadimata. Andmete teisaldamiseks kopeeri kaust.
JSONC-failid (storage: "jsonc")
Kirjed salvestatakse .jsonc-failis alamkaustas db/ nii, et igal real on üks JSON-objekt. Fail luuakse automaatselt esimesel kirjutamisel. Reaga // algavad read käsitletakse kommentaaridena ja säilitatakse.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Sobib kõige paremini: väikeste andmestike, konfiguratsioonilaadsete andmete, algkirjete ja versioonihalduse all hoitavate näidete jaoks. JSONC on tahtlikult üks fail sinu plokikaustas. Kasuta seda, kui soovid, et andmed liiguksid koos koodiga, mitte siis, kui ootad palju samaaegseid kirjutusi.
Storh-failid (storage: "storh")
Storh salvestab iga kirje eraldi failina asukohas WordPress uploads:
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
Avalikud kirjete ID-d jäävad samadeks täisarvulisteks ID-deks, mida kasutab ülejäänud bs.db().
Blockstudio seostab need ID-d Storh sisemiste UUIDv7 failide ID-dega ja salvestab kirje andmetesse täisarvulise id, nii et JavaScript, REST ja PHP kasutajad ei pea UUID-dega tegelema.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio koostab skeemi põhjal Storh indeksid. Kuna loendi filtrina saab kasutada kõiki deklareeritud välju, indekseeritakse iga deklareeritud väli. Täisarvu-, arvu- ja kuupäevalaadsete väljade jaoks kasutatakse vahemikuindekseid; väljad, mis on märgitud väärtustega 'unique' => true või 'index' => 'unique', saavad unikaalsed indeksid.
Sobib kõige paremini: failipõhiste tootmisandmete jaoks, mis vajavad turvalisemaid samaaegseid kirjutusi, skeemist tuletatud indekseid ja teisaldatavat salvestust uploads-tasandil, ilma et aktiivsed kirjed lisataks ploki lähtepuusse.
JSONC-i migreerimine Storh-i
Kui alustasid failiga .jsonc ja soovid samu kirjeid Storh-is, käivita:
wp bs db migrate my-theme/app subscribers --to=storh
Ühe skeemiga plokkide puhul:
wp bs db migrate my-theme/app --to=storh
Migreerimine loeb olemasoleva db/{schema}.jsonc, kirjutab kirjed Storh-i, säilitades täisarvulised ID-d, koostab indeksid, kontrollib sihtsalvestuskohta ja jätab faili JSONC puutumata. Tagasipööramiseks muuda skeemi storage tagasi väärtuseks "jsonc".
Post meta (storage: "meta")
Kirjed salvestatakse WordPress post meta hulka JSON-massiivina ja seotakse kindla postitusega postId kaudu.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Sobib kõige paremini: konkreetse postituse või lehe juurde kuuluva teabe jaoks.
Kohandatud postituse tüüp (storage: "post_type")
Iga kirje on automaatselt registreeritud kohandatud postituse tüübi WordPress-postitus. Iga skeemi väli muutub eraldi post_meta kirjeiks. Nii saab kirjete kohta päringuid teha WP_Query abil, need ühilduvad REST API lisandmoodulitega ja on nähtavad tööriistades nagu GraphQL.
Sobib kõige paremini: andmete jaoks, mis peaksid WordPress-iga algupäraselt lõimuma. Iga välja kohta saab eraldi päringuid teha ja selle indekseerida.
JavaScript klient
Blockstudio lisab bs.db() andmebaasiplokkidega lehtedele. See tagastab objekti viie meetodiga:
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);
Esimene argument on ploki nimi (koos /-ga), teine on skeemi nimi.
Ühe skeemiga plokkide puhul jäta skeemi nimi välja (vaikimisi on "default").
Vahemälu
bs.cache on mälusisene päringute vahemälu, mida jagavad kõik bs.query ja bs.mutate-kutsed. Saad seda kasutada ka otse:
// 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();
Vahemälu kirjed salvestatakse mällu ja kustutatakse lehelt lahkumisel. Neid kasutavad peamiselt sisemiselt bs.query ja bs.mutate, kuid otsene juurdepääs on kasulik andmete eeltäitmiseks või käsitsi kehtetuks tunnistamiseks pärast kohandatud toiminguid.
Päring
bs.query() ümbritseb mis tahes asünkroonset funktsiooni vahemällu salvestamise, duplikaatide eemaldamise ja aegumise juhtimisega. Kui päring on pooleli, tagastavad mitu sama võtmega kutset sama lubaduse (duplikaatpäringuid ei tehta).
// 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 }
);
Esimene argument on vahemälu võti (mis tahes string). Teine on funktsioon, mis tagastab lubaduse. Kolmas on valikuline suvandite objekt:
| Suvand | Tüüp | Kirjeldus |
|---|---|---|
staleTime |
number |
Millisekundid, mille möödudes käsitletakse vahemällu salvestatud andmeid aegununa. 0 (vaikimisi) hangib andmed alati uuesti. |
Kui vahemälus on selle võtme andmed ja nende vanus on väiksem kui staleTime, tagastatakse vahemällu salvestatud väärtus kohe, funktsiooni välja kutsumata.
Muuda
bs.mutate() haldab kirjutamistoiminguid optimistlike uuendustega ja tõrke korral automaatse tagasipööramisega. Sellel on kaks režiimi: automaatrežiim levinud CRUD-mustrite jaoks ja käsitsirežiim täielikuks juhtimiseks.
Automaatrežiim töötab reaktiivse olekuobjektiga (nt Alpine.js $data). Edasta state, key, action ja soovi korral 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),
});
Edu korral asendatakse optimistlikud andmed serveri vastusega. Tõrke korral taastatakse olek hetktõmmisele, mis tehti enne muutmist. Vahemälu võti muudetakse pärast iga edukat muudatust automaatselt kehtetuks.
Ebaõnnestumine tähendab, et fn tagastatud lubadus lükatakse tagasi. bs.db() ja
bs.fn() lahenevad valideerimisvea, puuduva kirje või ebaõnnestunud õiguste kontrolli korral vastuse sisuga, seega visake viga, kui tulemus sisaldab code ja ka need juhud peaksid muudatused tagasi pöörama:
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)),
});
Loomistoimingute puhul määratakse optimistlikule üksusele ajutine id (nt __temp_1). Kui server vastab, asendatakse ajutine üksus õigete andmetega, sealhulgas serveri määratud id-ga.
Käsitsirežiim annab täieliku juhtimise tagasihelistustega before, onSuccess ja 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;
},
});
| Suvand | Tüüp | Režiim | Kirjeldus |
|---|---|---|---|
fn |
function |
Mõlemad | Muudatuse teostav asünkroonne funktsioon. Kohustuslik. |
state |
object |
Automaatne | Reaktiivne olekuobjekt (e.g., Alpine $data). |
key |
string |
Automaatne | Oleku atribuudi nimi, mis sisaldab massiivi. Kasutatakse ka vahemälu võtmena. |
action |
string |
Automaatne | Üks väärtustest create, update või delete. |
id |
any |
Automaatne | Kirje ID toimingute update ja delete jaoks. |
optimistic |
object |
Automaatne | Enne serveri vastust optimistlikult rakendatavad andmed. |
before |
function |
Käsitsi | Kutsutakse enne fn. Tagastusväärtus antakse väärtusena snapshot edasi funktsioonidele onSuccess/onError. |
onSuccess |
function |
Käsitsi | Kutsutakse eduka tulemuse korral väärtusega (result, snapshot). |
onError |
function |
Käsitsi | Kutsutakse tõrke korral väärtusega (error, snapshot). |
invalidate |
string |
Käsitsi | Edu korral kehtetuks tunnistatav vahemälu võti. |
PHP API
Klass Db pakub samu toiminguid serveripoolel. Kasuta seda rpc.php-is,
cron.php-is, mallides või mis tahes PHP-koodis.
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);
Ühe skeemiga plokkide puhul:
$db = Db::get('my-theme/block');
Reaalaja küsitlus
Lisa skeemile realtime, et lubada automaatne küsitlus. Kui andmed serveris muutuvad, uuendab UI end automaatselt Interactivity API poe kaudu. JavaScript muudatusi pole vaja.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Kui kasutusel on true, küsitleb Blockstudio iga 3 sekundi järel, kasutades skeemi nime Interactivity API oleku võtmena (ühe skeemiga plokkide puhul default).
Kohandatud seadistus
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Suvand | Tüüp | Vaikeväärtus | Kirjeldus |
|---|---|---|---|
key |
string |
skeemi nimi | Atribuudi nimi objektis state, mis sisaldab andmemassiivi |
interval |
number |
3000 |
Küsitluste vahemik millisekundites |
Kuidas see töötab
- Lehe laadimisel hangib klient praeguste andmete kergekaalulise räsi
- Iga
intervalmillisekundi järel hangib see räsi uuesti - Kui räsi on muutunud, hangib see kogu andmestiku
- Uued andmed edastatakse Interactivity API poodi
store()kaudu - Kõik selle olekuatribuudiga seotud direktiivid renderdatakse automaatselt uuesti
Küsitlus toimub ainult lehtedel, kus leidub vastav element data-wp-interactive. See peatub, kui brauseri vahekaart on peidetud, ja jätkub, kui see on nähtav.
Räsi lõpp-punkt (?_hash=1) tagastab ainult md5-kontrollsumma ja kirjete arvu, hoides küsitluspäringud väikesena.
Kasutajapõhised andmed
Määra userScoped: true, et piirata kõik kirjed automaatselt praeguse kasutajaga.
Blockstudio lisab veeru user_id, määrab selle loomisel ning piirab kõik toimingud praeguse kasutaja kirjetega:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Käsitsi pole vaja user_id välja ega before_create hook’i lisada ega filtreerida RPC-is. Kasutajad näevad, muudavad ja kustutavad ainult enda kirjeid. Veergu user_id haldab täielikult Blockstudio.
Salvestusrežiimi post_type kasutamisel vastendatakse userScoped eraldi veeru user_id asemel väärtusega post_author.
Juurdepääsukontroll
Igal CRUD-toimingul on oma õigustase:
| Väärtus | Käitumine |
|---|---|
true |
Avalik CSRF-kaitsega (väljalogitud kasutajad lubatud, vajalik X-BS-Token) |
'open' |
Täiesti avalik, ilma CSRF-i ja autentimiseta (veebihaakide ja väliste API-de jaoks) |
'edit_posts' |
WordPress võimekuse kontroll |
['cap_a', 'cap_b'] |
Kasutajal peab olema loetletud võimekustest vähemalt üks |
välja jäetud / null |
Nõuab autentimist (sisselogitud kasutaja) |
'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-kaitse
Avalikud lõpp-punktid (true) on kaitstud päisega X-BS-Token. bs.db() ja bs.fn() hangivad värsked mandaadid vahemällu salvestamata sama päritoluga lõpp-punktist, selle asemel et lisada aeguvad tunnused lehe HTML sisse. Pikaajalistest välistest vahemäludest serveeritavad lehed töötavad edasi. Anonüümsed kutsed ilma kehtiva tunnuseta saavad vastuseks 403.
Mandaate küsitakse esimese API kutse korral, mitte iga lehevaatamisega. Mõlemad kliendid, sealhulgas andmebaasi reaalajas küsitlused, jagavad üht pooleliolevat mandaatide värskendust. Mandaate värskendatakse pärast viit minutit kasutamist. Tagasilükatud WordPress nonce või Blockstudio CSRF-token käivitab ühe värskenduse ja korduskatse; tavaliste õiguste vigade korral korduskatset ei tehta. Sisselogitud päringutes kasutatakse endiselt külastaja sessiooni ning skeemi võimekuse ja kirje omandi kontrolli.
Hoia POST /wp-json/blockstudio/v1/client/credentials eemal igasugusest puhverserveri või CDN vahemälust. See saadab Cache-Control: private, no-store ja nõuab sama päritoluga päringut, milles on mittelihtpäis. Sisseehitatud kliendid teevad seda automaatselt.
Kasuta 'open', kui vajad tõeliselt autentimata juurdepääsu ilma CSRF-kaitseta, näiteks välistest teenustest saabuvate veebihaakide jaoks.
Väljatüübid
| Tüüp | MySQL veerg | Tüüp PHP | Kirjeldus |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Tekst, vaikimisi maxLength 255 |
integer |
bigint(20) |
int |
Täisarvud |
number |
decimal(20,6) |
float |
Kümnendarvud |
boolean |
tinyint(1) |
bool |
Tõene/väär |
text |
longtext |
string |
Pikk tekstisisu |
Valideerimine
Kõik kirjutamistoimingud (loomine ja uuendamine) valideeritakse enne salvestuse muutmist skeemi alusel. Valideerimine toimub serveris sõltumata sellest, kas päring tuleb allikast bs.db(), kliendist REST API või kohast Db::get().
Sisseehitatud reeglid
| Reegel | Näide | Kirjeldus |
|---|---|---|
required |
'required' => true |
Väli peab loomisel olemas olema |
type |
'type' => 'integer' |
Väärtus peab vastama deklareeritud tüübile |
enum |
'enum' => ['a', 'b'] |
Väärtus peab olema üks loetletud valikutest |
maxLength |
'maxLength' => 100 |
String ei tohi olla sellest pikkusest pikem |
minLength |
'minLength' => 3 |
String peab olema vähemalt nii pikk |
format: "email" |
'format' => 'email' |
Peab olema kehtiv e-posti aadress |
format: "url" |
'format' => 'url' |
Peab olema kehtiv URL |
Kohandatud valideerimine
Lisa mis tahes väljale tagasihelistus validate, et teha serveripoolseid kontrolle, mis lähevad sisseehitatud reeglitest kaugemale. Edu korral tagasta true või vea kirjeldusstring:
'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;
},
],
Tagasihelistus saab argumendiks välja väärtuse ja kogu andmemassiivi, nii et saad valideerida väljadevahelisi seoseid.
Veavastuse vorming
Valideerimisvead tagastavad oleku 400 ja iga välja kohta veamassiivid. Vorming on inspireeritud Zod fieldErrors-ist ning teeb vigade vormiväljadega sidumise lihtsaks:
{
"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."]
}
}
}
Iga väli seotakse veateadete stringide massiiviga. Samal väljal võib mitu reeglit läbi kukkuda. Kasutajaliideses:
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 lõpp-punktid
Kõik lõpp-punktid asuvad nimeruumis blockstudio/v1/db/:
/db/{block-name}/{schema-name}
Ploki nimes asendatakse / väärtusega -. Ühe skeemiga plokkide puhul on skeemi nimi default.
| Meetod | Lõpp-punkt | Kirjeldus |
|---|---|---|
GET |
/db/{block}/{schema} |
Kirjete loendamine |
POST |
/db/{block}/{schema} |
Kirje loomine |
GET |
/db/{block}/{schema}/{id} |
Ühe kirje hankimine |
PUT |
/db/{block}/{schema}/{id} |
Kirje uuendamine |
DELETE |
/db/{block}/{schema}/{id} |
Kirje kustutamine |
Päringu parameetrid (loend)
| Parameeter | Kirjeldus |
|---|---|
limit |
Tagastatavate kirjete maksimum (vaikimisi 50, max 100) |
offset |
Vahele jäetavate kirjete arv |
| Mis tahes välja nimi | Filtreeri täpse väärtuse alusel |
Näide: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Vormi renderdamine
Väljad võivad määrata võtme component, mis viitab plokile Blockstudio. Kutsu mallis välja bs_db_form(), et renderdada kõik väljad vormina nende komponendiplokke kasutades.
'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>
Iga komponent saab kogu välja määratluse atribuudina field, nii et komponendid saavad skeemi põhjal oma renderdust kohandada. Näiteks $a['field']['name'] annab välja nime, $a['field']['type'] tüübi, $a['field']['required'] näitab, kas väli on kohustuslik, jne.
Komponendi struktuur järgib sama vormingut name, attributes, innerBlocks nagu WordPress plokid. Siseplokid renderdatakse kõigepealt ja edastatakse vanemplokile kujul $content.
PHP kasutamiseks ilma väljastamata:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hook’id
Tegevused käivituvad enne ja pärast iga kirjutamistoimingut. Kõik hook’id saavad ühe $params massiivi. Täieliku loendi leiate viitest PHP Hook’id.
Sisemised hook’id
Määratlege hook’id otse failis db.php. Need seotakse automaatselt selle skeemiga, nii et ploki või skeemi nime pole vaja kontrollida:
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']);
},
],
];
Globaalsed hook’id
Kuulake kõiki skeeme kõikjalt:
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
}
});
Kombineerimine süsteemiga RPC
db.php ja rpc.php on sõltumatud süsteemid. db.php loob skeemimääratluse põhjal CRUD-lõpp-punktid. rpc.php määratleb kohandatud serverifunktsioonid. Kumbki töötab ka eraldi.
Kasutage neid koos, kui vajate tavalisi andmetoiminguid ja kohandatud äriloogikat:
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',
],
];
Teisaldatavus
JSONC salvestusruumi korral paiknevad andmed koodi kõrval. Kopeerige ploki kaust teisele saidile ja kõik liigub koos: UI, loogika, juurdepääsukontroll ja andmed ise.
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
Pole andmebaasi migratsioone ega eksportimise ja importimise samme. Lihtsalt kopeerige kaust.
Ka Storh salvestusruum on teisaldatav, kuid paikneb ploki kausta asemel asukohas uploads/blockstudio/db/. Nii jäävad aktiivsed, kirjutatavad andmed lähtekoodipuust välja, kuid iga skeem saab endiselt lihttekstifailidel põhineva salvestusruumi, mida saab eraldi varundada, kopeerida või migreerida.
Filtreeri
Muutke skeeme programmiliselt väljastpoolt plokki:
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;
});