Datenbank
Mit der Datenbankschicht kannst du ein Datenmodell für deinen Block in einer db.php-Datei definieren. Blockstudio generiert REST-CRUD-Endpunkte, validiert Eingaben anhand des Schemas, verwaltet den Speicher automatisch und stellt sowohl einen JavaScript-Client (bs.db()) als auch eine PHP API-Klasse (Db) bereit.
Das ist das Datengrundgerüst für Full-Stack-Blöcke. Während RPC benutzerdefinierte Logik übernimmt, verarbeitet die Datenbankschicht strukturierte Daten ganz ohne Boilerplate.
So funktioniert es
- Du erstellst
db.phpin deinem Blockverzeichnis - Sie gibt ein Schema zurück: Felder, Typen, Validierungsregeln und Zugriffskontrolle
- Blockstudio erstellt den Speicher (Tabelle, Datei oder Post-Meta)
- Fünf REST-Endpunkte werden automatisch generiert (Auflisten, Abrufen, Erstellen, Aktualisieren, Löschen)
bs.db()undDb::get()ermöglichen den Zugriff über Client und Server
Keine Migrationen, keine Controller, keine Routenregistrierung.
Übergib den APIs REST und PHP Literalwerte. Die Backends meta und post_type übernehmen das Escaping von WordPress-Metadaten intern und erhalten Backslashes und Zeichenfolgen in Anführungszeichen sowohl in skalaren Werten als auch in verschachtelten Objekten oder Arrays. Versehe Datenbankdatensatzwerte nicht vorab mit Escape-Zeichen.
Schemas definieren
Einzelnes Schema
Die einfachste Variante: ein Datenmodell pro Block.
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-native Builder-Syntax
db.php unterstützt auch einen kleinen Builder API, der auf benannten Argumenten und schreibgeschützten Definitionsobjekten basiert. Arrays bleiben das Standardformat, doch so steht dir eine besser auffindbare, PHP-native Option zur Verfügung, sobald das Schema größer wird.
<?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'),
],
);
Verwende Schema::make() für ein einzelnes Schema oder gib für Blöcke mit mehreren Schemas ein Array benannter Schema::make(...)-Aufrufe zurück.
Mehrere Schemas
Ein einzelner Block kann mehrere Datenmodelle enthalten. Gib ein benanntes Array zurück:
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'],
],
],
];
Jedes Schema erhält eigene Endpunkte, eigenen Speicher und eigene Zugriffskontrolle.
Speichermodi
Sechs Speicher-Backends, jeweils für unterschiedliche Anwendungsfälle geeignet.
Benutzerdefinierte Tabelle (storage: "table")
Jeder Datensatz ist eine Zeile in einer eigenen MySQL-Tabelle. Blockstudio erstellt und verwaltet die Tabelle automatisch mit der Funktion dbDelta() von WordPress. Neue Felder im Schema werden beim nächsten Seitenaufruf als Spalten hinzugefügt. Vorhandene Spalten werden nie entfernt.
Ideal für: strukturierte Daten, Abfragen und Produktivanwendungen.
SQLite (storage: "sqlite")
Jedes Schema erhält eine eigene SQLite-Datenbankdatei in einem Unterordner db/. Blockstudio erstellt die Datei und Tabelle automatisch und fügt bei Schemaänderungen fehlende Spalten hinzu (wie dbDelta für MySQL). Verwendet den WAL-Journalmodus für parallele Lesezugriffe.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Ideal für: strukturierte Daten, die echte SQL-Abfragen benötigen, aber portabel bleiben sollen. Verarbeitet Tausende von Datensätzen effizient, ohne alles in den Arbeitsspeicher zu laden. Kopiere den Ordner, um die Daten zu übertragen.
JSONC-Dateien (storage: "jsonc")
Datensätze werden in einer .jsonc-Datei in einem Unterordner db/ gespeichert, ein JSON-Objekt pro Zeile. Die Datei wird beim ersten Schreibvorgang automatisch erstellt. Zeilen, die mit // beginnen, gelten als Kommentare und bleiben erhalten.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Ideal für: kleine Datensätze, konfigurationsähnliche Daten, Seed-Datensätze und Beispiele, die sich versionieren lassen. JSONC besteht bewusst aus einer einzelnen Datei in deinem Blockordner. Verwende es, wenn die Daten zusammen mit dem Code weitergegeben werden sollen, nicht bei vielen gleichzeitigen Schreibvorgängen.
Storh-Dateien (storage: "storh")
Storh speichert jeden Datensatz als einzelne Datei in den Uploads von WordPress:
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
Öffentliche Datensatz-IDs bleiben dieselben ganzzahligen IDs, die auch der Rest von bs.db() verwendet. Blockstudio ordnet diese IDs den internen UUIDv7-Datei-IDs von Storh zu und speichert die Ganzzahl id in den Datensatzdaten. Daher müssen Aufrufer von JavaScript, REST und PHP keine UUIDs verarbeiten.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio erstellt aus deinem Schema Storh-Indizes. Da jedes deklarierte Feld als Listenfilter dienen kann, wird jedes deklarierte Feld indiziert. Ganzzahl-, Zahlen- und datumsähnliche Felder erhalten Bereichsindizes; für Felder mit 'unique' => true oder 'index' => 'unique' werden eindeutige Indizes angelegt.
Ideal für: dateibasierte Produktivdaten mit sichereren gleichzeitigen Schreibvorgängen, schemabasierten Indizes und portablem Speicher auf Upload-Ebene, ohne Live-Datensätze im Quellbaum des Blocks abzulegen.
JSONC zu Storh migrieren
Wenn du mit einer .jsonc-Datei begonnen hast und dieselben Datensätze in Storh haben möchtest, führe Folgendes aus:
wp bs db migrate my-theme/app subscribers --to=storh
Für Blöcke mit einem Schema:
wp bs db migrate my-theme/app --to=storh
Bei der Migration wird die vorhandene db/{schema}.jsonc eingelesen und werden die Datensätze unter Beibehaltung der ganzzahligen IDs nach Storh geschrieben. Anschließend werden die Indizes neu erstellt und der Zielspeicher überprüft. Die JSONC-Datei bleibt unverändert. Für ein Rollback musst du den Wert von storage im Schema einfach wieder auf "jsonc" setzen.
Post-Meta (storage: "meta")
Datensätze werden als JSON-Array in den Post-Metadaten von WordPress gespeichert und über postId einem bestimmten Beitrag zugeordnet.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Ideal für: Daten, die zu einem bestimmten Beitrag oder einer Seite gehören.
Benutzerdefinierter Inhaltstyp (storage: "post_type")
Jeder Datensatz ist ein WordPress-Beitrag in einem automatisch registrierten benutzerdefinierten Inhaltstyp. Jedes Feld im Schema wird zu einem eigenen post_meta-Eintrag. Dadurch lassen sich Datensätze mit WP_Query abfragen, sind mit REST-API-Plugins kompatibel und in Tools wie GraphQL sichtbar.
Ideal für: Daten, die sich nativ in WordPress integrieren sollen. Jedes Feld lässt sich unabhängig abfragen und indizieren.
JavaScript-Client
Blockstudio bindet bs.db() auf Seiten mit Datenbankblöcken ein. Das Ergebnis ist ein Objekt mit fünf Methoden:
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);
Das erste Argument ist der Blockname (mit /), das zweite der Schemaname. Bei Blöcken mit nur einem Schema kannst du den Schemanamen weglassen (Standardwert: "default").
Cache
bs.cache ist ein speicherinterner Abfrage-Cache, den alle Aufrufe von bs.query und bs.mutate gemeinsam nutzen. Du kannst ihn auch direkt verwenden:
// 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();
Cache-Einträge werden im Arbeitsspeicher gespeichert und beim Seitenwechsel gelöscht. Sie werden hauptsächlich intern von bs.query und bs.mutate verwendet. Der direkte Zugriff ist jedoch nützlich, um Daten vorab zu laden oder den Cache nach benutzerdefinierten Vorgängen manuell zu entwerten.
Abfrage
bs.query() ergänzt jede asynchrone Funktion um Caching, Deduplizierung und eine Steuerung der Aktualität. Mehrere Aufrufe mit demselben Schlüssel während einer laufenden Anfrage geben dasselbe Promise zurück (keine doppelten Abrufe).
// 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 }
);
Das erste Argument ist ein Cache-Schlüssel (beliebiger String). Das zweite ist eine Funktion, die ein Promise zurückgibt. Das dritte ist ein optionales Optionsobjekt:
| Option | Typ | Beschreibung |
|---|---|---|
staleTime |
number |
Millisekunden, bis zwischengespeicherte Daten als veraltet gelten. 0 (Standard) ruft Daten immer erneut ab. |
Wenn der Cache Daten für den Schlüssel enthält und diese jünger als staleTime sind, wird der zwischengespeicherte Wert sofort zurückgegeben, ohne die Funktion aufzurufen.
Ändern
bs.mutate() führt Schreibvorgänge mit optimistischen Aktualisierungen und automatischem Rollback bei Fehlern aus. Es gibt zwei Modi: den Automatikmodus für gängige CRUD-Muster und den manuellen Modus für volle Kontrolle.
Der Automatikmodus funktioniert mit einem reaktiven Zustandsobjekt (etwa Alpine.js $data). Übergib state, key, action und optional 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),
});
Bei Erfolg werden die optimistischen Daten durch die Serverantwort ersetzt. Bei einem Fehler wird der Zustand auf eine Momentaufnahme vor der Änderung zurückgesetzt. Der Cache-Schlüssel wird nach jeder erfolgreichen Änderung automatisch entwertet.
Ein Fehler liegt vor, wenn das von fn zurückgegebene Promise abgelehnt wird. bs.db() und bs.fn() werden bei einem Validierungsfehler, einem fehlenden Datensatz oder einer fehlgeschlagenen Berechtigungsprüfung mit dem Fehlerinhalt aufgelöst. Wirf daher eine Ausnahme, wenn auch diese Fälle ein Rollback auslösen sollen und das Ergebnis ein code enthält:
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)),
});
Bei Erstellvorgängen wird dem optimistischen Eintrag eine temporäre id (etwa __temp_1) zugewiesen. Sobald der Server antwortet, wird der temporäre Eintrag mit den echten Daten einschließlich der vom Server vergebenen id aktualisiert.
Der manuelle Modus gibt dir mit den Callbacks before, onSuccess und onError volle Kontrolle:
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;
},
});
| Option | Typ | Modus | Beschreibung |
|---|---|---|---|
fn |
function |
Beide | Die asynchrone Funktion, die die Änderung ausführt. Erforderlich. |
state |
object |
Auto | Reaktives Zustandsobjekt (e.g., Alpine $data). |
key |
string |
Auto | Eigenschaft im Zustand, die das Array enthält. Wird auch als Cache-Schlüssel verwendet. |
action |
string |
Auto | Einer der Werte create, update oder delete. |
id |
any |
Auto | Datensatz-ID für die Aktionen update und delete. |
optimistic |
object |
Auto | Daten, die vor der Serverantwort optimistisch übernommen werden. |
before |
function |
Manuell | Wird vor fn aufgerufen. Der Rückgabewert wird als snapshot an onSuccess/onError übergeben. |
onSuccess |
function |
Manuell | Wird bei Erfolg mit (result, snapshot) aufgerufen. |
onError |
function |
Manuell | Wird bei einem Fehler mit (error, snapshot) aufgerufen. |
invalidate |
string |
Manuell | Cache-Schlüssel, der bei Erfolg entwertet werden soll. |
PHP API
Die Klasse Db stellt serverseitig dieselben Operationen bereit. Verwende sie in rpc.php, cron.php, Templates oder beliebigem PHP-Code.
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);
Für Blöcke mit einem Schema:
$db = Db::get('my-theme/block');
Echtzeitabfrage
Füge realtime zu deinem Schema hinzu, um automatische Abfragen zu aktivieren. Ändern sich Daten auf dem Server, aktualisiert sich der UI automatisch über den Interactivity-API-Store. Änderungen am JavaScript sind nicht nötig.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Mit true fragt Blockstudio alle 3 Sekunden ab. Als Interactivity-API-Statusschlüssel wird der Schemaname verwendet (default bei Blöcken mit nur einem Schema).
Benutzerdefinierte Konfiguration
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Option | Typ | Standardwert | Beschreibung |
|---|---|---|---|
key |
string |
Schemaname | Eigenschaft in state, die das Datenarray enthält |
interval |
number |
3000 |
Abfrageintervall in Millisekunden |
Funktionsweise
- Beim Laden der Seite ruft der Client einen kompakten Hash der aktuellen Daten ab
- Alle
intervalMillisekunden wird der Hash erneut abgerufen - Hat sich der Hash geändert, werden die vollständigen Daten abgerufen
- Die neuen Daten werden über
store()in den Interactivity-API-Store übertragen - Alle an diese Zustandseigenschaft gebundenen Direktiven werden automatisch neu gerendert
Abfragen laufen nur auf Seiten, auf denen ein passendes Element data-wp-interactive vorhanden ist. Sie pausieren, wenn der Browser-Tab verborgen ist, und werden fortgesetzt, sobald er wieder sichtbar ist.
Der Hash-Endpunkt (?_hash=1) gibt nur eine md5-Prüfsumme und die Anzahl der Datensätze zurück, damit Abfragen schlank bleiben.
Benutzerspezifische Daten
Setze userScoped: true, um alle Datensätze automatisch auf den aktuellen Benutzer zu beschränken. Blockstudio fügt eine Spalte user_id hinzu, setzt sie beim Erstellen und beschränkt alle Vorgänge auf die Datensätze des aktuellen Benutzers:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Kein manuelles Feld user_id, kein before_create-Hook, keine Filterung in RPC. Benutzer können nur ihre eigenen Datensätze ansehen, bearbeiten und löschen. Die Spalte user_id wird vollständig von Blockstudio verwaltet.
Bei Verwendung des Speichers post_type wird userScoped statt einer separaten Spalte user_id auf post_author abgebildet.
Zugriffskontrolle
Für jeden CRUD-Vorgang gilt eine eigene Berechtigungsstufe:
| Wert | Verhalten |
|---|---|
true |
Öffentlich mit CSRF-Schutz (abgemeldete Benutzer erlaubt, X-BS-Token erforderlich) |
'open' |
Wirklich öffentlich, ohne CSRF und Authentifizierung (für Webhooks und externe APIs) |
'edit_posts' |
Prüfung der WordPress-Fähigkeit |
['cap_a', 'cap_b'] |
Benutzer benötigt mindestens eine der aufgeführten Fähigkeiten |
weggelassen / null |
Authentifizierung erforderlich (angemeldeter Benutzer) |
'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-Schutz
Öffentliche Endpunkte (true) werden durch einen X-BS-Token-Header geschützt. bs.db() und bs.fn() rufen frische Zugangsdaten von einem nicht zwischengespeicherten Same-Origin-Endpunkt ab, statt ablaufende Tokens in Seiten-HTML einzubetten. Seiten, die über externe Caches mit langer Speicherdauer bereitgestellt werden, funktionieren weiterhin. Anonyme Aufrufe ohne gültiges Token erhalten eine 403-Antwort.
Zugangsdaten werden beim ersten API-Aufruf angefordert, nicht bei jedem Seitenaufruf. Beide Clients, einschließlich des Echtzeit-Pollings der Datenbank, teilen sich einen laufenden Zugangsdaten-Abruf. Die Zugangsdaten werden nach fünf Minuten Nutzung erneuert. Bei einer abgewiesenen WordPress-Nonce oder einem abgewiesenen Blockstudio-CSRF-Token wird einmalig erneuert und der Aufruf wiederholt; gewöhnliche Berechtigungsfehler führen nicht zu einem erneuten Versuch. Bei angemeldeten Anfragen gelten weiterhin die Sitzung des Besuchers sowie die Berechtigungs- und Datensatz-Eigentumsprüfungen des Schemas.
Halte POST /wp-json/blockstudio/v1/client/credentials von jedem Proxy- oder CDN-Cache fern. Der Endpunkt sendet Cache-Control: private, no-store und erfordert eine Same-Origin-Anfrage mit einem nicht einfachen Header. Die integrierten Clients erledigen das automatisch.
Verwende 'open', wenn du vollständig nicht authentifizierten Zugriff ohne CSRF benötigst, etwa für eingehende Webhooks externer Dienste.
Feldtypen
| Typ | MySQL-Spalte | Typ PHP | Beschreibung |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Text, standardmäßige maxLength 255 |
integer |
bigint(20) |
int |
Ganze Zahlen |
number |
decimal(20,6) |
float |
Dezimalzahlen |
boolean |
tinyint(1) |
bool |
Wahr/Falsch |
text |
longtext |
string |
Längere Textinhalte |
Validierung
Alle Schreibvorgänge (Erstellen und Aktualisieren) werden vor dem Zugriff auf den Speicher anhand des Schemas validiert. Die Validierung erfolgt serverseitig, unabhängig davon, ob die Anfrage von bs.db(), dem REST API oder Db::get() stammt.
Integrierte Regeln
| Regel | Beispiel | Beschreibung |
|---|---|---|
required |
'required' => true |
Feld muss beim Erstellen vorhanden sein |
type |
'type' => 'integer' |
Wert muss dem deklarierten Typ entsprechen |
enum |
'enum' => ['a', 'b'] |
Wert muss einer der aufgeführten Optionen entsprechen |
maxLength |
'maxLength' => 100 |
Zeichenfolge darf diese Länge nicht überschreiten |
minLength |
'minLength' => 3 |
Zeichenfolge muss mindestens diese Länge haben |
format: "email" |
'format' => 'email' |
Muss eine gültige E-Mail-Adresse sein |
format: "url" |
'format' => 'url' |
Muss eine gültige URL sein |
Benutzerdefinierte Validierung
Füge einem beliebigen Feld einen validate-Callback für serverseitige Prüfungen hinzu, die über die integrierten Regeln hinausgehen. Gib zum Bestehen true oder eine Zeichenfolge mit der Fehlermeldung zurück:
'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;
},
],
Der Callback erhält den Feldwert und das vollständige Datenarray, sodass du feldübergreifende Validierungen durchführen kannst.
Format der Fehlerantwort
Validierungsfehler geben den Status 400 mit Fehlerarrays für die einzelnen Felder zurück. Dieses Format orientiert sich an Zods fieldErrors und erleichtert die Zuordnung von Fehlern zu Formularfeldern:
{
"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."]
}
}
}
Jedem Feld ist ein Array mit Fehlermeldungen zugeordnet. Für dasselbe Feld können mehrere Regeln fehlschlagen. Im Frontend:
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-Endpunkte
Alle Endpunkte befinden sich im Namensraum blockstudio/v1/db/:
/db/{block-name}/{schema-name}
Im Blocknamen wird / durch - ersetzt. Bei Blöcken mit nur einem Schema ist der Schemaname default.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/db/{block}/{schema} |
Datensätze auflisten |
POST |
/db/{block}/{schema} |
Datensatz erstellen |
GET |
/db/{block}/{schema}/{id} |
Einzelnen Datensatz abrufen |
PUT |
/db/{block}/{schema}/{id} |
Datensatz aktualisieren |
DELETE |
/db/{block}/{schema}/{id} |
Datensatz löschen |
Abfrageparameter (Liste)
| Parameter | Beschreibung |
|---|---|
limit |
Maximale Anzahl zurückzugebender Datensätze (Standard 50, max. 100) |
offset |
Anzahl der zu überspringenden Datensätze |
| Beliebiger Feldname | Nach exakter Übereinstimmung filtern |
Beispiel: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Formularrendering
Felder können einen Schlüssel component definieren, der auf einen Blockstudio-Block verweist. Rufe
bs_db_form() in deinem Template auf, um alle Felder mithilfe ihrer
Komponentenblöcke als Formular auszugeben.
'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>
Jede Komponente erhält die vollständige Felddefinition als field in ihren Attributen,
damit sie ihre Darstellung anhand des Schemas anpassen kann. Zum Beispiel
liefert $a['field']['name'] den Feldnamen, $a['field']['type'] den Typ,
$a['field']['required'], ob das Feld erforderlich ist usw.
Die Komponentenstruktur folgt demselben Format name, attributes, innerBlocks
wie WordPress-Blöcke. Innere Blöcke werden zuerst gerendert und als
$content an den übergeordneten Block übergeben.
Für die Verwendung von PHP ohne Echo-Ausgabe:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hooks
Aktionen werden vor und nach jedem Schreibvorgang ausgelöst. Alle Hooks erhalten ein einzelnes
$params-Array. Die vollständige Liste findest du in der Referenz zu den PHP-Hooks.
Inline-Hooks
Definiere Hooks direkt in db.php. Sie sind automatisch auf dieses Schema beschränkt,
daher musst du den Block- oder Schemanamen nicht prüfen:
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']);
},
],
];
Globale Hooks
Höre von überall aus auf alle Schemas:
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
}
});
Kombination mit RPC
db.php und rpc.php sind unabhängige Systeme. db.php erzeugt CRUD-
Endpunkte aus einer Schemadefinition. rpc.php definiert benutzerdefinierte Serverfunktionen.
Beide funktionieren eigenständig.
Verwende sie zusammen, wenn du Standarddatenoperationen und benutzerdefinierte Geschäftslogik brauchst:
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',
],
];
Portabilität
Bei JSONC-Speicherung liegen die Daten zusammen mit dem Code. Kopiere den Blockordner auf eine andere Website, und alles zieht mit um: UI, Logik, Zugriffskontrolle und die Daten selbst.
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
Keine Datenbankmigrationen, keine Export- oder Importschritte. Kopiere einfach den Ordner.
Auch die Speicherung von Storh ist portabel, liegt aber unter uploads/blockstudio/db/
statt im Blockordner. So bleiben aktive, beschreibbare Daten aus deinem Quellverzeichnis heraus,
während jedes Schema weiterhin einen einfachen dateibasierten Speicher hat, der sich unabhängig sichern,
kopieren oder migrieren lässt.
Filter
Ändere Schemas programmatisch von außerhalb des Blocks:
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;
});