تحليل بلوكات ووردبريس: التشريح المعماري لدالة parse_blocks دون خلطه بالعرض

يا أهلاً بيك يا هندسة في واحد من أهم دروس الفصل المعماري في ووردبريس الحديث: التشريح العميق لدالة parse_blocks() وفصل طبقة تحليل البيانات عن طبقة العرض. كتير من المطورين لما بيبدأوا يتعاملوا مع محتوى المقالات برمجياً، بيقعوا في خلط كارثي بين “تحليل المحتوى كبيانات” (Content Parsing) وبين “تصيير المحتوى كـ HTML للزائر” (Content Rendering). تلاقيه يفكك المقال بـ parse_blocks() ويحاول يطبع $block['innerHTML'] في الصفحة مباشرة، فيتفاجأ إن البلوكات الديناميكية (زي أحدث المنشورات أو التغريدات المضمنة) طالعة فاضية، وإن التنسيقات والـ CSS طاروا في الهواء! في الدليل العملي المعمق ده، هنفكك كلاس WP_Block_Parser من جوة، نفهم شجرة الـ AST ومصفوفة innerContent، ونبني أدوات تحليل ذكاء محتوى برودكشن حقيقية.

ما هي دالة parse_blocks() وكيف تعمل في النواة؟

دالة parse_blocks( string $content ): array هي البوابة الرسمية في ووردبريس لتحويل النص المسطح لعمود post_content إلى شجرة كائنات برمجية مهيكلة (Abstract Syntax Tree – AST). الدالة دي مبنية فوق كلاس نواتي عملاق اسمه: WP_Block_Parser الموجود داخل wp-includes/class-wp-block-parser.php.

الكلاس ده مش مجرد دالة Regex عادية بتعمل preg_match()! ده عبارة عن State Machine Lexer حقيقي، بيقرا النص حرفاً بحرف، ويتتبع مسار تعليقات الفتح والإغلاق، ويفكك كائنات الـ JSON، وينظم البلوكات المتداخلة (Nested Blocks) في مصفوفات هرمية بدقة وسرعة ميكروثانية دون استهلاك مفرط للرامات.

التشريح التفصيلي للمصفوفة المرجعة من البلوك

لما دالة parse_blocks() بتفكك أي بلوك، بترجع مصفوفة ترابطية بتحتوي على 5 مفاتيح أساسية:

[
    'blockName'    => 'core/paragraph',
    'attrs'        => [
        'fontSize' => 'large'
    ],
    'innerBlocks'  => [],
    'innerHTML'    => '
نص الفقرة
',
    'innerContent' => [
        '
نص الفقرة
'
    ]
]

تعال نفهم دلالة كل مفتاح معمارياً:

• blockName: الاسم البرمجي الفريد للبلوك مسبوقاً بفضاء الاسم (مثل core/heading أو enterprise/pricing-card). إذا كان المحتوى عبارة عن نص كلاسيكي قديم أو مسافات بيضاء بين البلوكات، بيكون المفتاح ده null.
• attrs: مصفوفة الخصائص المخزنة كـ JSON في تعليق البلوك.
• innerBlocks: مصفوفة شجرية بتحتوي على كافة البلوكات المتداخلة التي يحتضنها هذا البلوك.
• innerHTML: كود الـ HTML الثابت للبلوك كاملاً ككتلة نصية واحدة.
• innerContent: مصفوفة خاصة جداً؛ بتقسم الـ HTML لأجزاء وتحط null في الأماكن الدقيقة التي يجب أن يحل فيها كل بلوك من الـ innerBlocks أثناء التصيير.

الفصل المعماري الصارم: التحليل (Parsing) مقابل التصيير (Rendering)

أخطر فخ بيقع فيه المطور هو الخلط بين أدوار الدوال النواتية. تعال نوضح الفرق الحاسم:

1. دور دالة parse_blocks()

وظيفتها: فهم وتحليل البيانات فقط (Data Analysis). تستخدمها لما تحب: 1. تعرف المقال فيه كام صورة أو كام جدول. 2. تستخرج عناوين الـ Headings لإنشاء جدول محتويات تلقائي (TOC). 3. تفحص هل المقال يحتوي على بلوك معين لحقن ملفات أو تشغيل شروط. 4. تعدل خصائص البلوكات برمجياً في الذاكرة قبل حفظها. تحذير قاطع: إياك تطبع مخرجات parse_blocks() للزائر في المتصفح مباشرة!

2. دور دالة render_block() و do_blocks()

وظيفتها: تحويل البيانات لواجهة مرئية للزائر (Visual Presentation). الدالة دي هي اللي بتاخد مصفوفة البلوك من parse_blocks()، وتروح تشغل كود الـ PHP في render_callback، وتطبق فلاتر الألوان والهوامش، وتشغل التضمينات (Embeds)، وتخرج كود الـ HTML النهائي السليم والجاهز للعرض.

مقارنة معمارية شاملة: دوال معالجة محتوى البلوكات في ووردبريس

تطبيق برودكشن متكامل: بناء نظام ذكاء المحتوى واستخراج جدول المحتويات (TOC Engine)

الكود ده بيوضح إزاي تستخدم parse_blocks() بأعلى درجات الاحترافية لبناء نظام تحليل محتوى ذكي: 1. يستخرج جدول محتويات تفاعلي (TOC) من بلوكات العناوين core/heading فقط مع مستويات العناوين الدقيقة. 2. يحسب زمن القراءة الحقيقي (Reading Time) بناءً على الكلمات الصافية لنصوص الفقرات العربية مع استبعاد الأكواد والجداول. 3. يستخرج قائمة الصور المضمنة لإنشاء معرض وسائط تلقائي:

<?php
/**
 * محرك ذكاء المحتوى واستخراج شجرة البلوكات
 * Author: Mohamed Abozaid
 */

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

class Enterprise_Content_Intelligence_Engine {

    /**
     * تحليل المقال واستخراج بيانات جدول المحتويات وزمن القراءة
     */
    public static function analyze_post(int $post_id): array {
        $post = get_post($post_id);
        if (!$post || empty($post->post_content)) {
            return [];
        }

        // 1. تحويل المحتوى إلى شجرة AST دون أي تصيير
        $blocks = parse_blocks($post->post_content);

        $table_of_contents = [];
        $total_words       = 0;
        $image_sources     = [];

        // 2. تتبع البلوكات واستخراج البيانات بذكاء
        self::extract_data_recursive($blocks, $table_of_contents, $total_words, $image_sources);

        // حساب زمن القراءة بالدقائق (متوسط سرعة القراءة العربية 180 كلمة/دقيقة)
        $reading_time_minutes = max(1, (int) ceil($total_words / 180));

        return [
            'post_id'              => $post_id,
            'reading_time_minutes' => $reading_time_minutes,
            'word_count'           => $total_words,
            'headings_toc'         => $table_of_contents,
            'gallery_images'       => $image_sources,
        ];
    }

    /**
     * الغوص التكراري داخل شجرة البلوكات لاستخراج البيانات بدقة
     */
    private static function extract_data_recursive(
        array $blocks, 
        array &$toc, 
        int &$words, 
        array &$images
    ): void {
        foreach ($blocks as $block) {
            $name = $block['blockName'];

            // 1. معالجة بلوكات العناوين وتوليد جدول المحتويات
            if ($name === 'core/heading' && !empty($block['innerHTML'])) {
                $raw_text = trim(strip_tags($block['innerHTML']));
                if (!empty($raw_text)) {
                    $level  = (int) ($block['attrs']['level'] ?? 2);
                    $anchor = !empty($block['attrs']['anchor']) 
                        ? $block['attrs']['anchor'] 
                        : sanitize_title_with_dashes($raw_text);

                    $toc[] = [
                        'title'  => $raw_text,
                        'level'  => $level,
                        'anchor' => $anchor,
                    ];
                }
            }

            // 2. حساب الكلمات للنصوص المكتوبة في الفقرات والقوائم فقط (استبعاد الأكواد)
            if (in_array($name, ['core/paragraph', 'core/list-item', 'core/quote'], true)) {
                if (!empty($block['innerHTML'])) {
                    $clean_text = trim(strip_tags($block['innerHTML']));
                    $words += count(preg_split('/s+/u', $clean_text, -1, PREG_SPLIT_NO_EMPTY));
                }
            }

            // 3. استخراج صور المقال
            if ($name === 'core/image' && !empty($block['attrs']['url'])) {
                $images[] = [
                    'url' => esc_url_raw($block['attrs']['url']),
                    'alt' => sanitize_text_field($block['attrs']['alt'] ?? ''),
                ];
            }

            // 4. الغوص في البلوكات المتداخلة (Columns, Groups, Covers)
            if (!empty($block['innerBlocks'])) {
                self::extract_data_recursive($block['innerBlocks'], $toc, $words, $images);
            }
        }
    }
}

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

بص يا صديقي على النظافة والاحترافية المعمارية في الكود ده:

• صفر Regex للأكواد والعناوين: مفيش سطر واحد مستخدم preg_match('/<h2>(.*)</h2>/')! لأن التعبير النمطي ده كان هيغلط لو المحرر كاتب كود برمجي جواه وسم <h2> أو لو العنوان واخد كلاسات معقدة. باستخدام parse_blocks()، إحنا بنفحص $block['blockName'] === 'core/heading' صراحة، وبناخد مستوى العنوان level من الـ attrs بدون تخمين!
• الحساب الدقيق لزمن القراءة للغة العربية: استبعدنا بلوكات الأكواد البرمجية (core/code) وبلوكات الـ HTML المخصص؛ لأنها مش نصوص مقروءة بنفس السرعة، واعتمدنا على PREG_SPLIT_NO_EMPTY مع دعم الـ Unicode /u عشان يقسم الكلمات العربية بدقة متناهية ويطلع زمن قراءة حقيقي يفيد القارئ.
• عدم لمس طبقة العرض (Pure Analysis): الكود ده مبيطبعش ولا سطر HTML على الشاشة، ومبيشغلش أي فلاتر ثقيلة؛ هو مجرد دالة تحليلية نقية تقدر تستخدمها في الـ REST API، أو تحفظ نتيجتها في Post Meta، أو تعرضها في تطبيق الموبايل بمرونة كاملة.

preg_match_all('/(.*?)/i', $content, $matches);

الوصايا العشر للتعامل مع دالة parse_blocks()

1. لا تخلط التحليل بالعرض (Keep Analysis Decoupled): استخدم parse_blocks() لقراءة ومعالجة البيانات فقط، واترك مهمة العرض لـ render_block() أو do_blocks().
2. تجنب استخدام التعبيرات النمطية (Regex) على المحتوى: اعتمد دائماً على شجرة الـ AST المرجعة من المحلل النواتي لضمان الدقة والسرعة.
3. تعامل مع البلوكات ذات الـ blockName === null: تذكر أن النصوص الكلاسيكية والمسافات البيضاء ترجع باسم فارغ، فلا تهمل معالجتها.
4. اغوص تكرارياً في innerBlocks: البلوكات الحديثة متداخلة (Nested)؛ أي دالة فحص يجب أن تتبع البلوكات الفرعية لضمان الشمولية.
5. خزن نتائج التحليل المكلفة في الكاش: إذا كنت تستخرج إحصائيات أو جدول محتويات، احفظ النتيجة في Transient ولا تكرر التحليل في كل زيارة.
6. استخدم has_blocks() كفحص مبكر: قبل استدعاء parse_blocks()، تأكد من أن المقال يحتوي على بلوكات لتوفير وقت المعالج في المقالات الكلاسيكية.
7. احترم اللغة والترميز في حساب الكلمات: استخدم preg_split('/s+/u', ...) مع مفتاح الـ Unicode لدعم الكلمات العربية بدقة.
8. لا تعتمد على innerHTML للبلوكات الديناميكية: تذكر أن البلوكات الديناميكية تخزن innerHTML فارغاً، وبياناتها موجودة في attrs.
9. طهر العناوين والـ Anchors: عند توليد روابط القفز (Jump Links) في جدول المحتويات، تأكد من تعقيمها بـ sanitize_title().
10. اختبر الدالة مع المقالات العملاقة: اختبر أدواتك التحليلية مع مقالات تتجاوز 10,000 كلمة للتأكد من كفاءة استهلاك الذاكرة.

التعمق المعماري: خوارزمية الـ Lexer وتتبع المؤشرات في WP_Block_Parser

يا صديقي المطور، عشان تفهم العبقرية الهندسية وراء كلاس WP_Block_Parser، لازم نبص على كود ملف class-wp-block-parser.php في النواة: الكلاس ده مبيعتمدش على تعبيرات نمطية عشوائية زي ما كتير من المطورين متخيلين؛ هو شغال بنظام State-Machine Tokenizer بيعتمد على تتبع مؤشرات الإزاحة (Byte Offsets):

1. حالة البحث عن البداية (Token Scanning): المحلل بيمشي على النص ويدور على الرمز الافتتاحي <!-- wp: عبر تعبير نمطي محكم جداً وخفيف ومُختبر على ملايين الحالات.
2. استخراج الـ Namespace واسم البلوك: بيفصل البادئة (مثلاً core/ أو woocommerce/) عن اسم المورد.
3. تحليل كتلة الـ JSON المحمولة (JSON Extraction): بيمشي على النص بعد اسم البلوك؛ لو لقى قوس معقوف {، بيبحث عن القوس المقابل له ويفكك الـ JSON بـ json_decode()، ويخزن الـ Attributes الناتجة.
4. حساب الإزاحة (Offset Calculation): بيسجل بدقة متناهية مكان بداية كود الـ HTML ونهايته.
5. إدارة مكدس التداخل (Stack of Open Blocks): لو البلوك مفتوح (له تعليق إغلاق <!-- /wp: -->)، المحلل بيحط البلوك في الـ Stack، ويبدأ يحلل البلوكات الفرعية اللي جواه، ومبيخرجش البلوك من المكدس إلا لما يلاقي تعليق الإغلاق المطابق له تماماً!

النظام ده بيخلي ووردبريس يقدر يحلل مقال فيه 500 بلوك متداخل في أقل من 4 مللي ثانية!

بناء محولات البلوكات لمعمارية Headless WordPress (AST to Clean JSON)

في بيئات الـ Headless المبنية بـ React و Next.js و Mobile Apps، تطبيقات الفرونت إند مش عايزة كود HTML خام عشان تعرضه بـ dangerouslySetInnerHTML؛ التطبيقات دي عايزة Structured JSON Data! هنا بتظهر القوة الحقيقية لـ parse_blocks(): تقدر تبني Rest API Endpoint مخصصة بتمرر المحتوى على parse_blocks()، وبعدين تحول مصفوفات البلوكات إلى كائنات JSON نظيفة ومجردة:

<?php
/**
 * محول البلوكات إلى JSON نقي لتطبيقات الموبايل
 */
function enterprise_transform_blocks_for_mobile(string $raw_content): array {
    $parsed_blocks = parse_blocks($raw_content);
    $clean_tree    = [];

    foreach ($parsed_blocks as $block) {
        if (empty($block['blockName'])) {
            continue; // تجاهل المسافات الفارغة والنصوص الكلاسيكية
        }

        $node = [
            'type'       => $block['blockName'],
            'attributes' => $block['attrs'],
        ];

        // استخراج المحتوى النقي بناءً على نوع البلوك
        switch ($block['blockName']) {
            case 'core/paragraph':
                $node['text'] = wp_strip_all_tags($block['innerHTML']);
                break;

            case 'core/heading':
                $node['text']  = wp_strip_all_tags($block['innerHTML']);
                $node['level'] = $block['attrs']['level'] ?? 2;
                break;

            case 'core/image':
                $node['media'] = [
                    'url'    => $block['attrs']['url'] ?? '',
                    'alt'    => $block['attrs']['alt'] ?? '',
                    'width'  => $block['attrs']['width'] ?? null,
                    'height' => $block['attrs']['height'] ?? null,
                ];
                break;

            case 'core/quote':
                $node['quote_text'] = wp_strip_all_tags($block['innerHTML']);
                break;
        }

        // معالجة البلوكات المتداخلة تكرارياً
        if (!empty($block['innerBlocks'])) {
            $node['children'] = enterprise_transform_blocks_for_mobile(
                serialize_blocks($block['innerBlocks'])
            );
        }

        $clean_tree[] = $node;
    }

    return $clean_tree;
}

المحول المعماري ده بيمنح مطوري Flutter و Swift و React Native القدرة على رسم واجهات أصلية (Native Components) في التطبيق، مع الاستفادة الكاملة من محرر ووردبريس كلوحة إدارة محتوى عالمية.

تطهير وتعقيم المحتوى على مستوى شجرة الـ AST

من المزايا الأمنية الجبارة للتعامل مع parse_blocks() هي القدرة على تنفيذ AST-Level Content Sanitization: تخيل لو موقعك بيسمح لمستخدمين برتبة “محرر مساهم” (Contributor) بنشر مقالات، وأنت خايف إن محرر منهم يحقن وسوم <script> خبيثة أو بلوكات HTML مخصصة غير مصرح بها. بدل ما تشغل فلاتر معقدة على النصوص، أنت ببساطة بتفكك المقال بـ parse_blocks()، وتلف على المصفوفة وتعمل unset() لأي بلوك نوعه core/html أو أي بلوك مخصص غير مسجل في القائمة البيضاء (Whitelisted Blocks)، ثم تعيد تسلسل المقال بـ serialize_blocks()! ده بيقضي تماماً على ثغرات الـ Stored XSS ويوفر أماناً حاسماً للمنصات الكبيرة.

التعمق المعماري: ربط parse_blocks بمحركات البحث وفهرسة النصوص (ElasticSearch & Algolia)

يا صديقي المطور، من أقوى التطبيقات المؤسسية لدالة parse_blocks() هي تغذية محركات البحث الذكية وفهرسة المحتوى (Enterprise Search Indexing): المواقع الكبيرة بتستخدم محركات بحث خارجية زي ElasticSearch أو Algolia أو Meilisearch. المطور المبتدئ بياخد نص post_content الخام ويبعته للمحرك، فالمحرك بيفهرس تعليقات الـ JSON والـ HTML Tags والرموز المشفرة، والنتيجة إن المستخدم لما يبحث عن كلمة تطلع له نتائج مشوهة! الطريقة المعمارية الاحترافية: عند إطلاق خطاف save_post، بنمرر المحتوى على parse_blocks(): 1. نستخرج العناوين الرئيسية بوزن بحثي مرتفع (High Search Weight). 2. نستخرج نصوص الفقرات والقوائم الصافية عبر wp_strip_all_tags(). 3. نستخرج وسوم الـ Alt لجميع الصور المضمنة لتمكين البحث في الصور. 4. نستبعد تماماً كتل الكود البرمجي والإعلانات من الفهرسة لتفادي تلوث نتائج البحث.

النتيجة هي كائن JSON مفهرس وموزون بدقة هندسية متناهية، بيخلي محرك البحث يرجع نتائج مطابقة بدقة 100% في أقل من 5 مللي ثانية، وده اللي بينقل تجربة التصفح في المنصات الضخمة لمستوى الشركات التكنولوجية العالمية.

إدارة الذاكرة في عمليات المعالجة الدفعية الكبرى (Batch CLI Processing)

يا صديقي المطور، عند تشغيل سكريبتات WP-CLI لمعالجة مئات الآلاف من المقالات باستخدام parse_blocks()، ممكن تواجه مشكلة تسريب الذاكرة (Memory Leak). الحل المعماري الحاسم: بعد معالجة كل دفعة من 100 مقال، يجب تفريغ مصفوفات البلوكات في الذاكرة عبر unset($blocks)، وإطلاق جامع القمامة في PHP عبر استدعاء gc_collect_cycles()، وتفريغ كاش النواة بـ wp_cache_flush(). هذا الانضباط الهندسي يضمن بقاء استهلاك الرامات ثابتاً ومستقراً تحت 50 ميجابايت حتى لو كان السكريبت يعالج مليون مقال دفعة واحدة دون أي انهيار.