Preskoči na vsebino

Podatkovna zbirka

Plast podatkovne zbirke vam omogoča, da v datoteki db.php določite podatkovni model za svoj blok. Blockstudio ustvari REST CRUD-končne točke, preveri vhodne podatke glede na shemo, samodejno upravlja shranjevanje ter zagotavlja odjemalca JavaScript (bs.db()) in PHP API (razred Db).

To je podatkovna hrbtenica za bloke s celotnim skladom. Medtem ko RPC skrbi za logiko po meri, plast podatkovne zbirke brez dodatne predloge skrbi za strukturirane podatke.

Kako deluje

  1. V imeniku svojega bloka ustvarite db.php
  2. Ta vrne shemo: polja, vrste, pravila preverjanja in nadzor dostopa
  3. Blockstudio ustvari shrambo (tabelo, datoteko ali metapodatke objave)
  4. Samodejno se ustvari pet končnih točk REST (seznam, pridobivanje, ustvarjanje, posodabljanje, brisanje)
  5. bs.db() in Db::get() omogočata dostop odjemalca in strežnika

Brez migracij, krmilnikov in registracije poti.

Dobesedne vrednosti posredujte API-jema REST in PHP. Zaledna sistema meta in post_type sama obravnavata odstranjevanje poševnic iz meta podatkov WordPress, pri čemer ohranita poševnice nazaj in nize v narekovajih tako v skalarnih vrednostih kot v ugnezdenih objektih ali poljih. Vrednostim iz zapisov v zbirki podatkov ne dodajajte poševnic vnaprej.

Določanje shem

Ena shema

Najpreprostejša oblika: en podatkovni model na blok.

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

Skladnja gradnika za PHP

db.php lahko uporablja tudi majhen gradnik API, ki temelji na poimenovanih argumentih in objektih definicije samo za branje. Nizi ostajajo privzeta oblika, ta možnost pa ponuja bolj pregledno alternativo, prilagojeno za PHP, ko se shema poveča.

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

Za eno shemo uporabite Schema::make(), za bloke z več shemami pa vrnite polje poimenovanih klicev Schema::make(...).

Več shem

En blok ima lahko več podatkovnih modelov. Vrnite poimenovano polje:

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

Vsaka shema dobi svoje končne točke, shrambo in nadzor dostopa.

Načini shranjevanja

Šest zalednih sistemov za shranjevanje, vsak primeren za drugačne potrebe.

Tabela po meri (storage: "table")

Vsak zapis je vrstica v namenski tabeli MySQL. Blockstudio tabelo samodejno ustvari in upravlja s funkcijo dbDelta() iz WordPress. Dodajanje novih polj v shemo doda stolpce ob naslednjem nalaganju strani. Obstoječi stolpci se nikoli ne odstranijo.

Najprimernejše za: strukturirane podatke, poizvedbe in produkcijske aplikacije.

SQLite (storage: "sqlite")

Vsaka shema dobi svojo datoteko podatkovne zbirke SQLite v podmapi db/. Blockstudio samodejno ustvari datoteko in tabelo ter ob spremembi sheme doda manjkajoče stolpce (kot dbDelta za MySQL). Uporablja način dnevnika WAL za sočasno branje.

Koda
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

Najprimernejše za: strukturirane podatke, ki potrebujejo prave poizvedbe SQL, vendar morajo ostati prenosljivi. Učinkovito obdela na tisoče zapisov, ne da bi jih vse naložil v pomnilnik. Za prenos podatkov kopirajte mapo.

Datoteke JSONC (storage: "jsonc")

Zapisi so v datoteki .jsonc v podmapi db/ shranjeni kot po en objekt JSON v vsaki vrstici. Datoteka se samodejno ustvari ob prvem pisanju. Vrstice, ki se začnejo z //, so obravnavane kot komentarji in ohranjene.

Koda
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

Najprimernejše za: majhne nabore podatkov, podatke, podobne konfiguracijskim, začetne zapise in primere, ki jih je mogoče nadzorovati z različicami. JSONC je namenoma ena sama datoteka v mapi vašega bloka. Uporabite jo, kadar želite, da se podatki prenašajo skupaj s kodo, ne pa kadar pričakujete veliko sočasnih zapisov.

Datoteke Storh (storage: "storh")

Storh vsak zapis shrani kot posamezno datoteko v naložene datoteke WordPress:

Koda
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

Javni ID-ji zapisov ostanejo enaka celoštevilska ID-ja, kot ju uporablja preostali del bs.db(). Blockstudio te ID-je preslika v interne ID-je datotek UUIDv7 v Storh in v podatke zapisa shrani celo število id, zato klicateljem JavaScript, REST in PHP ni treba obravnavati UUID-jev.

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Blockstudio iz vaše sheme izdela indekse Storh. Ker je vsako deklarirano polje mogoče uporabiti kot filter seznama, se indeksira vsako deklarirano polje. Polja s celoštevilskimi, številskimi in datumi podobnimi vrednostmi uporabljajo območne indekse; polja, označena z 'unique' => true ali 'index' => 'unique', uporabljajo enolične indekse.

Najprimernejše za: produkcijske podatke v datotekah, ki potrebujejo varnejše sočasno zapisovanje, indekse, izpeljane iz sheme, in prenosljivo shranjevanje na ravni naloženih datotek brez vključevanja aktivnih zapisov v izvorno drevo bloka.

Selitev iz JSONC v Storh

Če ste začeli z datoteko .jsonc in želite iste zapise v Storh, zaženite:

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

Za bloke z eno shemo:

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

Selitev prebere obstoječi db/{schema}.jsonc, zapiše zapise v Storh in pri tem ohrani celoštevilske ID-je, znova izdela indekse, preveri ciljno shrambo ter pusti datoteko JSONC nedotaknjeno. Za povrnitev je dovolj, da možnost storage v shemi spremenite nazaj na "jsonc".

Metapodatki objave (storage: "meta")

Zapisi so v metapodatkih objave WordPress shranjeni kot polje JSON in povezani z določeno objavo prek postId.

PHP
return [
    'storage' => 'meta',
    'postId'  => 42,
    'fields'  => [ /* ... */ ],
];

Najprimernejše za: podatke, povezane z določeno objavo ali stranjo.

Vrsta objave po meri (storage: "post_type")

Vsak zapis je objava WordPress v samodejno registrirani vrsti objav po meri. Vsako polje v shemi postane ločen vnos post_meta. Tako je mogoče poizvedovati po zapisih z WP_Query, združljivi so z vtičniki REST API in vidni orodjem, kot je GraphQL.

Najprimernejše za: podatke, ki se morajo izvorno povezovati z WordPress. Po vsakem polju je mogoče samostojno poizvedovati in ga indeksirati.

Odjemalec JavaScript

Blockstudio vstavi bs.db() na strani z bloki podatkovne zbirke. Vrne objekt s petimi metodami:

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

Prvi argument je ime bloka (z /), drugi pa ime sheme. Pri blokih z eno shemo ime sheme izpustite (privzeta vrednost je "default").

Predpomnilnik

bs.cache je skupni predpomnilnik poizvedb v pomnilniku za vse klice bs.query in bs.mutate. Uporabite ga lahko tudi neposredno:

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

Vnosi v predpomnilniku so shranjeni v pomnilniku in se izbrišejo ob prehodu na drugo stran. Uporabljata jih predvsem interno bs.query in bs.mutate, neposreden dostop pa je uporaben za predhodno polnjenje podatkov ali ročno razveljavitev po meri izvedenih operacij.

Poizvedba

bs.query() katero koli asinhrono funkcijo ovije s predpomnjenjem, odstranjevanjem podvojenih zahtev in nadzorom zastarelosti. Več klicev z istim ključem med izvajanjem zahteve vrne isti obljubljeni rezultat (brez podvojenih pridobivanj).

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

Prvi argument je ključ predpomnilnika (poljuben niz). Drugi je funkcija, ki vrne obljubljeni rezultat. Tretji je neobvezen objekt z možnostmi:

Možnost Vrsta Opis
staleTime number Milisekunde, preden predpomnjeni podatki veljajo za zastarele. 0 (privzeto) vedno znova pridobi podatke.

Če predpomnilnik vsebuje podatke za ta ključ in so mlajši od staleTime, se predpomnjena vrednost takoj vrne, ne da bi se poklicala funkcija.

Spreminjanje

bs.mutate() obravnava operacije pisanja z optimističnimi posodobitvami in samodejno povrnitvijo ob napaki. Na voljo sta dva načina: samodejni način za običajne vzorce CRUD in ročni način za popoln nadzor.

Samodejni način deluje z reaktivnim objektom stanja (kot je Alpine.js $data). Podajte state, key, action in po želji 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),
});

Ob uspehu optimistične podatke nadomesti odgovor strežnika. Ob napaki se stanje povrne na posnetek, ustvarjen pred spremembo. Ključ predpomnilnika se samodejno razveljavi po vsaki uspešni spremembi.

Napaka pomeni, da je obljubljeni rezultat, ki ga vrne fn, zavrnjen. bs.db() in bs.fn() ob napaki pri preverjanju, manjkajočem zapisu ali neuspešnem preverjanju dovoljenj vrneta telo napake, zato sprožite izjemo, ko rezultat vsebuje code, če želite, da se tudi ti primeri povrnejo:

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

Pri ustvarjanju se optimističnemu elementu dodeli začasni id (na primer __temp_1). Ko se strežnik odzove, se začasni element dopolni s pravimi podatki, vključno z ID-jem id, ki ga dodeli strežnik.

Ročni način vam omogoča popoln nadzor s povratnimi klici before, onSuccess in 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;
  },
});
Možnost Vrsta Način Opis
fn function Oba Asinhrona funkcija, ki izvede spremembo. Obvezno.
state object Samodejni Reaktivni objekt stanja (e.g., Alpine $data).
key string Samodejni Ime lastnosti stanja, ki vsebuje polje. Uporablja se tudi kot ključ predpomnilnika.
action string Samodejni Ena od možnosti create, update ali delete.
id any Samodejni ID zapisa za dejanja update in delete.
optimistic object Samodejni Podatki, ki se optimistično uporabijo pred odgovorom strežnika.
before function Ročni Pokliče se pred fn. Vrnjena vrednost se kot snapshot posreduje funkcijama onSuccess/onError.
onSuccess function Ročni Pokliče se z (result, snapshot) ob uspehu.
onError function Ročni Pokliče se z (error, snapshot) ob napaki.
invalidate string Ročni Ključ predpomnilnika, ki se ob uspehu razveljavi.

PHP API

Razred Db zagotavlja enake operacije na strežniški strani. Uporabite ga v rpc.php, cron.php, predlogah ali kateri koli kodi PHP.

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

Za bloke z eno shemo:

PHP
$db = Db::get('my-theme/block');

Anketiranje v realnem času

V shemo dodajte realtime, da omogočite samodejno anketiranje. Ob spremembi podatkov na strežniku se UI samodejno posodobi prek shrambe Interactivity API. Spremembe JavaScript niso potrebne.

PHP
return [
    'storage'  => 'table',
    'realtime' => true,
    'fields'   => [ /* ... */ ],
];

Ko je omogočen true, Blockstudio poizveduje vsake 3 sekunde in kot ključ stanja v shrambi Interactivity API uporabi ime sheme (default za bloke z eno shemo).

Nastavitve po meri

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Možnost Vrsta Privzeto Opis
key string ime sheme Ime lastnosti v state, ki vsebuje podatkovno polje
interval number 3000 Interval anketiranja v milisekundah

Kako deluje

  1. Ob nalaganju strani odjemalec pridobi lahek zgoščeni povzetek trenutnih podatkov
  2. Vsakih interval milisekund znova pridobi zgoščeni povzetek
  3. Če se je zgoščeni povzetek spremenil, pridobi celoten nabor podatkov
  4. Novi podatki se prek store() potisnejo v shrambo Interactivity API
  5. Vse direktive, povezane s to lastnostjo stanja, se samodejno znova izrišejo

Anketiranje se izvaja samo na straneh z ustreznim elementom data-wp-interactive. Začasno se ustavi, ko je zavihek brskalnika skrit, in nadaljuje, ko postane viden.

Končna točka zgoščenega povzetka (?_hash=1) vrne samo kontrolno vsoto md5 in število zapisov, zato so zahteve za anketiranje majhne.

Podatki za posameznega uporabnika

Nastavite userScoped: true, da se vsi zapisi samodejno omejijo na trenutnega uporabnika. Blockstudio doda stolpec user_id, ga nastavi ob ustvarjanju in vse operacije omeji na zapise trenutnega uporabnika:

PHP
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [
        'text' => ['type' => 'string', 'required' => true],
        'done' => ['type' => 'boolean', 'default' => false],
    ],
];

Brez ročnega polja user_id, kaveljčka before_create ali filtriranja v RPC. Uporabniki lahko vidijo, urejajo in brišejo samo svoje zapise. Za stolpec user_id v celoti skrbi Blockstudio.

Pri uporabi shrambe post_type se userScoped preslika v post_author namesto v ločen stolpec user_id.

Nadzor dostopa

Vsaka operacija CRUD ima svojo raven dovoljenj:

Vrednost Delovanje
true Javno z zaščito CSRF (odjavljeni uporabniki imajo dostop, zahtevan je X-BS-Token)
'open' Resnično javno, brez CSRF in preverjanja pristnosti (za spletne kavlje in zunanje API-je)
'edit_posts' Preverjanje zmožnosti WordPress
['cap_a', 'cap_b'] Uporabnik potrebuje katero koli od navedenih zmožnosti
izpuščeno / null Zahteva preverjanje pristnosti (prijavljen uporabnik)
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
],

Zaščita CSRF

Javne končne točke (true) so zaščitene z glavo X-BS-Token. bs.db() in bs.fn() pridobita sveže poverilnice iz nepredpomnjene končne točke istega izvora, namesto da bi v stran vdelala žetone HTML s časovno omejeno veljavnostjo. Strani, postrežene iz zunanjih predpomnilnikov z dolgo življenjsko dobo, še naprej delujejo. Anonimni klici brez veljavnega žetona prejmejo odgovor 403.

Poverilnice se zahtevajo ob prvem klicu API, ne ob vsakem ogledu strani. Oba odjemalca, tudi tisti za sprotno poizvedovanje po zbirki podatkov, uporabljata isto zahtevo za osvežitev poverilnic, ki je že v teku. Poverilnice se osvežijo po petih minutah uporabe. Ob zavrnjenem žetonu nonce WordPress ali žetonu CSRF Blockstudio sledi ena osvežitev in ponovni poskus; pri običajnih napakah dovoljenj se poskus ne ponovi. Zahteve prijavljenih uporabnikov še naprej uporabljajo sejo trenutnega obiskovalca ter preverjanja zmožnosti in lastništva zapisov, določena v shemi.

POST /wp-json/blockstudio/v1/client/credentials hranite zunaj predpomnilnika katerega koli posredniškega strežnika ali predpomnilnika CDN. Pošilja Cache-Control: private, no-store in zahteva zahtevo istega izvora z nepreprosto glavo. Vgrajena odjemalca to uredita samodejno.

Uporabite 'open', kadar potrebujete dostop brez preverjanja pristnosti in zaščite CSRF, na primer za dohodne spletne kavlje zunanjih storitev.

Vrste polj

Vrsta Stolpec MySQL Vrsta PHP Opis
string varchar(maxLength) string Besedilo, privzeti maxLength 255
integer bigint(20) int Cela števila
number decimal(20,6) float Decimalna števila
boolean tinyint(1) bool Resnično/napačno
text longtext string Daljša besedilna vsebina

Preverjanje veljavnosti

Vsi zapisi (ustvarjanje in posodabljanje) se pred shranjevanjem preverijo glede na shemo. Preverjanje poteka na strežniški strani ne glede na to, ali zahteva prihaja iz bs.db(), odjemalca REST API ali iz Db::get().

Vgrajena pravila

Pravilo Primer Opis
required 'required' => true Polje mora biti prisotno ob ustvarjanju
type 'type' => 'integer' Vrednost se mora ujemati z navedeno vrsto
enum 'enum' => ['a', 'b'] Vrednost mora biti ena od navedenih možnosti
maxLength 'maxLength' => 100 Niz ne sme presegati te dolžine
minLength 'minLength' => 3 Niz mora biti vsaj tako dolg
format: "email" 'format' => 'email' Biti mora veljaven e-poštni naslov
format: "url" 'format' => 'url' Biti mora veljaven URL

Preverjanje po meri

Dodajte povratni klic validate kateremu koli polju za preverjanja na strežniški strani, ki presegajo vgrajena pravila. Za uspešno preverjanje vrnite true ali niz s sporočilom o napaki:

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

Povratni klic prejme vrednost polja in celotno podatkovno polje, zato lahko preverjate tudi povezana polja.

Oblika odgovora ob napaki

Napake pri preverjanju vrnejo status 400 s polji napak za posamezna polja. Oblika se zgleduje po ZodfieldErrors in olajša povezovanje napak s polji obrazca:

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

Za vsako polje je navedeno polje nizov z napakami. Pri istem polju lahko odpove več pravil. Na sprednji strani:

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

Končne točke REST

Vse končne točke so v imenskem prostoru blockstudio/v1/db/:

Koda
/db/{block-name}/{schema-name}

V imenu bloka se / nadomesti z -. Pri blokih z eno shemo je ime sheme default.

Metoda Končna točka Opis
GET /db/{block}/{schema} Prikaže seznam zapisov
POST /db/{block}/{schema} Ustvari zapis
GET /db/{block}/{schema}/{id} Pridobi posamezen zapis
PUT /db/{block}/{schema}/{id} Posodobi zapis
DELETE /db/{block}/{schema}/{id} Izbriše zapis

Parametri poizvedbe (seznam)

Parameter Opis
limit Največje število vrnjenih zapisov (privzeto 50, največ 100)
offset Število zapisov za preskok
Poljubno ime polja Filtriranje po natančnem ujemanju vrednosti

Primer: GET /db/my-theme-app/subscribers?plan=pro&limit=10

Izris obrazca

Polja lahko določijo ključ component, ki se nanaša na blok Blockstudio. V predlogi pokličite bs_db_form(), da se vsa polja izrišejo kot obrazec z uporabo njihovih komponentnih blokov.

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>

Vsaka komponenta prejme celotno definicijo polja kot field v svojih atributih, zato lahko komponente prilagodijo izris glede na shemo. Na primer, $a['field']['name'] poda ime polja, $a['field']['type'] tip, $a['field']['required'] pa pove, ali je polje obvezno itd.

Struktura komponente sledi isti obliki name, attributes, innerBlocks kot bloki WordPress. Notranji bloki se izrišejo najprej in se staršu posredujejo kot $content.

Za uporabo PHP brez izpisa:

PHP
use Blockstudio\Db;

$db   = Db::get('my-theme/app', 'subscribers');
$html = $db->form();

Kavlji

Dejanja se sprožijo pred vsako operacijo pisanja in po njej. Vsi kavlji prejmejo en sam niz $params. Celoten seznam najdete v referenčni dokumentaciji za PHP kavlje.

Vgrajeni kavlji

Kavlje določite neposredno v db.php. Samodejno so omejeni na to shemo, zato vam ni treba preverjati imena bloka ali sheme:

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

Globalni kavlji

Poslušajte dogodke v vseh shemah od koder koli:

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

Kombiniranje z RPC

db.php in rpc.php sta neodvisna sistema. db.php iz definicije sheme ustvari končne točke CRUD. rpc.php določa funkcije strežnika po meri. Vsak sistem deluje samostojno.

Uporabite ju skupaj, kadar potrebujete standardne operacije nad podatki in poslovno logiko po meri:

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

Prenosljivost

Pri shrambi JSONC so podatki shranjeni skupaj s kodo. Kopirajte mapo bloka na drugo spletno mesto in vse se prenese skupaj: UI, logika, nadzor dostopa in sami podatki.

Koda
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

Brez migracij podatkovne baze in korakov za izvoz ali uvoz. Preprosto kopirajte mapo.

Prenosljiva je tudi shramba Storh, vendar je namesto v mapi bloka shranjena pod uploads/blockstudio/db/. Tako so podatki, ki se uporabljajo in vanje zapisuje, zunaj izvornega drevesa, vsaka shema pa ima še vedno shrambo v navadnih datotekah, ki jo lahko varnostno kopirate, kopirate ali neodvisno preselite.

Filtriranje

Shematske definicije spreminjajte programsko od zunaj bloka:

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