تسجيل بلوكات ووردبريس: توحيد تعريف PHP وJavaScript عبر register_block_type

add_action('init', function() {
    register_block_type( __DIR__ . '/build' );
});

function render_callback( array $attributes, string $content, WP_Block $block ): string

<?php
/**
 * مدير تسجيل بلوكات ووردبريس المعماري الحديث
 * Author: Mohamed Abozaid
 */

if (!defined('ABSPATH')) {
    exit;
}

class Enterprise_Block_Registration_Manager {

    private const BLOCKS_DIRECTORY = __DIR__ . '/build';

    public static function init(): void {
        add_action('init', [__CLASS__, 'register_all_blocks']);
    }

    /**
     * تسجيل كافة البلوكات المعتمدة على block.json
     */
    public static function register_all_blocks(): void {
        // 1. تسجيل بلوك بطاقة التسعير الثابت
        register_block_type(self::BLOCKS_DIRECTORY . '/pricing-card');

        // 2. تسجيل بلوك الدورات التدريبية الديناميكي مع معالج PHP
        register_block_type(
            self::BLOCKS_DIRECTORY . '/latest-courses',
            [
                'render_callback' => [__CLASS__, 'render_latest_courses_block'],
            ]
        );
    }

    /**
     * معالج تصيير البلوك الديناميكي في السيرفر مع التخزين المؤقت الذكي
     */
    public static function render_latest_courses_block(array $attributes, string $content, WP_Block $block): string {
        $number_of_courses = (int) ($attributes['numberOfCourses'] ?? 3);
        $category_slug     = sanitize_key($attributes['category'] ?? '');

        // مفتاح كاش فريد لكل تشكيلة معاملات
        $cache_key = sprintf('az_courses_block_%s_%d', $category_slug, $number_of_courses);

        // محاولة جلب كود الـ HTML من الكاش السريع
        $cached_html = get_transient($cache_key);
        if ($cached_html !== false && !is_user_logged_in()) {
            return $cached_html;
        }

        // إعداد استعلام جلب الدورات التدريبية
        $query_args = [
            'post_type'      => 'courses',
            'post_status'    => 'publish',
            'posts_per_page' => $number_of_courses,
            'no_found_rows'  => true, // تسريع الاستعلام بتخطي حساب إجمالي الصفحات
        ];

        if (!empty($category_slug)) {
            $query_args['tax_query'] = [
                [
                    'taxonomy' => 'course_category',
                    'field'    => 'slug',
                    'terms'    => $category_slug,
                ],
            ];
        }

        $courses_query = new WP_Query($query_args);

        if (!$courses_query->have_posts()) {
            return sprintf(
                '
%s
',
                get_block_wrapper_attributes(['class' => 'az-courses-container']),
                esc_html__('لا توجد دورات تدريبية متاحة حالياً في هذا القسم.', 'text-domain')
            );
        }

        // بناء كود الـ HTML الدلالي فائق السرعة
        ob_start();
        ?>
        <div  'az-courses-grid-wrapper']); ?>>
            

                have_posts()) : $courses_query->the_post(); ?>
                    

                        
                            

                                 'lazy']); ?>
                            
                        
                        
                        

                            

                                <a href="">
                            
                            

                            
                            

                                
                                    
                                
                                <a href="" class="btn-enroll">سجل الآن
                            
                        
                    
                
            
        

تفكيك الكود وشرح فلسفته المعمارية بالعامية المصرية

تعال نفصص مع بعض دقة البناء المعماري في الكود ده:

• استدعاء get_block_wrapper_attributes(): دي دالة نواتية سحرية في PHP. وظيفتها تاخد كل خيارات الألوان، المسافات، والـ Classes اللي المحرر اختارها في لوحة التحكم وتدمجها في الوسم الجذري <div> تلقائياً! ده بيضمن إن البلوك الديناميكي يتوافق مع ثيم الموقع بالكامل بدون ما تضطر تكتب منطق دمج الـ Styles بإيدك.
• طبقة الكاش الذكية للمخرجات (Fragment Caching): البلوك ده بيعرض محتوى من قاعدة البيانات. لو كل زائر دخل قرأ الداتابيز، السيرفر هيتحرق. الكود بيحفظ ناتج الـ HTML الجاهز في الـ Transient API لمدة ساعة. أول ريكوست بس هو اللي بيكلم MySQL، والـ 10,000 زائر اللي بعده بياخدوا كود الـ HTML الجاهز من الرام في 0.2 مللي ثانية!
• تحسين أداء استعلام WP_Query بـ 'no_found_rows' => true: ووردبريس افتراضياً مع كل استعلام بيعمل SQL_CALC_FOUND_ROWS عشان يعرف إجمالي الصفحات للـ Pagination. بما إننا بنعرض مجرد 3 أو 5 دورات في الصفحة الرئيسية، إلغاء الحساب ده بيوفر أكثر من 40% من زمن تنفيذ استعلام MySQL!

دراسة حالة واقعية من السوق المصري: إنقاذ منصة مؤتمرات طبية من بطء الـ 6 ثواني

تعال أحكيلك كواليس واقعة تقنية حقيقية حصلت مع منصة متخصصة في تنظيم المؤتمرات والتعليم الطبي المستمر في القاهرة والإسكندرية:

الأزمة في أسلوب التسجيل القديم

المنصة طورت حزمة من 12 بلوك مخصص (بلوك جدول المحاضرات، بلوك المتحدثين، بلوك التسجيل، بلوك المعرض، إلخ). المطورين كانوا شغالين بالنظام القديم: في ملف functions.php، كانوا كاتبين كود بيعمل wp_enqueue_script و wp_enqueue_style لـ 12 ملف JS و 8 ملفات CSS في كل ريكوست بيوصل للموقع! حتى لما زائر كان يدخل يفتح صفحة “شروط الاستخدام” أو “اتصل بنا” اللي مفيهاش غير نص عادي، كان متصفحه بيحمل أكثر من 3.8 ميجابايت من ملفات الجافاسكريبت والـ CSS الخاصة بكل البلوكات الـ 12!

الكارثة على شبكات الموبايل المصرية

الأطباء والمشاركين كانوا بيحاولوا يفتحوا الموقع من هواتفهم عبر شبكات المحمول (4G/3G) داخل قاعات المؤتمرات. زمن فتح الصفحة وصل لـ 6.5 ثانية كاملة! درجة الموقع في Google PageSpeed سقطت لـ 34 من 100. والأخطر من كده، إن أطباء كتير مكنوش عارفين يسجلوا في ورش العمل بسبب ثقل الصفحة وتجمد المتصفح، مما كلف المنصة خسائر في اشتراكات المؤتمر تجاوزت 200,000 جنيه!

خطة الإنقاذ بالهجرة إلى block.json والتحميل المشروط

1. إعادة صياغة كافة البلوكات بمعيار block.json: تم تحويل البلوكات الـ 12 إلى بنية المجلدات الحديثة، مع ربط ملفات الأصول بخصائص editorScript و style داخل كل ملف block.json مستقل.
2. إلغاء أكواد wp_enqueue_scripts اليدوية: لغينا كل أكواد التحميل الإجباري في functions.php، واعتمدنا حصرياً على register_block_type().
3. تفعيل ميزة الـ Dynamic Script Loading: ووردبريس بقى يحمل فقط ملف الـ JS والـ CSS الخاص ببلوك “المتحدثين” لو الصفحة فيها بلوك متحدثين، وصفحة سياسة الخصوصية بقت تحمل صفر كيلوبايت من ملفات البلوكات!

جدول نتائج التحول الهندسي

الوصايا العشر لتسجيل بلوكات ووردبريس الحديثة

1. سجل دائماً بمسار المجلد (Register via Directory Path): استخدم register_block_type( __DIR__ . '/build' ) ودع ووردبريس يقرأ block.json تلقائياً.
2. لا تحمل الملفات يدوياً بـ wp_enqueue_scripts: دع ملف block.json يتولى إدارة التحميل المشروط لضمان عدم تحميل الملفات إلا عند الحاجة.
3. اعتمد على أداة @wordpress/scripts: هي الأداة الرسمية لتوليد ملفات التوزيع وملف التبعيات index.asset.php مع أرقام الـ Hashes للكاش.
4. احرص على استخدام get_block_wrapper_attributes(): في أي بلوك ديناميكي بـ PHP، يجب حقن هذه الدالة في الوسم الجذري لتطبيق الـ Styles المحددة.
5. طبق التخزين المؤقت للبلوكات الديناميكية (Fragment Caching): لا تترك الـ render_callback تستعلم الداتابيز في كل زيارة؛ خزن الـ HTML في Transients.
6. استخدم 'no_found_rows' => true في استعلامات الـ WP_Query: تسريع استعلامات قاعدة البيانات الخاصة بالبلوكات عبر تخطي حساب الترقيم غير الضروري.
7. لا تعتمد على التسجيل في JavaScript فقط: التسجيل في PHP إلزامي لضمان عمل البلوك مع الـ REST API ومحركات الـ Full Site Editing.
8. حدد فضاء اسم فريد وموحد لبلوكاتك (Vendor Namespace): استخدم بادئة شركتك أو مشروعك دائماً مثل my-org/block-name لمنع التضارب.
9. احرص على تسجيل خطاف init حصرياً: مكان تسجيل البلوكات النواتي هو خطاف init؛ لا تسجل البلوكات في wp_loaded أو after_setup_theme.
10. اختبر البلوكات مع تفعيل SCRIPT_DEBUG: تأكد من فحص كفاءة تحميل الملفات في بيئة التطوير لاكتشاف أي تبعيات مفقودة قبل النشر.

التعمق المعماري: كلاس WP_Block_Type_Registry وسجل الذاكرة المركزي

يا صديقي المطور، لما بتنادي register_block_type()، الكود ده مبيحتفظش بالبيانات في الهواء؛ في كائن نواتي عملاق شغال بنمط Singleton في الذاكرة اسمه WP_Block_Type_Registry: الموجود في wp-includes/class-wp-block-type-registry.php. الكائن ده هو الدفتر الرسمي اللي ووردبريس بيسجل فيه كل بلوك دخل النظام: 1. بيخزن كائنات WP_Block_Type في مصفوفة خاصة $registered_block_types. 2. بيتحقق من عدم تكرار نفس الاسم البرمجي للبلوك، ولو لقى إضافة تانية مسجلة نفس الاسم بيرمي تحذير أمني فوري. 3. بيمرر الخصائص المحددة في block.json لمحرك الـ REST API لتمكين المحرر من جلب قائمة البلوكات وصلاحياتها عبر مسار /wp/v2/block-types!

كواليس التحميل المشروط للأصول في script-loader.php

كتير من المطورين بيسألوا: “هو ووردبريس بيعرف منين إن الصفحة فيها البلوك ده بالذات عشان يحمل ملف الـ CSS والـ JS بتاعه، ويتجاهل باقي البلوكات؟” السر بيكمن في التكامل المعماري بين دالة do_blocks() وملف wp-includes/script-loader.php: لما ووردبريس بيعمل Parse لمحتوى المقال، بيجمع قائمة بأسماء البلوكات المستخدمة في الصفحة في مصفوفة بالذاكرة. قبل ما ترويسة الصفحة تتقفل في wp_head() أو التذييل في wp_footer()، النواة بتنادي دالة wp_enqueue_registered_block_scripts_and_styles(). الدالة دي بتلف فقط على البلوكات اللي تم استخدامها بالفعل، وتطلب من نظام الأصول wp_enqueue_script() و wp_enqueue_style() للملفات المعرفة في حقول style و viewScript! ده اللي بيخلي موقعك فائق الخفة، لأن صفحة المقال اللي فيها 3 بلوكات هتحمل أصول الـ 3 بلوكات دول فقط، حتى لو عندك في لوحة التحكم 200 بلوك مسجلين!

هندسة تنويعات البلوكات (Block Variations) والأنماط الجاهزة (Patterns)

في المعمارية المؤسسية، مش كل ميزة محتاجة إنك تبني لها بلوك جديد بالكامل من الصفر. ووردبريس بيوفر آليتين عبقريتين للتوسع:

• تنويعات البلوكات (Block Variations): زي ما ووردبريس عامل في بلوك الأعمدة (Columns)؛ هو بلوك واحد أساسي، لكن لما تيجي تدرجه بيعرض لك تنويعات: عمودين متساويين (50/50)، أو عمود ثلث وثلثين (33/66). تقدر تعرف Variations خاصة ببلوكك في ملف block.json أو عبر JavaScript بـ registerBlockVariation() لنفس البلوك بقيم افتراضية مختلفة.
• أنماط البلوكات المجمعة (Block Patterns): تسجيل تشكيلات كاملة من عدة بلوكات جاهزة (Header كامل، أو Pricing Section مركب) عبر الدالة النواتية register_block_pattern(). ده بيدي المحررين القدرة على إدراج أقسام كاملة مصممة باحترافية بضغطة زر واحدة دون الحاجة لتثبيت إضافات بناة صفحات خارجية!

التعامل الاحترافي مع الترجمة عبر wp_set_script_translations

عشان تخلي البلوك بتاعك متاح بلغات متعددة (عربي، إنجليزي، فرنسي) في واجهة التحرير، ووردبريس بيوفر الدالة النواتية: wp_set_script_translations( 'my-block-editor-script', 'text-domain', $languages_path );. بفضل معمارية block.json، لو حددت خاصية "textdomain": "my-domain"، ووردبريس بيقوم بربط ملفات الـ JSON المترجمة تلقائياً مع ملف الجافاسكريبت المولد من Webpack، والمحرر بيشوف كل نصوص الواجهة بلغته الأم فوراً بدون أي تدخل يدوي معقد.

التعمق المعماري: معمارية Block Bindings API والتحكم في إلغاء البلوكات النواتية

يا صديقي المطور، في ووردبريس 6.5+ تم إطلاق واحدة من أثور المعماريات في تاريخ النظام: Block Bindings API. الميزة دي بتمكنك من ربط خصائص بلوكات جوتنبرج النواتية (زي Paragraph أو Heading أو Image) ببيانات ديناميكية مباشرة (Custom Post Meta أو استعلامات داتابيز) بدون ما تبني Custom Block كامل بالـ React من الصفر! ببساطة، في ملف الـ PHP بتسجل مصدر البيانات:

<?php
add_action('init', function() {
    register_block_bindings_source('enterprise/client-meta', [
        'label'              => __('بيانات العميل المالية', 'text-domain'),
        'get_value_callback' => function(array $source_args, $block_instance) {
            $post_id = $block_instance->context['postId'] ?? get_the_ID();
            return get_post_meta($post_id, '_client_balance', true);
        },
    ]);
});

وفي المحرر، الكاتب يقدر يربط نص الفقرة بالـ Binding Source ده بضغطة زرار واحدة! البلوك يفضل بلوك Paragraph عادي ونظيف، لكن النص بتاعه بيتولد لحظياً من الداتابيز في السيرفر!

إلغاء تسجيل البلوكات النواتية لتأمين وتوحيد هوية النظام

في المواقع الحكومية والشركات الكبرى، مش مسموح للمحررين إنهم يدرجوا أي بلوك عشوائي يبوظ التصميم (زي بلوك الفيرسات، أو بلوك الشورت كود القديم، أو الأكواد المخصصة). تقدر تلغي تسجيل أي بلوك نواتي من السيرفر تماماً باستخدام: unregister_block_type( 'core/shortcode' );. أو تقيد البلوكات المسموح بها في المحرر بفلتر: allowed_block_types_all. ده بيحول لوحة التحكم لبيئة عمل مؤسسية منضبطة ومنيعة ضد الأخطاء البشرية.

آلية التخزين المؤقت لبيانات block.json في بيئات الإنتاج

تقوم نواة ووردبريس بتخزين نتائج قراءة ملفات block.json في الذاكرة اللحظية عبر Object Cache لتفادي قراءة ملفات القرص مع كل زيارة. لذلك في بيئات الإنتاج، يضمن تفعيل Redis سرعة فائقة في تسجيل واسترجاع تعريفات الكتل دون أي تأخير في وقت استجابة السيرفر.