Zum Inhalt springen

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

  1. Du erstellst db.php in deinem Blockverzeichnis
  2. Sie gibt ein Schema zurück: Felder, Typen, Validierungsregeln und Zugriffskontrolle
  3. Blockstudio erstellt den Speicher (Tabelle, Datei oder Post-Meta)
  4. Fünf REST-Endpunkte werden automatisch generiert (Auflisten, Abrufen, Erstellen, Aktualisieren, Löschen)
  5. bs.db() und Db::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.

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

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

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.

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

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

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

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

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

Für Blöcke mit einem Schema:

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

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

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

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:

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

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

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

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:

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

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:

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

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:

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

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

Für Blöcke mit einem Schema:

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

PHP
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

PHP
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

  1. Beim Laden der Seite ruft der Client einen kompakten Hash der aktuellen Daten ab
  2. Alle interval Millisekunden wird der Hash erneut abgerufen
  3. Hat sich der Hash geändert, werden die vollständigen Daten abgerufen
  4. Die neuen Daten werden über store() in den Interactivity-API-Store übertragen
  5. 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:

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

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

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:

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

Jedem Feld ist ein Array mit Fehlermeldungen zugeordnet. Für dasselbe Feld können mehrere Regeln fehlschlagen. Im Frontend:

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-Endpunkte

Alle Endpunkte befinden sich im Namensraum blockstudio/v1/db/:

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

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>

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:

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

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

Globale Hooks

Höre von überall aus auf alle Schemas:

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

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:

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

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.

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

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