Datu bāze
Datu bāzes slānis ļauj definēt bloka datu modeli db.php failā. Blockstudio ģenerē REST CRUD galapunktus, validē ievaddatus atbilstoši shēmai, automātiski pārvalda datu glabāšanu un nodrošina gan klienta JavaScript (bs.db()), gan servera PHP API (Db klase).
Šis ir pilna steka bloku datu pamats. Kamēr RPC apstrādā pielāgoto loģiku, datu bāzes slānis bez lieka palīgkoda apstrādā strukturētus datus.
Kā tas darbojas
- Bloka mapē izveidojiet
db.php - Tas atgriež shēmu: laukus, tipus, validācijas noteikumus un piekļuves kontroli
- Blockstudio izveido datu krātuvi (tabulu, failu vai ieraksta metadatus)
- Automātiski tiek ģenerēti pieci REST galapunkti (saraksta iegūšanai, izgūšanai, izveidei, atjaunināšanai un dzēšanai)
bs.db()unDb::get()nodrošina piekļuvi no klienta un servera
Bez migrācijām, kontrolieriem un maršrutu reģistrēšanas.
Nododiet burtiskas vērtības REST un PHP API. meta un post_type aizmugursistēmas pašas apstrādā WordPress metadatu slīpsvītru pievienošanu, saglabājot slīpsvītras un pēdiņās ietvertas virknes gan skalārās vērtībās, gan ligzdotos objektos vai masīvos. Datubāzes ierakstu vērtībām slīpsvītras nepievienojiet iepriekš.
Shēmu definēšana
Viena shēma
Vienkāršākais variants: viens datu modelis katram blokam.
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 standarta veidotāja sintakse
db.php var izmantot arī vienkāršu veidotāja API, kas balstīts uz nosauktiem argumentiem un tikai lasāmiem definīciju objektiem. Masīvi joprojām ir noklusējuma formāts, taču šī iespēja nodrošina pārskatāmāku, PHP vidē ierastu risinājumu, kad shēma kļūst lielāka.
<?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'),
],
);
Vienai shēmai izmantojiet Schema::make(), bet blokiem ar vairākām shēmām atgrieziet nosauktu Schema::make(...) izsaukumu masīvu.
Vairākas shēmas
Vienā blokā var būt vairāki datu modeļi. Atgrieziet nosauktu masīvu:
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'],
],
],
];
Katrai shēmai ir savi galapunkti, datu krātuve un piekļuves kontrole.
Datu glabāšanas režīmi
Sešas datu glabāšanas iespējas dažādiem lietojuma gadījumiem.
Pielāgota tabula (storage: "table")
Katrs ieraksts ir rinda atsevišķā MySQL tabulā. Blockstudio automātiski izveido un pārvalda tabulu, izmantojot WordPress funkciju dbDelta(). Pievienojot shēmai laukus, nākamajā lapas ielādes reizē tiek pievienotas kolonnas. Esošās kolonnas nekad netiek noņemtas.
Ieteicams: strukturētiem datiem, vaicājumiem un ražošanas lietotnēm.
SQLite (storage: "sqlite")
Katrai shēmai ir savs SQLite datubāzes fails mapes db/ apakšmapē. Blockstudio automātiski izveido failu un tabulu un pievieno trūkstošās kolonnas, mainoties shēmai (līdzīgi kā dbDelta priekš MySQL). Vienlaicīgas lasīšanas veiktspējai tiek izmantots WAL žurnāla režīms.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Ieteicams: strukturētiem datiem, kuriem vajadzīgi īsti SQL vaicājumi, bet kuriem jāpaliek pārnesamiem. Efektīvi apstrādā tūkstošiem ierakstu, neielādējot tos visus atmiņā. Lai pārvietotu datus, nokopējiet mapi.
JSONC faili (storage: "jsonc")
Ieraksti tiek glabāti kā atsevišķi JSON objekti, pa vienam katrā rindā .jsonc failā mapes db/ apakšmapē. Fails tiek automātiski izveidots pirmajā rakstīšanas reizē. Rindas, kas sākas ar //, tiek uzskatītas par komentāriem un saglabātas.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Ieteicams: nelielām datu kopām, konfigurācijas datiem, sākotnējiem ierakstiem un piemēriem, kuru versijas var kontrolēt. JSONC apzināti ir viens fails jūsu bloka mapē. Izmantojiet to, ja vēlaties glabāt datus kopā ar kodu, nevis tad, ja paredzēts daudz vienlaicīgu rakstīšanas darbību.
Storh faili (storage: "storh")
Storh katru ierakstu glabā kā atsevišķu failu mapē WordPress augšupielāžu direktorijā:
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
Publiskie ierakstu ID joprojām ir tie paši veselo skaitļu ID, ko izmanto pārējā bs.db() sistēma. Blockstudio sasaista šos ID ar iekšējiem UUIDv7 failu ID, ko izmanto Storh, un ieraksta datos saglabā vesela skaitļa id, tāpēc JavaScript, REST un PHP klientiem nav jāapstrādā UUID.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio veido Storh indeksus, izmantojot jūsu shēmu. Tā kā katru deklarēto lauku var izmantot kā saraksta filtru, tiek indeksēts ikviens deklarētais lauks. Veselu skaitļu, skaitļu un datumiem līdzīgiem laukiem izmanto intervālu indeksus; laukiem, kas atzīmēti ar 'unique' => true vai 'index' => 'unique', izmanto unikālos indeksus.
Ieteicams: ražošanas datiem failu krātuvē, kam vajadzīga drošāka vienlaicīga rakstīšana, no shēmas veidoti indeksi un pārnesama glabāšana augšupielāžu līmenī, neiekļaujot aktīvos ierakstus bloka avota kokā.
Migrēšana no JSONC uz Storh
Ja sākāt ar .jsonc failu un vēlaties tos pašus ierakstus Storh, izpildiet:
wp bs db migrate my-theme/app subscribers --to=storh
Blokiem ar vienu shēmu:
wp bs db migrate my-theme/app --to=storh
Migrācija nolasa esošo db/{schema}.jsonc, ieraksta datus Storh, saglabājot veselo skaitļu ID, atkārtoti izveido indeksus, pārbauda mērķa krātuvi un atstāj JSONC failu neskartu. Lai atgrieztos, shēmas storage vienkārši nomainiet atpakaļ uz "jsonc".
Ieraksta metadati (storage: "meta")
Ieraksti tiek glabāti kā JSON masīvs WordPress ieraksta metadatos un piesaistīti konkrētam ierakstam, izmantojot postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Ieteicams: datiem, kas pieder konkrētam ierakstam vai lapai.
Pielāgots ieraksta tips (storage: "post_type")
Katrs ieraksts ir WordPress ieraksts automātiski reģistrētā pielāgotā ierakstu tipā. Katrs shēmas lauks kļūst par atsevišķu post_meta ierakstu. Tādējādi ierakstus var vaicāt ar WP_Query, tie ir saderīgi ar REST API spraudņiem un redzami tādiem rīkiem kā GraphQL.
Ieteicams: datiem, kuriem jābūt dabiski integrētiem ar WordPress. Katru lauku var atsevišķi vaicāt un indeksēt.
JavaScript klients
Blockstudio lapās ar datubāzes blokiem ievieto bs.db(). Tas atgriež objektu ar piecām metodēm:
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);
Pirmais arguments ir bloka nosaukums (ar /), otrais ir shēmas nosaukums. Blokiem ar vienu shēmu nenorādiet shēmas nosaukumu (pēc noklusējuma tiek izmantots "default").
Kešatmiņa
bs.cache ir atmiņā saglabāta vaicājumu kešatmiņa, ko kopīgi izmanto visi bs.query un bs.mutate izsaukumi. To var izmantot arī tieši:
// 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();
Kešatmiņas ieraksti tiek glabāti atmiņā un dzēsti, pārejot uz citu lapu. Tos galvenokārt iekšēji izmanto bs.query un bs.mutate, bet tieša piekļuve noder datu iepriekšējai ievietošanai vai manuālai kešatmiņas ierakstu nederīguma atzīmēšanai pēc pielāgotām darbībām.
Vaicājums
bs.query() aptver jebkuru asinhrono funkciju, nodrošinot kešošanu, dublēšanas novēršanu un novecošanas kontroli. Kamēr pieprasījums vēl tiek apstrādāts, vairāki izsaukumi ar vienu un to pašu atslēgu atgriež vienu un to pašu solījumu (netiek veikti dublēti datu ielādes pieprasījumi).
// 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 }
);
Pirmais arguments ir kešatmiņas atslēga (jebkura virkne). Otrais ir funkcija, kas atgriež solījumu. Trešais ir neobligāts opciju objekts:
| Opcija | Tips | Apraksts |
|---|---|---|
staleTime |
number |
Milisekunžu skaits, pēc kura kešatmiņas dati tiek uzskatīti par novecojušiem. 0 (noklusējums) vienmēr atkārtoti ielādē datus. |
Ja kešatmiņā ir dati ar attiecīgo atslēgu un tie ir jaunāki par staleTime, kešotā vērtība tiek atgriezta uzreiz, neizsaucot funkciju.
Datu maiņa
bs.mutate() apstrādā rakstīšanas darbības ar optimistiskajiem atjauninājumiem un automātisku atcelšanu kļūmes gadījumā. Tam ir divi režīmi: automātiskais režīms biežākajiem CRUD scenārijiem un manuālais režīms pilnīgai kontrolei.
Automātiskais režīms darbojas ar reaktīvu stāvokļa objektu (piemēram, Alpine.js $data). Norādiet state, key, action un pēc izvēles 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),
});
Ja darbība izdodas, optimistiskos datus aizstāj servera atbilde. Ja tā neizdodas, stāvoklis tiek atjaunots uz momentuzņēmumu, kas uzņemts pirms izmaiņas. Pēc katras veiksmīgas izmaiņas kešatmiņas atslēga tiek automātiski atzīmēta kā nederīga.
Kļūme ir gadījums, kad fn atgrieztais solījums tiek noraidīts. bs.db() un bs.fn() validācijas kļūdas, neesoša ieraksta vai neveiksmīgas atļauju pārbaudes gadījumā atgriež kļūdas pamattekstu, tāpēc izmetiet kļūdu, kad rezultātā ir code, ja arī šajos gadījumos jāatceļ izmaiņas:
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)),
});
Izveides darbībām optimistiskajam ierakstam tiek piešķirts pagaidu id (piemēram, __temp_1). Kad serveris atbild, pagaidu ieraksta dati tiek aizstāti ar īstajiem, tostarp servera piešķirto id.
Manuālais režīms nodrošina pilnīgu kontroli ar before, onSuccess un onError atzvanīšanas funkcijām:
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;
},
});
| Opcija | Tips | Režīms | Apraksts |
|---|---|---|---|
fn |
function |
Abi | Asinhronā funkcija, kas veic izmaiņu. Obligāta. |
state |
object |
Automātiskais | Reaktīvs stāvokļa objekts (e.g., Alpine $data). |
key |
string |
Automātiskais | Stāvokļa rekvizīta nosaukums, kurā glabājas masīvs. Tiek izmantots arī kā kešatmiņas atslēga. |
action |
string |
Automātiskais | Viena no vērtībām: create, update vai delete. |
id |
any |
Automātiskais | Ieraksta ID darbībām update un delete. |
optimistic |
object |
Automātiskais | Dati, ko optimistiski lietot, pirms serveris atbild. |
before |
function |
Manuālais | Tiek izsaukta pirms fn. Atgrieztā vērtība tiek nodota funkcijām onSuccess/onError kā snapshot. |
onSuccess |
function |
Manuālais | Tiek izsaukta ar (result, snapshot), ja darbība izdodas. |
onError |
function |
Manuālais | Tiek izsaukta ar (error, snapshot), ja darbība neizdodas. |
invalidate |
string |
Manuālais | Kešatmiņas atslēga, kuras ieraksts pēc veiksmīgas darbības jāatzīmē kā nederīgs. |
PHP API
Klase Db nodrošina tās pašas darbības servera pusē. Izmantojiet to rpc.php, cron.php, veidnēs vai jebkurā PHP kodā.
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);
Blokiem ar vienu shēmu:
$db = Db::get('my-theme/block');
Datu periodiska atjaunināšana
Pievienojiet shēmai realtime, lai iespējotu automātisku datu periodisku atjaunināšanu. Mainoties datiem serverī, UI automātiski atjaunina datus, izmantojot interaktivitātes API krātuvi. JavaScript izmaiņas nav nepieciešamas.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Ja ir norādīts true, Blockstudio pieprasa atjauninājumus ik pēc 3 sekundēm, izmantojot shēmas nosaukumu kā interaktivitātes API stāvokļa atslēgu (default blokiem ar vienu shēmu).
Pielāgota konfigurācija
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Opcija | Tips | Noklusējums | Apraksts |
|---|---|---|---|
key |
string |
shēmas nosaukums | Rekvizīta nosaukums state, kurā glabājas datu masīvs |
interval |
number |
3000 |
Atjauninājumu pieprasīšanas intervāls milisekundēs |
Kā tas darbojas
- Ielādējot lapu, klients izgūst pašreizējo datu vienkāršoto jaucējvērtību
- Ik pēc
intervalmilisekundēm tas izgūst jaucējvērtību vēlreiz - Ja jaucējvērtība ir mainījusies, tas izgūst pilnu datu kopu
- Jaunie dati tiek nosūtīti uz interaktivitātes API krātuvi, izmantojot
store() - Visas šī stāvokļa rekvizītam piesaistītās direktīvas tiek automātiski attēlotas no jauna
Atjauninājumu pieprasīšana notiek tikai lapās, kurās ir atbilstošs data-wp-interactive elements. Tā tiek apturēta, kad pārlūka cilne ir paslēpta, un atsākta, kad tā atkal ir redzama.
Jaucējvērtības galapunkts (?_hash=1) atgriež tikai md5 kontrolsummu un ierakstu skaitu, tādēļ atjauninājumu pieprasījumi ir nelieli.
Lietotājam piesaistīti dati
Iestatiet userScoped: true, lai visus ierakstus automātiski piesaistītu pašreizējam lietotājam. Blockstudio pievieno kolonnu user_id, iestata tās vērtību, veidojot ierakstu, un ierobežo visas darbības ar pašreizējā lietotāja ierakstiem:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Nav jāveido manuāls user_id lauks vai before_create āķis, kā arī nav jāfiltrē dati RPC. Lietotāji var skatīt, rediģēt un dzēst tikai savus ierakstus. Kolonnu user_id pilnībā pārvalda Blockstudio.
Izmantojot post_type krātuvi, userScoped tiek piesaistīts post_author, nevis atsevišķai kolonnai user_id.
Piekļuves kontrole
Katrai CRUD darbībai ir savs atļauju līmenis:
| Vērtība | Darbība |
|---|---|
true |
Publiska, ar CSRF aizsardzību (atļauti lietotāji bez pieteikšanās, nepieciešams X-BS-Token) |
'open' |
Pilnībā publiska, bez CSRF un autentifikācijas (tīmekļa āķiem un ārējām API) |
'edit_posts' |
WordPress iespēju pārbaude |
['cap_a', 'cap_b'] |
Lietotājam nepieciešama vismaz viena no norādītajām iespējām |
izlaists / null |
Nepieciešama autentifikācija (lietotājam jābūt pieteikušamies) |
'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 aizsardzība
Publiskos galapunktus (true) aizsargā X-BS-Token galvene. bs.db() un bs.fn() iegūst jaunus akreditācijas datus no kešatmiņā neglabāta tās pašas izcelsmes galapunkta, nevis iegulst lapas HTML tokenus, kam beidzas derīguma termiņš. Lapas, ko apkalpo ilgstošas ārējās kešatmiņas, turpina darboties. Anonīmi izsaukumi bez derīga tokena saņem atbildi 403.
Akreditācijas dati tiek pieprasīti pirmajā API izsaukumā, nevis katrā lapas skatījumā. Abi klienti, tostarp datubāzes reāllaika aptauja, koplieto vienu notiekošu akreditācijas datu atsvaidzināšanu. Akreditācijas dati tiek atsvaidzināti pēc piecu minūšu lietošanas. Ja tiek noraidīts WordPress nonce vai Blockstudio CSRF tokens, notiek viena atsvaidzināšana un atkārtots mēģinājums; parastās atļauju kļūdas netiek mēģinātas vēlreiz. Autentificēti pieprasījumi joprojām izmanto apmeklētāja sesiju un shēmas iespēju un ierakstu īpašumtiesību pārbaudes.
Nenovietojiet POST /wp-json/blockstudio/v1/client/credentials aiz starpniekservera vai CDN kešatmiņā. Tas sūta Cache-Control: private, no-store un pieprasa tās pašas izcelsmes pieprasījumu ar ne vienkāršu galveni. Iebūvētie klienti to apstrādā automātiski.
Izmantojiet 'open', ja nepieciešama piekļuve bez autentifikācijas un CSRF aizsardzības, piemēram, ārēju pakalpojumu ienākošajiem tīmekļa āķiem.
Lauku tipi
| Tips | MySQL kolonna | PHP tips | Apraksts |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Teksts, noklusējuma maxLength 255 |
integer |
bigint(20) |
int |
Veseli skaitļi |
number |
decimal(20,6) |
float |
Decimālskaitļi |
boolean |
tinyint(1) |
bool |
Patiesuma vērtības |
text |
longtext |
string |
Garas formas teksta saturs |
Validācija
Visi rakstīšanas pieprasījumi (izveide un atjaunināšana) tiek validēti atbilstoši shēmai, pirms datiem tiek piekļūts krātuvē. Validācija notiek servera pusē neatkarīgi no tā, vai pieprasījums nāk no bs.db(), klienta REST API vai Db::get().
Iebūvētie noteikumi
| Noteikums | Piemērs | Apraksts |
|---|---|---|
required |
'required' => true |
Veidojot ierakstu, laukam jābūt norādītam |
type |
'type' => 'integer' |
Vērtībai jāatbilst deklarētajam tipam |
enum |
'enum' => ['a', 'b'] |
Vērtībai jābūt vienai no norādītajām iespējām |
maxLength |
'maxLength' => 100 |
Virkne nedrīkst pārsniegt šo garumu |
minLength |
'minLength' => 3 |
Virknei jābūt vismaz šādā garumā |
format: "email" |
'format' => 'email' |
Jābūt derīgai e-pasta adresei |
format: "url" |
'format' => 'url' |
Jābūt derīgam URL |
Pielāgota validācija
Pievienojiet jebkuram laukam validate atzvanīšanas funkciju, lai veiktu servera puses pārbaudes ārpus iebūvētajiem noteikumiem. Lai pārbaude būtu veiksmīga, atgrieziet true; pretējā gadījumā atgrieziet virkni ar kļūdas ziņojumu:
'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;
},
],
Atzvanīšanas funkcija saņem lauka vērtību un visu datu masīvu, tāpēc varat validēt vairākus laukus kopā.
Kļūdas atbildes formāts
Validācijas kļūdas atgriež statusu 400 ar katra lauka kļūdu masīviem. Šis formāts veidots, iedvesmojoties no Zod fieldErrors, un atvieglo kļūdu piesaisti veidlapas laukiem:
{
"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."]
}
}
}
Katram laukam atbilst kļūdu virkņu masīvs. Vienam laukam var būt vairākas kļūdas. Priekšgala kodā:
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 galapunkti
Visi galapunkti atrodas nosaukumtelpā blockstudio/v1/db/:
/db/{block-name}/{schema-name}
Bloka nosaukumā / tiek aizstāts ar -. Blokiem ar vienu shēmu shēmas nosaukums ir default.
| Metode | Galapunkts | Apraksts |
|---|---|---|
GET |
/db/{block}/{schema} |
Uzskaitīt ierakstus |
POST |
/db/{block}/{schema} |
Izveidot ierakstu |
GET |
/db/{block}/{schema}/{id} |
Iegūt vienu ierakstu |
PUT |
/db/{block}/{schema}/{id} |
Atjaunināt ierakstu |
DELETE |
/db/{block}/{schema}/{id} |
Dzēst ierakstu |
Vaicājuma parametri (saraksts)
| Parametrs | Apraksts |
|---|---|
limit |
Maksimālais atgriežamo ierakstu skaits (pēc noklusējuma 50, maksimums 100) |
offset |
Izlaižamo ierakstu skaits |
| Jebkura lauka nosaukums | Filtrēt pēc precīzas vērtības |
Piemērs: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Veidlapu attēlošana
Laukiem var norādīt atslēgu component, kas atsaucas uz Blockstudio bloku. Veidnē izsauciet bs_db_form(), lai attēlotu visus laukus kā veidlapu, izmantojot to komponentu blokus.
'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>
Katrs komponents saņem pilnu lauka definīciju kā field savos atribūtos, tāpēc komponenti var pielāgot attēlojumu shēmai. Piemēram, $a['field']['name'] norāda lauka nosaukumu, $a['field']['type'] — tipu, $a['field']['required'] — vai tas ir obligāts u. c.
Komponentu struktūrā tiek izmantots tas pats name, attributes, innerBlocks formāts kā WordPress blokiem. Iekšējie bloki tiek attēloti vispirms un nodoti vecākblokam kā $content.
Lai izmantotu PHP bez izvades ar echo:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Āķi
Darbības tiek izpildītas pirms un pēc katras rakstīšanas operācijas. Visi āķi saņem vienu $params masīvu. Pilnu sarakstu skatiet PHP āķu atsaucē.
Iekļautie āķi
Definējiet āķus tieši db.php. Tie automātiski ir piesaistīti attiecīgajai shēmai, tāpēc nav jāpārbauda bloka vai shēmas nosaukums:
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']);
},
],
];
Globālie āķi
Klausieties notikumus visās shēmās no jebkuras vietas:
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
}
});
Apvienošana ar RPC
db.php un rpc.php ir neatkarīgas sistēmas. db.php ģenerē CRUD galapunktus no shēmas definīcijas. rpc.php definē pielāgotas servera funkcijas. Katru no tām var izmantot atsevišķi.
Izmantojiet tās kopā, ja nepieciešamas standarta datu operācijas un pielāgota biznesa loģika:
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',
],
];
Pārnesamība
Izmantojot JSONC krātuvi, dati atrodas līdzās kodam. Nokopējiet bloka mapi uz citu vietni, un viss būs kopā: UI, loģika, piekļuves kontrole un paši dati.
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
Nav datubāzes migrāciju un eksportēšanas/importēšanas darbību. Vienkārši nokopējiet mapi.
Arī Storh krātuve ir pārnesama, taču tā atrodas mapē uploads/blockstudio/db/, nevis bloka mapē. Tādējādi aktuālie rakstāmie dati neatrodas avota kokā, bet katrai shēmai joprojām ir vienkārša failu krātuve, ko var neatkarīgi dublēt, kopēt vai migrēt.
Filtrs
Modificējiet shēmas programmatiski ārpus bloka:
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;
});