Bloki full-stack
Blockstudio pozwala tworzyć kompletne aplikacje w katalogu bloku. Pojedynczy katalog może zawierać UI, logikę serwera, model danych, zaplanowane zadania, a nawet same dane.
Ten przewodnik przedstawia dwa działające przykłady, które ilustrują ten wzorzec: aplikację z listą zadań dla poszczególnych użytkowników oraz publiczny formularz zapisu do newslettera. Taka sama struktura plików, różne modele dostępu.
Poniższe przykłady używają składni tablicowej, ponieważ jest najbardziej zwięzła, ale wszystkie trzy warstwy PHP mają również natywne dla PHP alternatywy:
db.phpmoże używaćBlockstudio\\Db\\SchemaiBlockstudio\\Db\\Fieldrpc.phpmoże zwrócić obiekt z metodami#[Rpc]cron.phpmoże zwrócić obiekt z metodami#[Cron]
Aplikacja z listą zadań
Menedżer zadań dla poszczególnych użytkowników. Każdy zalogowany użytkownik widzi tylko własne zadania. Wykorzystuje userScoped: true do automatycznej izolacji użytkowników, SQLite do przenośnego przechowywania danych, bs.mutate() do optymistycznych aktualizacji oraz odpytywanie w czasie rzeczywistym, dzięki któremu zmiany z innych kart są automatycznie widoczne.
Struktura plików
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Definicja bloku
{
"$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 włącza przetwarzanie dyrektyw przez WordPress (SSR dla data-wp-each, data-wp-bind itd.). interactivity.enqueue ładuje moduł @wordpress/interactivity na frontendzie.
Model danych
userScoped: true automatycznie dodaje kolumnę user_id, ustawia jej wartość podczas tworzenia i filtruje wszystkie zapytania według bieżącego użytkownika. realtime włącza automatyczne odpytywanie, dzięki czemu zmiany z innych kart lub urządzeń są widoczne bez odświeżania strony.
<?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,
],
],
];
Przechowywanie danych w SQLite oznacza, że plik bazy danych znajduje się w todo/db/default.sqlite. Skopiuj katalog bloku do innej witryny, a dane przeniosą się razem z nim.
Konfiguracja realtime instruuje klienta, by co 3 sekundy sprawdzał zmiany za pomocą lekkiego porównania skrótów. Gdy dane się zmienią, state.todos zostanie zaktualizowane, a UI automatycznie ponownie wyrenderuje widok.
Własna logika serwera
Ponieważ userScoped automatycznie filtruje dane według bieżącego użytkownika, wbudowane bs.db().list() zwraca już tylko rekordy tego użytkownika. RPC jest potrzebne wyłącznie do operacji wykraczających poza CRUD: przełączania statusu i zbiorczego usuwania.
<?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'],
],
];
Zaplanowane czyszczenie
Stare, ukończone zadania są automatycznie usuwane.
<?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']);
}
}
},
],
];
Szablon
PHP ładuje początkowe zadania po stronie serwera za pomocą wp_interactivity_state(), które dostarcza dane zarówno do przetwarzania dyrektyw SSR, jak i do uwodnienia po stronie klienta. Stan UI dla poszczególnych instancji (na przykład wartość pola wejściowego) umieszcza się w 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>
Kluczowe wzorce:
wp_interactivity_state()dla danych pochodzących z serwera (zadania, liczniki)data-wp-contextdla tymczasowego stanu UI (tekst w polu wejściowym)data-wp-each--todoprzypisuje nazwaną przestrzeń kontekstu każdemu elementowi iteracji (context.todo)state.*odwołuje się do globalnego magazynu, acontext.*do danych poszczególnych instancji
Logika klienta
bs.mutate() obsługuje wszystkie operacje zapisu za pomocą optymistycznych aktualizacji i automatycznego wycofywania zmian. UI aktualizuje się natychmiast; jeśli wywołanie serwera zostanie odrzucone, stan wraca do poprzedniej wartości. Błąd walidacji lub uprawnień powoduje zwrócenie treści błędu zamiast odrzucenia, jak opisano w sekcji 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',
});
},
},
});
Kluczowe wzorce:
bs.mutate()Tryb automatyczny dla tworzenia, aktualizowania i usuwania: przekaż danestate,key,actionioptimistic. UI aktualizuje się natychmiast, wywołanie serwera odbywa się w tle, a w razie niepowodzenia stan wraca do poprzedniej wartości.bs.mutate()Tryb ręczny dlaclearDone:before()tworzy migawkę i wprowadza zmianę, aonError()przywraca stan z migawki.- Funkcje generatorowe (
*addTodo) zyielddo operacji asynchronicznych w API interaktywności. bs.db()do bezpośredniego CRUD,bs.fn()do niestandardowych funkcji serwera.
Style
.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
Zapisy do newslettera
Publiczny formularz subskrypcji. Każdy może się zapisać, ale tylko administratorzy mogą przeglądać subskrybentów i zarządzać nimi. Bez userScoped, bez uwierzytelniania dla głównej operacji. Do zastosowań produkcyjnych wykorzystuje przechowywanie w tabeli MySQL.
Struktura plików
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Definicja bloku
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Model danych
Publiczne tworzenie wpisów z ochroną CSRF. Własna walidacja blokuje jednorazowe adresy e-mail. Odczyt i usuwanie tylko dla administratorów.
<?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" : '') . '.'
);
},
],
];
Własna logika
Publiczny punkt końcowy rezygnacji z subskrypcji (działa z linków w wiadomościach e-mail bez logowania) oraz statystyki dostępne tylko dla administratorów:
<?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',
],
];
Zaplanowane czyszczenie
<?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']);
}
}
},
],
];
Szablon
<?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>
Logika klienta
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;
},
},
});
Style
.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
Porównanie
| Aspekt | Aplikacja z listą zadań | Newsletter |
|---|---|---|
| Model uwierzytelniania | userScoped: true |
Publiczne tworzenie, odczyt przez administratora |
| Przechowywanie danych | SQLite (przenośne) | Tabela MySQL (środowisko produkcyjne) |
| Filtrowanie użytkowników | Automatyczne | Niepotrzebne |
| CSRF | Za pomocą X-BS-Token |
Za pomocą X-BS-Token |
| Własne RPC | Zmiana statusu, czyszczenie ukończonych | Rezygnacja z subskrypcji, statystyki |
| Cron | Usuwanie starych ukończonych zadań | Usuwanie osób, które zrezygnowały |
| Walidacja | Ograniczenia długości | Format e-maila + blokada domeny |
| Aktualizacje na żywo | Odpytywanie co 3 s | Niepotrzebne |
| Optymistyczne UI | Tryb automatyczny bs.mutate() |
Bezpośrednie bs.db().create() |
| Stan | wp_interactivity_state() |
wp_interactivity_state() + kontekst |
Ten sam wzorzec, różne modele dostępu. Podstawowe elementy są identyczne: db.php dla modelu danych, rpc.php dla logiki biznesowej, cron.php dla zadań w tle, index.php + script.inline.js dla UI, style.css dla wyglądu. Każdy blok to samodzielna aplikacja.