Liigu sisu juurde

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

  1. Loo oma ploki kataloogis db.php
  2. See tagastab skeemi: väljad, tüübid, valideerimisreeglid ja juurdepääsukontroll
  3. Blockstudio loob salvestuskoha (tabeli, faili või post meta)
  4. Automaatselt luuakse viis REST lõpp-punkti (loendamine, hankimine, loomine, uuendamine, kustutamine)
  5. bs.db() ja Db::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.

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

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

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.

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

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

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

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

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

Ühe skeemiga plokkide puhul:

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

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

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

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:

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

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

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

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:

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

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:

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

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:

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

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

Ühe skeemiga plokkide puhul:

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

PHP
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

PHP
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

  1. Lehe laadimisel hangib klient praeguste andmete kergekaalulise räsi
  2. Iga interval millisekundi järel hangib see räsi uuesti
  3. Kui räsi on muutunud, hangib see kogu andmestiku
  4. Uued andmed edastatakse Interactivity API poodi store() kaudu
  5. 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:

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

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

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:

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

Iga väli seotakse veateadete stringide massiiviga. Samal väljal võib mitu reeglit läbi kukkuda. Kasutajaliideses:

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 lõpp-punktid

Kõik lõpp-punktid asuvad nimeruumis blockstudio/v1/db/:

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

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>

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:

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

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

Globaalsed hook’id

Kuulake kõiki skeeme kõikjalt:

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

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:

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

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.

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

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