قاعدة البيانات
تتيح لك طبقة قاعدة البيانات تعريف نموذج بيانات للكتلة في ملف db.php. تنشئ Blockstudio نقاط نهاية CRUD REST، وتتحقق من صحة الإدخال وفقًا للمخطط، وتدير التخزين تلقائيًا، وتوفر عميلًا من JavaScript (bs.db()) وPHP API (الفئة Db).
هذا هو العمود الفقري للبيانات في الكتل المتكاملة. بينما تتولى RPC المنطق المخصص، تتولى طبقة قاعدة البيانات البيانات المنظمة دون كتابة تعليمات تمهيدية.
طريقة العمل
- أنشئ
db.phpفي مجلد الكتلة - يعيد مخططًا: الحقول والأنواع وقواعد التحقق من الصحة والتحكم في الوصول
- ينشئ Blockstudio التخزين (جدولًا أو ملفًا أو بيانات وصفية للمنشور)
- تُنشأ خمس نقاط نهاية REST تلقائيًا (قائمة، جلب، إنشاء، تحديث، حذف)
- يتيح
bs.db()وDb::get()الوصول من العميل والخادم
لا حاجة إلى عمليات ترحيل أو وحدات تحكم أو تسجيل للمسارات.
مرّر القيم الحرفية إلى واجهتي API REST وPHP. تتولى الواجهتان الخلفيتان meta وpost_type معالجة إلغاء تهريب شرطات الهروب في بيانات التعريف WordPress داخليًا، مع الحفاظ على الشرطات العكسية والسلاسل المحاطة بعلامات اقتباس في القيم المفردة والكائنات أو المصفوفات المتداخلة. لا تضف شرطات الهروب مسبقًا إلى قيم سجلات قاعدة البيانات.
تعريف المخططات
مخطط واحد
أبسط صيغة: نموذج بيانات واحد لكل كتلة.
return [
'storage' => 'table',
'capability' => [
'create' => true,
'read' => true,
'update' => 'edit_posts',
'delete' => 'manage_options',
],
'fields' => [
'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
'name' => ['type' => 'string', 'maxLength' => 100],
'plan' => ['type' => 'string', 'enum' => ['free', 'pro'], 'default' => 'free'],
],
];
صياغة أداة إنشاء أصلية لـ PHP
يمكن لـ db.php أيضًا استخدام أداة إنشاء صغيرة API تعتمد على الوسائط المسماة وكائنات تعريف للقراءة فقط. تظل المصفوفات هي التنسيق الافتراضي، لكن هذا يوفر خيارًا أصليًا لـ PHP أسهل في الاستكشاف عندما يكبر المخطط.
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;
return Schema::make(
storage: Storage::Table,
capability: [
'create' => true,
'read' => true,
'update' => 'edit_posts',
'delete' => 'manage_options',
],
fields: [
'email' => Field::string(required: true, format: 'email'),
'name' => Field::string(maxLength: 100),
'plan' => Field::string(enum: ['free', 'pro'], default: 'free'),
],
);
استخدم Schema::make() لمخطط واحد، أو أعد مصفوفة من استدعاءات Schema::make(...) المسماة للكتل متعددة المخططات.
مخططات متعددة
يمكن لكتلة واحدة أن تضم عدة نماذج بيانات. أعد مصفوفة مسماة:
return [
'subscribers' => [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
'plan' => ['type' => 'string', 'enum' => ['free', 'pro']],
],
],
'activity_log' => [
'storage' => 'jsonc',
'fields' => [
'action' => ['type' => 'string', 'required' => true],
'details' => ['type' => 'string'],
],
],
];
يحصل كل مخطط على نقاط نهايته وتخزينه والتحكم في الوصول الخاص به.
أوضاع التخزين
ستة خيارات تخزين، لكل منها حالات استخدام مختلفة.
جدول مخصص (storage: "table")
يُخزَّن كل سجل في صف ضمن جدول MySQL مخصص. ينشئ Blockstudio الجدول ويديره تلقائيًا باستخدام الدالة dbDelta() التابعة لـ WordPress. تؤدي إضافة حقول جديدة إلى المخطط إلى إضافة أعمدة عند تحميل الصفحة التالية. لا تُحذف الأعمدة الموجودة مطلقًا.
الأنسب للبيانات المنظمة والاستعلامات وتطبيقات الإنتاج.
SQLite (storage: "sqlite")
يحصل كل مخطط على ملف قاعدة بيانات SQLite خاص به في مجلد فرعي db/. ينشئ Blockstudio الملف والجدول تلقائيًا، ويضيف الأعمدة الناقصة عند تغيير المخطط (مثل dbDelta لـ MySQL). يستخدم وضع سجل WAL لتحسين أداء القراءة المتزامنة.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
الأنسب للبيانات المنظمة التي تحتاج إلى استعلامات SQL حقيقية مع ضرورة بقائها قابلة للنقل. يتعامل بكفاءة مع آلاف السجلات دون تحميلها كلها إلى الذاكرة. انسخ المجلد لنقل البيانات.
ملفات JSONC (storage: "jsonc")
تُخزَّن السجلات ككائن JSON واحد في كل سطر داخل ملف .jsonc في مجلد فرعي db/. يُنشأ الملف تلقائيًا عند أول كتابة. وتُعامل الأسطر التي تبدأ بـ // كتعليقات ويُحتفظ بها.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
الأنسب لمجموعات البيانات الصغيرة والبيانات الشبيهة بالإعدادات والسجلات الأولية والأمثلة القابلة للتحكم في إصداراتها. يتعمد JSONC استخدام ملف واحد في مجلد الكتلة. استخدمه عندما تريد أن تنتقل البيانات مع الكود، لا عندما تتوقع عمليات كتابة متزامنة كثيرة.
ملفات Storh (storage: "storh")
يخزّن Storh كل سجل في ملف منفصل ضمن مجلد uploads الخاص بـ WordPress:
wp-content/uploads/blockstudio/db/
└── my-theme-my-block/
└── subscribers/
├── data/
│ └── 00/
│ ├── 00000000-0000-7000-8000-000000000001.jsonc
│ └── 00000000-0000-7000-8000-000000000002.jsonc
├── .storh/
│ └── indexes/
└── .blockstudio/
└── sequence.json
تظل معرّفات السجلات العامة هي الأعداد الصحيحة نفسها المستخدمة في بقية bs.db().
يربط Blockstudio هذه المعرّفات بمعرّفات الملفات الداخلية UUIDv7 الخاصة بـ Storh، ويخزّن العدد الصحيح id في بيانات السجل، لذا لا تحتاج الجهات المستدعية لـ JavaScript وREST وPHP إلى التعامل مع UUIDs.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
ينشئ Blockstudio فهارس Storh من مخططك. وبما أن كل حقل مُعرّف يمكن استخدامه مرشحًا للقائمة، تتم فهرسة جميع الحقول المُعرّفة. تستخدم حقول الأعداد الصحيحة والأرقام والتواريخ فهارس النطاق؛ أما الحقول المحددة بـ 'unique' => true أو 'index' => 'unique' فتستخدم فهارس فريدة.
الأنسب لبيانات الإنتاج القائمة على الملفات التي تحتاج إلى كتابة متزامنة أكثر أمانًا، وفهارس مشتقة من المخطط، وتخزين محمول على مستوى uploads دون إدراج السجلات الحية في شجرة مصدر الكتلة.
ترحيل JSONC إلى Storh
إذا بدأت بملف .jsonc وأردت نقل السجلات نفسها إلى Storh، فنفّذ:
wp bs db migrate my-theme/app subscribers --to=storh
للكتل ذات المخطط الواحد:
wp bs db migrate my-theme/app --to=storh
تقرأ عملية الترحيل ملف db/{schema}.jsonc الحالي، وتكتب السجلات إلى Storh مع الحفاظ على المعرّفات الصحيحة، ثم تعيد الفهرسة وتتحقق من المخزن المستهدف وتُبقي ملف JSONC دون تغيير. للتراجع، ما عليك سوى إعادة storage في المخطط إلى "jsonc".
البيانات الوصفية للمنشور (storage: "meta")
تُخزَّن السجلات كمصفوفة JSON في البيانات الوصفية لمنشور WordPress، مرتبطة بمنشور محدد عبر postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
الأنسب للبيانات المرتبطة بمنشور أو صفحة محددة.
نوع منشور مخصص (storage: "post_type")
كل سجل هو منشور WordPress ضمن نوع منشور مخصص يُسجَّل تلقائيًا. يصبح كل حقل في المخطط إدخال post_meta منفصلًا. يتيح ذلك الاستعلام عن السجلات باستخدام WP_Query، والتوافق مع إضافات REST API، وظهورها لأدوات مثل GraphQL.
الأنسب للبيانات التي ينبغي أن تتكامل مع WordPress بشكل أصلي. يمكن الاستعلام عن كل حقل وفهرسته بصورة مستقلة.
عميل JavaScript
يحقن Blockstudio الرمز bs.db() في الصفحات التي تحتوي على كتل قاعدة البيانات. ويعيد كائنًا بخمس طرائق:
const db = bs.db('my-theme/block', 'subscribers');
// Create a record
const record = await db.create({ email: 'a@b.com', plan: 'pro' });
// List all records (with optional filters)
const all = await db.list();
const pros = await db.list({ plan: 'pro', limit: 10, offset: 0 });
// Get a single record
const one = await db.get(record.id);
// Update specific fields
const updated = await db.update(record.id, { plan: 'enterprise' });
// Delete a record
await db.delete(record.id);
الوسيطة الأولى هي اسم الكتلة (مع /)، والثانية اسم المخطط.
في الكتل ذات المخطط الواحد، احذف اسم المخطط (القيمة الافتراضية هي "default").
ذاكرة التخزين المؤقت
bs.cache هي ذاكرة تخزين مؤقت للاستعلامات في الذاكرة، مشتركة بين جميع استدعاءات bs.query وbs.mutate. يمكنك استخدامها مباشرة أيضًا:
// Read a cached value
const data = bs.cache.get('my-key');
// Write to the cache
bs.cache.set('my-key', { items: [...] });
// Invalidate a single key
bs.cache.invalidate('my-key');
// Clear all cached entries
bs.cache.clear();
تُخزَّن عناصر ذاكرة التخزين المؤقت في الذاكرة وتُمسح عند الانتقال بين الصفحات. يستخدمها bs.query وbs.mutate أساسًا داخليًا، لكن الوصول المباشر مفيد لتهيئة البيانات مسبقًا أو إبطالها يدويًا بعد عمليات مخصصة.
الاستعلام
يلتف bs.query() حول أي دالة غير متزامنة، موفرًا التخزين المؤقت وإزالة التكرار والتحكم في تقادم البيانات. تُعيد الاستدعاءات المتعددة بالمفتاح نفسه أثناء تنفيذ الطلب الوعد نفسه (دون جلب مكرر).
// Basic cached fetch
const subscribers = await bs.query('subscribers', () =>
bs.db('my-theme/app', 'subscribers').list()
);
// With staleTime: skip the fetch if cached data is younger than 30 seconds
const subscribers = await bs.query('subscribers', () =>
bs.db('my-theme/app', 'subscribers').list(),
{ staleTime: 30000 }
);
الوسيطة الأولى مفتاح لذاكرة التخزين المؤقت (أي سلسلة نصية). والثانية دالة تعيد وعدًا. والثالثة كائن خيارات اختياري:
| الخيار | النوع | الوصف |
|---|---|---|
staleTime |
number |
عدد المللي ثانية قبل اعتبار البيانات المخزنة مؤقتًا قديمة. 0 (افتراضيًا) يعيد الجلب دائمًا. |
إذا احتوت ذاكرة التخزين المؤقت على بيانات لهذا المفتاح وكان عمرها أقل من staleTime، تُعاد القيمة المخزنة فورًا دون استدعاء الدالة.
التعديل
يتولى bs.mutate() عمليات الكتابة مع تحديثات تفاؤلية وتراجع تلقائي عند الفشل. وله وضعان: الوضع التلقائي لأنماط CRUD الشائعة، والوضع اليدوي للتحكم الكامل.
يعمل الوضع التلقائي مع كائن حالة تفاعلي (مثل Alpine.js $data). مرّر state وkey وaction، واختياريًا optimistic:
// Optimistic create: item appears instantly, gets real ID on success
await bs.mutate({
state: $data,
key: 'todos',
action: 'create',
optimistic: { text: 'New todo', done: false },
fn: () =>
bs.db('my-theme/app', 'todos').create({ text: 'New todo', done: false }),
});
// Optimistic update: field changes instantly, reverts on failure
await bs.mutate({
state: $data,
key: 'todos',
action: 'update',
id: todoId,
optimistic: { done: true },
fn: () => bs.db('my-theme/app', 'todos').update(todoId, { done: true }),
});
// Delete: item removed from the array immediately
await bs.mutate({
state: $data,
key: 'todos',
action: 'delete',
id: todoId,
fn: () => bs.db('my-theme/app', 'todos').delete(todoId),
});
عند النجاح، تُستبدل البيانات التفاؤلية باستجابة الخادم. وعند الفشل، تعود الحالة إلى لقطة أُخذت قبل التعديل. يُبطَل مفتاح ذاكرة التخزين المؤقت تلقائيًا بعد كل تعديل ناجح.
يعني الفشل أن الوعد الذي يعيده fn قد رُفض. يُكمل bs.db() وbs.fn() التنفيذ مع نص الخطأ عند فشل التحقق من الصحة أو غياب سجل أو فشل التحقق من الأذونات؛ لذا اطرح خطأً عندما تتضمن النتيجة code إذا كان ينبغي التراجع في هذه الحالات أيضًا:
const ok = (request) =>
request.then((result) => {
if (result?.code) {
throw result;
}
return result;
});
await bs.mutate({
state: $data,
key: 'todos',
action: 'delete',
id: todoId,
fn: () => ok(bs.db('my-theme/app', 'todos').delete(todoId)),
});
في عمليات الإنشاء، يُعيَّن معرّف id مؤقت (مثل __temp_1) للعنصر التفاؤلي. وعند استجابة الخادم، يُحدَّث العنصر المؤقت بالبيانات الفعلية، بما فيها id الذي عيّنه الخادم.
يوفر الوضع اليدوي تحكمًا كاملًا باستخدام عمليات الاستدعاء اللاحقة before وonSuccess وonError:
await bs.mutate({
fn: () => bs.db('my-theme/app', 'todos').create({ text: 'New' }),
invalidate: 'todos',
before: () => {
// Take a snapshot, return it for use in onError
const snapshot = [...$data.todos];
$data.todos.push({ id: '__temp', text: 'New' });
return snapshot;
},
onSuccess: (result, snapshot) => {
// Replace temp item with server response
},
onError: (error, snapshot) => {
// Restore from snapshot
$data.todos = snapshot;
},
});
| الخيار | النوع | الوضع | الوصف |
|---|---|---|---|
fn |
function |
كلاهما | الدالة غير المتزامنة التي تنفذ التعديل. مطلوبة. |
state |
object |
تلقائي | كائن حالة تفاعلي (e.g، Alpine $data). |
key |
string |
تلقائي | اسم الخاصية في الحالة التي تحتوي على المصفوفة. يُستخدم أيضًا مفتاحًا لذاكرة التخزين المؤقت. |
action |
string |
تلقائي | أحد الخيارات: create أو update أو delete. |
id |
any |
تلقائي | معرّف السجل لإجراءي update وdelete. |
optimistic |
object |
تلقائي | البيانات التي تُطبَّق بتفاؤل قبل استجابة الخادم. |
before |
function |
يدوي | تُستدعى قبل fn. تُمرر القيمة المعادة إلى onSuccess/onError على أنها snapshot. |
onSuccess |
function |
يدوي | تُستدعى مع (result, snapshot) عند النجاح. |
onError |
function |
يدوي | تُستدعى مع (error, snapshot) عند الفشل. |
invalidate |
string |
يدوي | مفتاح ذاكرة التخزين المؤقت المطلوب إبطاله عند النجاح. |
PHP API
توفر فئة Db العمليات نفسها على جانب الخادم. استخدمها في rpc.php وcron.php والقوالب أو أي كود PHP.
use Blockstudio\Db;
$db = Db::get('my-theme/block', 'subscribers');
// Create
$record = $db->create(['email' => 'a@b.com', 'plan' => 'pro']);
// List with filters
$all = $db->list();
$pros = $db->list(['plan' => 'pro'], limit: 10, offset: 0);
// Count and paginate
$count = $db->count(['plan' => 'pro']);
$page = $db->paginate(['plan' => 'pro'], limit: 10, offset: 20);
// Get by ID
$one = $db->get_record(1);
// Update
$db->update(1, ['plan' => 'enterprise']);
// Delete
$db->delete(1);
للكتل ذات المخطط الواحد:
$db = Db::get('my-theme/block');
الاستقصاء الفوري
أضف realtime إلى مخططك لتمكين الاستقصاء التلقائي. عند تغير البيانات على الخادم، يُحدَّث UI تلقائيًا عبر مخزن Interactivity API. لا حاجة إلى تغييرات في JavaScript.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
باستخدام true، يستقصي Blockstudio كل 3 ثوانٍ، مستخدمًا اسم المخطط مفتاح حالة Interactivity API (default للكتل ذات المخطط الواحد).
إعداد مخصص
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| الخيار | النوع | الافتراضي | الوصف |
|---|---|---|---|
key |
string |
اسم المخطط | اسم الخاصية في state التي تحتوي على مصفوفة البيانات |
interval |
number |
3000 |
الفاصل الزمني للاستقصاء بالمللي ثانية |
آلية العمل
- عند تحميل الصفحة، يجلب العميل قيمة تجزئة خفيفة للبيانات الحالية
- كل
intervalمللي ثانية، يعيد جلب قيمة التجزئة - إذا تغيرت قيمة التجزئة، يجلب مجموعة البيانات كاملة
- تُرسل البيانات الجديدة إلى مخزن Interactivity API عبر
store() - يُعاد العرض تلقائيًا لأي توجيهات مرتبطة بخاصية الحالة هذه
لا يعمل الاستقصاء إلا في الصفحات التي يوجد فيها عنصر data-wp-interactive مطابق.
ويتوقف مؤقتًا عند إخفاء علامة تبويب المتصفح، ثم يُستأنف عند ظهورها.
تعيد نقطة نهاية التجزئة (?_hash=1) مجموع التحقق md5 وعدد السجلات فقط، ما يجعل طلبات الاستقصاء خفيفة.
البيانات المخصصة للمستخدم
اضبط userScoped: true لتقييد جميع السجلات تلقائيًا بالمستخدم الحالي.
يضيف Blockstudio عمود user_id ويعيّنه عند الإنشاء، ويقصر جميع العمليات على سجلات المستخدم الحالي فقط:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
لا حاجة إلى حقل user_id يدوي أو خطاف before_create أو تصفية في RPC. يمكن للمستخدمين عرض سجلاتهم وتعديلها وحذفها فقط. يتولى Blockstudio إدارة عمود user_id بالكامل.
عند استخدام التخزين post_type، يُربط userScoped بـ post_author بدلًا من عمود user_id منفصل.
التحكم في الوصول
لكل عملية CRUD مستوى أذونات خاص بها:
| القيمة | السلوك |
|---|---|
true |
عام مع حماية CSRF (يُسمح للمستخدمين غير المسجلين، ويتطلب X-BS-Token) |
'open' |
عام بالكامل، دون CSRF أو مصادقة (لـ webhooks وواجهات API الخارجية) |
'edit_posts' |
التحقق من صلاحية WordPress |
['cap_a', 'cap_b'] |
يحتاج المستخدم إلى أي صلاحية واحدة من القائمة |
محذوف / null |
يتطلب المصادقة (مستخدم مسجل الدخول) |
'capability' => [
'create' => true, // public + CSRF protected
'read' => 'open', // truly open, no protection
'update' => 'edit_posts', // editors and above
'delete' => ['delete_posts', 'manage_options'], // either capability works
],
حماية CSRF
تُحمى نقاط النهاية العامة (true) بترويسة X-BS-Token. وتجلب bs.db() وbs.fn() بيانات اعتماد حديثة من نقطة نهاية من المصدر نفسه وغير مخزنة مؤقتًا، بدلًا من تضمين رموز تنتهي صلاحيتها في HTML الصفحة. وتظل الصفحات المقدمة من مخابئ خارجية طويلة الأمد تعمل. أما الطلبات المجهولة التي لا تتضمن رمزًا صالحًا، فتتلقى استجابة 403.
تُطلب بيانات الاعتماد عند أول استدعاء لـ API، وليس عند كل زيارة للصفحة. ويشترك العميلان، بما في ذلك استطلاع قاعدة البيانات للبيانات الآنية، في عملية تحديث واحدة لبيانات الاعتماد قيد التنفيذ. وتُحدّث بيانات الاعتماد بعد خمس دقائق من الاستخدام. ويؤدي رفض قيمة nonce لـ WordPress أو رمز CSRF لـ Blockstudio إلى تحديث واحد وإعادة المحاولة؛ أما أخطاء الأذونات العادية فلا تؤدي إلى إعادة المحاولة. وتظل الطلبات من المستخدمين المسجلين تستخدم جلسة المستخدم الزائر وفحوصات الصلاحيات وملكية السجلات الخاصة بالمخطط.
أبقِ POST /wp-json/blockstudio/v1/client/credentials خارج أي ذاكرة تخزين مؤقت للوكيل أو CDN. فهو يرسل Cache-Control: private, no-store ويتطلب طلبًا من المصدر نفسه يتضمن ترويسة غير بسيطة. ويتولى العملاء المضمنون ذلك تلقائيًا.
استخدم 'open' عندما تحتاج إلى وصول غير مصادق عليه بالكامل ودون CSRF، مثل webhooks الواردة من خدمات خارجية.
أنواع الحقول
| النوع | عمود MySQL | نوع PHP | الوصف |
|---|---|---|---|
string |
varchar(maxLength) |
string |
نص، الحد الأقصى الافتراضي لـ maxLength هو 255 |
integer |
bigint(20) |
int |
أعداد صحيحة |
number |
decimal(20,6) |
float |
أعداد عشرية |
boolean |
tinyint(1) |
bool |
صح/خطأ |
text |
longtext |
string |
محتوى نصي طويل |
التحقق من الصحة
تُفحَص صحة جميع عمليات الكتابة (الإنشاء والتحديث) وفق المخطط قبل الوصول إلى التخزين. ويُجرى التحقق على الخادم، سواء أتى الطلب من bs.db() أو REST API أو Db::get().
القواعد المضمنة
| القاعدة | المثال | الوصف |
|---|---|---|
required |
'required' => true |
يجب توفير الحقل عند الإنشاء |
type |
'type' => 'integer' |
يجب أن تطابق القيمة النوع المُعلن |
enum |
'enum' => ['a', 'b'] |
يجب أن تكون القيمة أحد الخيارات المدرجة |
maxLength |
'maxLength' => 100 |
يجب ألا يتجاوز طول السلسلة هذا الحد |
minLength |
'minLength' => 3 |
يجب ألا يقل طول السلسلة عن هذا الحد |
format: "email" |
'format' => 'email' |
يجب أن يكون عنوان بريد إلكتروني صالحًا |
format: "url" |
'format' => 'url' |
يجب أن يكون URL صالحًا |
تحقق مخصص
أضف رد نداء validate إلى أي حقل لإجراء فحوصات على جانب الخادم تتجاوز القواعد المضمنة. أعد true للنجاح، أو سلسلة نصية تتضمن رسالة الخطأ:
'email' => [
'type' => 'string',
'format' => 'email',
'required' => true,
'validate' => function ($value, $data) {
if (str_ends_with($value, '@disposable.com')) {
return 'Disposable email addresses are not allowed.';
}
return true;
},
],
يتلقى رد النداء قيمة الحقل ومصفوفة البيانات كاملة، ما يتيح لك التحقق من الصحة عبر الحقول.
تنسيق استجابة الخطأ
تعيد أخطاء التحقق من الصحة حالة 400 مع مصفوفات أخطاء لكل حقل. استُلهم هذا التنسيق من fieldErrors الخاصة بـ Zod، ويجعل ربط الأخطاء بحقول النماذج أمرًا مباشرًا:
{
"code": "blockstudio_db_validation",
"message": "Validation failed.",
"data": {
"status": 400,
"errors": {
"email": [
"Must be a valid email address.",
"Disposable email addresses are not allowed."
],
"plan": ["Must be one of: free, pro."]
}
}
}
يرتبط كل حقل بمصفوفة من سلاسل الأخطاء. قد تفشل قواعد متعددة للحقل نفسه. في الواجهة الأمامية:
const result = await db.create({ email: 'bad', plan: 'invalid' });
if (result.data?.errors) {
// { email: ["Must be a valid email address."], plan: ["Must be one of: free, pro."] }
Object.entries(result.data.errors).forEach(([field, messages]) => {
showFieldError(field, messages[0]);
});
}
نقاط نهاية REST
تقع جميع نقاط النهاية ضمن مساحة الأسماء blockstudio/v1/db/:
/db/{block-name}/{schema-name}
يُستبدل / في اسم الكتلة بـ -. أما في الكتل ذات المخطط الواحد، فيكون اسم المخطط default.
| الطريقة | نقطة النهاية | الوصف |
|---|---|---|
GET |
/db/{block}/{schema} |
سرد السجلات |
POST |
/db/{block}/{schema} |
إنشاء سجل |
GET |
/db/{block}/{schema}/{id} |
جلب سجل واحد |
PUT |
/db/{block}/{schema}/{id} |
تحديث سجل |
DELETE |
/db/{block}/{schema}/{id} |
حذف سجل |
معلمات الاستعلام (القائمة)
| المعلمة | الوصف |
|---|---|
limit |
الحد الأقصى للسجلات المطلوب إرجاعها (الافتراضي 50، والحد الأقصى 100) |
offset |
عدد السجلات المطلوب تخطيها |
| اسم أي حقل | التصفية حسب تطابق القيمة تمامًا |
مثال: GET /db/my-theme-app/subscribers?plan=pro&limit=10
عرض النموذج
يمكن للحقول تعريف مفتاح component يشير إلى كتلة Blockstudio. استدعِ
bs_db_form() في القالب لعرض جميع الحقول كنموذج باستخدام
كتل مكوناتها.
'fields' => [
'email' => [
'type' => 'string',
'format' => 'email',
'required' => true,
'component' => [
'name' => 'my-theme/field',
'attributes' => ['label' => 'Email', 'type' => 'email'],
'innerBlocks' => [
[
'name' => 'my-theme/input',
'attributes' => ['placeholder' => 'Enter your email'],
],
],
],
],
'plan' => [
'type' => 'string',
'enum' => ['free', 'pro'],
'component' => [
'name' => 'my-theme/field',
'attributes' => ['label' => 'Plan'],
'innerBlocks' => [
[
'name' => 'my-theme/select',
'attributes' => ['options' => ['free', 'pro']],
],
],
],
],
],
<form>
<?php bs_db_form('my-theme/app', 'subscribers'); ?>
<button type="submit">Subscribe</button>
</form>
يتلقى كل مكون تعريف الحقل كاملًا في field ضمن سماته،
حتى تتمكن المكونات من تكييف طريقة عرضها وفقًا للمخطط. على سبيل المثال،
يعطي $a['field']['name'] اسم الحقل، ويعطي $a['field']['type'] النوع،
ويحدد $a['field']['required'] ما إذا كان الحقل مطلوبًا، وغير ذلك.
يتبع هيكل المكونات التنسيق نفسه لـ name وattributes وinnerBlocks
كما في كتل WordPress. تُعرض الكتل الداخلية أولًا وتُمرر بصفتها
$content إلى الكتلة الأم.
لاستخدام PHP دون إخراج المحتوى:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
الخطافات
تُفعَّل الإجراءات قبل كل عملية كتابة وبعدها. وتتلقى جميع الخطافات مصفوفة
$params واحدة. راجع مرجع الخطافات PHP
للاطلاع على القائمة كاملة.
الخطافات المضمنة
عرّف الخطافات مباشرةً في db.php. يتم تقييد نطاقها تلقائيًا بهذا المخطط،
لذلك لا تحتاج إلى التحقق من اسم الكتلة أو المخطط:
return [
'storage' => 'table',
'fields' => [ /* ... */ ],
'hooks' => [
'after_create' => function ($params) {
// $params['record'] is the created record
wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
},
'before_delete' => function ($params) {
// $params['id'] is the record being deleted
error_log('Deleting subscriber ' . $params['id']);
},
],
];
الخطافات العامة
استمع إلى جميع المخططات من أي مكان:
add_action('blockstudio/db/after_create', function ($params) {
// $params['block'] and $params['schema'] identify the source
if ('my-theme/app' === $params['block'] && 'subscribers' === $params['schema']) {
// sync to external CRM
}
});
الدمج مع RPC
db.php وrpc.php نظامان مستقلان. ينشئ db.php نقاط نهاية CRUD
من تعريف المخطط. أما rpc.php فيعرّف وظائف مخصصة على الخادم.
يمكن استخدام كل منهما بمفرده.
استخدمهما معًا عندما تحتاج إلى عمليات بيانات قياسية بالإضافة إلى منطق أعمال مخصص:
use Blockstudio\Db;
return [
'export' => [
'callback' => function (array $params): array {
$db = Db::get('my-theme/app', 'subscribers');
$rows = $db->list(['plan' => 'pro']);
// custom CSV generation, email sending, etc.
return ['exported' => count($rows)];
},
'capability' => 'manage_options',
],
];
قابلية النقل
مع تخزين JSONC، تكون البيانات إلى جانب الأكواد. انسخ مجلد الكتلة إلى موقع آخر، وسينتقل كل شيء معًا: UI والمنطق والتحكم في الوصول والبيانات نفسها.
my-app/
├── block.json
├── index.twig
├── style.css
├── rpc.php ← custom endpoints
├── db.php ← data schema
├── cron.php ← scheduled tasks
└── db/
└── entries.jsonc ← the actual data
لا حاجة إلى ترحيل قاعدة البيانات أو خطوات التصدير والاستيراد. انسخ المجلد فحسب.
يمكن نقل تخزين Storh أيضًا، لكنه يوجد في uploads/blockstudio/db/
بدلًا من مجلد الكتلة. وبذلك تبقى البيانات الحية القابلة للكتابة خارج شجرة المصدر،
مع الاحتفاظ لكل مخطط بمخزن ملفات عادي يمكن نسخه احتياطيًا أو نسخه أو ترحيله
بشكل مستقل.
التصفية
عدّل المخططات برمجيًا من خارج الكتلة:
add_filter('blockstudio/database', function (array $schemas): array {
// Add a field to an existing schema
$schemas['my-theme/app:subscribers']['fields']['source'] = [
'type' => 'string',
'default' => 'website',
];
return $schemas;
});