Tietokanta
Tietokantakerroksessa voit määrittää lohkollesi tietomallin db.php-tiedostossa. Blockstudio luo automaattisesti REST CRUD-päätepisteet, validoi syötteen skeemaa vasten, hallinnoi tallennusta ja tarjoaa sekä JavaScript-asiakasohjelman (bs.db()) että PHP APIn (Db-luokan).
Tämä on täysimittaisten lohkojen tietoperusta. Siinä missä RPC hoitaa mukautetun logiikan, tietokantakerros käsittelee rakenteista dataa ilman ylimääräistä pohjakoodia.
Näin se toimii
- Luo
db.phplohkohakemistoosi - Se palauttaa skeeman: kentät, tyypit, validointisäännöt ja käyttöoikeuksien hallinta
- Blockstudio luo tallennustilan (taulukko, tiedosto tai artikkelin metatiedot)
- Viisi REST-päätepistettä luodaan automaattisesti (listaus, haku, luonti, päivitys, poisto)
bs.db()jaDb::get()tarjoavat asiakas- ja palvelinkäytön
Ei migraatioita, ohjaimia eikä reittien rekisteröintiä.
Välitä kirjaimelliset arvot REST- ja PHP-rajapinnoille. Taustajärjestelmät meta ja post_type käsittelevät WordPress-metatietojen kenoviivoituksen itse ja säilyttävät kenoviivat sekä lainausmerkein rajatut merkkijonot sekä skalaariarvoissa että sisäkkäisissä objekteissa tai taulukoissa. Älä lisää tietokantatietueiden arvoihin kenoviivoja etukäteen.
Skeemojen määrittely
Yksi skeema
Yksinkertaisin muoto: yksi tietomalli lohkoa kohden.
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-natiivi rakentajasyntaksi
db.php voi käyttää myös pientä rakentaja-APIa, joka perustuu nimettyihin argumentteihin ja vain luku -määrittelyobjekteihin. Taulukot säilyvät oletusmuotona, mutta tämä tarjoaa helpommin hahmotettavan PHP-natiivin vaihtoehdon, kun skeema kasvaa.
<?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'),
],
);
Käytä Schema::make() yhtä skeemaa varten tai palauta nimettyjen Schema::make(...)-kutsujen taulukko lohkoille, joissa on useita skeemoja.
Useita skeemoja
Yksi lohko voi sisältää useita tietomalleja. Palauta nimetty taulukko:
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'],
],
],
];
Jokaisella skeemalla on omat päätepisteet, tallennustila ja käyttöoikeuksien hallinta.
Tallennustilat
Kuusi tallennustaustaa eri käyttötarkoituksiin.
Mukautettu taulukko (storage: "table")
Jokainen tietue on rivinä erillisessä MySQL-taulukossa. Blockstudio luo taulukon automaattisesti ja hallinnoi sitä käyttämällä WordPressn dbDelta()-funktiota. Uusien kenttien lisääminen skeemaan lisää sarakkeet seuraavalla sivulatauksella. Olemassa olevia sarakkeita ei koskaan poisteta.
Sopii parhaiten rakenteiselle datalle, kyselyille ja tuotantosovelluksille.
SQLite (storage: "sqlite")
Jokaisella skeemalla on oma SQLite-tietokantatiedosto db/-alikansiossa. Blockstudio luo tiedoston ja taulukon automaattisesti sekä lisää puuttuvat sarakkeet skeeman muuttuessa (kuten dbDelta MySQLlle). Käyttää WAL-päiväkirjatilaa samanaikaisten lukujen suorituskyvyn parantamiseksi.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Sopii parhaiten rakenteiselle datalle, joka tarvitsee oikeita SQL-kyselyitä mutta jonka on pysyttävä siirrettävänä. Käsittelee tehokkaasti tuhansia tietueita lataamatta kaikkea muistiin. Siirrä data kopioimalla kansio.
JSONC-tiedostot (storage: "jsonc")
Tietueet tallennetaan yksi JSON-objekti riville .jsonc-tiedostoon db/-alikansiossa. Tiedosto luodaan automaattisesti ensimmäisellä kirjoituskerralla. Merkillä // alkavat rivit tulkitaan kommenteiksi ja säilytetään.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Sopii parhaiten pienille tietojoukoille, asetustyyppiselle datalle, alustustietueille ja versionhallintaan soveltuville esimerkeille. JSONC on tarkoituksella yksi tiedosto lohkokansiossasi. Käytä sitä, kun haluat datan kulkevan koodin mukana, älä silloin, kun odotat useita samanaikaisia kirjoituksia.
Storh-tiedostot (storage: "storh")
Storh tallentaa jokaisen tietueen erillisenä tiedostona osoitteessa 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
Julkiset tietuetunnukset pysyvät samoina kokonaislukutunnuksina kuin muualla bs.db()ssa. Blockstudio yhdistää nämä tunnukset Storhn sisäisiin UUIDv7-tiedostotunnuksiin ja tallentaa kokonaisluvun id tietuedataan, joten JavaScript-, REST- ja PHP-kutsujien ei tarvitse käsitellä UUID-tunnuksia.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio luo Storh-indeksit skeemasi perusteella. Koska jokaista määritettyä kenttää voi käyttää listasuodattimena, kaikki määritetyt kentät indeksoidaan. Kokonaisluku-, numero- ja päivämääräkentät käyttävät alueindeksejä; 'unique' => true– tai 'index' => 'unique'-merkityt kentät käyttävät yksilöllisyysindeksejä.
Sopii parhaiten tuotantokäyttöön tarkoitettuun tiedostopohjaiseen dataan, joka tarvitsee turvallisempia samanaikaisia kirjoituksia, skeemasta johdettuja indeksejä ja siirrettävää uploads-tason tallennusta ilman, että aktiiviset tietueet lisätään lohkon lähdekoodipuuhun.
JSONCn siirtäminen muotoon Storh
Jos aloitit .jsonc-tiedostolla ja haluat samat tietueet Storheen, suorita:
wp bs db migrate my-theme/app subscribers --to=storh
Yhden skeeman lohkoille:
wp bs db migrate my-theme/app --to=storh
Siirto lukee olemassa olevan db/{schema}.jsoncn, kirjoittaa tietueet muotoon Storh säilyttäen kokonaislukutunnukset, luo indeksit uudelleen, tarkistaa kohdetallennuksen ja jättää JSONC-tiedoston koskemattomaksi. Palautus onnistuu vaihtamalla skeeman storage takaisin arvoon "jsonc".
Artikkelin metatiedot (storage: "meta")
Tietueet tallennetaan JSON-taulukkona WordPress-artikkelin metatietoihin ja liitetään tiettyyn artikkeliin postIdn avulla.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Sopii parhaiten tietylle artikkelille tai sivulle kuuluvalle datalle.
Mukautettu artikkelityyppi (storage: "post_type")
Jokainen tietue on WordPress-artikkeli automaattisesti rekisteröidyssä mukautetussa artikkelityypissä. Jokaisesta skeeman kentästä tulee erillinen post_meta-merkintä. Näin tietueita voi hakea WP_Querylla, ne ovat yhteensopivia REST API -lisäosien kanssa ja näkyvät työkaluille, kuten GraphQL.
Sopii parhaiten datalle, jonka tulee integroitua WordPressiin natiivisti. Jokainen kenttä on erikseen haettavissa ja indeksoitavissa.
JavaScript-asiakas
Blockstudio lisää bs.db()n sivuille, joilla on tietokantalohkoja. Se palauttaa objektin, jossa on viisi metodia:
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);
Ensimmäinen argumentti on lohkon nimi (mukana /), toinen on skeeman nimi. Yhden skeeman lohkoissa skeeman nimen voi jättää pois (oletusarvo on "default").
Välimuisti
bs.cache on muistissa oleva kyselyvälimuisti, joka on jaettu kaikkien bs.query– ja bs.mutate-kutsujen kesken. Voit käyttää sitä myös suoraan:
// 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();
Välimuistimerkinnät tallennetaan muistiin ja tyhjennetään sivun navigoinnin yhteydessä. Niitä käyttävät pääasiassa sisäisesti bs.query ja bs.mutate, mutta suora käyttö on hyödyllistä datan esilataamiseen tai välimuistin mitätöimiseen manuaalisesti mukautettujen toimintojen jälkeen.
Kysely
bs.query() käärii asynkronisen funktion ja lisää siihen välimuistituksen, päällekkäisten kutsujen yhdistämisen ja vanhenemisen hallinnan. Useat kutsut samalla avaimella käynnissä olevan pyynnön aikana palauttavat saman promisen (ei päällekkäisiä hakuja).
// 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 }
);
Ensimmäinen argumentti on välimuistiavain (mikä tahansa merkkijono). Toinen on promise-olion palauttava funktio. Kolmas on valinnainen asetusobjekti:
| Asetus | Tyyppi | Kuvaus |
|---|---|---|
staleTime |
number |
Millisekunnit, joiden jälkeen välimuistissa oleva data katsotaan vanhentuneeksi. 0 (oletus) hakee aina uudelleen. |
Jos välimuistissa on avaimen data ja se on nuorempaa kuin staleTime, välimuistiarvo palautetaan heti kutsumatta funktiota.
Muuta
bs.mutate() käsittelee kirjoitustoiminnot optimistisilla päivityksillä ja palauttaa automaattisesti aiempaan tilaan virheen sattuessa. Käytössä on kaksi tilaa: automaattinen tila tavallisille CRUD-toiminnoille ja manuaalinen tila täyteen hallintaan.
Automaattinen tila toimii reaktiivisen tilan objektin kanssa (kuten Alpine.js $data). Anna sille state, key, action ja halutessasi 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),
});
Onnistumisen jälkeen palvelimen vastaus korvaa optimistisen datan. Virheen sattuessa tila palautetaan ennen muutosta otettuun tilannekuvaan. Välimuistiavain mitätöidään automaattisesti jokaisen onnistuneen muutoksen jälkeen.
Virhe tarkoittaa, että kohteen fn palauttama promise hylätään. bs.db() ja bs.fn() palauttavat virheen sisältävän vastauksen validointivirheen, puuttuvan tietueen tai epäonnistuneen käyttöoikeustarkistuksen yhteydessä, joten heitä poikkeus, kun tulos sisältää coden, jos näidenkin tapausten pitäisi palauttaa tila:
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)),
});
Luontitoiminnoissa optimistiselle kohteelle annetaan väliaikainen id (kuten __temp_1). Kun palvelin vastaa, väliaikainen kohde päivitetään todellisilla tiedoilla, mukaan lukien palvelimen määrittämä id.
Manuaalinen tila antaa täyden hallinnan before-, onSuccess– ja onError-takaisinkutsujen avulla:
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;
},
});
| Asetus | Tyyppi | Tila | Kuvaus |
|---|---|---|---|
fn |
function |
Molemmat | Muutoksen suorittava asynkroninen funktio. Pakollinen. |
state |
object |
Automaattinen | Reaktiivisen tilan objekti (e.g., Alpine $data). |
key |
string |
Automaattinen | Tilan ominaisuuden nimi, johon taulukko tallennetaan. Käytetään myös välimuistiavaimena. |
action |
string |
Automaattinen | Yksi arvoista create, update tai delete. |
id |
any |
Automaattinen | Tietueen tunnus toiminnoille update ja delete. |
optimistic |
object |
Automaattinen | Optimistisesti käytettävät tiedot ennen palvelimen vastausta. |
before |
function |
Manuaalinen | Kutsutaan ennen kohdetta fn. Palautusarvo välitetään kohteelle onSuccess/onError arvona snapshot. |
onSuccess |
function |
Manuaalinen | Kutsutaan arvolla (result, snapshot) onnistumisen yhteydessä. |
onError |
function |
Manuaalinen | Kutsutaan arvolla (error, snapshot) virheen yhteydessä. |
invalidate |
string |
Manuaalinen | Onnistumisen yhteydessä mitätöitävä välimuistiavain. |
PHP API
Db-luokka tarjoaa samat toiminnot palvelinpuolella. Käytä sitä kohdissa rpc.php, cron.php, malleissa tai missä tahansa PHP-koodissa.
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);
Yhden skeeman lohkoille:
$db = Db::get('my-theme/block');
Reaaliaikainen kysely
Lisää realtime skeemaasi ottaaksesi automaattisen kyselyn käyttöön. Kun data muuttuu palvelimella, UI päivittyy automaattisesti Interactivity API -säilön kautta. JavaScript-muutoksia ei tarvita.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Kun käytössä on true, Blockstudio kyselee 3 sekunnin välein käyttäen skeeman nimeä Interactivity API -tilan avaimena (default yhden skeeman lohkoissa).
Mukautetut asetukset
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Asetus | Tyyppi | Oletus | Kuvaus |
|---|---|---|---|
key |
string |
skeeman nimi | staten ominaisuuden nimi, johon datataulukko tallennetaan |
interval |
number |
3000 |
Kyselyväli millisekunteina |
Näin se toimii
- Sivun latautuessa asiakasohjelma hakee kevyen tiivisteen nykyisestä datasta
- Joka
intervalmillisekunti se hakee tiivisteen uudelleen - Jos tiiviste on muuttunut, se hakee koko tietojoukon
- Uusi data viedään Interactivity API -säilöön kohteen
store()kautta - Kaikki kyseiseen tilan ominaisuuteen sidotut direktiivit renderöidään uudelleen automaattisesti
Kysely toimii vain sivuilla, joilla vastaava data-wp-interactive-elementti on olemassa. Se keskeytyy, kun selaimen välilehti on piilotettu, ja jatkuu, kun välilehti tulee näkyviin.
Tiivistepäätepiste (?_hash=1) palauttaa vain MD5-tarkistussumman ja tietuemäärän, joten kyselypyynnöt pysyvät kevyinä.
Käyttäjäkohtainen data
Aseta userScoped: true, niin kaikki tietueet rajataan automaattisesti nykyiseen käyttäjään. Blockstudio lisää user_id-sarakkeen, asettaa sen luotaessa ja suodattaa kaikki toiminnot nykyisen käyttäjän tietueisiin:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Ei manuaalista user_id-kenttää, before_create-koukkua eikä suodatusta kohdassa RPC. Käyttäjät voivat nähdä, muokata ja poistaa vain omia tietueitaan. user_id-saraketta hallinnoi kokonaan Blockstudio.
Käytettäessä post_type-tallennusta userScoped yhdistetään kohteeseen post_author erillisen user_id-sarakkeen sijaan.
Käyttöoikeuksien hallinta
Jokaisella CRUD-toiminnolla on oma käyttöoikeustasonsa:
| Arvo | Toiminta |
|---|---|
true |
Julkinen CSRF-suojauksella (kirjautumattomat käyttäjät sallitaan, X-BS-Token vaaditaan) |
'open' |
Aidosti julkinen, ei CSRF-suojausta eikä tunnistautumista (webhookeille ja ulkoisille API-rajapinnoille) |
'edit_posts' |
WordPress-kyvykkyyden tarkistus |
['cap_a', 'cap_b'] |
Käyttäjällä on oltava jokin luetelluista kyvykkyyksistä |
pois jätetty / null |
Edellyttää tunnistautumista (sisäänkirjautunut käyttäjä) |
'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-suojaus
Julkiset päätepisteet (true) on suojattu X-BS-Token-otsakkeella. bs.db() ja bs.fn() hakevat uudet tunnistetiedot välimuistittamattomasta saman alkuperän päätepisteestä sen sijaan, että sivun HTML-sisältöön upotettaisiin vanhenevia tunnisteita. Pitkäaikaisissa ulkoisissa välimuisteissa olevat sivut toimivat edelleen. Anonyymit kutsut ilman kelvollista tunnistetta saavat vastaukseksi 403-tilakoodin.
Tunnistetietoja pyydetään ensimmäisellä API-kutsulla, ei jokaisella sivun katselukerralla. Molemmat asiakasohjelmat, myös tietokannan reaaliaikainen kysely, käyttävät samaa käynnissä olevaa tunnistetietojen päivitystä. Tunnistetiedot päivitetään viiden minuutin käytön jälkeen. Vanhentunut WordPress-nonce tai Blockstudio CSRF-tunniste käynnistää yhden päivitys- ja uudelleenyritysyrityksen; tavallisia käyttöoikeusvirheitä ei yritetä uudelleen. Kirjautuneiden pyynnöissä käytetään edelleen vierailevan käyttäjän istuntoa sekä skeeman kyvykkyys- ja tietueen omistajuustarkistuksia.
Pidä POST /wp-json/blockstudio/v1/client/credentials kaikkien välityspalvelinten tai CDN-välimuistien ulkopuolella. Se lähettää Cache-Control: private, no-store-otsakkeen ja edellyttää saman alkuperän pyyntöä, jossa on ei-yksinkertainen otsake. Sisäänrakennetut asiakasohjelmat hoitavat tämän automaattisesti.
Käytä 'open', kun tarvitset aidosti tunnistautumatonta käyttöä ilman CSRF-suojausta, esimerkiksi ulkoisista palveluista tuleville webhookeille.
Kenttätyypit
| Tyyppi | MySQL-sarake | PHP-tyyppi | Kuvaus |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Teksti, oletusarvoinen enimmäispituus 255 |
integer |
bigint(20) |
int |
Kokonaisluvut |
number |
decimal(20,6) |
float |
Desimaaliluvut |
boolean |
tinyint(1) |
bool |
Tosi/epätosi |
text |
longtext |
string |
Pitkä tekstisisältö |
Validointi
Kaikki kirjoitukset (luonti ja päivitys) validoidaan skeemaa vasten ennen tallennustilan käsittelyä. Validointi tehdään palvelinpuolella riippumatta siitä, tuleeko pyyntö kohteesta bs.db(), REST APIsta vai kohteesta Db::get().
Sisäänrakennetut säännöt
| Sääntö | Esimerkki | Kuvaus |
|---|---|---|
required |
'required' => true |
Kentän on oltava mukana luonnin yhteydessä |
type |
'type' => 'integer' |
Arvon on vastattava määritettyä tyyppiä |
enum |
'enum' => ['a', 'b'] |
Arvon on oltava jokin luetelluista vaihtoehdoista |
maxLength |
'maxLength' => 100 |
Merkkijono ei saa ylittää tätä pituutta |
minLength |
'minLength' => 3 |
Merkkijonon on oltava vähintään tämän pituinen |
format: "email" |
'format' => 'email' |
Oltava kelvollinen sähköpostiosoite |
format: "url" |
'format' => 'url' |
Oltava kelvollinen URL |
Mukautettu validointi
Lisää validate-takaisinkutsu mihin tahansa kenttään palvelinpuolen tarkistuksia varten, kun sisäänrakennetut säännöt eivät riitä. Palauta true, jos tarkistus menee läpi, tai merkkijono, jossa on virheilmoitus:
'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;
},
],
Takaisinkutsu saa kentän arvon ja koko data-taulukon, joten voit validoida kenttien välisiä suhteita.
Virhevastausten muoto
Validointivirheet palauttavat 400-tilan ja kenttäkohtaiset virhetaulukot. Tämä muoto on saanut vaikutteita Zodn fieldErrorssta, ja virheet on helppo yhdistää lomakekenttiin:
{
"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."]
}
}
}
Kukin kenttä vastaa virheviestien taulukkoa. Samassa kentässä voi olla useita sääntörikkeitä. Käyttöliittymässä:
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-päätepisteet
Kaikki päätepisteet ovat blockstudio/v1/db/-nimiavaruudessa:
/db/{block-name}/{schema-name}
Lohkon nimessä / korvataan arvolla -. Yhden skeeman lohkoissa skeeman nimi on default.
| Metodi | Päätepiste | Kuvaus |
|---|---|---|
GET |
/db/{block}/{schema} |
Listaa tietueet |
POST |
/db/{block}/{schema} |
Luo tietue |
GET |
/db/{block}/{schema}/{id} |
Hae yksittäinen tietue |
PUT |
/db/{block}/{schema}/{id} |
Päivitä tietue |
DELETE |
/db/{block}/{schema}/{id} |
Poista tietue |
Kyselyparametrit (lista)
| Parametri | Kuvaus |
|---|---|
limit |
Palautettavien tietueiden enimmäismäärä (oletus 50, enintään 100) |
offset |
Ohitettavien tietueiden määrä |
| Mikä tahansa kentän nimi | Suodata tarkan arvon perusteella |
Esimerkki: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Lomakkeen renderöinti
Kentissä voi määrittää component-avaimen, joka viittaa Blockstudio-lohkoon. Kutsu mallipohjassasi funktiota bs_db_form(), niin kaikki kentät renderöidään lomakkeeksi niiden komponenttilohkoja käyttäen.
'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>
Jokainen komponentti saa koko kentän määrittelyn field attribuuteissaan, joten komponentit voivat mukauttaa renderöintiään skeeman perusteella. Esimerkiksi $a['field']['name'] kertoo kentän nimen, $a['field']['type'] tyypin, $a['field']['required'] sen, onko kenttä pakollinen, jne.
Komponentin rakenne noudattaa samaa name-, attributes-, innerBlocks-muotoa kuin WordPress-lohkot. Sisälohkot renderöidään ensin ja välitetään vanhemmalle muodossa $content.
Käytä PHP ilman tulostamista näin:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hookit
Toiminnot suoritetaan ennen jokaista kirjoitusoperaatiota ja sen jälkeen. Kaikki hookit saavat yhden $params-taulukon. Katso PHP-hookien viitteestä täydellinen luettelo.
Rivinsisäiset hookit
Määritä hookit suoraan db.php-määrityksessä. Ne rajautuvat automaattisesti kyseiseen skeemaan, joten lohkon tai skeeman nimeä ei tarvitse tarkistaa:
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']);
},
],
];
Globaalit hookit
Kuuntele kaikkia skeemoja mistä tahansa:
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
}
});
Yhdistäminen: RPC
db.php ja rpc.php ovat itsenäisiä järjestelmiä. db.php luo CRUD-päätepisteet skeeman määrittelystä. rpc.php määrittää mukautettuja palvelinfunktioita. Kumpikin toimii itsenäisesti.
Käytä niitä yhdessä, kun tarvitset sekä tavallisia datatoimintoja että mukautettua liiketoimintalogiikkaa:
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',
],
];
Siirrettävyys
JSONC-tallennuksessa data sijaitsee koodin yhteydessä. Kopioi lohkon kansio toiselle sivustolle, niin kaikki siirtyy mukana: UI, logiikka, käyttöoikeuksien hallinta ja itse data.
my-app/
├── block.json
├── index.twig
├── style.css
├── rpc.php ← custom endpoints
├── db.php ← data schema
├── cron.php ← scheduled tasks
└── db/
└── entries.jsonc ← the actual data
Ei tietokantasiirtoja eikä vienti- tai tuontivaiheita. Kopioi vain kansio.
Myös Storh-tallennus on siirrettävä, mutta se sijaitsee polussa uploads/blockstudio/db/ lohkon kansion sijaan. Näin käytössä oleva, kirjoitettava data pysyy lähdepuun ulkopuolella, mutta jokaisella skeemalla on silti tavallisiin tiedostoihin perustuva tallennus, jonka voi varmuuskopioida, kopioida tai siirtää erikseen.
Suodatin
Muokkaa skeemoja ohjelmallisesti lohkon ulkopuolelta:
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;
});