Tam Yığın Blokları
Blockstudio, bir blok klasörünün içinde eksiksiz uygulamalar oluşturmanızı sağlar. Tek bir dizin; UI, sunucu mantığını, veri modelini, zamanlanmış görevleri ve hatta verilerin kendisini içerebilir.
Bu kılavuz, bu yaklaşımı göstermek için iki gerçek uygulama oluşturur: kullanıcı başına bir yapılacaklar uygulaması ve herkese açık bir bülten aboneliği formu. Aynı dosya yapısı, farklı erişim modelleri.
Aşağıdaki örneklerde en kısa biçim olduğu için dizi söz dizimi kullanılıyor; ancak üç PHP yüzeyinin tümünde PHP tabanlı alternatifler de bulunuyor:
db.php,Blockstudio\\Db\\SchemaveBlockstudio\\Db\\Fieldkullanabilirrpc.php,#[Rpc]yöntemlerine sahip bir nesne döndürebilircron.php,#[Cron]yöntemlerine sahip bir nesne döndürebilir
Yapılacaklar Uygulaması
Kullanıcı başına bir görev yöneticisi. Oturum açmış her kullanıcı yalnızca kendi yapılacaklarını görür. Otomatik kullanıcı yalıtımı için userScoped: true, taşınabilir depolama için SQLite, iyimser güncellemeler için bs.mutate() ve diğer sekmelerdeki değişikliklerin otomatik olarak görünmesi için gerçek zamanlı yoklama kullanır.
Dosya yapısı
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Blok tanımı
{
"$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, WordPress yönergelerinin işlenmesini etkinleştirir (data-wp-each, data-wp-bind vb. için SSR). interactivity.enqueue, frontend’de @wordpress/interactivity modülünü yükler.
Veri modeli
userScoped: true otomatik olarak bir user_id sütunu ekler, oluşturma sırasında bu sütuna değer atar ve tüm sorguları geçerli kullanıcıya göre filtreler. realtime, diğer sekmelerdeki veya cihazlardaki değişikliklerin sayfa yenilenmeden görünmesi için otomatik yoklamayı etkinleştirir.
<?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,
],
],
];
SQLite depolama, veritabanı dosyasının todo/db/default.sqlite konumunda bulunduğu anlamına gelir. Blok klasörünü başka bir siteye kopyaladığınızda veriler de onunla birlikte taşınır.
realtime yapılandırması, istemciye hafif bir karma karşılaştırması kullanarak her 3 saniyede bir değişiklikleri yoklamasını söyler. Veriler değiştiğinde state.todos güncellenir ve UI otomatik olarak yeniden oluşturulur.
Özel sunucu mantığı
userScoped geçerli kullanıcıya göre otomatik filtreleme yaptığından, yerleşik bs.db().list() yalnızca geçerli kullanıcının kayıtlarını döndürür. RPC yalnızca CRUD dışındaki işlemler için gerekir: durum değiştirme ve tümünü temizleme.
<?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'],
],
];
Zamanlanmış temizleme
Eski ve tamamlanmış yapılacaklar otomatik olarak temizlenir.
<?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']);
}
}
},
],
];
Şablon
PHP, başlangıçtaki yapılacakları sunucu tarafında wp_interactivity_state() aracılığıyla yükler; bu, hem SSR yönerge işlemesi hem de istemci tarafı hidratasyonu için veri sağlar. Örnek başına UI durumu (giriş alanının değeri gibi) data-wp-context içinde tutulur.
<?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>
Temel kalıplar:
- Sunucudan gelen veriler için (yapılacaklar, sayılar)
wp_interactivity_state()kullanın - Geçici UI durumu (giriş metni) için
data-wp-contextkullanın data-wp-each--todo, her yineleme öğesine adlandırılmış bir bağlam verir (context.todo)state.*genel depoya,context.*ise örnek başına verilere başvurur
İstemci mantığı
bs.mutate() tüm yazma işlemlerini iyimser güncellemeler ve otomatik geri alma ile yürütür. UI hemen güncellenir; sunucu çağrısı reddedilirse durum geri alınır. Mutate bölümünde açıklandığı gibi, doğrulama veya izin hatası reddedilmek yerine hata gövdesiyle sonuçlanır.
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',
});
},
},
});
Temel kalıplar:
- Oluşturma/güncelleme/silme işlemleri için
bs.mutate()otomatik mod:state,key,actionveoptimisticverilerini iletin. UI hemen güncellenir, sunucu çağrısı arka planda yapılır ve hata durumunda durum geri alınır. bs.mutate()işlemleri içinclearDoneel ile mod:before()anlık görüntü alır ve değişikliği uygular;onError()ise anlık görüntüden geri yükler.- Etkileşim API içindeki eşzamansız işlemler için
yieldkullanan üretici işlevler (*addTodo). - Doğrudan CRUD için
bs.db(), özel sunucu işlevleri içinbs.fn().
Stiller
.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
Bülten Aboneliği
Herkese açık bir abonelik formu. Herkes abone olabilir, aboneleri yalnızca yöneticiler görüntüleyip yönetebilir. Ana işlem için userScoped gerekmez, kimlik doğrulama gerekmez. Üretim kullanımı için MySQL tablo depolamasını kullanır.
Dosya yapısı
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Blok tanımı
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Veri modeli
CSRF korumalı herkese açık oluşturma. Özel doğrulama, tek kullanımlık e-posta adreslerini engeller. Okuma ve silme işlemleri yalnızca yöneticilere açıktır.
<?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" : '') . '.'
);
},
],
];
Özel mantık
Herkese açık abonelikten çıkma uç noktası (giriş yapmadan e-posta bağlantıları üzerinden çalışır) ve yalnızca yöneticilere açık istatistikler:
<?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',
],
];
Zamanlanmış temizleme
<?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']);
}
}
},
],
];
Şablon
<?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>
İstemci mantığı
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;
},
},
});
Stiller
.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
Yan yana karşılaştırma
| Özellik | Yapılacaklar Uygulaması | Bülten |
|---|---|---|
| Kimlik doğrulama modeli | userScoped: true |
Herkese açık oluşturma, yönetici okuması |
| Depolama | SQLite (taşınabilir) | MySQL tablosu (üretim) |
| Kullanıcı filtreleme | Otomatik | Gerekmez |
| CSRF | X-BS-Token aracılığıyla |
X-BS-Token aracılığıyla |
| Özel RPC | Durum değiştirme, tamamlananları temizleme | Abonelikten çıkma, istatistikler |
| Cron | Eski ve tamamlanmışları silme | Abonelikten çıkanları kaldırma |
| Doğrulama | Uzunluk kısıtlamaları | E-posta biçimi + etki alanı engelleme |
| Gerçek zamanlı | 3 saniyelik yoklama | Gerekmez |
| İyimser UI | bs.mutate() otomatik mod |
Doğrudan bs.db().create() |
| Durum | wp_interactivity_state() |
wp_interactivity_state() + bağlam |
Aynı yaklaşım, farklı erişim modelleri. Yapı taşları aynıdır:
veri modeli için db.php, iş mantığı için rpc.php, arka plan görevleri için cron.php, UI için index.php + script.inline.js ve görünüm için style.css. Her blok kendi içinde eksiksiz bir uygulamadır.