Database
Met de databaselaag definieer je een datamodel voor je blok in een db.php-bestand. Blockstudio genereert automatisch REST CRUD-eindpunten, valideert invoer aan de hand van het schema, beheert de opslag automatisch en biedt zowel een JavaScript-client (bs.db()) als een PHP API (klasse Db).
Dit is de datafundering voor full-stackblokken. Waar RPC aangepaste logica afhandelt, verwerkt de databaselaag gestructureerde gegevens zonder boilerplate.
Werking
- Maak
db.phpaan in de map van je blok - Deze retourneert een schema met velden, typen, validatieregels en toegangsbeheer
- Blockstudio maakt de opslag aan (tabel, bestand of postmeta)
- Er worden automatisch vijf REST-eindpunten gegenereerd (lijst, ophalen, aanmaken, bijwerken, verwijderen)
bs.db()enDb::get()bieden toegang voor client en server
Geen migraties, controllers of routeregistratie nodig.
Geef letterlijke waarden door aan de API’s REST en PHP. De backends meta en post_type verwerken het escapen van WordPress-meta intern, waarbij backslashes en aanhalingstekens behouden blijven in zowel scalaire waarden als geneste objecten of arrays. Escap database-recordwaarden niet vooraf.
Schema’s definiëren
Eén schema
De eenvoudigste vorm: één datamodel per blok.
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-eigen builder-syntaxis
db.php kan ook een kleine builder-API gebruiken, gebaseerd op benoemde argumenten en onveranderlijke definitieobjecten. Arrays blijven de standaardindeling, maar dit biedt een beter vindbare, PHP-eigen optie wanneer het schema groter wordt.
<?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'),
],
);
Gebruik Schema::make() voor één schema of retourneer een benoemde array met aanroepen van Schema::make(...) voor blokken met meerdere schema’s.
Meerdere schema’s
Eén blok kan meerdere datamodellen bevatten. Retourneer een benoemde array:
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'],
],
],
];
Elk schema krijgt eigen eindpunten, opslag en toegangsbeheer.
Opslagmodi
Zes opslagbackends, elk geschikt voor verschillende toepassingen.
Aangepaste tabel (storage: "table")
Elk record is een rij in een speciale MySQL-tabel. Blockstudio maakt en beheert de tabel automatisch met de functie dbDelta() van WordPress. Nieuwe velden aan het schema toevoegen voegt bij de volgende paginalading kolommen toe. Bestaande kolommen worden nooit verwijderd.
Geschikt voor: gestructureerde gegevens, query’s en productieapplicaties.
SQLite (storage: "sqlite")
Elk schema krijgt een eigen SQLite-databasebestand in een submap db/. Blockstudio maakt het bestand en de tabel automatisch aan en voegt ontbrekende kolommen toe wanneer het schema verandert (zoals dbDelta voor MySQL). Gebruikt WAL-journalmodus voor gelijktijdige leesbewerkingen.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Geschikt voor: gestructureerde gegevens waarvoor echte SQL-query’s nodig zijn, maar die overdraagbaar moeten blijven. Verwerkt duizenden records efficiënt zonder alles in het geheugen te laden. Kopieer de map om de gegevens te verplaatsen.
JSONC-bestanden (storage: "jsonc")
Records worden opgeslagen als één JSON-object per regel in een .jsonc-bestand in een submap db/. Het bestand wordt automatisch aangemaakt bij de eerste schrijfbewerking. Regels die beginnen met // worden als opmerkingen behandeld en behouden.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Geschikt voor: kleine datasets, configuratieachtige gegevens, seedrecords en voorbeelden die versiebeheerbaar zijn. JSONC is bewust één bestand in de map van je blok. Gebruik dit als je wilt dat de gegevens met de code meereizen, niet als je veel gelijktijdige schrijfbewerkingen verwacht.
Storh-bestanden (storage: "storh")
Storh slaat elk record op als een afzonderlijk bestand onder WordPress-uploads:
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
Openbare record-ID’s blijven dezelfde gehele getallen als elders in bs.db(). Blockstudio koppelt die ID’s aan de interne UUIDv7-bestands-ID’s van Storh en slaat het gehele getal id op in de recordgegevens, zodat aanroepende code van JavaScript, REST en PHP geen UUID’s hoeft af te handelen.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio bouwt Storh-indexen op basis van je schema. Omdat elk gedeclareerd veld als filter voor lijsten kan worden gebruikt, wordt elk gedeclareerd veld geïndexeerd. Velden met gehele getallen, getallen en datumachtige waarden gebruiken bereikindexen; velden met 'unique' => true of 'index' => 'unique' gebruiken unieke indexen.
Geschikt voor: productiegegevens op basis van bestanden die veiliger gelijktijdig schrijven vereisen, schema-afgeleide indexen en overdraagbare opslag op uploadniveau, zonder live records in de bronstructuur van het blok vast te leggen.
JSONC migreren naar Storh
Als je bent begonnen met een .jsonc-bestand en dezelfde records in Storh wilt hebben, voer dan dit uit:
wp bs db migrate my-theme/app subscribers --to=storh
Voor blokken met één schema:
wp bs db migrate my-theme/app --to=storh
De migratie leest de bestaande db/{schema}.jsonc, schrijft records naar Storh met behoud van gehele getallen als ID’s, bouwt de indexen opnieuw op, controleert de doelopslag en laat het JSONC-bestand ongemoeid. Terugdraaien kan eenvoudig door de storage van het schema terug te zetten op "jsonc".
Postmeta (storage: "meta")
Records worden opgeslagen als een JSON-array in postmeta van WordPress, gekoppeld aan een specifieke post via postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Geschikt voor: gegevens die bij een specifieke post of pagina horen.
Aangepast posttype (storage: "post_type")
Elk record is een WordPress-post in een automatisch geregistreerd aangepast posttype. Elk veld in het schema wordt een afzonderlijk post_meta-item. Daardoor zijn records opvraagbaar met WP_Query, compatibel met API-plug-ins voor REST en zichtbaar in tools zoals GraphQL.
Geschikt voor: gegevens die standaard met WordPress moeten integreren. Elk veld kan afzonderlijk worden opgevraagd en geïndexeerd.
JavaScript-client
Blockstudio voegt bs.db() toe aan pagina’s met databaseblokken. Het retourneert een object met vijf 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);
Het eerste argument is de bloknaam (met /), het tweede is de schemanaam. Laat de schemanaam weg voor blokken met één schema (standaard "default").
Cache
bs.cache is een querycache in het geheugen die wordt gedeeld door alle aanroepen van bs.query en bs.mutate. Je kunt deze ook rechtstreeks gebruiken:
// 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-items worden in het geheugen opgeslagen en bij paginanavigatie gewist. Ze worden voornamelijk intern gebruikt door bs.query en bs.mutate, maar rechtstreekse toegang is handig om gegevens vooraf te vullen of de cache na aangepaste bewerkingen handmatig ongeldig te maken.
Query
bs.query() voorziet elke asynchrone functie van caching, deduplicatie en verouderingsbeheer. Meerdere aanroepen met dezelfde sleutel terwijl een verzoek wordt verwerkt, retourneren dezelfde promise (er worden geen dubbele gegevens opgehaald).
// 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 }
);
Het eerste argument is een cachesleutel (willekeurige tekenreeks). Het tweede is een functie die een promise retourneert. Het derde is een optioneel optiesobject:
| Optie | Type | Beschrijving |
|---|---|---|
staleTime |
number |
Aantal milliseconden voordat gegevens in de cache als verouderd gelden. 0 (standaard) haalt altijd opnieuw op. |
Als de cache gegevens voor de sleutel bevat en die minder oud zijn dan staleTime, wordt de gecachete waarde onmiddellijk geretourneerd zonder de functie aan te roepen.
Muteren
bs.mutate() verwerkt schrijfbewerkingen met optimistische updates en automatisch terugdraaien bij fouten. Er zijn twee modi: de automatische modus voor gangbare CRUD-patronen en de handmatige modus voor volledige controle.
Automatische modus werkt met een reactief statusobject (zoals Alpine.js $data). Geef state, key, action en eventueel optimistic door:
// 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),
});
Bij succes worden de optimistische gegevens vervangen door het serverantwoord. Bij een fout wordt de status teruggezet naar een momentopname van vóór de wijziging. Na elke geslaagde wijziging wordt de cachesleutel automatisch ongeldig gemaakt.
Er is sprake van een fout wanneer de promise die fn retourneert wordt afgewezen. bs.db() en bs.fn() worden opgelost met de foutinhoud bij een validatiefout, een ontbrekend record of een mislukte machtigingscontrole. Werp daarom een fout wanneer het resultaat een code bevat, als ook die gevallen moeten worden teruggedraaid:
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)),
});
Bij aanmaakbewerkingen krijgt het optimistische item een tijdelijk id (zoals __temp_1). Wanneer de server reageert, wordt het tijdelijke item bijgewerkt met de echte gegevens, inclusief het door de server toegewezen id.
Handmatige modus geeft je volledige controle met de callbacks before, onSuccess en onError:
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;
},
});
| Optie | Type | Modus | Beschrijving |
|---|---|---|---|
fn |
function |
Beide | De asynchrone functie die de wijziging uitvoert. Verplicht. |
state |
object |
Automatisch | Reactief statusobject (e.g., Alpine $data). |
key |
string |
Automatisch | Eigenschapsnaam op de status die de array bevat. Wordt ook als cachesleutel gebruikt. |
action |
string |
Automatisch | Een van create, update of delete. |
id |
any |
Automatisch | Record-ID voor acties update en delete. |
optimistic |
object |
Automatisch | Gegevens die optimistisch worden toegepast voordat de server reageert. |
before |
function |
Handmatig | Wordt aangeroepen vóór fn. De retourwaarde wordt als snapshot doorgegeven aan onSuccess/onError. |
onSuccess |
function |
Handmatig | Wordt bij succes aangeroepen met (result, snapshot). |
onError |
function |
Handmatig | Wordt bij een fout aangeroepen met (error, snapshot). |
invalidate |
string |
Handmatig | Cachesleutel die bij succes ongeldig moet worden gemaakt. |
PHP API
De klasse Db biedt dezelfde bewerkingen aan de serverzijde. Gebruik deze in rpc.php, cron.php, templates of andere 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);
Voor blokken met één schema:
$db = Db::get('my-theme/block');
Realtime peilen
Voeg realtime toe aan je schema om automatisch peilen in te schakelen. Wanneer gegevens op de server veranderen, wordt de UI automatisch bijgewerkt via de Interactivity-API-store. Er zijn geen wijzigingen aan JavaScript nodig.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Met true peilt Blockstudio elke 3 seconden, met de schemanaam als sleutel voor de status van de Interactivity-API (default voor blokken met één schema).
Aangepaste configuratie
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Optie | Type | Standaard | Beschrijving |
|---|---|---|---|
key |
string |
schemanaam | Eigenschapsnaam op state die de gegevensarray bevat |
interval |
number |
3000 |
Peilinterval in milliseconden |
Werking
- Bij het laden van de pagina haalt de client een lichte hash van de huidige gegevens op
- Elke
intervalmilliseconden wordt de hash opnieuw opgehaald - Als de hash is veranderd, wordt de volledige dataset opgehaald
- De nieuwe gegevens worden via
store()naar de Interactivity-API-store verzonden - Directieven die aan die statuseigenschap zijn gekoppeld, worden automatisch opnieuw weergegeven
Peilen wordt alleen uitgevoerd op pagina’s waar een overeenkomend data-wp-interactive-element aanwezig is. Het wordt gepauzeerd wanneer het browsertabblad verborgen is en hervat zodra het weer zichtbaar is.
Het hash-eindpunt (?_hash=1) retourneert alleen een md5-checksum en het aantal records, zodat peilverzoeken klein blijven.
Gebruikersgebonden gegevens
Stel userScoped: true in om alle records automatisch aan de huidige gebruiker te koppelen. Blockstudio voegt een kolom user_id toe, stelt deze in bij het aanmaken en beperkt alle bewerkingen tot de records van de huidige gebruiker:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Geen handmatig veld user_id, geen hook before_create en geen filtering in RPC. Gebruikers kunnen alleen hun eigen records bekijken, bewerken en verwijderen. De kolom user_id wordt volledig beheerd door Blockstudio.
Bij opslag in post_type koppelt userScoped aan post_author in plaats van aan een afzonderlijke kolom user_id.
Toegangsbeheer
Elke CRUD-bewerking heeft een eigen machtigingsniveau:
| Waarde | Gedrag |
|---|---|
true |
Openbaar met CSRF-bescherming (uitgelogde gebruikers toegestaan, X-BS-Token vereist) |
'open' |
Echt openbaar, zonder CSRF of authenticatie (voor webhooks en externe API’s) |
'edit_posts' |
Controle van de mogelijkheid WordPress |
['cap_a', 'cap_b'] |
Gebruiker heeft een van de vermelde mogelijkheden nodig |
weggelaten / null |
Authenticatie vereist (aangemelde gebruiker) |
'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-bescherming
Openbare endpoints (true) worden beveiligd met een X-BS-Token-header. bs.db() en bs.fn() halen actuele inloggegevens op bij een niet-gecachet endpoint van dezelfde oorsprong, in plaats van verlopen tokens in de paginacache HTML op te nemen. Pagina’s die vanuit langdurige externe caches worden aangeboden, blijven werken. Anonieme aanroepen zonder geldig token krijgen een 403-reactie.
Inloggegevens worden opgevraagd bij de eerste API-aanroep, niet bij elke paginaweergave. Beide clients, inclusief het pollen van realtime databasegegevens, delen één lopende vernieuwing van inloggegevens. Na vijf minuten gebruik worden de inloggegevens vernieuwd. Een afgewezen WordPress-nonce of Blockstudio-CSRF-token leidt tot één vernieuwing en nieuwe poging; gewone toestemmingsfouten worden niet opnieuw geprobeerd. Ingelogde aanvragen gebruiken nog steeds de sessie van de bezoeker en de bevoegdheids- en recordeigendomcontroles van het schema.
Houd POST /wp-json/blockstudio/v1/client/credentials buiten elke proxy- of CDN-cache. Het verstuurt Cache-Control: private, no-store en vereist een aanvraag van dezelfde oorsprong met een niet-eenvoudige header. De ingebouwde clients regelen dit automatisch.
Gebruik 'open' wanneer je werkelijk toegang zonder authenticatie en zonder CSRF nodig hebt, bijvoorbeeld voor binnenkomende webhooks van externe services.
Veldtypen
| Type | Kolom MySQL | Type PHP | Beschrijving |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Tekst, standaard maxLength 255 |
integer |
bigint(20) |
int |
Gehele getallen |
number |
decimal(20,6) |
float |
Decimale getallen |
boolean |
tinyint(1) |
bool |
Waar/onwaar |
text |
longtext |
string |
Tekst met lange inhoud |
Validatie
Alle schrijfopdrachten (aanmaken en bijwerken) worden aan het schema getoetst voordat de opslag wordt aangepast. Validatie vindt plaats aan de serverzijde, ongeacht of het verzoek afkomstig is van bs.db(), de REST API of Db::get().
Ingebouwde regels
| Regel | Voorbeeld | Beschrijving |
|---|---|---|
required |
'required' => true |
Veld moet aanwezig zijn bij aanmaken |
type |
'type' => 'integer' |
Waarde moet overeenkomen met het opgegeven type |
enum |
'enum' => ['a', 'b'] |
Waarde moet een van de vermelde opties zijn |
maxLength |
'maxLength' => 100 |
Tekenreeks mag deze lengte niet overschrijden |
minLength |
'minLength' => 3 |
Tekenreeks moet minimaal deze lengte hebben |
format: "email" |
'format' => 'email' |
Moet een geldig e-mailadres zijn |
format: "url" |
'format' => 'url' |
Moet een geldige URL zijn |
Aangepaste validatie
Voeg aan een veld een callback validate toe voor controles aan de serverzijde die verder gaan dan de ingebouwde regels. Retourneer true om goed te keuren, of een tekenreeks met de foutmelding:
'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;
},
],
De callback ontvangt de veldwaarde en de volledige gegevensarray, zodat je validatie tussen velden kunt uitvoeren.
Indeling van foutantwoorden
Validatiefouten retourneren status 400 met foutarrays per veld. Deze indeling is geïnspireerd op ZodfieldErrors en maakt het eenvoudig om fouten aan formuliervelden te koppelen:
{
"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."]
}
}
}
Elk veld wordt gekoppeld aan een array met foutmeldingen. Meerdere regels kunnen voor hetzelfde veld mislukken. Aan de 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-eindpunten
Alle eindpunten vallen onder de namespace blockstudio/v1/db/:
/db/{block-name}/{schema-name}
In de bloknaam wordt / vervangen door -. Voor blokken met één schema is de schemanaam default.
| Methode | Eindpunt | Beschrijving |
|---|---|---|
GET |
/db/{block}/{schema} |
Records weergeven |
POST |
/db/{block}/{schema} |
Een record aanmaken |
GET |
/db/{block}/{schema}/{id} |
Eén record ophalen |
PUT |
/db/{block}/{schema}/{id} |
Een record bijwerken |
DELETE |
/db/{block}/{schema}/{id} |
Een record verwijderen |
Queryparameters (lijst)
| Parameter | Beschrijving |
|---|---|
limit |
Maximaal aantal te retourneren records (standaard 50, max. 100) |
offset |
Aantal records dat wordt overgeslagen |
| Elke veldnaam | Filteren op exacte overeenkomst van de waarde |
Voorbeeld: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Formulieren weergeven
Velden kunnen een component-sleutel definiëren die naar een Blockstudio-blok verwijst. Roep bs_db_form() aan in je template om alle velden als formulier weer te geven met hun componentblokken.
'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>
Elk component ontvangt de volledige velddefinitie als field in de attributen, zodat componenten hun weergave kunnen aanpassen op basis van het schema. $a['field']['name'] geeft bijvoorbeeld de veldnaam, $a['field']['type'] het type en $a['field']['required'] aan of het veld verplicht is, enzovoort.
De componentstructuur volgt hetzelfde name-, attributes-, innerBlocks-formaat als WordPress-blokken. Binnenblokken worden eerst weergegeven en als $content aan het bovenliggende blok doorgegeven.
Voor gebruik van PHP zonder echo:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hooks
Acties worden uitgevoerd vóór en na elke schrijfbewerking. Alle hooks ontvangen één $params-array. Bekijk de referentie voor HooksPHP voor de volledige lijst.
Inline hooks
Definieer hooks rechtstreeks in db.php. Ze worden automatisch aan dat schema gekoppeld, zodat je de naam van het blok of schema niet hoeft te controleren:
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
Luister vanuit elke plek naar gebeurtenissen in alle schema’s:
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
}
});
Combineren met RPC
db.php en rpc.php zijn onafhankelijke systemen. db.php genereert CRUD-eindpunten op basis van een schemadefinitie. rpc.php definieert aangepaste serverfuncties. Elk systeem werkt afzonderlijk.
Gebruik ze samen wanneer je standaardgegevensbewerkingen en aangepaste bedrijfslogica nodig hebt:
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',
],
];
Overdraagbaarheid
Met JSONC-opslag staan gegevens naast de code. Kopieer de blokmap naar een andere site en alles gaat mee: de UI, de logica, de toegangscontrole en de gegevens zelf.
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
Geen databasemigraties en geen export- of importstappen. Kopieer gewoon de map.
Ook Storh-opslag is overdraagbaar, maar de gegevens staan onder uploads/blockstudio/db/ in plaats van in de blokmap. Zo blijven actieve, beschrijfbare gegevens buiten je broncode, terwijl elk schema een opslagplaats met gewone bestanden heeft waarvan je onafhankelijk een back-up kunt maken, die je kunt kopiëren of migreren.
Filter
Wijzig schema’s programmatisch van buiten het blok:
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;
});