Blocchi full stack
Blockstudio permette di creare applicazioni complete all’interno di una cartella di blocco. Una singola directory può contenere il UI, la logica server, il modello dei dati, le attività pianificate e persino i dati stessi.
Questa guida crea due applicazioni reali per mostrare il modello: un’app per le attività personali e una registrazione pubblica alla newsletter. La struttura dei file è la stessa, i modelli di accesso sono diversi.
Gli esempi qui sotto usano la sintassi con array perché è la più compatta, ma tutte e tre le superfici PHP hanno anche alternative native per PHP:
db.phppuò usareBlockstudio\\Db\\SchemaeBlockstudio\\Db\\Fieldrpc.phppuò restituire un oggetto con metodi#[Rpc]cron.phppuò restituire un oggetto con metodi#[Cron]
App per le attività
Un task manager per singolo utente. Ogni utente che ha effettuato l’accesso vede solo le proprie attività. Usa userScoped: true per isolare automaticamente gli utenti, SQLite per un’archiviazione portatile, bs.mutate() per gli aggiornamenti ottimistici e il polling in tempo reale, così le modifiche apportate in altre schede vengono visualizzate automaticamente.
Struttura dei file
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Definizione del blocco
{
"$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 abilita l’elaborazione delle direttive di WordPress (SSR per data-wp-each, data-wp-bind e così via). interactivity.enqueue carica il modulo @wordpress/interactivity nel frontend.
Modello dei dati
userScoped: true aggiunge automaticamente una colonna user_id, la imposta alla creazione e filtra tutte le query in base all’utente corrente. realtime abilita il polling automatico, così le modifiche apportate in altre schede o dispositivi vengono visualizzate senza ricaricare la pagina.
<?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,
],
],
];
L’archiviazione SQLite significa che il file del database si trova in todo/db/default.sqlite. Copiate la cartella del blocco su un altro sito e i dati verranno trasferiti insieme a essa.
La configurazione realtime indica al client di controllare la presenza di modifiche ogni 3 secondi usando un confronto leggero degli hash. Quando i dati cambiano, state.todos viene aggiornato e UI si aggiorna automaticamente.
Logica server personalizzata
Poiché userScoped filtra automaticamente in base all’utente corrente, il bs.db().list() integrato restituisce già solo i record dell’utente corrente. RPC serve solo per operazioni che vanno oltre il CRUD: attivazione e svuotamento in blocco.
<?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'],
],
];
Pulizia pianificata
Le vecchie attività completate vengono eliminate automaticamente.
<?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']);
}
}
},
],
];
Template
PHP carica le attività iniziali lato server tramite wp_interactivity_state(), che fornisce i dati sia per l’elaborazione delle direttive SSR sia per l’hydration lato client. Lo stato UI per ciascuna istanza (come il valore del campo di input) va in 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>
Pattern principali:
wp_interactivity_state()per i dati provenienti dal server (attività, conteggi)data-wp-contextper lo stato UI temporaneo (testo inserito)data-wp-each--todoassegna a ogni elemento dell’iterazione un contesto denominato (context.todo)state.*fa riferimento allo store globale,context.*ai dati specifici dell’istanza
Logica lato client
bs.mutate() gestisce tutte le scritture con aggiornamenti ottimistici e rollback automatico. UI si aggiorna immediatamente; se la chiamata al server viene rifiutata, lo stato viene ripristinato. Un errore di convalida o di autorizzazione restituisce un corpo di risposta con l’errore anziché rifiutare la chiamata, come descritto nella sezione Mutate.
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',
});
},
},
});
Pattern principali:
bs.mutate()modalità automatica per creare, aggiornare ed eliminare: passate i datistate,key,actioneoptimistic. UI si aggiorna immediatamente, la chiamata al server viene eseguita in background e, in caso di errore, lo stato viene ripristinato.bs.mutate()modalità manuale perclearDone:before()crea un’istantanea e applica la modifica, mentreonError()ripristina l’istantanea.- Funzioni generatrici (
*addTodo) conyieldper le operazioni asincrone in API Interactivity. bs.db()per il CRUD diretto,bs.fn()per le funzioni server personalizzate.
Stili
.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
Registrazione alla newsletter
Un modulo di iscrizione pubblico. Chiunque può iscriversi, ma solo gli amministratori possono visualizzare e gestire gli iscritti. Nessun userScoped, nessuna autenticazione per l’azione principale. Per l’uso in produzione, usa l’archiviazione in tabella MySQL.
Struttura dei file
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Definizione del blocco
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Modello dei dati
Creazione pubblica con protezione CSRF. La convalida personalizzata blocca gli indirizzi email temporanei. Solo gli amministratori possono leggere ed eliminare.
<?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" : '') . '.'
);
},
],
];
Logica personalizzata
Un endpoint pubblico per annullare l’iscrizione (funziona dai link nelle email senza effettuare l’accesso) e statistiche riservate agli amministratori:
<?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',
],
];
Pulizia pianificata
<?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']);
}
}
},
],
];
Template
<?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>
Logica lato 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;
},
},
});
Stili
.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
Confronto affiancato
| Aspetto | App per le attività | Newsletter |
|---|---|---|
| Modello di autenticazione | userScoped: true |
Creazione pubblica, lettura riservata agli amministratori |
| Archiviazione | SQLite (portatile) | Tabella MySQL (produzione) |
| Filtro per utente | Automatico | Non necessario |
| CSRF | Tramite X-BS-Token |
Tramite X-BS-Token |
| RPC personalizzata | Attivazione, cancellazione delle attività completate | Annullamento dell’iscrizione, statistiche |
| Cron | Elimina le vecchie attività completate | Rimuove gli utenti che hanno annullato l’iscrizione |
| Convalida | Vincoli sulla lunghezza | Formato email + blocco del dominio |
| Tempo reale | Polling ogni 3 s | Non necessario |
| UI ottimistici | Modalità automatica bs.mutate() |
bs.db().create() diretto |
| Stato | wp_interactivity_state() |
wp_interactivity_state() + contesto |
Stesso modello, diversi livelli di accesso. Gli elementi di base sono identici: db.php per il modello dei dati, rpc.php per la logica di business, cron.php per le attività in background, index.php + script.inline.js per UI, style.css per l’aspetto. Ogni blocco è un’applicazione indipendente.