Base de données
La couche de base de données vous permet de définir un modèle de données pour votre bloc dans un fichier db.php.
Blockstudio génère des points de terminaison CRUD REST, valide les entrées selon le schéma, gère automatiquement le stockage et fournit un client JavaScript (bs.db()) ainsi qu’une classe PHP API (classe Db).
C’est l’épine dorsale des données des blocs full-stack. Tandis que RPC gère la logique personnalisée, la couche de base de données gère les données structurées sans code passe-partout.
Fonctionnement
- Vous créez
db.phpdans le répertoire de votre bloc - Il renvoie un schéma : champs, types, règles de validation et contrôle d’accès
- Blockstudio crée le stockage (table, fichier ou métadonnées de publication)
- Cinq points de terminaison REST sont générés automatiquement (liste, récupération, création, mise à jour, suppression)
bs.db()etDb::get()fournissent un accès client et serveur
Aucune migration, aucun contrôleur, aucun enregistrement de route.
Transmettez des valeurs littérales aux API REST et PHP. Les backends meta et post_type gèrent en interne l’échappement des barres obliques inverses dans les métadonnées WordPress, en préservant les barres obliques inverses et les chaînes entre guillemets dans les valeurs scalaires comme dans les objets ou tableaux imbriqués. N’ajoutez pas de barres obliques inverses aux valeurs des enregistrements de la base de données au préalable.
Définition des schémas
Schéma unique
La forme la plus simple : un seul modèle de données par bloc.
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'],
],
];
Syntaxe de construction native PHP
db.php peut aussi utiliser un petit générateur API fondé sur des arguments nommés et des objets de définition en lecture seule. Les tableaux restent le format par défaut, mais cette option native PHP est plus facile à explorer lorsque le schéma prend de l’ampleur.
<?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'),
],
);
Utilisez Schema::make() pour un schéma unique, ou renvoyez un tableau d’appels Schema::make(...) nommés pour les blocs à plusieurs schémas.
Schémas multiples
Un bloc peut avoir plusieurs modèles de données. Renvoyez un tableau nommé :
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'],
],
],
];
Chaque schéma dispose de ses propres points de terminaison, stockage et contrôle d’accès.
Modes de stockage
Six systèmes de stockage, chacun adapté à des cas d’utilisation différents.
Table personnalisée (storage: "table")
Chaque enregistrement est une ligne dans une table MySQL dédiée. Blockstudio crée et gère automatiquement la table à l’aide de la fonction dbDelta() de WordPress. L’ajout de nouveaux champs au schéma ajoute des colonnes au prochain chargement de page. Les colonnes existantes ne sont jamais supprimées.
Idéal pour : les données structurées, les requêtes et les applications de production.
SQLite (storage: "sqlite")
Chaque schéma dispose de son propre fichier de base de données SQLite dans un sous-dossier db/. Blockstudio crée automatiquement le fichier et la table, et ajoute les colonnes manquantes lorsque le schéma change (comme dbDelta pour MySQL). Utilise le mode journal WAL pour les lectures concurrentes.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Idéal pour : les données structurées qui nécessitent de vraies requêtes SQL tout en restant portables. Gère efficacement des milliers d’enregistrements sans tout charger en mémoire. Copiez le dossier pour déplacer les données.
Fichiers JSONC (storage: "jsonc")
Les enregistrements sont stockés sous forme d’un objet JSON par ligne dans un fichier .jsonc, dans un sous-dossier db/. Le fichier est créé automatiquement à la première écriture. Les lignes commençant par // sont traitées comme des commentaires et conservées.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Idéal pour : les petits jeux de données, les données de type configuration, les enregistrements initiaux et les exemples dont les versions sont suivies. JSONC est volontairement un fichier unique dans le dossier de votre bloc. Utilisez-le lorsque vous voulez que les données accompagnent le code, et non lorsque vous prévoyez de nombreuses écritures simultanées.
Fichiers Storh (storage: "storh")
Storh stocke chaque enregistrement dans un fichier distinct sous les téléversements 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
Les ID publics des enregistrements restent les mêmes ID entiers que ceux utilisés ailleurs dans bs.db().
Blockstudio associe ces ID aux ID de fichiers UUIDv7 internes de Storh et stocke l’id entier dans les données de l’enregistrement. Ainsi, les appels JavaScript, REST et PHP n’ont pas à gérer les UUID.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio crée des index Storh à partir de votre schéma. Comme chaque champ déclaré peut servir de filtre de liste, tous les champs déclarés sont indexés. Les champs de type entier, nombre et date utilisent des index de plage ; les champs marqués 'unique' => true ou 'index' => 'unique' utilisent des index uniques.
Idéal pour : les données de production stockées dans des fichiers qui nécessitent des écritures simultanées plus sûres, des index dérivés du schéma et un stockage portable au niveau des téléversements, sans intégrer les enregistrements actifs à l’arborescence source du bloc.
Migration de JSONC vers Storh
Si vous avez commencé avec un fichier .jsonc et souhaitez transférer les mêmes enregistrements vers Storh, exécutez :
wp bs db migrate my-theme/app subscribers --to=storh
Pour les blocs à schéma unique :
wp bs db migrate my-theme/app --to=storh
La migration lit le fichier db/{schema}.jsonc existant, écrit les enregistrements dans Storh en préservant les ID entiers, recrée les index, vérifie le stockage cible et laisse le fichier JSONC intact. Pour revenir en arrière, il suffit de rétablir storage à "jsonc" dans le schéma.
Métadonnées de publication (storage: "meta")
Les enregistrements sont stockés sous forme de tableau JSON dans les métadonnées de publication WordPress, associées à une publication précise via postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Idéal pour : les données liées à une publication ou à une page précise.
Type de publication personnalisé (storage: "post_type")
Chaque enregistrement est une publication WordPress dans un type de publication personnalisé enregistré automatiquement. Chaque champ du schéma devient une entrée post_meta distincte. Les enregistrements peuvent ainsi être interrogés avec WP_Query, sont compatibles avec les extensions REST API et sont visibles par des outils comme GraphQL.
Idéal pour : les données qui doivent s’intégrer nativement à WordPress. Chaque champ peut être interrogé et indexé indépendamment.
Client JavaScript
Blockstudio injecte bs.db() sur les pages contenant des blocs de base de données. Il renvoie un objet doté de cinq méthodes :
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);
Le premier argument est le nom du bloc (avec /), le deuxième est le nom du schéma.
Pour les blocs à schéma unique, omettez le nom du schéma (la valeur par défaut est "default").
Cache
bs.cache est un cache de requêtes en mémoire, partagé entre tous les appels bs.query et bs.mutate. Vous pouvez aussi l’utiliser directement :
// 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();
Les entrées du cache sont stockées en mémoire et effacées lors de la navigation entre les pages. Elles sont principalement utilisées en interne par bs.query et bs.mutate, mais un accès direct est utile pour préremplir des données ou invalider manuellement le cache après des opérations personnalisées.
Requête
bs.query() enveloppe toute fonction asynchrone avec la mise en cache, la déduplication et le contrôle de l’ancienneté. Plusieurs appels utilisant la même clé pendant une requête renvoient la même promesse (aucune récupération en double).
// 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 }
);
Le premier argument est une clé de cache (n’importe quelle chaîne). Le deuxième est une fonction qui renvoie une promesse. Le troisième est un objet d’options facultatif :
| Option | Type | Description |
|---|---|---|
staleTime |
number |
Délai en millisecondes avant que les données en cache soient considérées comme obsolètes. 0 (par défaut) relance toujours la récupération. |
Si le cache contient une donnée associée à la clé et que cette donnée date de moins de staleTime, la valeur en cache est renvoyée immédiatement sans appeler la fonction.
Mutation
bs.mutate() gère les opérations d’écriture avec des mises à jour optimistes et un retour arrière automatique en cas d’échec. Il propose deux modes : le mode automatique pour les schémas CRUD courants et le mode manuel pour un contrôle total.
Le mode automatique fonctionne avec un objet d’état réactif (comme Alpine.js $data). Transmettez state, key, action et, éventuellement, 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),
});
En cas de réussite, les données optimistes sont remplacées par la réponse du serveur. En cas d’échec, l’état revient à un instantané pris avant la mutation. La clé de cache est automatiquement invalidée après chaque mutation réussie.
Un échec signifie que la promesse renvoyée par fn est rejetée. bs.db() et bs.fn() se résolvent avec le corps de l’erreur en cas d’erreur de validation, d’enregistrement manquant ou d’échec du contrôle des autorisations. Lancez donc une exception si le résultat contient code et que vous souhaitez également déclencher un retour arrière dans ces cas :
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)),
});
Pour les opérations de création, un id temporaire (comme __temp_1) est attribué à l’élément optimiste. Lorsque le serveur répond, l’élément temporaire est remplacé par les données réelles, y compris l’id attribué par le serveur.
Le mode manuel vous donne un contrôle total grâce aux fonctions de rappel before, onSuccess et 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;
},
});
| Option | Type | Mode | Description |
|---|---|---|---|
fn |
function |
Les deux | Fonction asynchrone qui effectue la mutation. Obligatoire. |
state |
object |
Automatique | Objet d’état réactif (e.g., Alpine $data). |
key |
string |
Automatique | Nom de la propriété d’état qui contient le tableau. Sert aussi de clé de cache. |
action |
string |
Automatique | L’une des valeurs suivantes : create, update ou delete. |
id |
any |
Automatique | ID de l’enregistrement pour les actions update et delete. |
optimistic |
object |
Automatique | Données à appliquer de manière optimiste avant la réponse du serveur. |
before |
function |
Manuel | Appelée avant fn. Sa valeur de retour est transmise à onSuccess/onError en tant que snapshot. |
onSuccess |
function |
Manuel | Appelée avec (result, snapshot) en cas de réussite. |
onError |
function |
Manuel | Appelée avec (error, snapshot) en cas d’échec. |
invalidate |
string |
Manuel | Clé de cache à invalider en cas de réussite. |
PHP API
La classe Db fournit les mêmes opérations côté serveur. Utilisez-la dans rpc.php, cron.php, des modèles ou n’importe quel 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);
Pour les blocs à schéma unique :
$db = Db::get('my-theme/block');
Interrogation périodique en temps réel
Ajoutez realtime à votre schéma pour activer l’interrogation périodique automatique. Lorsque les données changent sur le serveur, le UI est automatiquement mis à jour via le magasin Interactivity API. Aucune modification de JavaScript n’est nécessaire.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Avec true, Blockstudio effectue une interrogation périodique toutes les 3 secondes, en utilisant le nom du schéma comme clé d’état du magasin Interactivity API (default pour les blocs à schéma unique).
Configuration personnalisée
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Option | Type | Valeur par défaut | Description |
|---|---|---|---|
key |
string |
nom du schéma | Nom de la propriété de state qui contient le tableau de données |
interval |
number |
3000 |
Intervalle d’interrogation en millisecondes |
Fonctionnement
- Au chargement de la page, le client récupère une empreinte légère des données actuelles
- Toutes les
intervalmillisecondes, il récupère à nouveau l’empreinte - Si l’empreinte a changé, il récupère l’ensemble des données
- Les nouvelles données sont envoyées au magasin Interactivity API via
store() - Toutes les directives liées à cette propriété d’état sont automatiquement affichées à nouveau
L’interrogation périodique s’exécute uniquement sur les pages où se trouve un élément data-wp-interactive correspondant. Elle s’interrompt lorsque l’onglet du navigateur est masqué et reprend lorsqu’il redevient visible.
Le point de terminaison d’empreinte (?_hash=1) renvoie uniquement une somme de contrôle md5 et le nombre d’enregistrements, ce qui allège les requêtes périodiques.
Données propres à l’utilisateur
Définissez userScoped: true pour associer automatiquement tous les enregistrements à l’utilisateur actuel.
Blockstudio ajoute une colonne user_id, la renseigne à la création et filtre toutes les opérations pour ne conserver que les enregistrements de l’utilisateur actuel :
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Aucun champ user_id à gérer manuellement, aucun hook before_create, aucun filtrage dans RPC. Les utilisateurs peuvent uniquement consulter, modifier et supprimer leurs propres enregistrements. La colonne user_id est entièrement gérée par Blockstudio.
Avec le stockage post_type, userScoped est associé à post_author au lieu d’être stocké dans une colonne user_id distincte.
Contrôle d’accès
Chaque opération CRUD dispose de son propre niveau d’autorisation :
| Valeur | Comportement |
|---|---|
true |
Accès public protégé contre les attaques CSRF (autorise les utilisateurs déconnectés, X-BS-Token requis) |
'open' |
Accès réellement public, sans protection CSRF ni authentification (pour les webhooks et les API externes) |
'edit_posts' |
Vérification de la permission WordPress |
['cap_a', 'cap_b'] |
L’utilisateur doit disposer d’au moins une des permissions répertoriées |
omis / null |
Authentification requise (utilisateur connecté) |
'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
],
Protection CSRF
Les points de terminaison publics (true) sont protégés par un en-tête X-BS-Token. bs.db() et bs.fn() récupèrent des identifiants à jour depuis un point de terminaison de même origine sans cache, au lieu d’intégrer des jetons à expiration dans le HTML de la page. Les pages servies depuis des caches externes de longue durée continuent de fonctionner. Les appels anonymes sans jeton valide reçoivent une réponse 403.
Les identifiants sont demandés lors du premier appel API, et non à chaque affichage de page. Les deux clients, y compris l’interrogation en temps réel de la base de données, partagent une seule actualisation des identifiants en cours. Les identifiants sont actualisés après cinq minutes d’utilisation. Un nonce WordPress ou un jeton CSRF Blockstudio rejeté déclenche une actualisation et une nouvelle tentative ; les erreurs de permission ordinaires ne donnent lieu à aucune nouvelle tentative. Les requêtes des utilisateurs connectés utilisent toujours la session de l’utilisateur actuel ainsi que les vérifications de capacité et de propriété des enregistrements du schéma.
Placez POST /wp-json/blockstudio/v1/client/credentials hors de tout cache de proxy ou CDN. Il envoie Cache-Control: private, no-store et exige une requête de même origine avec un en-tête non simple. Les clients intégrés gèrent cela automatiquement.
Utilisez 'open' lorsque vous avez besoin d’un accès réellement non authentifié et sans protection CSRF, par exemple pour recevoir des webhooks de services externes.
Types de champs
| Type | Colonne MySQL | Type PHP | Description |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Texte, maxLength par défaut 255 |
integer |
bigint(20) |
int |
Nombres entiers |
number |
decimal(20,6) |
float |
Nombres décimaux |
boolean |
tinyint(1) |
bool |
Vrai/faux |
text |
longtext |
string |
Contenu textuel long |
Validation
Toutes les écritures (création et mise à jour) sont validées selon le schéma avant de toucher au stockage. La validation a lieu côté serveur, que la requête provienne de bs.db(), du REST API ou de Db::get().
Règles intégrées
| Règle | Exemple | Description |
|---|---|---|
required |
'required' => true |
Le champ doit être renseigné lors de la création |
type |
'type' => 'integer' |
La valeur doit correspondre au type déclaré |
enum |
'enum' => ['a', 'b'] |
La valeur doit correspondre à l’une des options répertoriées |
maxLength |
'maxLength' => 100 |
La chaîne ne peut pas dépasser cette longueur |
minLength |
'minLength' => 3 |
La chaîne doit comporter au moins ce nombre de caractères |
format: "email" |
'format' => 'email' |
Doit être une adresse e-mail valide |
format: "url" |
'format' => 'url' |
Doit être une valeur URL valide |
Validation personnalisée
Ajoutez une fonction de rappel validate à n’importe quel champ pour effectuer des vérifications côté serveur au-delà des règles intégrées. Renvoyez true pour valider, ou une chaîne contenant le message d’erreur :
'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;
},
],
La fonction de rappel reçoit la valeur du champ et le tableau complet de données, ce qui permet d’effectuer une validation entre plusieurs champs.
Format des réponses d’erreur
Les erreurs de validation renvoient un statut 400 avec des tableaux d’erreurs pour chaque champ. Ce format s’inspire de ZodfieldErrors et permet d’associer facilement les erreurs aux champs du formulaire :
{
"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."]
}
}
}
Chaque champ correspond à un tableau de messages d’erreur. Plusieurs règles peuvent échouer pour un même champ. Côté interface :
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]);
});
}
Points de terminaison REST
Tous les points de terminaison se trouvent dans l’espace de noms blockstudio/v1/db/ :
/db/{block-name}/{schema-name}
Le nom du bloc remplace / par -. Pour les blocs à schéma unique, le nom du schéma est default.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/db/{block}/{schema} |
Lister les enregistrements |
POST |
/db/{block}/{schema} |
Créer un enregistrement |
GET |
/db/{block}/{schema}/{id} |
Récupérer un enregistrement |
PUT |
/db/{block}/{schema}/{id} |
Mettre à jour un enregistrement |
DELETE |
/db/{block}/{schema}/{id} |
Supprimer un enregistrement |
Paramètres de requête (liste)
| Paramètre | Description |
|---|---|
limit |
Nombre maximal d’enregistrements à renvoyer (50 par défaut, maximum 100) |
offset |
Nombre d’enregistrements à ignorer |
| N’importe quel nom de champ | Filtrer selon une correspondance exacte de valeur |
Exemple : GET /db/my-theme-app/subscribers?plan=pro&limit=10
Rendu de formulaires
Les champs peuvent définir une clé component faisant référence à un bloc Blockstudio. Appelez bs_db_form() dans votre modèle pour afficher tous les champs dans un formulaire à l’aide de leurs blocs de composant.
'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>
Chaque composant reçoit la définition complète du champ sous forme de field dans ses attributs, ce qui lui permet d’adapter son rendu en fonction du schéma. Par exemple, $a['field']['name'] indique le nom du champ, $a['field']['type'] son type, $a['field']['required'] s’il est obligatoire, etc.
La structure du composant suit le même format name, attributes, innerBlocks que les blocs WordPress. Les blocs internes sont rendus en premier et transmis au parent sous forme de $content.
Pour utiliser PHP sans effectuer d’écho :
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hooks
Les actions se déclenchent avant et après chaque opération d’écriture. Tous les hooks reçoivent un seul tableau $params. Consultez la référence des hooks PHP Hooks pour la liste complète.
Hooks intégrés
Définissez les hooks directement dans db.php. Leur portée est automatiquement limitée à ce schéma : vous n’avez donc pas besoin de vérifier le nom du bloc ou du schéma :
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']);
},
],
];
Hooks globaux
Écoutez tous les schémas depuis n’importe quel endroit :
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
}
});
Combiner avec RPC
db.php et rpc.php sont des systèmes indépendants. db.php génère des points de terminaison CRUD à partir d’une définition de schéma. rpc.php définit des fonctions serveur personnalisées. Chacun fonctionne de manière autonome.
Utilisez-les ensemble lorsque vous avez besoin d’opérations de données standard et d’une logique métier personnalisée :
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é
Avec le stockage JSONC, les données sont stockées avec le code. Copiez le dossier du bloc vers un autre site et tout est transféré ensemble : le UI, la logique, le contrôle d’accès et les données elles-mêmes.
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
Aucune migration de base de données, aucune étape d’exportation ou d’importation. Copiez simplement le dossier.
Le stockage Storh est également portable, mais il se trouve sous uploads/blockstudio/db/ plutôt que dans le dossier du bloc. Les données actives et modifiables restent ainsi hors de votre arborescence source, tandis que chaque schéma dispose d’un stockage en fichiers simples pouvant être sauvegardé, copié ou migré indépendamment.
Filtrer
Modifiez des schémas par programmation depuis l’extérieur du bloc :
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;
});