Ga naar de inhoud

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

  1. Maak db.php aan in de map van je blok
  2. Deze retourneert een schema met velden, typen, validatieregels en toegangsbeheer
  3. Blockstudio maakt de opslag aan (tabel, bestand of postmeta)
  4. Er worden automatisch vijf REST-eindpunten gegenereerd (lijst, ophalen, aanmaken, bijwerken, verwijderen)
  5. bs.db() en Db::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.

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

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

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.

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

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

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

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.

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

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

Voor blokken met één schema:

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

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

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

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:

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

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

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:

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

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:

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

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:

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

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

Voor blokken met één schema:

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

PHP
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

PHP
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

  1. Bij het laden van de pagina haalt de client een lichte hash van de huidige gegevens op
  2. Elke interval milliseconden wordt de hash opnieuw opgehaald
  3. Als de hash is veranderd, wordt de volledige dataset opgehaald
  4. De nieuwe gegevens worden via store() naar de Interactivity-API-store verzonden
  5. 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:

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

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

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:

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

Elk veld wordt gekoppeld aan een array met foutmeldingen. Meerdere regels kunnen voor hetzelfde veld mislukken. Aan de 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-eindpunten

Alle eindpunten vallen onder de namespace blockstudio/v1/db/:

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

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>

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:

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

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

Luister vanuit elke plek naar gebeurtenissen in alle schema’s:

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

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:

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

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.

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

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:

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