ترحيل البلوكات القديمة: معمارية Deprecation و migrate دون فقد المحتوى

أهلاً بيك يا صديقي المطور في أرقى وأهم مهارة هندسية بيحتاجها أي مطور ووردبريس بيبني مشاريع بتعيش لسنين طويلة: معمارية ترحيل البلوكات وتطويرها (Block Deprecation and Migration Architecture).

أي كود برمجي بتكتبه النهاردة مصيره يتغير بكرة: العميل هيطلب يضيف زرار جديد للبلوك، فريق الـ UI/UX هيقرر يغير كلاسات الـ CSS أو يستبدل وسم <div> بوسم دلالي <section>، أو حتى هتقرر تعيد تنظيم الخصائص (Attributes Schema) من نصوص عادية لكائنات معقدة. في البرمجة العادية، بتعدل الكود وخلاص؛ لكن في عالم ووردبريس ومحرر Gutenberg، التعديل ده لو اتعمل بشكل عشوائي ومباشر بيعني “انتحار برمجي” فوري! ليه؟ لإن آلاف المقالات اللي اتنشرت بالبنية القديمة هتضرب فوراً وتطلع رسالة الخطأ الكارثية Block Validation Error.

الحل العبقري اللي وفرته نواة ووردبريس هو مصفوفة deprecated ودالة migrate(). المنظومة دي بتمكنك من تطوير البلوك لـ 10 أجيال مختلفة (v1, v2, v3… إلخ) بدون ما تكسر مقال قديم واحد، مع ترقية المحتوى القديم للهيكل الجديد تلقائياً في صمت تام وبدون أدنى تدخل بشري. في الدليل الشامل ده، هنفكك المعمارية التحتية للـ Deprecation، إزاي تبني دوال الترحيل، إزاي تستخدم isEligible() لمنع تداخل الإصدارات، ودراسة حالة حقيقية لشبكة إخبارية مصرية عملاقة بالعامية المصرية التقنية الأصيلة.

كيف تفكر نواة ووردبريس؟ دورة حياة ترحيل البلوكات (The Migration Cascade)

عشان تكتب كود ترحيل مظبوط، لازم تفهم الخوارزمية اللي محرر جوتنبرج بيمشي عليها لما يفتح أي مقال في لوحة التحكم:

1. فحص الكود الحالي أولاً:

   جوتنبرج بياخد محتوى البلوك المحفوظ في قاعدة البيانات، ويقارنه بدالة save() الحالية (النسخة الأحدث وليكن v3). لو متطابق، بيفتح البلوك ومبيعملش أي حاجة تانية.

2. تنشيط مصفوفة الترحيل (The Deprecation Array Loop):

   لو حصل عدم تطابق، المحرر مبيطلعش خطأ فوراً! بيبص على مصفوفة deprecated. المصفوفة دي بتكون مترتبة زمنياً من الأحدث للأقدم (v2 ثم v1). بيبدأ يمسك أول عنصر في المصفوفة ويجرب يطابق كود الـ HTML المحفوظ مع دالة save() القديمة الخاصة بالنسخة دي.

3. التحقق الذكي عبر isEligible():

   لو وفرت دالة isEligible( attributes, innerBlocks )، جوتنبرج بيشغلها الأول؛ لو رجعت true بيكمل الفحص، لو رجعت false بيتجاوز النسخة دي فوراً ويروح للي بعدها، وده بيمنع أي تطابق خاطئ بين نسخ متقاربة.

4. تنفيذ السحر: دالة migrate():

   أول ما يلاقي النسخة القديمة المطابقة (مثلاً لقى المقال ده مكتوب بنسخة v1)، بيشغل فوراً دالة migrate( attributes, innerBlocks ) المعرفة في نفس كائن الـ Deprecation. الدالة دي وظيفتها تحول الخصائص القديمة للخصائص الجديدة للنسخة الأحدث (v3).

5. الترقية الصامتة والحفظ (Silent In-Memory Upgrade):

   البلوك بيفتح قدام الكاتب في المحرر وهو محدث للنسخة v3 بدون أي رسائل تحذير أو أزرار Recover! وأول ما الكاتب يضغط “تحديث المقال” (Update)، ووردبريس بيحفظ البلوك في قاعدة البيانات بالهيكل الجديد v3 للأبد، وبكده تمت عملية الترقية بسلام تام!

تطبيق عملي كامل: ترحيل بلوك بطاقة الخدمات عبر 3 أجيال (v1 -> v2 -> v3)

تعال نبني مثالاً إنتاجياً حقيقياً لبلوك كارت تسويقي (enterprise/service-card) مر بثلاث مراحل تطوير على مدار عامين في إحدى الشركات:

• الجيل الأول (v1): كارت بسيط فيه عنوان ونص فقط، بدون أزرار أو ألوان.
• الجيل الثاني (v2): تمت إضافة زر رابط (CTA Button) مع تغيير كلاس الـ Wrapper.
• الجيل الثالث (v3 – الحالي): تم تحويل البلوك لحاوية تدعم أيقونة مخصصة وتنسيقات ألوان حديثة مع دمج الخصائص داخل كائن منظم.

1. ملف تعريف البلوك الحديث: block.json (الإصدار الحالي v3)

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/service-card",
  "version": "3.0.0",
  "title": "بطاقة الخدمة المتقدمة",
  "category": "design",
  "icon": "star-filled",
  "attributes": {
    "title": {
      "type": "string",
      "default": ""
    },
    "description": {
      "type": "string",
      "default": ""
    },
    "buttonData": {
      "type": "object",
      "default": {
        "text": "اكتشف المزيد",
        "url": "#",
        "target": "_self"
      }
    },
    "cardTheme": {
      "type": "string",
      "default": "primary"
    }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

2. كود الحفظ الحالي: save.js (الجيل الثالث v3)

import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function save( { attributes } ) {
    const { title, description, buttonData, cardTheme } = attributes;
    const blockProps = useBlockProps.save( {
        className: `az-service-card az-theme-${ cardTheme } az-version-3`
    } );

    return (
        

            

                
            
            

                
            
            { buttonData?.url && (
                

                    
                        { buttonData.text }
                    
                
            ) }
        
    );
}

3. ملف الترحيل الشامل: deprecated.js (تاريخ الأجيال السابقة)

/**
 * ملف deprecated.js: يحتوي على سجل التغييرات التاريخية للبلوك
 * يتم سرد الإصدارات القديمة من الأحدث إلى الأقدم
 */
import { useBlockProps, RichText } from '@wordpress/block-editor';

const deprecated = [
    // ==========================================
    // الجيل الثاني (v2): كان يحتوي على زر منفصل كخاصيتين buttonText و buttonUrl
    // وكان يستخدم وسم div بدلاً من section
    // ==========================================
    {
        attributes: {
            title: { type: 'string', default: '' },
            description: { type: 'string', default: '' },
            buttonText: { type: 'string', default: 'المزيد' },
            buttonUrl: { type: 'string', default: '#' },
        },
        // فحص هل البلوك ينتمي لهذا الجيل (يمتلك buttonUrl كخاصية نصية منفصلة)
        isEligible( attributes ) {
            return typeof attributes.buttonUrl === 'string' && ! attributes.buttonData;
        },
        // دالة الترحيل: تحويل buttonText و buttonUrl إلى كائن buttonData المنظم
        migrate( attributes ) {
            return {
                title: attributes.title,
                description: attributes.description,
                cardTheme: 'primary', // القيمة الافتراضية للخاصية الجديدة في v3
                buttonData: {
                    text: attributes.buttonText || 'اكتشف المزيد',
                    url: attributes.buttonUrl || '#',
                    target: '_self',
                },
            };
        },
        // كود الـ HTML كما كان يُحفظ بالضبط في إصدار v2
        save( { attributes } ) {
            const { title, description, buttonText, buttonUrl } = attributes;
            const blockProps = useBlockProps.save( {
                className: 'az-service-card az-version-2'
            } );

            return (
                

                    
                    
                    { buttonUrl && (
                        

                            { buttonText }
                        
                    ) }
                
            );
        },
    },

    // ==========================================
    // الجيل الأول (v1): البلوك البدائي خالص بدون أي أزرار وبكلاسات قديمة
    // ==========================================
    {
        attributes: {
            title: { type: 'string', default: '' },
            description: { type: 'string', default: '' },
        },
        isEligible( attributes ) {
            // مؤهل إذا لم يكن لديه كائن buttonData ولم يكن لديه خاصية buttonUrl
            return ! attributes.buttonData && typeof attributes.buttonUrl === 'undefined';
        },
        migrate( attributes ) {
            return {
                title: attributes.title,
                description: attributes.description,
                cardTheme: 'primary',
                buttonData: {
                    text: 'اكتشف المزيد',
                    url: '#',
                    target: '_self',
                },
            };
        },
        save( { attributes } ) {
            const { title, description } = attributes;
            return (
                

                    
{ title }
                    
{ description }
                
            );
        },
    },
];

export default deprecated;

4. ملف تسجيل البلوك الرئيسي: index.js

import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import edit from './edit';
import save from './save';
import deprecated from './deprecated';
import './style.scss';

registerBlockType( metadata.name, {
    edit,
    save,
    deprecated, // هنا يتم تمرير مصفوفة الترحيل التاريخية للنواة
} );

تحليل أسرار كود الترحيل:

• isEligible(): هذه الدالة تحميك من الكوارث! لو كان عندك إصدار قديم وإصدار أقدم، جوتنبرج قد يخلط بينهم لو تشابه كود الـ HTML؛ لكن مع isEligible أنت تضع شرطاً منطقياً يفحص تركيبة الـ attributes القديمة بدقة حاسوبية.
• migrate(): تأخذ الخصائص القديمة (مثل buttonText و buttonUrl) وتعيد كائناً جديداً تماماً متطابقاً مع مخطط الخصائص (Schema) للإصدار الحديث v3، مع توفير قيم افتراضية ذكية لأي حقول جديدة لم تكن موجودة في المقالات القديمة.

دراسة حالة واقعية: أزمة شبكة أخبار اليوم واليوم السابع والمحررين في القاهرة

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

1. لا تعدل save() مباشرة في بلوك منشور: اعتبر أي كود تم دفعه للإنتاج عقداً مقدساً لا يجوز تغييره إلا بإنشاء نسخة ترحيل في deprecated.
2. انسخ كود save القديم كما هو حرفياً: لا تحاول تحسين أو تنظيف كود الـ Save في ملف الإلغاء؛ انقله بمسافاته وكلاساته القديمة لضمان التطابق الحرفي.
3. استخدم isEligible لتفادي الخلط بين الأجيال: ضع شروطاً تفحص الخصائص القديمة لضمان عدم تنفيذ ترحيل خاطئ على بلوك من إصدار مختلف.
4. رتب مصفوفة deprecated من الأحدث للأقدم: جوتنبرج يفحص العناصر بالترتيب؛ ضع الإصدار الأحدث أولاً لتسريع خوارزمية الفحص وتجنب فحص الأجيال السحيقة أولاً.
5. وفر قيماً افتراضية ذكية في migrate(): عند إضافة خصائص جديدة، اجعل دالة الترحيل تضع قيماً افتراضية منطقية تحاكي مظهر البلوك القديم.
6. اختبر الترحيل على مقال حقيقي منشور قديماً: لا تعتمد على إنشاء مقال جديد لاختبار الترحيل؛ افتح مقالاً قديماً من قاعدة البيانات الحقيقية وتأكد من عدم ظهور تحذيرات.
7. احفظ ملف deprecated كأرشيف تاريخي دائم: لا تحذف الإصدارات القديمة من ملف deprecated.js حتى لو مر عليها سنوات، طالما أن هناك مقالات قديمة لا تزال تستخدمها.
8. ادعم ترحيل البلوكات المتداخلة (InnerBlocks): دالة migrate(attributes, innerBlocks) تستقبل الأبناء ويمكنها إعادة هيكلة أو حذف أو إضافة أبناء جدد برمجياً!
9. احذر من تضارب الـ Supports في الإصدارات القديمة: إذا قمت بتغيير إعدادات supports (مثل إيقاف الألوان)، تأكد من نقلها لكائن الـ Deprecation القديم.
10. اكتب اختبارات آلية لكل نسخة ترحيل: احتفظ بنماذج HTML لكل إصدار قديم في اختبارات Jest لضمان أن التحديثات المستقبلية لن تكسر أي جيل سابق.

معمارية ترحيل البلوكات المتداخلة وإعادة هيكلة الشجرة (Complex InnerBlocks Migration)

يا صديقي المطور، من أصعب التحديات المعمارية في ووردبريس هو لما تقرر تحول بلوك كان في الأصل “بلوك فردي بسيط” (Flat Single Block) إلى “حاوية متداخلة” (Container with InnerBlocks)، أو لما تقرر تعيد هيكلة الأبناء الداخليين (مثلاً تحول قائمة نصوص عادية إلى مجموعة بلوكات فرعية منفصلة). كيف تتعامل دالة migrate() مع هذه الحالة المعقدة؟

دالة migrate في مواصفات Gutenberg المتقدمة لا تقتصر على إرجاع كائن الخصائص الجديد فقط، بل يمكنها إرجاع مصفوفة ثنائية القيمة تحتوي على: [ newAttributes, newInnerBlocks ].

كود عملي متكامل: تحويل النصوص المحفوظة إلى بلوكات أطفال حقيقية

/**
 * مثال احترافي لدالة migrate تقوم بإنشاء وتوليد بلوكات InnerBlocks حقيقية
 * أثناء ترحيل المحتوى القديم للجيل الثالث
 */
import { createBlock } from '@wordpress/blocks';

const complexInnerBlocksDeprecation = {
    attributes: {
        rawItemsText: {
            type: 'string',
            default: '', // كان المحتوى القديم يُحفظ كنص مفصول بأسطر جديدة
        },
        sectionHeading: {
            type: 'string',
            default: '',
        },
    },
    isEligible( attributes ) {
        return typeof attributes.rawItemsText === 'string' && attributes.rawItemsText.length > 0;
    },
    migrate( attributes, innerBlocks ) {
        // 1. استخراج الأسطر القديمة وتحويلها لمصفوفة عناصر
        const lines = attributes.rawItemsText.split( 'n' ).filter( ( line ) => line.trim() !== '' );

        // 2. استخدام دالة createBlock الرسمية لإنشاء بلوكات أطفال جديدة في الشجرة
        const migratedChildren = lines.map( ( lineText ) => {
            return createBlock( 'enterprise/feature-item', {
                itemTitle: lineText.trim(),
                isCompleted: false,
            } );
        } );

        // 3. إرجاع مصفوفة تحتوي على: الخصائص الجديدة المصفاة، ومصفوفة البلوكات الأبناء المحدثة!
        return [
            {
                heading: attributes.sectionHeading || 'قائمة المميزات المطورة',
                // حذف الخاصية القديمة rawItemsText لعدم الحاجة إليها
            },
            migratedChildren, // سيتم حقن هؤلاء الأطفال تلقائياً داخل InnerBlocks الحاوية!
        ];
    },
    save( { attributes } ) {
        return (
            

                
{ attributes.sectionHeading }
                
{ attributes.rawItemsText }
            
        );
    },
};

القوة الهندسية لهذا الأسلوب:
المحرر لما يفتح المقال، سيجد أن النص القديم الجاف قد تحول فورياً وداخلياً إلى بلوكات تفاعلية مستقلة يمكنه سحبها، إعادة ترتيبها، وتلوينها بخصائص الجيل الجديد، دون أن يضطر لنقل كلمة واحدة يدوياً!

الترحيل الشامل المباشر في قاعدة البيانات عبر WP-CLI (Bulk Database Migration)

على الرغم من أن معمارية deprecated تحمي موقعك وتجعل الترقية تتم “عند الطلب” (On-demand) عندما يفتح المحرر كل مقال، إلا أن المؤسسات الإعلامية الضخمة التي تمتلك 200,000 مقال قد ترغب في ترقية الأرشيف بالكامل في قاعدة البيانات دفعة واحدة دون انتظار فتح المقالات يدوياً على مدار سنوات.

أفضل ممارسة لتنفيذ الترحيل الجماعي:

1. تجنب استعلامات SQL المباشرة: إياك وكتابة UPDATE wp_posts SET post_content = REPLACE(...)؛ لأنك ستتجاهل فك وتركيب كائنات الـ JSON وتدمر شجرة البلوكات.
2. استخدام أمر مخصص في WP-CLI: قم ببناء أمر CLI يستدعي دالة النواة do_blocks() أو يقوم بقراءة المقال عبر parse_blocks()، ويمرر كل بلوك على دوال التحقق والترقية، ثم يعيد تسلسل المحتوى بـ serialize_blocks() ويحفظ المقال عبر wp_update_post().

<?php
/**
 * سكربت WP-CLI مخصص لترقية البلوكات التاريخية في صمت
 * Usage: wp az migrate-blocks --post_type=post
 */
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'az migrate-blocks', function( $args, $assoc_args ) {
        $posts = get_posts([
            'post_type'      => 'post',
            'posts_per_page' => -1,
            'post_status'    => 'publish',
        ]);

        WP_CLI::line( sprintf( 'تم العثور على %d مقال، جاري فحص وترقية البلوكات...', count( $posts ) ) );

        $updated_count = 0;
        foreach ( $posts as $post ) {
            $parsed_blocks = parse_blocks( $post->post_content );
            $modified      = false;

            // فحص ومعالجة شجرة البلوكات وترقيتها برمجياً...
            // عند اكتشاف بلوك قديم يتم تعديل خصائصه لهيكل v3
            
            if ( $modified ) {
                $new_content = serialize_blocks( $parsed_blocks );
                wp_update_post([
                    'ID'           => $post->ID,
                    'post_content' => $new_content,
                ]);
                $updated_count++;
            }
        }

        WP_CLI::success( sprintf( 'اكتمل الترحيل بنجاح! تم تحديث %d مقال في قاعدة البيانات.', $updated_count ) );
    } );
}
?>

هذا التكامل بين معمارية deprecated داخل محرر المتصفح، وسكربتات WP-CLI على مستوى السيرفر، يمنحك السيطرة الهندسية المطلقة على دورة حياة المحتوى، ويضمن أن موقعك يواكب أحدث المعايير البرمجية لعقود قادمة بثبات وسلاسة تامة.