Siirry sisältöön

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

  1. Luo db.php lohkohakemistoosi
  2. Se palauttaa skeeman: kentät, tyypit, validointisäännöt ja käyttöoikeuksien hallinta
  3. Blockstudio luo tallennustilan (taulukko, tiedosto tai artikkelin metatiedot)
  4. Viisi REST-päätepistettä luodaan automaattisesti (listaus, haku, luonti, päivitys, poisto)
  5. bs.db() ja Db::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.

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

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

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.

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

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

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

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

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

Yhden skeeman lohkoille:

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

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

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

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:

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

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

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

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:

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

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:

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

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:

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

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

Yhden skeeman lohkoille:

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

PHP
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

PHP
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

  1. Sivun latautuessa asiakasohjelma hakee kevyen tiivisteen nykyisestä datasta
  2. Joka interval millisekunti se hakee tiivisteen uudelleen
  3. Jos tiiviste on muuttunut, se hakee koko tietojoukon
  4. Uusi data viedään Interactivity API -säilöön kohteen store() kautta
  5. 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:

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

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

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:

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

Kukin kenttä vastaa virheviestien taulukkoa. Samassa kentässä voi olla useita sääntörikkeitä. Käyttöliittymässä:

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-päätepisteet

Kaikki päätepisteet ovat blockstudio/v1/db/-nimiavaruudessa:

Koodi
/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.

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>

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:

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

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

Globaalit hookit

Kuuntele kaikkia skeemoja mistä tahansa:

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

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:

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

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.

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

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