انتقل إلى المحتوى

كتل متكاملة

تتيح لك 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

تعريف الكتلة

JSON
{
  "$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
<?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
<?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
<?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
<?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"
                >&times;</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 فورًا؛ وإذا رفض استدعاء الخادم، تعود الحالة إلى ما كانت عليه. أما خطأ التحقق أو الصلاحيات فيُرجع جسم استجابة يتضمن الخطأ بدلًا من الرفض، كما هو موضح في قسم التعديل.

JavaScript
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() لدوال الخادم المخصصة.

الأنماط

CSS
.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

تعريف الكتلة

JSON
{
  "$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
<?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
<?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
<?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
<?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>

منطق العميل

JavaScript
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;
        },
    },
});

الأنماط

CSS
.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 للمظهر. كل كتلة تطبيق مستقل بذاته.