Blocs full-stack
Blockstudio vous permet de créer des applications complètes dans le dossier d’un bloc. Un seul répertoire peut contenir le UI, la logique serveur, le modèle de données, les tâches planifiées et même les données elles-mêmes.
Ce guide présente deux applications concrètes pour illustrer ce modèle : une liste de tâches par utilisateur et un formulaire public d’inscription à une newsletter. Même structure de fichiers, modèles d’accès différents.
Les exemples ci-dessous utilisent la syntaxe des tableaux, car c’est la plus compacte, mais les trois interfaces PHP disposent aussi de variantes natives en PHP :
db.phppeut utiliserBlockstudio\\Db\\SchemaetBlockstudio\\Db\\Fieldrpc.phppeut renvoyer un objet contenant des méthodes#[Rpc]cron.phppeut renvoyer un objet contenant des méthodes#[Cron]
Application de gestion des tâches
Un gestionnaire de tâches individuel. Chaque utilisateur connecté ne voit que ses propres tâches. Il utilise userScoped: true pour isoler automatiquement les données des utilisateurs, SQLite pour un stockage portable, bs.mutate() pour les mises à jour optimistes et l’interrogation périodique en temps réel pour afficher automatiquement les modifications effectuées dans d’autres onglets.
Structure des fichiers
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Définition du bloc
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/todo",
"title": "Todo App",
"category": "widgets",
"icon": "editor-ul",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
supports.interactivity active le traitement des directives de WordPress (rendu côté serveur pour data-wp-each, data-wp-bind, etc.). interactivity.enqueue charge le module @wordpress/interactivity sur le site.
Modèle de données
userScoped: true ajoute automatiquement une colonne user_id, lui attribue une valeur à la création et filtre toutes les requêtes selon l’utilisateur actuel. realtime active l’interrogation périodique automatique afin que les modifications effectuées depuis d’autres onglets ou appareils s’affichent sans actualiser la page.
<?php
return [
'storage' => 'sqlite',
'userScoped' => true,
'realtime' => [
'key' => 'todos',
'interval' => 3000,
],
'capability' => [
'create' => true,
'read' => true,
'update' => true,
'delete' => true,
],
'fields' => [
'text' => [
'type' => 'string',
'required' => true,
'minLength' => 1,
'maxLength' => 500,
],
'done' => [
'type' => 'boolean',
'default' => false,
],
],
];
Le stockage SQLite signifie que le fichier de base de données se trouve à l’emplacement todo/db/default.sqlite. Copiez le dossier du bloc sur un autre site et les données le suivent.
La configuration realtime indique au client de vérifier les modifications toutes les 3 secondes à l’aide d’une comparaison légère des hachages. Lorsque les données changent, state.todos est mis à jour et UI s’affiche à nouveau automatiquement.
Logique serveur personnalisée
Comme userScoped filtre automatiquement les données selon l’utilisateur actuel, le bs.db().list() intégré renvoie déjà uniquement les enregistrements de cet utilisateur. RPC n’est nécessaire que pour les opérations qui dépassent le CRUD : inverser l’état des tâches et tout effacer en bloc.
<?php
use Blockstudio\Db;
return [
'toggle' => [
'callback' => function (array $params) {
$id = (int) ($params['id'] ?? 0);
if (!$id) {
return new \WP_Error('missing_id', 'ID is required.', ['status' => 400]);
}
$db = Db::get('my-theme/todo');
$todo = $db->get_record($id);
if (!$todo) {
return new \WP_Error('not_found', 'Not found.', ['status' => 404]);
}
return $db->update($id, ['done' => !$todo['done']]);
},
'public' => true,
'methods' => ['POST'],
],
'clear_done' => [
'callback' => function () {
$db = Db::get('my-theme/todo');
$todos = $db->list();
$count = 0;
foreach ($todos as $todo) {
if (!empty($todo['done'])) {
$db->delete((int) $todo['id']);
++$count;
}
}
return ['deleted' => $count];
},
'public' => true,
'methods' => ['POST'],
],
];
Nettoyage planifié
Les anciennes tâches terminées sont automatiquement supprimées.
<?php
use Blockstudio\Db;
return [
'cleanup_old_todos' => [
'schedule' => 'daily',
'callback' => function () {
$db = Db::get('my-theme/todo');
$todos = $db->list();
foreach ($todos as $todo) {
$is_done = $todo['done'];
$is_old = strtotime($todo['updated_at']) < strtotime('-30 days');
if ($is_done && $is_old) {
$db->delete((int) $todo['id']);
}
}
},
],
];
Modèle
PHP charge les tâches initiales côté serveur via wp_interactivity_state(), qui fournit les données au traitement des directives pour le rendu côté serveur et à l’hydratation côté client. L’état UI propre à chaque instance (comme la valeur du champ de saisie) se trouve dans data-wp-context.
<?php
$db = \Blockstudio\Db::get('my-theme/todo');
$todos = $db ? $db->list() : [];
$items_left = count(array_filter($todos, fn($t) => empty($t['done'])));
wp_interactivity_state('my-theme/todo', [
'todos' => array_values($todos),
'hasTodos' => !empty($todos),
'hasDone' => count($todos) !== $items_left,
'itemsLeft' => $items_left . ($items_left === 1 ? ' item left' : ' items left'),
]);
?>
<div
data-wp-interactive="my-theme/todo"
data-wp-context='<?php echo esc_attr(wp_json_encode(['newText' => ''])); ?>'
useBlockProps
class="todo-app"
>
<h2>Todos</h2>
<div class="todo-input">
<input
type="text"
placeholder="What needs to be done?"
data-wp-bind--value="context.newText"
data-wp-on--input="my-theme/todo::actions.updateNewText"
data-wp-on--keydown="my-theme/todo::actions.handleKeyDown"
/>
<button
data-wp-on--click="my-theme/todo::actions.addTodo"
data-wp-bind--disabled="!state.canAdd"
>Add</button>
</div>
<ul class="todo-list">
<template data-wp-each--todo="state.todos" data-wp-each-key="context.todo.id">
<li>
<label>
<input
type="checkbox"
data-wp-bind--checked="context.todo.done"
data-wp-on--change="actions.toggleTodo"
/>
<span
data-wp-text="context.todo.text"
data-wp-class--done="context.todo.done"
></span>
</label>
<button
class="todo-delete"
data-wp-on--click="actions.deleteTodo"
>×</button>
</li>
</template>
</ul>
<div class="todo-footer" data-wp-bind--hidden="!state.hasTodos">
<span data-wp-text="state.itemsLeft"></span>
<button
data-wp-on--click="my-theme/todo::actions.clearDone"
data-wp-bind--hidden="!state.hasDone"
>Clear done</button>
</div>
</div>
Principaux modèles :
wp_interactivity_state()pour les données provenant du serveur (tâches, nombres)data-wp-contextpour l’état UI éphémère (texte saisi)data-wp-each--todoattribue un contexte nommé à chaque élément de l’itération (context.todo)state.*fait référence au magasin global ;context.*fait référence aux données propres à une instance
Logique côté client
bs.mutate() gère toutes les écritures avec des mises à jour optimistes et une annulation automatique. L’UI est mis à jour immédiatement ; si l’appel au serveur échoue, l’état est rétabli. En cas d’erreur de validation ou d’autorisation, la requête aboutit avec un corps contenant l’erreur au lieu d’échouer, comme indiqué dans la section Mutation.
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('my-theme/todo', {
state: {
get canAdd() {
return getContext().newText.trim() !== '';
},
get hasTodos() {
return state.todos.length > 0;
},
get hasDone() {
return state.todos.some(t => t.done);
},
get itemsLeft() {
const count = state.todos.filter(t => !t.done).length;
return count + (count === 1 ? ' item left' : ' items left');
},
},
actions: {
updateNewText(event) {
getContext().newText = event.target.value;
},
handleKeyDown(event) {
if (event.key === 'Enter') {
event.preventDefault();
store('my-theme/todo').actions.addTodo();
}
},
*addTodo() {
const ctx = getContext();
const text = ctx.newText.trim();
if (!text) return;
ctx.newText = '';
yield bs.mutate({
fn: () => bs.db('my-theme/todo').create({ text, done: false }),
state, key: 'todos', action: 'create',
optimistic: { text, done: false },
});
},
*toggleTodo() {
const todo = getContext().todo;
yield bs.mutate({
fn: () => bs.fn('toggle', { id: todo.id }, 'my-theme/todo'),
state, key: 'todos', action: 'update', id: todo.id,
optimistic: { ...todo, done: !todo.done },
});
},
*deleteTodo() {
const todo = getContext().todo;
yield bs.mutate({
fn: () => bs.db('my-theme/todo').delete(todo.id),
state, key: 'todos', action: 'delete', id: todo.id,
});
},
*clearDone() {
yield bs.mutate({
fn: () => bs.fn('clear_done', {}, 'my-theme/todo'),
before() {
const snap = state.todos.slice();
state.todos = state.todos.filter(t => !t.done);
return snap;
},
onError(err, snap) { state.todos = snap; },
invalidate: 'todos',
});
},
},
});
Principaux modèles :
- Mode automatique
bs.mutate()pour créer, mettre à jour ou supprimer : transmettez les donnéesstate,key,actionetoptimistic. L’UI est mis à jour immédiatement ; l’appel au serveur s’exécute en arrière-plan et l’état est rétabli en cas d’échec. - Mode manuel
bs.mutate()pourclearDone:before()crée un instantané et applique la modification ;onError()restaure l’état à partir de l’instantané. - Fonctions génératrices (
*addTodo) avecyieldpour les opérations asynchrones dans l’API Interactivity. bs.db()pour le CRUD direct,bs.fn()pour les fonctions serveur personnalisées.
Styles
.todo-app {
max-width: 500px;
margin: 0 auto;
font-family: system-ui, sans-serif;
}
.todo-input {
display: flex;
gap: 0.5rem;
margin-bottom: 1rem;
}
.todo-input input {
flex: 1;
padding: 0.5rem 0.75rem;
border: 1px solid #d1d5db;
border-radius: 0.375rem;
}
.todo-input button {
padding: 0.5rem 1rem;
background: #3b82f6;
color: white;
border: none;
border-radius: 0.375rem;
cursor: pointer;
}
.todo-list {
list-style: none;
padding: 0;
}
.todo-list li {
display: flex;
align-items: center;
justify-content: space-between;
padding: 0.75rem 0;
border-bottom: 1px solid #f3f4f6;
}
.todo-list label {
display: flex;
align-items: center;
gap: 0.5rem;
flex: 1;
cursor: pointer;
}
.todo-list .done {
text-decoration: line-through;
color: #9ca3af;
}
.todo-delete {
background: none;
border: none;
color: #ef4444;
font-size: 1.25rem;
cursor: pointer;
opacity: 0;
transition: opacity 0.15s;
}
.todo-list li:hover .todo-delete {
opacity: 1;
}
.todo-footer {
display: flex;
justify-content: space-between;
align-items: center;
padding: 0.75rem 0;
font-size: 0.875rem;
color: #6b7280;
}
.todo-footer button {
background: none;
border: none;
color: #6b7280;
cursor: pointer;
text-decoration: underline;
}
CLI
wp bs db list my-theme/todo
wp bs db create my-theme/todo --text="Buy milk" --user_id=1
wp bs cron run my-theme/todo cleanup_old_todos
wp bs rpc call my-theme/todo toggle --id=1
Inscription à la newsletter
Un formulaire d’inscription public. Tout le monde peut s’inscrire, mais seuls les administrateurs peuvent consulter et gérer les abonnés. Pas de userScoped, pas d’authentification pour l’action principale. Utilise le stockage en table MySQL pour un usage en production.
Structure des fichiers
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Définition du bloc
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Modèle de données
Création publique avec protection CSRF. Une validation personnalisée bloque les adresses e-mail temporaires. La lecture et la suppression sont réservées aux administrateurs.
<?php
return [
'storage' => 'table',
'capability' => [
'create' => true,
'read' => 'manage_options',
'update' => 'manage_options',
'delete' => 'manage_options',
],
'fields' => [
'email' => [
'type' => 'string',
'format' => 'email',
'required' => true,
'validate' => function ($value) {
$blocked = ['mailinator.com', 'tempmail.com', 'throwaway.email'];
$domain = substr($value, strpos($value, '@') + 1);
if (in_array($domain, $blocked, true)) {
return 'Please use a permanent email address.';
}
return true;
},
],
'name' => [
'type' => 'string',
'maxLength' => 100,
],
'status' => [
'type' => 'string',
'enum' => ['active', 'unsubscribed'],
'default' => 'active',
],
],
'hooks' => [
'after_create' => function ($params) {
$name = $params['record']['name'];
wp_mail(
$params['record']['email'],
'Welcome!',
'Thanks for subscribing' . ($name ? ", $name" : '') . '.'
);
},
],
];
Logique personnalisée
Un point de terminaison public de désabonnement (accessible depuis les liens des e-mails sans connexion) et des statistiques réservées aux administrateurs :
<?php
use Blockstudio\Db;
return [
'unsubscribe' => [
'callback' => function (array $params): array {
$email = sanitize_email($params['email'] ?? '');
$db = Db::get('my-theme/newsletter');
$subs = $db->list(['email' => $email]);
if (empty($subs)) {
return ['error' => 'Email not found.'];
}
$db->update((int) $subs[0]['id'], ['status' => 'unsubscribed']);
return ['success' => true];
},
'public' => true,
],
'stats' => [
'callback' => function (array $params): array {
$db = Db::get('my-theme/newsletter');
return [
'total' => count($db->list()),
'active' => count($db->list(['status' => 'active'])),
];
},
'capability' => 'manage_options',
],
];
Nettoyage planifié
<?php
use Blockstudio\Db;
return [
'cleanup' => [
'schedule' => 'weekly',
'callback' => function () {
$db = Db::get('my-theme/newsletter');
$unsub = $db->list(['status' => 'unsubscribed']);
foreach ($unsub as $row) {
if (strtotime($row['updated_at']) < strtotime('-90 days')) {
$db->delete((int) $row['id']);
}
}
},
],
];
Modèle
<?php
wp_interactivity_state('my-theme/newsletter', [
'submitted' => false,
]);
?>
<div
data-wp-interactive="my-theme/newsletter"
data-wp-context='<?php echo esc_attr(wp_json_encode([
'email' => '',
'name' => '',
'loading' => false,
'error' => '',
])); ?>'
useBlockProps
class="newsletter"
>
<div data-wp-bind--hidden="state.submitted">
<h3>Stay in the loop</h3>
<div class="newsletter-form">
<input
type="text"
placeholder="Name (optional)"
data-wp-bind--value="context.name"
data-wp-on--input="actions.setName"
/>
<input
type="email"
placeholder="Email address"
data-wp-bind--value="context.email"
data-wp-on--input="actions.setEmail"
data-wp-on--keydown="actions.handleKeydown"
/>
<button
data-wp-on--click="actions.subscribe"
data-wp-bind--disabled="context.loading"
>
<span data-wp-text="context.loading ? 'Subscribing...' : 'Subscribe'"></span>
</button>
</div>
<p data-wp-bind--hidden="!context.error" class="newsletter-error" data-wp-text="context.error"></p>
</div>
<div data-wp-bind--hidden="!state.submitted">
<p class="newsletter-success">You're in! Check your email.</p>
</div>
</div>
Logique côté client
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('my-theme/newsletter', {
actions: {
setName(event) {
getContext().name = event.target.value;
},
setEmail(event) {
getContext().email = event.target.value;
},
handleKeydown(event) {
if (event.key === 'Enter') {
store('my-theme/newsletter').actions.subscribe();
}
},
*subscribe() {
const ctx = getContext();
const email = ctx.email.trim();
if (!email) return;
ctx.loading = true;
ctx.error = '';
const result = yield bs.db('my-theme/newsletter').create({
email,
name: ctx.name.trim(),
});
if (result.data?.errors) {
ctx.error = Object.values(result.data.errors)[0][0];
ctx.loading = false;
return;
}
if (result.code) {
ctx.error = result.message || 'Something went wrong.';
ctx.loading = false;
return;
}
state.submitted = true;
ctx.loading = false;
},
},
});
Styles
.newsletter {
max-width: 480px;
margin: 0 auto;
padding: 2rem;
text-align: center;
}
.newsletter h3 {
margin: 0 0 1rem;
}
.newsletter-form {
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.newsletter-form input {
padding: 0.625rem 0.75rem;
border: 1px solid #d1d5db;
border-radius: 0.375rem;
font-size: 1rem;
}
.newsletter-form button {
padding: 0.625rem 1rem;
background: #3b82f6;
color: white;
border: none;
border-radius: 0.375rem;
font-size: 1rem;
cursor: pointer;
}
.newsletter-form button:disabled {
opacity: 0.6;
cursor: not-allowed;
}
.newsletter-error {
color: #ef4444;
font-size: 0.875rem;
margin: 0.5rem 0 0;
}
.newsletter-success {
color: #10b981;
font-size: 1.125rem;
}
CLI
wp bs db list my-theme/newsletter --format=table
wp bs rpc call my-theme/newsletter stats
wp bs rpc call my-theme/newsletter unsubscribe --email=user@example.com
wp bs cron run my-theme/newsletter cleanup
Comparaison côte à côte
| Aspect | Gestion des tâches | Newsletter |
|---|---|---|
| Modèle d’authentification | userScoped: true |
Création publique, lecture par l’administrateur |
| Stockage | SQLite (portable) | Table MySQL (production) |
| Filtrage des utilisateurs | Automatique | Inutile |
| CSRF | Via X-BS-Token |
Via X-BS-Token |
| RPC personnalisés | Inverser l’état, effacer les tâches terminées | Désabonnement, statistiques |
| Cron | Supprimer les anciennes tâches terminées | Supprimer les personnes désabonnées |
| Validation | Contraintes de longueur | Format des adresses e-mail et blocage de domaines |
| Temps réel | Interrogation toutes les 3 secondes | Inutile |
| Mises à jour UI | Mode automatique bs.mutate() |
bs.db().create() direct |
| État | wp_interactivity_state() |
wp_interactivity_state() + contexte |
Même modèle, modèles d’accès différents. Les composants de base sont identiques : db.php pour le modèle de données, rpc.php pour la logique métier, cron.php pour les tâches en arrière-plan, index.php + script.inline.js pour l’UI et style.css pour l’apparence. Chaque bloc est une application autonome.