عرض البلوكات على السيرفر: render.php والتحقق من الخصائص

أهلاً بيك يا هندسة في قلب المعمارية السيرفرية لووردبريس الحديث (Server-Side Rendering Architecture). لو كنت فاكر إن محرر Gutenberg اتعمل عشان يرمي الـ PHP في الزبالة ونقضي حياتنا كلها نكتب React و JavaScript، أحب أقولك إنك غلطان تماماً! الـ PHP لسه هو العمود الفقري، والقوة الحقيقية بتظهر لما نعرف نربط عالم الـ React في شاشة التحرير بالسيرفر في الواجهة الأمامية بسلاسة وذكاء.

النقلة النوعية الأكبر اللي حصلت في ووردبريس 6.1 وما بعدها كانت تقديم ملف render.php المباشر داخل ملف تعريف البلوك block.json كبديل رسمي ومتقدم عن الـ Closures والـ Callback Functions القديمة. في المقال ده، هنغوص في أعماق دورة حياة عرض البلوك على السيرفر (Server Block Rendering Lifecycle)، إزاي السيرفر بيفكك تعليقات البلوك ويحقن المتغيرات ($attributes، $content، $block)، إزاي نعمل تحقق أمني صارم (Server-side Sanitization & Validation) يمنع هجمات الـ XSS وحقن البيانات، واستراتيجيات التخزين المؤقت (Fragment Caching) بالعامية المصرية التقنية المعمقة.

دورة حياة رندرة البلوك على السيرفر (The Execution Pipeline)

لما المستخدم يفتح متصفحه ويكتب عنوان مقال على موقعك، إيه اللي بيحصل خلف الكواليس داخل نواة ووردبريس عشان كود الـ PHP بتاع البلوك يتنفذ؟ تعال نتتبع الرحلة خطوة بخطوة:

1. مرحلة جلب النص الخام (Post Fetching):

   ووردبريس بيسحب محتوى المقال من عمود post_content في جدول wp_posts كنص متصل يحتوي على تعليقات البلوكات.

2. مرحلة التحليل اللغوي (Block Parsing):

   دالة parse_blocks( $content ) بتبدأ تقطع النص لشجرة مصفوفات (Block Tree AST). بتتعرف على البلوك من خلال اسمه (مثلاً: enterprise/currency-tracker) وبتفك تشفير كائن الـ JSON الخاص بالـ Attributes.

3. حلقة المعالجة العامة (The Render Loop – do_blocks):

   الدالة do_blocks() بتمر على كل بلوك في المصفوفة وتستدعي الدالة المركزية render_block( $parsed_block ).

4. حقن السياق (Block Context Filtering):

   قبل ما ملف render.php يشتغل، ووردبريس بيمرر البلوك على فلتر render_block_context، عشان يحقن فيه أي بيانات جاية من البلوكات الأب (زي الـ Post ID، أو الـ Query Pagination، أو إعدادات الحاوية).

5. تنفيذ قالب render.php (Template Execution):

   ووردبريس بيفتح عزلاً محلياً للمتغيرات (Isolated Variable Scope)، وبيجهز 3 متغيرات أساسية:

   • $attributes: مصفوفة الخصائص اللي جاية من تعليق البلوك ومدموجة مع القيم الافتراضية المحددة في block.json.
   • $content: كود الـ HTML الناتج عن البلوكات الأبناء لو كان البلوك حاوية (InnerBlocks).
   • $block: كائن كامل من نوع WP_Block بيمتلك خصائص البلوك وسياقه (Context) والـ Registry الخاص بيه.
6. تطبيق الفلاتر النهائية (Post-render Filtering):

   المخرجات الناتجة من ملف render.php بتمر على فلتر render_block وفلتر render_block_{$this->name}، وده بيسمح لأي مطور خارجي إنه يعدل في كود الـ HTML قبل ما يتبعت لمتصفح العميل نهائياً!

تطبيق عملي كامل: بناء بلوك أسعار الصرف وتحويل العملات (Enterprise Currency Tracker)

تعال نبني مع بعض بلوك ديناميكي متطور لمتابعة أسعار صرف الجنيه المصري أمام العملات الأجنبية (الدولار واليورو والريال السعودي)، مع تطبيق أعلى معايير الأمان، والتحقق السيرفري الصارم من الخصائص، والتخزين المؤقت فائق السرعة عبر Transients API.

1. ملف block.json مع ربط render.php

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/currency-tracker",
  "version": "1.0.0",
  "title": "مؤشر أسعار العملات والذهب اللحظي",
  "category": "widgets",
  "icon": "money-alt",
  "description": "بلوك يعرض أسعار الصرف الرسمية المحدثة لحظياً على السيرفر مع حماية كاش فائقة.",
  "supports": {
    "html": false,
    "color": {
      "background": true,
      "text": true
    },
    "spacing": {
      "margin": true,
      "padding": true
    }
  },
  "attributes": {
    "baseCurrency": {
      "type": "string",
      "default": "USD"
    },
    "targetCurrencies": {
      "type": "array",
      "default": [ "EGP", "SAR", "EUR" ]
    },
    "showUpdatedTime": {
      "type": "boolean",
      "default": true
    },
    "alertThreshold": {
      "type": "number",
      "default": 50.0
    }
  },
  "render": "file:./render.php",
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

2. ملف السيرفر الحصري: render.php المحصن برمجياً

<?php
/**
 * ملف العرض السيرفري لبلوك مؤشر أسعار العملات
 * 
 * @var array    $attributes خصائص البلوك المستلمة من المحرر
 * @var string   $content    محتوى الأبناء (InnerBlocks)
 * @var WP_Block $block      كائن البلوك من نواة ووردبريس
 */

// 1. مرحلة التحقق والتعقيم الصارم للمدخلات (Sanitization & Defense-in-depth)
// لا تثق أبداً في البيانات القادمة من الـ Attributes دون فحص، حتى لو كان المحرر موثوقاً!
$allowed_bases = [ 'USD', 'EUR', 'GBP', 'SAR', 'AED' ];
$base_currency = isset( $attributes['baseCurrency'] ) ? sanitize_text_field( $attributes['baseCurrency'] ) : 'USD';

if ( ! in_array( $base_currency, $allowed_bases, true ) ) {
    $base_currency = 'USD'; // العودة للقيمة الافتراضية الآمنة في حالة التلاعب
}

$target_currencies = isset( $attributes['targetCurrencies'] ) && is_array( $attributes['targetCurrencies'] )
    ? array_map( 'sanitize_text_field', $attributes['targetCurrencies'] )
    : [ 'EGP', 'SAR', 'EUR' ];

$show_updated_time = ! empty( $attributes['showUpdatedTime'] );
$alert_threshold   = isset( $attributes['alertThreshold'] ) ? floatval( $attributes['alertThreshold'] ) : 50.0;

// 2. معمارية التخزين المؤقت وحماية قاعدة البيانات (Caching Layer)
// نقوم بإنشاء مفتاح كاش فريد للعملة الأساسية
$transient_key = 'az_rates_' . strtolower( $base_currency );
$rates_data    = get_transient( $transient_key );

if ( false === $rates_data ) {
    // في بيئة الإنتاج: استدعاء API البنك المركزي أو مزود أسعار الصرف الرسمي
    // هنا نحاكي جلب البيانات مع تسجيل وقت التحديث بدقة
    $rates_data = [
        'base'      => $base_currency,
        'timestamp' => current_time( 'mysql' ),
        'rates'     => [
            'EGP' => 49.35,
            'SAR' => 3.75,
            'EUR' => 0.92,
            'AED' => 3.67,
        ],
    ];

    // تخزين البيانات في الكاش لمدة 15 دقيقة لتفادي الضغط اللحظي على السيرفر
    set_transient( $transient_key, $rates_data, 15 * MINUTE_IN_SECONDS );
}

// 3. توليد خصائص الغلاف الخارجي مع احترام خصائص Block Supports
$wrapper_attributes = get_block_wrapper_attributes( [
    'class' => 'az-currency-tracker-wrapper az-base-' . strtolower( $base_currency ),
    'data-base' => esc_attr( $base_currency ),
] );
?>

<aside <?php echo $wrapper_attributes; ?>>
    <div class="az-currency-header">
        <h3 class="az-currency-title">
            <?php
            printf(
                /* translators: %s: Base Currency Code */
                esc_html__( 'أسعار صرف العملات مقابل (%s)', 'az-currency' ),
                esc_html( $base_currency )
            );
            ?>
        </h3>
        <?php if ( $show_updated_time && ! empty( $rates_data['timestamp'] ) ) : ?>
            <span class="az-update-clock">
                <?php printf( esc_html__( 'آخر تحديث رسمي: %s', 'az-currency' ), esc_html( $rates_data['timestamp'] ) ); ?>
            </span>
        <?php endif; ?>
    </div>

    <div class="az-rates-grid">
        <?php foreach ( $target_currencies as $curr ) : ?>
            <?php
            if ( ! isset( $rates_data['rates'][ $curr ] ) ) {
                continue;
            }
            $rate_value = floatval( $rates_data['rates'][ $curr ] );
            $is_high    = ( 'EGP' === $curr && $rate_value >= $alert_threshold );
            ?>
            <div class="az-rate-card <?php echo $is_high ? 'has-alert-rate' : ''; ?>">
                <span class="az-currency-symbol"><?php echo esc_html( $curr ); ?></span>
                <span class="az-currency-value">
                    <?php echo esc_html( number_format( $rate_value, 2 ) ); ?>
                </span>
            </div>
        <?php endforeach; ?>
    </div>

    <!-- إذا كان البلوك يحتوي على أبناء InnerBlocks مخصصين لروابط إضافية يتم طباعتهم هنا -->
    <?php if ( ! empty( $content ) ) : ?>
        <div class="az-currency-extra-content">
            <?php echo $content; ?>
        </div>
    <?php endif; ?>
</aside>

3. كود الجافاسكريبت للتحرير والحفظ: edit.js و save.js

// save.js: خالي تماماً لتسليم المسؤولية الكاملة للسيرفر
export default function save() {
    return null;
}

// edit.js: شاشة التحرير مع عناصر تحكم متطورة
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, SelectControl, ToggleControl, RangeControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

export default function Edit( { attributes, setAttributes } ) {
    const { baseCurrency, showUpdatedTime, alertThreshold } = attributes;
    const blockProps = useBlockProps( { className: 'az-currency-tracker-editor' } );

    return (
        

            
                
                     setAttributes( { baseCurrency: val } ) }
                    />
                     setAttributes( { showUpdatedTime: val } ) }
                    />
                     setAttributes( { alertThreshold: val } ) }
                        min={ 30 }
                        max={ 80 }
                        step={ 0.5 }
                    />
                
            

            

                
                
{ __( 'مؤشر أسعار الصرف اللحظي (Server Rendered)', 'az-currency' ) }
                

                    { __( 'العملة المحددة حالياً: ', 'az-currency' ) }
                    { baseCurrency }
                
                

                    { __( 'يتم جلب وعرض البيانات الحية والتحقق منها مباشرة من السيرفر في الواجهة الأمامية.', 'az-currency' ) }
                
            
        
    );
}

هندسة الأمان السيرفري: التحقق والتعقيم الصارم للخصائص

من أكبر الأخطاء الكارثية التي يقع فيها المطورون عند الانتقال لـ render.php هو الافتراض الساذج بأن البيانات الموجودة داخل $attributes آمنة بنسبة 100% لأنها تم إدخالها من شاشة تحرير ووردبريس. هذا الافتراض قد يدمر موقعك للأسباب التالية:

1. التلاعب عبر الـ REST API: أي مستخدم يمتلك صلاحية كتابة مقال (Contributor أو Author) يمكنه إرسال طلب REST API مباشر يحتوي على كود جافاسكريبت خبيث داخل أي خاصية نصية مثل: {"baseCurrency": "<script>stealCookies()</script>"}.
2. التلاعب عبر مسودة المقال (Code Editor): يمكن للمستخدم الانتقال لوضع “Code Editor” في جوتنبرج وتعديل كائن الـ JSON الخاص بالبلوك يدوياً وحقن نصوص مشوهة أو روابط تصيد.

القواعد الذهبية لتعقيم الخصائص داخل render.php:

• الأرقام الصحيحة: استخدم دائماً absint() أو intval() لمنع حقن نصوص داخل الحقول الرقمية.
• الأرقام العشرية: استخدم floatval() مع تحديد عدد الخانات بـ number_format().
• القوائم المغلقة (Whitelisting): إذا كانت الخاصية تقبل خيارات محددة (مثل أسماء العملات أو ألوان معينة)، قارن القيمة بمصفوفة ثابتة عبر in_array( $val, $allowed, true ) ولا تعتمد على النص القادم مطلقاً.
• النصوص الحرة: طبق sanitize_text_field() قبل المعالجة، و esc_html() لحظة الطباعة في المتصفح.
• نصوص الـ HTML المسموحة: استخدم wp_kses_post() إذا كان الحقل مخصصاً لنصوص غنية تحتوي على روابط وتنسيقات عريضة.

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

الوصايا العشر لعرض البلوكات على السيرفر عبر render.php

1. لا تثق في $attributes أبداً: اعتبر كل خاصية قادمة من المحرر مدخلاً غير موثوق وعقمها فوراً بالدالة المناسبة لنوعها قبل معالجتها.
2. استخدم get_block_wrapper_attributes دائماً: هو الوسم الوحيد الذي يضمن سريان تنسيقات ووردبريس، الهوامش، الألوان، وكلاسات المحاذاة على البلوك.
3. افصل ملف render.php عن منطق التسجيل: ضعه داخل مجلد البلوك بجوار block.json وابتعد عن حشو functions.php بدوال مجهولة.
4. اعتمد على Transients في العمليات المكلفة: إذا كان البلوك يستدعي API خارجي أو استعلام SQL معقد، خزن النتيجة في كاش مؤقت دائماً.
5. تحقق من وجود الدوال قبل استدعائها: إذا كان البلوك يعتمد على إضافة خارجية (مثل WooCommerce أو ACF)، افحص function_exists() أولاً لتفادي Fatal Errors.
6. وفر مخرجات بديلة فارغة عند الخطأ (Fail Gracefully): إذا كانت البيانات المطلوبة غير متوفرة، اخرج بـ return; صامتة دون إفساد منظر المقال بالتحذيرات.
7. دعم الـ InnerBlocks بحكمة: اطبع المتغير $content فقط إذا كان البلوك يدعم الأبناء، وضعه في المكان الصحيح هندسياً داخل التصميم.
8. استخدم translators comments في الترجمة: زود المترجمين بسياق المتغيرات في دوال printf و esc_html__ لتسهيل تعريب البلوك.
9. استفد من سياق البلوك ($block->context): اقرأ معرف المقال postId ونوع المنشور مباشرة من كائن البلوك بدلاً من الاعتماد على المتغيرات العامة العشوائية.
10. اختبر الكود مع تفعيل WP_DEBUG: تأكد تماماً من عدم ظهور أي PHP Notices أو Warnings أثناء عرض البلوك في الواجهة الأمامية.

معمارية تمرير السياق على السيرفر (Server-Side Block Context Propagation)

يا صديقي المطور، من أقوى وأخطر الميزات في عالم البلوكات السيرفرية هي الـ Block Context لما يشتغل في بيئة الـ PHP. في المتصفح وجافاسكريبت، إحنا متعودين إن الـ Context بيتنقل بسهولة بين مكونات React عبر خطافات التحرير. لكن على السيرفر، إزاي البلوك الابن (Child Block) بيعرف بيانات البلوك الأب (Parent Block) لحظة تنفيذ ملف render.php؟

نواة ووردبريس بتمتلك آلية هرمية داخل كائن WP_Block:

1. البلوك الأب بيعلن في ملف block.json الخاص بيه إنه بيوفر سياق معين عبر خاصية providesContext.
2. البلوك الابن بيعلن في block.json إنه بيحتاج السياق ده عبر خاصية usesContext.
3. أثناء قيام ووردبريس بمعالجة حلقة do_blocks()، النواة بتقوم بنسخ قيم الخصائص من كائن الأب وتمريرها في مصفوفة السياق $block->context للابن قبل تنفيذ ملف render.php الخاص به!

كود عملي: قراءة السياق وتوريث المعرفات في PHP

<?php
/**
 * مثال لاستخدام سياق البلوك الأب داخل ملف render.php للبلوك الابن
 */

// استخراج المعرف الفريد القادم من الحاوية الأب
$parent_card_theme = isset( $block->context['enterprise/cardTheme'] ) 
    ? sanitize_key( $block->context['enterprise/cardTheme'] ) 
    : 'light';

// استخراج المعرف التعريفي للمقال التابع له
$current_post_id = isset( $block->context['postId'] ) 
    ? absint( $block->context['postId'] ) 
    : get_the_ID();

// بناء كلاسات مخصصة مبنية على سياق الحاوية بدون تدخل يدوي من المستخدم
$wrapper_attributes = get_block_wrapper_attributes([
    'class' => 'az-child-block az-theme-' . esc_attr( $parent_card_theme ),
    'data-post-origin' => esc_attr( $current_post_id ),
]);
?>

<div <?php echo $wrapper_attributes; ?>>
    <p>
        <?php printf( esc_html__( 'هذا الابن موروث من سياق السيرفر بمظهر: %s', 'az-context' ), esc_html( $parent_card_theme ) ); ?>
    </p>
</div>

معمارية تفادي انهيار الكاش (Cache Stampede & Dog-piling Prevention)

في المواقع الإخبارية والاقتصادية الكبرى في مصر والوطن العربي، عندما ينتهي وقت صلاحية الكاش (Transient Expiry) في لحظة ذروة زيارة (مثلاً 50,000 زائر متزامن يقرأون أسعار الدولار)، قد يحدث ما يسمى بـ Cache Stampede (أو انهيار تدافع الكاش). في هذه اللحظة، يكتشف 1,000 طلب متزامن في نفس الجزء من الثانية أن الكاش منتهي الصلاحية، فيقوم الألف زائر بإرسال 1,000 استعلام ثقيل لقاعدة البيانات في نفس التوقيت بالملي ثانية، مما يسقط السيرفر في الحال!

حل المعضلة بنمط قفل الطفرة (Locking / Mutex Pattern):

<?php
/**
 * دالة جلب مؤمنة ضد تدافع الكاش لبلوكات render.php
 */
function az_get_protected_currency_rates( $base_currency ) {
    $cache_key = 'az_currency_data_' . strtolower( $base_currency );
    $lock_key  = 'az_lock_' . $cache_key;
    
    $data = get_transient( $cache_key );
    
    if ( false !== $data ) {
        return $data; // تم العثور على الكاش السريع
    }
    
    // محاولة حجز قفل مؤقت لمدة دقيقة واحدة لمنع باقي الطلبات من ضرب قاعدة البيانات
    $is_locked = get_transient( $lock_key );
    if ( $is_locked ) {
        // هناك طلب آخر يقوم بتحديث الكاش حالياً، ارجع بيانات قديمة مؤقتة أو قيم آمنة
        return az_get_stale_fallback_rates( $base_currency );
    }
    
    // وضع القفل الفوري
    set_transient( $lock_key, '1', 60 );
    
    // تنفيذ الاستعلام المكلف بأمان
    $fresh_data = az_fetch_heavy_currency_from_api( $base_currency );
    
    // تخزين البيانات الطازجة لـ 15 دقيقة
    set_transient( $cache_key, $fresh_data, 15 * MINUTE_IN_SECONDS );
    
    // حذف القفل بعد انتهاء التحديث بنجاح
    delete_transient( $lock_key );
    
    return $fresh_data;
}

هذا النمط المعماري يضمن أن طلباً واحداً فقط من بين آلاف الطلبات المتزامنة هو الذي يتكفل بالاتصال بمصدر البيانات الثقيل، بينما يتلقى باقي الزوار استجابة فورية فائقة السرعة، مما يحافظ على ثبات معالج السيرفر (CPU Usage) تحت سقف 15% دائماً حتى في أعتى موجات الزيارات المليونية.