حفظ بلوكات Gutenberg: كواليس الـ Serialization وتعليقات الـ HTML في قاعدة البيانات

يا أهلاً بيك يا هندسة في واحد من أعمق دروس الهندسة الداخلية لنواة ووردبريس الحديث: كواليس عملية الـ Serialization وتسلسل تعليقات البلوكات في قاعدة البيانات. لما الكاتب يخلص كتابة مقال طويل في جوتنبرج ويضغط زرار “حفظ المسودة” أو “نشر”، إيه اللي بيحصل في أجزاء الألف من الثانية خلف الستار؟ شجرة مكونات React المعقدة والـ DOM Nodes اللي في متصفحك بتتحول لسلسلة نصية واحدة (Serialized String) بيتم تخزينها في عمود post_content داخل جدول wp_posts. الطريقة اللي ووردبريس بيعمل بيها التسلسل ده (Gutenberg Grammar Specification) كانت محل نقاشات هندسية عالمية استمرت لسنين بين كبار مهندسي الويب. في الدليل العملي المعمق ده، هنشرح قواعد النحو البرمجي لتعليقات البلوكات، نفكك دوال serialize_blocks() في PHP و JavaScript، ونعرف إزاي نعدل ونسلسل البلوكات برمجياً بدون ما نكسر كود المقال أو نقع في فخ الـ Broken Blocks.

ما هي عملية الـ Serialization في جوتنبرج؟

في علوم الحاسب، الـ Serialization (التسلسل) هو عملية تحويل هياكل البيانات المعقدة والكائنات الموجودة في الذاكرة (In-Memory Objects) إلى صيغة نصية أو ثنائية (Format) يسهل تخزينها في ملف أو قاعدة بيانات أو إرسالها عبر الشبكة، مع إمكانية استعادتها لاحقاً (Deserialization). في ووردبريس، قبل جوتنبرج، المقال كان عبارة عن نص HTML مسطح، وكان المطورين بيعتمدوا على الـ Shortcodes زي لتمثيل العناصر المعقدة. المشكلة في الـ Shortcodes كانت: 1. بطيئة جداً في الفك لأنها بتعتمد على Regex معقد في كل زيارة لصفحة المقال. 2. عرضة للتكسير وتداخل الأقواس [[shortcode]]. 3. ملهاش معيار قياسي موحد للبيانات (Schema).

عشان يحلوا المشكلة دي، مهندسو ووردبريس صمموا Gutenberg Grammar؛ نظام تسلسل بيعتمد على تعليقات الـ HTML المهيكلة لتعريف حدود البلوكات وبياناتها الوصفية، مع وضع ناتج كود الـ HTML الدلالي بداخلها مباشرة.

القواعد النحوية لتسلسل البلوكات (Gutenberg Grammar Specification)

تعليقات البلوكات في ووردبريس بتخضع لقواعد نحوية صارمة جداً (Formal Grammar). تعال نفصص الأنماط الأساسية:

1. البلوك المفتوح ذو المحتوى (Block with Inner Content)

<!-- wp:namespace/block-name {"attrKey":"value"} -->
<div class="wp-block-namespace-block-name">
    <p>المحتوى الظاهر للزائر في المتصفح</p>
</div>
<!-- /wp:namespace/block-name -->

لاحظ التركيب:

• يبدأ بتعليق فتح: <!-- wp: متبوعاً بفضاء الاسم واسم البلوك.
• يليه كائن JSON اختياري محاط بأقواس معقوفة {...} بيحتوي على الخصائص (Comment Attributes).
• ينتهي تعليق الفتح بـ -->.
• يأتي بعده كود الـ HTML الذي تم توليده بواسطة دالة save.js أو render.php.
• ينتهي بتعليق إغلاق صريح: <!-- /wp:namespace/block-name -->.

2. البلوكات ذاتية الإغلاق (Void / Self-Closing Blocks)

لو البلوك ديناميكي (Dynamic Block) ومبيخزنش أي كود HTML في الداتابيز، أو كان بلوك فاصل (زي فاصل الصفحات أو الفاصل الزمني):

<!-- wp:core/separator {"className":"is-style-wide"} /-->

بينتهي بـ /--> مباشرة دون الحاجة لتعليق إغلاق منفصل، مما يوفر مساحة تخزينية إضافية.

3. البلوكات المتداخلة (Nested Tree Serialization)

لو عندك بلوك أعمدة (Columns) وجواه عمودين وكل عمود جواه فقرة، التسلسل بيمشي بنظام شجري متداخل (Tree Hierarchy):

<!-- wp:columns -->
<div class="wp-block-columns">
    <!-- wp:column -->
    <div class="wp-block-column">
        <!-- wp:paragraph -->
        <p>نص العمود الأول</p>
        <!-- /wp:paragraph -->
    </div>
    <!-- /wp:column -->
</div>
<!-- /wp:columns -->

تفكيك محرك الـ Serializer في JavaScript و PHP

عملية الـ Serialization بتتم في بيئتين مختلفتين داخل ووردبريس:

1. في الفرونت إند ولوحة التحكم (JavaScript via @wordpress/blocks)

لما الكاتب يضغط “حفظ”، ووردبريس بيستدعي دالة serialize():

import { serialize } from '@wordpress/blocks';

const blocks = wp.data.select('core/block-editor').getBlocks();
const postContent = serialize(blocks);

الدالة دي بتلف على كل كائن بلوك في شجرة الـ AST، وتستدعي دالة save(attributes) لتوليد كود الـ HTML، وتدمج الـ Attributes غير المستخرجة من الـ DOM في تعليق البلوك كـ JSON، وتطبع النص المتسلسل النهائي ليتم إرساله في ريكوست الـ REST API إلى السيرفر.

2. في الباك إند (PHP via wp-includes/blocks.php)

لو أنت بتكتب كود إضافة أو سكريبت CLI بيعدل المحتوى على السيرفر، ووردبريس بيوفر دوال النواة: serialize_blocks( array $blocks ): string و serialize_block( array $block ): string. الدالة دي بتاخد مصفوفة البلوكات الناتجة من parse_blocks() وتعيد تحويلها لنص التعليقات القياسي.

مقارنة معمارية شاملة: طرق تسلسل وتخزين المحتوى في أنظمة إدارة المحتوى

تطبيق برودكشن متكامل: بناء أداة فك وتعديل وإعادة تسلسل المقالات برمجياً

الكود ده بيوضح إزاي تبني سكريبت معالجة مؤسسي آمن، بيقرأ محتوى أي مقال في ووردبريس، ويفك تسلسله بـ parse_blocks()، ويبحث عن كل الروابط القديمة أو أزرار الـ CTA ويعدل خصائصها برمجياً، ثم يعيد تسلسلها بأمان تام عبر serialize_blocks() ويحفظ المقال في الداتابيز:

<?php
/**
 * أداة تسلسل وتعديل محتوى البلوكات برمجياً بأمان تام
 * Author: Mohamed Abozaid
 */

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

class Enterprise_Block_Content_Processor {

    /**
     * تحديث روابط وأزرار المقال وإعادة التسلسل بأمان
     */
    public static function update_cta_links_in_post(int $post_id, string $old_url, string $new_url): bool {
        $post = get_post($post_id);
        if (!$post || empty($post->post_content)) {
            return false;
        }

        // إذا كان المقال لا يحتوي على بلوكات جوتنبرج، نتجاوز
        if (!has_blocks($post->post_content)) {
            return false;
        }

        // 1. فك تسلسل كود الـ HTML إلى شجرة كائنات AST مهيكلة
        $blocks = parse_blocks($post->post_content);

        $has_modifications = false;

        // 2. معالجة وتعديل شجرة البلوكات تكرارياً (Recursive Modification)
        self::traverse_and_modify_blocks($blocks, $old_url, $new_url, $has_modifications);

        if (!$has_modifications) {
            return false; // لم يتم العثور على روابط تتطلب التعديل
        }

        // 3. إعادة تسلسل شجرة البلوكات المعدلة إلى كود Gutenberg Grammar رسمي
        $serialized_content = serialize_blocks($blocks);

        // 4. حفظ المحتوى المحدث في قاعدة البيانات النواتية
        $updated = wp_update_post([
            'ID'           => $post_id,
            'post_content' => $serialized_content,
        ]);

        return ($updated !== 0 && !is_wp_error($updated));
    }

    /**
     * تتبع وتعديل كائنات البلوكات المتداخلة تكرارياً
     */
    private static function traverse_and_modify_blocks(
        array &$blocks, 
        string $old_url, 
        string $new_url, 
        bool &$modified
    ): void {
        foreach ($blocks as &$block) {
            // فحص بلوكات الأزرار النواتية (Core Buttons)
            if ($block['blockName'] === 'core/button') {
                if (!empty($block['attrs']['url']) && str_contains($block['attrs']['url'], $old_url)) {
                    // تعديل الخاصية في الـ Attributes
                    $block['attrs']['url'] = str_replace($old_url, $new_url, $block['attrs']['url']);

                    // تعديل الخاصية في كود الـ HTML المحفوظ
                    if (!empty($block['innerHTML'])) {
                        $block['innerHTML'] = str_replace($old_url, $new_url, $block['innerHTML']);
                    }
                    if (!empty($block['innerContent'])) {
                        foreach ($block['innerContent'] as &$content_part) {
                            if (is_string($content_part)) {
                                $content_part = str_replace($old_url, $new_url, $content_part);
                            }
                        }
                    }

                    $modified = true;
                }
            }

            // فحص الروابط العادية المضمنة داخل الفقرات
            if ($block['blockName'] === 'core/paragraph' && !empty($block['innerHTML'])) {
                if (str_contains($block['innerHTML'], $old_url)) {
                    $block['innerHTML'] = str_replace($old_url, $new_url, $block['innerHTML']);
                    if (!empty($block['innerContent'])) {
                        foreach ($block['innerContent'] as &$part) {
                            if (is_string($part)) {
                                $part = str_replace($old_url, $new_url, $part);
                            }
                        }
                    }
                    $modified = true;
                }
            }

            // الغوص في البلوكات المتداخلة (Columns, Groups, Covers)
            if (!empty($block['innerBlocks'])) {
                self::traverse_and_modify_blocks($block['innerBlocks'], $old_url, $new_url, $modified);
            }
        }
    }
}

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

ركز معايا يا صديقي في النقاط المعمارية الحساسة جداً في الكود ده:

• التعديل المتزامن على attrs و innerHTML و innerContent: لو بصيت في الكود، هتلاقينا لما بنغير الرابط بنغيره في التلات أماكن مع بعض! ليه؟ لأن لو غيرته في attrs وسبت innerHTML برابط قديم، المحرر أول ما يفتح المقال هيكتشف عدم التطابق ويرمي فوراً خطأ Block Invalidation! الاتساق التام بين مصفوفة الخصائص ومخرجات الـ HTML هو مفتاح الأمان عند إعادة التسلسل.
• استخدام الدالة النواتية serialize_blocks(): مجمعناش النصوص بـ implode() ولا كتبنا تعليقات الـ HTML بإيدينا؛ سلمنا المصفوفة للدالة الرسمية في ووردبريس. هي اللي بتتكفل بحساب الفراغات البيضاء (Whitespace Indentation)، وكتابة أقواس تعليقات الفتح والإغلاق بدقة متناهية، والتأكد من إغلاق البلوكات ذاتية الإغلاق بالشكل السليم.
• التتبع التكراري الآمن للبلوكات المتداخلة: استدعاء traverse_and_modify_blocks لنفسها مع $block['innerBlocks'] بيضمن إنك لو عندك زرار جوة عمود، والعمود جوة جروب، والجروب جوة سيكشن مخصص، الكود هيوصل له ويعدله بدون ما يسيب أي جزء مفقود.

UPDATE wp_posts 
SET post_content = REPLACE(post_content, 'cdn-old.portal.eg', 'media.portal.eg');

الوصايا العشر للتعامل مع تسلسل بلوكات ووردبريس

1. إياك واستخدام استعلامات SQL REPLACE المباشرة: لا تعدل محتوى post_content باستعلامات مباشرة دون فك وتسلسل البلوكات عبر دوال النواة.
2. استخدم serialize_blocks() دائماً في PHP: هي الطريقة الرسمية والمعيارية الوحيدة لتوليد تعليقات البلوكات المطابقة لقواعد النواة.
3. حافظ على الاتساق بين attrs و innerHTML: عند تعديل خاصية برمجياً تؤثر على الـ HTML، يجب تحديث كود الـ HTML الموازي لمنع أخطاء التحقق.
4. احترم قواعد المسافات البيضاء (Whitespace Significance): لا تقم بعمل trim() عشوائي لكود الـ HTML الداخلي للبلوك لتفادي تشويه المسافات بين الكلمات.
5. لا تعدل أقواس تعليقات البلوكات يدوياً: أي خطأ في وسم <!-- wp: --> سيحول البلوك بالكامل إلى كود كلاسيكي غير قابل للتحرير.
6. تأكد من إغلاق البلوكات ذاتية الإغلاق بـ /-->: البلوكات التي ليس لها محتوى داخلي يجب أن تنتهي بالشرطة المائلة لتوفير المساحة وتجنب التداخل.
7. استخدم الـ JSON السليم والخالي من أخطاء الـ Escaping: تأكد من أن أي قيم نصية تحتوي على علامات تنصيص يتم ترميزها بشكل صحيح في كائن الخصائص.
8. عالج البلوكات المتداخلة تكرارياً (Recursively): تأكد من فحص شجرة innerBlocks بالكامل عند إجراء أي عمليات بحث واستبدال جماعية.
9. اختبر المقالات المعدلة بفتحها في لوحة التحكم: بعد تشغيل أي سكريبت تسلسل دفعي (Batch Script)، افتح عينات من المقالات للتأكد من عدم ظهور تحذيرات الـ Invalidation.
10. احرص على أخذ نسخة احتياطية كاملة قبل أي تعديل تسلسلي: العمليات على عمود post_content حساسة جداً وتتطلب دائماً وجود نقطة استعادة فورية.

التعمق المعماري: الفرق الجوهري بين serialize_blocks و render_block

يا صديقي المطور، من أكتر الأخطاء المعمارية الشائعة بين المطورين هي الخلط بين وظيفة serialize_blocks() ووظيفة render_block(): كتير من المطورين بيفتكروا إن الدالتين بيعملوا نفس الحاجة، لكن الحقيقة المعمارية مختلفة تماماً:

• دالة serialize_blocks() (وظيفتها التخزين والأرشفة): وظيفتها الأساسية هي إعادة تشكيل نص الـ Gutenberg Grammar عشان يتحفظ في الداتابيز! الدالة دي بتاخد شجرة الـ AST وبتحط تعليقات البلوكات <!-- wp: --> وتحقن الـ JSON Attributes. هي مبيفهمهاش ولا بيحتاجها المتصفح؛ هي مخصصة لعمود post_content في MySQL عشان لما المحرر يفتح المقال تاني يقدر جوتنبرج يفككها.
• دالة render_block() (وظيفتها العرض للزائر): وظيفتها هي التصيير النهائي لكود الـ HTML اللي الزائر هيشوفه في المتصفح! الدالة دي بتشيل كل تعليقات البلوكات، وبتشغل دوال render_callback للبلوكات الديناميكية، وبتطبق فلاتر the_content، وتخرج كود HTML خالص ونظيف تماماً بدون أي أثر لتعليقات جوتنبرج!

لو أنت بتبني سكريبت بيعدل محتوى المقال ويحفظه في الداتابيز، لازم تستخدم serialize_blocks(). لو استخدمت render_block() وخزنت الناتج في الداتابيز، أنت كده مسحت تعليقات البلوكات وحولت مقالك لبلوك كلاسيكي ميت يستحيل تحريره في جوتنبرج مرة تانية!

التعامل مع التعليقات المشوهة وتطهير التسلسل

في حالات استيراد المقالات من أنظمة خارجية (زي ووردبريس قديم، أو استيراد محتوى من منصات زي Medium أو Drupal)، ساعات بتوصل تعليقات بلوكات مشوهة أو أقواس ناقصة زي: <!-- wp:paragraph {"fontSize": -->. نواة ووردبريس مزودة بخوارزمية فحص تراجع (Fallback Parser) في ملف class-wp-block-parser.php: إذا اكتشف المحلل النواتي أن تعليق البلوك لا يتطابق مع الـ Formal Grammar، لا يرمي Fatal Error ولا يوقف إقلاع الصفحة؛ بدلاً من ذلك، يقوم بتغليف النص المشوه بالكامل كـ Freeform Classic HTML، ويعرضه للزائر بأمان، مع إتاحة خيار “تحويل إلى بلوكات” للمحرر عند فتح المقال لتصحيح الخطأ يدوياً دون أي فقد للمحتوى.

التعمق المعماري: إدارة الترميز العالمي (UTF-8 / Unicode) في تعليقات البلوكات

يا صديقي المطور، عند التعامل مع المحتوى العربي أو النصوص التي تحتوي على إيموجي (Emojis) وتشكيل لغوي معقد، دالة serialize_blocks() بتعتمد داخلياً على دالة wp_json_encode(): الدالة دي بتضمن تشفير المحارف غير اللاتينية بخاصية JSON_UNESCAPED_UNICODE و JSON_UNESCAPED_SLASHES افتراضياً إذا كانت مدعومة. ده بيخلي الـ JSON داخل تعليق البلوك مقروءاً ونقياً: <!-- wp:paragraph {"content":"أهلاً بكم"} --> بدلاً من السلاسل الطويلة البشعة مثل u0623u0647u0644u0627! هذا التنسيق الدقيق مش بس بيوفر مساحة التخزين في عمود post_content بنسبة تتجاوز 40% للنصوص العربية، بل يتيح لمسؤولي قواعد البيانات ومطوري الـ DevOps قراءة سجلات التعديل (Audit Logs) وفحص المحتوى مباشرة دون الحاجة لأدوات فك تشفير إضافية.