Aller au contenu

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

  1. Vous créez db.php dans le répertoire de votre bloc
  2. Il renvoie un schéma : champs, types, règles de validation et contrôle d’accès
  3. Blockstudio crée le stockage (table, fichier ou métadonnées de publication)
  4. Cinq points de terminaison REST sont générés automatiquement (liste, récupération, création, mise à jour, suppression)
  5. bs.db() et Db::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.

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

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

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

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.

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

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

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

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.

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

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

Pour les blocs à schéma unique :

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

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

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

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 :

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

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

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

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 :

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

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 :

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

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 :

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

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 :

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

PHP
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

PHP
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

  1. Au chargement de la page, le client récupère une empreinte légère des données actuelles
  2. Toutes les interval millisecondes, il récupère à nouveau l’empreinte
  3. Si l’empreinte a changé, il récupère l’ensemble des données
  4. Les nouvelles données sont envoyées au magasin Interactivity API via store()
  5. 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 :

PHP
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é)
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
],

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 :

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

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 :

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

Chaque champ correspond à un tableau de messages d’erreur. Plusieurs règles peuvent échouer pour un même champ. Côté interface :

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

Points de terminaison REST

Tous les points de terminaison se trouvent dans l’espace de noms blockstudio/v1/db/ :

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

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>

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 :

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

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

Hooks globaux

Écoutez tous les schémas depuis n’importe quel endroit :

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

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 :

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é

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.

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

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 :

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