كتل متكاملة
تتيح لك Blockstudio إنشاء تطبيقات متكاملة داخل مجلد كتلة. ويمكن لدليل واحد أن يضم UI ومنطق الخادم ونموذج البيانات والمهام المجدولة، وحتى البيانات نفسها.
يعرض هذا الدليل تطبيقين حقيقيين لتوضيح النمط: تطبيق مهام لكل مستخدم، ونموذج اشتراك عام في نشرة إخبارية. بنية الملفات واحدة، لكن نماذج الوصول مختلفة.
تستخدم الأمثلة أدناه صياغة المصفوفة لأنها الأكثر اختصارًا، لكن تتوفر أيضًا بدائل أصلية لـPHP في واجهات PHP الثلاث:
- يمكن أن يستخدم
db.phpكلًا منBlockstudio\\Db\\SchemaوBlockstudio\\Db\\Field - يمكن أن يُرجع
rpc.phpكائنًا يضم أساليب#[Rpc] - يمكن أن يُرجع
cron.phpكائنًا يضم أساليب#[Cron]
تطبيق المهام
مدير مهام لكل مستخدم. يرى كل مستخدم مسجل الدخول مهامه الخاصة فقط. يستخدم userScoped: true لعزل المستخدمين تلقائيًا، وSQLite للتخزين القابل للنقل، وbs.mutate() للتحديثات التفاؤلية، والاستقصاء الفوري لتظهر التغييرات من علامات التبويب الأخرى تلقائيًا.
بنية الملفات
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
تعريف الكتلة
{
"$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 (العرض من جهة الخادم لـdata-wp-each وdata-wp-bind وغيرها). ويحمّل interactivity.enqueue الوحدة @wordpress/interactivity في الواجهة الأمامية.
نموذج البيانات
يضيف userScoped: true عمود user_id تلقائيًا، ويضبطه عند الإنشاء، ويقصر جميع الاستعلامات على المستخدم الحالي. ويتيح realtime الاستقصاء التلقائي لتظهر التغييرات من علامات التبويب أو الأجهزة الأخرى دون تحديث الصفحة.
<?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 وجود ملف قاعدة البيانات في todo/db/default.sqlite. انسخ مجلد الكتلة إلى موقع آخر وستنتقل البيانات معه.
تطلب إعدادات realtime من العميل الاستقصاء عن التغييرات كل 3 ثوانٍ باستخدام مقارنة تجزئة خفيفة. وعند تغير البيانات، يُحدّث state.todos وتُعاد عملية العرض في UI تلقائيًا.
منطق خادم مخصص
بما أن userScoped يقصر النتائج تلقائيًا على المستخدم الحالي، فإن bs.db().list() المدمج يعيد سجلات المستخدم الحالي وحدها. ولا يلزم RPC إلا للعمليات التي تتجاوز CRUD: التبديل والمسح الجماعي.
<?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'],
],
];
التنظيف المجدول
تُحذف المهام القديمة المكتملة تلقائيًا.
<?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']);
}
}
},
],
];
القالب
يحمّل PHP المهام الأولية من جهة الخادم عبر wp_interactivity_state()، الذي يوفر البيانات لكل من معالجة توجيهات SSR والتهيئة الأولية من جهة العميل. توضع حالة UI الخاصة بكل مثيل (مثل قيمة حقل الإدخال) في 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>
أنماط أساسية:
- استخدم
wp_interactivity_state()للبيانات القادمة من الخادم (المهام والأعداد) - استخدم
data-wp-contextلحالة UI المؤقتة (نص الإدخال) - يمنح
data-wp-each--todoكل عنصر في التكرار سياقًا باسم (context.todo) - يشير
state.*إلى المخزن العام، ويشيرcontext.*إلى بيانات كل مثيل
منطق العميل
يتولى bs.mutate() جميع عمليات الكتابة مع تحديثات تفاؤلية واسترجاع تلقائي للحالة السابقة. ويُحدّث UI فورًا؛ وإذا رفض استدعاء الخادم، تعود الحالة إلى ما كانت عليه. أما خطأ التحقق أو الصلاحيات فيُرجع جسم استجابة يتضمن الخطأ بدلًا من الرفض، كما هو موضح في قسم التعديل.
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',
});
},
},
});
أنماط أساسية:
bs.mutate()في الوضع التلقائي للإنشاء والتحديث والحذف: مرّر بياناتstateوkeyوactionوoptimistic. يُحدّث UI فورًا، ويُنفّذ استدعاء الخادم في الخلفية، ثم تعود الحالة إلى ما كانت عليه عند الفشل.bs.mutate()في الوضع اليدوي لـclearDone: يأخذbefore()لقطة ويطبق التغيير، بينما يعيدonError()الحالة من اللقطة.- دوال المولّدات (
*addTodo) معyieldللعمليات غير المتزامنة في API للتفاعلية. bs.db()لعمليات CRUD المباشرة، وbs.fn()لدوال الخادم المخصصة.
الأنماط
.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
الاشتراك في النشرة الإخبارية
نموذج اشتراك عام. يمكن لأي شخص الاشتراك، ولا يمكن عرض المشتركين وإدارتهم إلا للمشرفين. لا userScoped ولا مصادقة للإجراء الرئيسي. يستخدم تخزينًا في جدول MySQL للاستخدام الإنتاجي.
بنية الملفات
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
تعريف الكتلة
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
نموذج البيانات
إنشاء عام مع حماية CSRF. يمنع التحقق المخصص عناوين البريد الإلكتروني المؤقتة. القراءة والحذف للمشرفين فقط.
<?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" : '') . '.'
);
},
],
];
منطق مخصص
نقطة نهاية عامة لإلغاء الاشتراك (تعمل عبر روابط البريد الإلكتروني دون تسجيل الدخول)، وإحصاءات للمشرفين فقط:
<?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',
],
];
التنظيف المجدول
<?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']);
}
}
},
],
];
القالب
<?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>
منطق العميل
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;
},
},
});
الأنماط
.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
مقارنة جنبًا إلى جنب
| الجانب | تطبيق المهام | النشرة الإخبارية |
|---|---|---|
| نموذج المصادقة | userScoped: true |
إنشاء عام، وقراءة للمشرف |
| التخزين | SQLite (قابل للنقل) | جدول MySQL (للإنتاج) |
| تصفية المستخدمين | تلقائية | غير مطلوبة |
| CSRF | عبر X-BS-Token |
عبر X-BS-Token |
| RPC مخصص | تبديل الحالة، ومسح المكتمل | إلغاء الاشتراك، والإحصاءات |
| Cron | حذف المهام القديمة المكتملة | إزالة من ألغوا اشتراكهم |
| التحقق | قيود الطول | تنسيق البريد الإلكتروني وحظر النطاقات |
| التحديث الفوري | استقصاء كل 3 ثوانٍ | غير مطلوب |
| UI التفاؤلية | الوضع التلقائي لـbs.mutate() |
bs.db().create() مباشرة |
| الحالة | wp_interactivity_state() |
wp_interactivity_state() + السياق |
النمط نفسه، لكن نماذج الوصول مختلفة. وحدات البناء متطابقة: db.php لنموذج البيانات، وrpc.php لمنطق الأعمال، وcron.php للمهام الخلفية، وindex.php + script.inline.js لـUI، وstyle.css للمظهر. كل كتلة تطبيق مستقل بذاته.