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

Dennis · 10 أبريل 2026

Blockstudio 7.2

Blockstudio يوسّع الإصدار 7.2 إطار العمل في اتجاهين معًا.

الأول هو الرؤية وسير العمل ضمن المشروع الواحد: نظرة عامة جديدة للمسؤول، ومتصفح لقواعد البيانات، ومتصفح لسجل المسؤول، ومقدمات SCSS لإعداد Sass المشترك.

والثاني هو المنظومة المحيطة بـ Blockstudio: ‏CLI للسجل لتوزيع الكتل (على غرار shadcn لـ WordPress)، وإضافة PHPStan تجلب أمان الأنواع بأسلوب TypeScript إلى القوالب ووسوم الكتل وdb.php وrpc.php وcron.php وملفات المخططات المحيطة بها.

يصب كلا الاتجاهين في الهدف نفسه: تسهيل فهم مشاريع Blockstudio الكبيرة والبناء عليها ومشاركتها.

تجربة المسؤول

تسهل إضافتان التنقل في المشروع الكبير داخل wp-admin.

النظرة العامة للمسؤول

يتضمن Blockstudio الآن شاشة إدارة ضمن أدوات > Blockstudio. تتيح لك مكانًا واحدًا لفحص ما سجّله النظام من نظام الملفات.

تتضمن النظرة العامة علامات تبويب مخصصة لـ:

  • الكتل
  • الامتدادات
  • الحقول
  • الصفحات
  • المخططات

إلى جانب النظرة العامة، تتضمن منطقة الإدارة الآن قسمًا مخصصًا بعنوان قواعد البيانات. يسرد كل مخطط Blockstudio\Db مسجل، ويتيح لك فحص السجلات الفعلية مباشرةً داخل wp-admin.

بدلًا من إنشاء شبكة مخصصة من اللوحات، تستخدم الشاشة جداول DataViews الأصلية في WordPress. وهذا يبقي UI متوافقًا مع wp-admin ويجعله عمليًا عندما يضم المشروع عشرات أو مئات التسجيلات.

في التثبيت الصغير، يمكنك تذكر حالة التشغيل. لكن ذلك لا يعود ممكنًا في قاعدة شفرات أكبر، وتبدأ بطرح أسئلة مثل:

  • ما أنواع الكتل المسجلة حاليًا؟
  • ما الامتدادات التي تستهدف core/* وتلك التي تستهدف كتلًا بعينها؟
  • ما الصفحات المتزامنة وما أنواع المنشورات المرتبطة بها؟
  • ما الحقول القابلة لإعادة الاستخدام الموجودة في هذا المشروع؟
  • ما المخططات المسجلة وما واجهة التخزين الخلفية التي تستخدمها؟

حتى الآن، كانت الإجابة مزيجًا من تفحّص المجلدات وفتح ملفات JSON والتنقل خطوة بخطوة في PHP. أما النظرة العامة فتحول ذلك إلى واجهة إدارية فعلية.

صُممت كل علامة تبويب للإجابة عن أسئلة مختلفة:

  • الكتل تعرض أنواع الكتل المسجلة ووضع العرض وإصدار API وعدد السمات
  • الامتدادات تعرض الكتل المستهدفة، إلى جانب الأولوية وتفاصيل العرض
  • الحقول تقدم قائمة سريعة بتعريفات الحقول المخصصة القابلة لإعادة الاستخدام
  • الصفحات تعرض الصفحات المتزامنة المعتمدة على الملفات، مع نوع المنشور والحالة ومحرك القالب وحالة المزامنة
  • المخططات تعرض مخططات التخزين المسجلة، مع الواجهة الخلفية وعدد الحقول ونطاق الصلاحيات

أُبقي متصفح قواعد البيانات منفصلًا عمدًا عن بيانات النظرة العامة الأولية. فبدلًا من تسلسل كل صف عند تحميل الصفحة، لا يحمّل مسبقًا سوى المخططات المتاحة، ويجلب السجلات عند الطلب عند فتح علامة تبويب قاعدة بيانات. وهذا يجعل واجهة الإدارة مفيدة حتى عندما يحتوي المشروع على مجموعات بيانات أكبر وراء db.php.

يركز هذا الإصدار الأول عمدًا على التسجيلات المدعومة بالمخططات. فهو ليس صفحة إعدادات، بل صفحة فحص.

إذا لم تكن تريده مطلقًا، فقم بتعطيله بالكامل:

PHP
add_filter('blockstudio/admin/enabled', '__return_false');

متصفح سجل الإدارة

إلى جانب النظرة العامة توجد علامة تبويب ثانية: السجل. وهي متصفح لسجلات الكتل البعيدة المُهيأة في blocks.json الخاص بقالبك، وتتيح لك استيراد الكتل مباشرةً من إدارة WordPress دون الحاجة إلى لمس CLI.

JSON
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

يجلب المتصفح كل سجل مُهيأ، ويسرد جميع الكتل المتاحة، ويوضح ما إذا كانت مثبتة محليًا بالفعل أو متاحة للاستيراد. يحتوي كل صف على زر «استيراد» ينزّل ملفات الكتلة إلى المجلد المُهيأ في قالبك. أما الكتل المثبتة بالفعل فيظهر لها زر «إعادة الاستيراد» بدلًا منه.

تُدعم السجلات التي تتطلب مصادقة عبر تنسيق الكائن الذي يستخدم headers، بما في ذلك استيفاء ${ENV_VAR} حتى لا ينتهي المطاف بالرموز في نظام التحكم بالإصدارات.

وهذا يجعل تصفح السجلات واستخدامها تجربة إدارية متكاملة، لا مجرد سير عمل CLI.

سجل CLI

الجزء الآخر من قصة السجل هو أداة CLI مستقلة: blockstudio/registry.

إنها أداة على نمط shadcn لكتل WordPress. لا حزمة npm ولا خطوة بناء. شغّل أمرًا، فيُنسخ الكود المصدري للكتلة إلى مشروعك، وتصبح ملكًا لك بالكامل.

سطر الأوامر
npx blockstudio init
npx blockstudio add ui/tabs

يعمل CLI مع أي نوع من الكتل: كتل Blockstudio، ومخرجات @wordpress/create-block، وكتل PHP عادية. لا يهتم السجل بمحتويات المجلد؛ إذ يقرأ بيان الملفات من registry.json وينسخ تلك الملفات وحدها.

ينشر مؤلفو الكتل ملف registry.json على أي URL (GitHub محتوى خام، أو S3، أو خادم مخصص) يسرد الكتل المتاحة مع بياناتها الوصفية وتبعياتها وقوائم ملفاتها. ويضيف المستخدمون URL إلى blocks.json لديهم، ثم يجلبون الكتل بأسمائها.

يدعم CLI ما يلي:

  • حل التبعيات: يمكن للكتل إعلان تبعيتها إلى كتل أخرى، ويُحل ذلك تلقائيًا مع اكتشاف الدورات
  • معالجة التعارض بين السجلات المتعددة: عندما يوجد اسم الكتلة نفسه في سجلات متعددة، يطلب منك CLI اختيار أحدها
  • السجلات التي تتطلب مصادقة: رموز حامل، ومصادقة أساسية، وترويسات مخصصة مع استيفاء متغيرات البيئة
  • واجهة TUI تفاعلية: مبنية باستخدام Ink، وتتضمن مؤشرات انتظار وقوائم اختيار ومؤشرات تقدم
  • وضع غير تفاعلي: الخيار --yes والانتقال التلقائي إليه في بيئات CI أو عند تمرير البيانات عبر الأنابيب
  • البحث والسرد: تصفح السجلات من سطر الأوامر

تتضمن الحزمة 130 اختبارًا تغطي المخططات وحل التبعيات وجلب HTTP وكتابة الملفات وتدفقات كل الأوامر وUI التفاعلية في Ink.

الوثائق الكاملة في blockstudio.dev/registry.

إضافة PHPStan

الإضافة الكبيرة الأخرى هي blockstudio/phpstan: إضافة PHPStan تمنح مستخدمي Blockstudio مستوى أمان الأنواع الذي يتوقعه مطورو TypeScript.

سطر الأوامر
composer require --dev blockstudio/phpstan

تقرأ الإضافة المخططات الفعلية لمشروعك وقت التحليل، ثم تمرر الأنواع الناتجة إلى PHPStan. وتشمل الآن قوالب PHP وTwig وBlade وعلامات الكتل وسجلات قواعد البيانات ذات الأنواع المحددة ومسارات الإعدادات وأسماء الخطافات والتحقق من المخططات عبر block.json وfield.json وJSON الإضافة وpage.json وdb.php وrpc.php وcron.php وblockstudio.json.

قوالب كتل آمنة الأنواع

يجري التحقق من الوصول إلى الحقول في $a وفقًا لـblock.json المجاور:

PHP
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?

سجلات قواعد بيانات آمنة الأنواع

يعيد Db::get() مثيلًا محدد الأنواع استنادًا إلى مخطط db.php لديك. ويُبنى شكل السجل من الحقول الفعلية:

PHP
return [
  'storage' => 'table',
  'fields' => [
    'email' => ['type' => 'string', 'required' => true],
    'name'  => ['type' => 'string'],
  ],
];
PHP
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}

التحقق من المخططات

تُكتشف ملفات المخططات غير الصالحة وقت التحليل: block.json وfield.json وJSON الإضافة وpage.json وdb.php وrpc.php وcron.php وblockstudio.json. ويُبلغ عن الأسماء المفقودة وأنواع الحقول الخاطئة والتعريفات ذات التنسيق غير الصحيح والقيم المنطقية المختصرة القديمة ("tailwind": true بدلًا من الكائن المتداخل)، مع تحديد السطر الدقيق في الملف المصدر.

التحقق من مسارات الإعدادات

يجري التحقق من استدعاءات Settings::get() وفقًا لمخطط الإعدادات المعروف:

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?

التحقق من أسماء الخطافات

وينطبق الأمر نفسه على أسماء خطافات التصفية والإجراءات:

PHP
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?

تتضمن الإضافة أيضًا تعريفات بديلة لكامل Blockstudio العام في API: Db وSettings وField_Registry وBuild والمساعدات العامة. وستحصل على الإكمال التلقائي والتحقق من الأنواع لجميع واجهات Blockstudio البرمجية دون الحاجة إلى الشفرة المصدرية للإضافة على جهاز التطوير.

تسهيلات التأليف

يُكمل الإصدار بتسهيلين صغيرين في التأليف.

مقدمات SCSS العامة

كان Blockstudio يدعم بالفعل تجميع SCSS، لكن كانت هناك عقبة مزعجة واحدة: إعداد Sass المشترك.

إذا أردت استخدام مجموعة مشتركة من المتغيرات أو الدوال أو المزائج، كان عليك استيرادها في كل ملف SCSS. وسرعان ما يصبح ذلك متكررًا، خصوصًا مع أنظمة التصميم الكبيرة أو أدوات Sass مثل Bootstrap.

يضيف الإصدار 7.2 خطافًا للمقدمات لهذا الغرض تحديدًا:

PHP
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);

وبالاقتران مع مرشح blockstudio/assets/process/scss/import_paths الحالي، يمكنك تعريف موارد Sass المشتركة مرة واحدة لتصبح متاحة لكل ملف مُجمّع.

يمكن أن تظل ورقة أنماط الكتلة مركزة على الأنماط التي تحتاج إليها فعليًا:

Scss
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}

لا حاجة إلى تكرار عمليات الاستيراد في كل أصل للكتلة. فهذا ليس «دعمًا لـ Bootstrap» في وضع خاص، بل خطاف عام لمشاركة Sass عبر المشروع، سواء أكان مصدرها Bootstrap أم مجموعة أدوات داخلية خاصة بك.

تعريفات PHP الأصلية لكتل API

يضيف الإصدار 7.2 أيضًا صياغة اختيارية أصلية في PHP لواجهات برمجة الكتل المتكاملة. تظل المصفوفات الخيار الافتراضي والمدعوم بالكامل، ولم يُستبدل أي شيء. لكن إذا كنت تفضل الوسائط المسماة والتعدادات والسمات على مصفوفات الإعدادات المتداخلة، فيمكنك الآن اختيار هذا الأسلوب.

بالنسبة إلى rpc.php، أعد كائنًا بأساليب مزودة بسمات:

PHP
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};

وبالنسبة إلى cron.php، تعمل الفكرة نفسها مع #[Cron]:

PHP
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};

أما بالنسبة إلى db.php، فتتوفر الآن طبقة منشئ صغيرة:

PHP
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);

يحقق هذا توازنًا أفضل لقواعد الشفرة الكبيرة. تحتفظ ببساطة تنسيق المصفوفات عندما تريده، ويمكنك الانتقال إلى واجهة PHP أوضح عند نمو الكتلة لتتجاوز بضعة حقول أو نقاط نهاية.

لماذا يجري طرح هذه الميزات معًا

تجيب نظرة الإدارة العامة ومتصفح السجل وCLI السجل وإضافة PHPStan كلها عن السؤال نفسه: كيف تحافظ على وضوح مشروع Blockstudio مع نموه؟

تجيب أدوات الإدارة عن ذلك على مستوى المشروع: رؤية ما هو مسجل، وإمكانية جلب الكتل من السجلات، وتقليل التخمين.

يجيب CLI عن ذلك على مستوى المنظومة: طريقة لمشاركة الكتل بين المشاريع والفرق دون تضمينها في حزم npm أو المعاناة مع أنظمة البناء.

تجيب إضافة PHPStan عن ذلك على مستوى الشفرة: اكتشاف الوصول إلى الحقول الخاطئة وأخطاء المخططات الإملائية واستدعاءات الخطافات المعطلة قبل وصولها إلى وقت التشغيل.

هذا هو التوجه العام للإصدار 7.2: تخمين وتكرار أقل، ورؤية أوضح، وأمان فعلي للأنواع.

إصلاحات الأخطاء

  • حقل Classes: كانت أسماء الفئات المخصصة التي يكتبها المستخدم تُحذف بصمت عند مغادرة الحقل، لأن أداة التحقق لم تقبل سوى الفئات الموجودة في قائمة Tailwind/الإعدادات المحددة مسبقًا. يقبل الآن أي سلسلة غير فارغة.
  • حقل Attributes: كان حذف زوج من السمات يترك عناصر null في البيانات المحفوظة. استُبدل lodash unset() (الذي يحول عناصر المصفوفة إلى null) بـ splice() (الذي يحذفها).
  • مصغّر CSS: أزال مصغّر TailwindPHP المسافات البيضاء حول + داخل calc() وclamp()، ما أدى إلى إنتاج CSS غير صالح مثل calc(1rem+0.5vw). عولجت المشكلة في المنبع ضمن TailwindPHP v1.3.1 بخوارزمية تمر على المحارف مع مراعاة العمق، ولا تزيل المسافات البيضاء حول مُجمّعات المحددات إلا عند مستوى الأقواس 0.
  • معاينة Block Inserter: كان $isPreview دائمًا false في معاينة Block Inserter، لأن تجزئة مفتاح ذاكرة التخزين المؤقت للتصيير لم تتضمن وضع التصيير. أصبح تصيير المحرر والمعاينة الآن يُنتج مدخلين منفصلين في ذاكرة التخزين المؤقت.
  • قالب InnerBlocks المتداخل: أسقط المكوّن <InnerBlocks template="..."/> العنصر الثالث (العناصر الفرعية) من صفوف القالب مثل ['core/group', {}, [['core/paragraph']]]، ما أدى إلى إنشاء كتل حاوية فارغة. ويحافظ الآن على العناصر الفرعية المتداخلة.