شرح parse_request في ووردبريس: من مسار الرابط إلى Query Vars

هذا المقال رقم 9 من 100 في سلسلة معمارية ووردبريس من الأساسيات إلى المشروع النهائي، ضمن المستوى 2: التوجيه ونظام الروابط (Routing & Rewrite).

يا صباح الفل يا هندسة! لو سألت مطور ووردبريس عادي: “مين الكائن المسؤول عن إدارة كل حركة المرور في ووردبريس؟”، غالباً هيقولك: “كائن WP_Query!”. لكن في الحقيقة، WP_Query هو مجرد منفذ بيستلم أوامر جاهزة؛ العقل المدبر الحقيقي والمايسترو اللي بيقف في أول الخط، يستلم الرابط من المتصفح، يفككه، ينظفه، ويحدد إيه المتغيرات اللي هتدخل لقاعدة البيانات أصلاً، هو كائن النواة المركزي: كائن $wp (كلاس WP) وتحديداً عمليته الحيوية الأهم: parse_request().

مرحلة parse_request هي محطة الفرز المركزية في ووردبريس؛ هنا بيتم تحويل النص المكتوب في شريط المتصفح (مثل: /courses/advanced-php/page/2/) إلى مصفوفة بيانات منظمة وقوية تسمى متغيرات الاستعلام (Query Variables) تفهمها النواة بدقة. ولو فهمت إزاي التابع ده بيشتغل تحت الكبوت، هتقدر تبني مسارات API مخصصة فائقة السرعة، وتتعامل مع إشعارات بوابات الدفع (Webhooks) بكفاءة خيالية بدون استهلاك موارد السيرفر، وتمنع محاولات التلاعب بالمدخلات الأمنية. في هذا الدليل المعماري الموسع، هنشرح بالعامية المصرية التقنية تشريح كلاس WP، وتفكيك كود parse_request() خطوة بخطوة، ونظام الفلترة بالقائمة البيضاء، وبناء موجه مسارات خفيف (Micro-Router)، مع دراسة حالة واقعية لحل اختناق السيرفر وبنك أسئلة شائعة شامل ومصادر رسمية.

1. الفكرة المعمارية لـ parse_request: الجسر الرابط بين الـ URL واستعلام MySQL

تعال نتخيل دورة حياة الطلب كمصنع تجميع سيارات متطور:

1. خادم الويب (Nginx / Apache) يستلم الطلب الخام من الإنترنت ويسلمه لملف index.php.
2. ملف index.php يستدعي ملف wp-blog-header.php، والذي يقوم بدوره بطلب wp-load.php وتهيئة النواة بالكامل.
3. بعد تحميل الإضافات والقالب، يستدعي ملف wp-blog-header.php الدالة المركزية: wp().
4. دالة wp() تستدعي التابع $GLOBALS['wp']->main().
5. وهنا تبدأ الخطوة الحاسمة: $wp->parse_request()! وظيفته أخذ الرابط وفحصه، وتحديد: هل هذا رابط مقال؟ تصنيف؟ صفحة ثابتة؟ بحث؟ خلاصة RSS؟ أم طلب غير صالح يعطي خطأ 404؟
6. الناتج النهائي لهذه الخطوة هو تعبئة المصفوفة العامة $wp->query_vars، وهي المصفوفة الذهبية التي يتم تسليمها فوراً لكائن $wp_the_query->query() ليبدأ استخراج البيانات من MySQL!

بدون خطوة parse_request، ستكون النواة عمياء تماماً لا تعرف ماذا يريد الزائر، ولن تستطيع WP_Query كتابة سطر SQL واحد!

2. تشريح كلاس WP والفرق بين $wp و $wp_query و $wp_rewrite

في نواة ووردبريس، توجد ثلاثة كائنات عظمى تتشابه أسماؤها وتسبب خلطاً شديداً لدى المطورين؛ احفظ هذا التقسيم الهندسي الفاصل:

تشريح التابع الرئيسي $wp->main():

إذا فتحت ملف wp-includes/class-wp.php، ستجد أن التابع main() يمثل الترتيب العسكري الصارم لمعالجة أي زيارة في ووردبريس:

// الكود المصدري الأصلي لدورة حياة الطلب في كلاس WP:
public function main( $query_args = '' ) {
    $this->init();            // تهيئة البيئة وتعيين المستخدم الحالي
    $this->parse_request( $query_args ); // تحليل الرابط واستخراج المتغيرات
    $this->send_headers();    // إرسال ترويسات HTTP (مثل Content-Type والتشفير)
    $this->query_posts();     // استدعاء WP_Query لجلب المنشورات من قاعدة البيانات
    $this->handle_404();      // ضبط ترويسة 404 إذا لم يتم العثور على محتوى
    $this->register_globals();// تسجيل المتغيرات العامة القديمة للتوافق
    do_action_ref_array( 'wp', array( &$this ) ); // إطلاق خطاف اكتمال المعالجة
}

3. تشريح كود WP::parse_request() خطوة بخطوة

تعال نتتبع ما يفعله التابع parse_request() في النواة سطراً بسطر عندما يطلب المستخدم رابطاً مثل abozaid.local/courses/php-masterclass/?coupon=SAVE20:

الخطوة أ: استخراج المسار الحقيقي وتجريده

يقوم التابع بفحص متغيرات الخادم $_SERVER['REQUEST_URI'] و$_SERVER['PATH_INFO']. ثم يقوم بعملية تنظيف هندسية:

• فصل معلمات الـ Query String (أي شيء بعد علامة ? مثل coupon=SAVE20) والاحتفاظ بها جانباً.
• إزالة مسار المجلدات الفرعية؛ فإذا كان ووردبريس مثبتاً في مجلد فرعي مثل domain.com/blog/، يقوم التابع بقص كلمة blog/ ليبقى المسار النسبي النقي فقط: courses/php-masterclass/.

الخطوة ب: مطابقة المسار مع مصفوفة الروابط الدائمة (Rewrite Matching)

يأخذ التابع المسار النظيف، ويستدعي مصفوفة $wp_rewrite->wp_rewrite_rules(). ويبدأ في الدوران عبر حلقة foreach لتجربة كل تعبير نمطي (Regex):

// المطابقة الداخلية في كود النواة:
foreach ( (array) $rewrite as $match => $query ) {
    // إذا تطابق المسار مع التعبير النمطي:
    if ( preg_match( "#^$match#", $request_match, $matches ) ) {
        // استبدال $matches[1] و $matches[2] بالقيم الملتقطة
        $this->matched_rule = $match;
        $this->matched_query = $query;
        // تحويل جملة الاستعلام إلى مصفوفة متغيرات عبر wp_parse_str
        wp_parse_str( $query, $perma_query_vars );
        break; // التوقف فوراً عند أول قاعدة مطابقة!
    }
}

الخطوة ج: دمج المتغيرات والتصفية بالقائمة البيضاء (Sanitization & Whitelist)

يقوم التابع بدمج المتغيرات المستخرجة من الرابط الدائم مع المعلمات القادمة في رابط الـ URL عبر $_GET. وهنا يطبق ووردبريس الفلتر الأمني الصارم:

تفحص النواة مصفوفة $this->public_query_vars؛ أي متغير ليس موجوداً في هذه القائمة البيضاء المعتمدة يتم حذفه ورميه في سلة المهملات، ولا يتم تمريره إطلاقاً لكائن WP_Query! هذه الخطوة تحمي الموقع من قيام المهاجمين بتمرير معلمات استعلام خطيرة قد تتلاعب ببنود الاستعلام الداخلي لقاعدة البيانات.

4. محطات التدخل البرمجي: الفلتر do_parse_request والأكشن parse_request

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

أ. الفلتر السحري: do_parse_request (صمام الإلغاء الكامل)

في أول سطر من التابع، تطلق النواة هذا الفلتر:

if ( ! apply_filters( 'do_parse_request', true, $this, $extra_query_vars ) ) {
    return false;
}

إذا قمت بإرجاع false في هذا الفلتر، فإنك تقول لووردبريس: “توقف فوراً في مكانك! لا تفحص الروابط، ولا تذهب لقاعدة البيانات، ولا تشغل The Loop، أنا سأتولى معالجة هذا الطلب بالكامل بنفسي!”. هذا الفلتر هو السلاح السري لبناء بوابات الـ Webhooks وأنظمة الـ Headless فائقة السرعة!

ب. الأكشن: parse_request (الوصول للمتغيرات المنقحة)

يتم إطلاقه في نهاية التابع بعد اكتمال تفكيك الرابط واعتماد المتغيرات، ولكنه يسبق استعلام قاعدة البيانات WP_Query. يمرر لك كائن $wp كمرجع (Reference)، مما يتيح لك تعديل المتغيرات في $wp->query_vars أو قراءتها برمجياً:

add_action( 'parse_request', 'az_inspect_parsed_request' );

function az_inspect_parsed_request( WP $wp ): void {
    // فحص المتغيرات المعتمدة قبل تسليمها لـ WP_Query
    if ( isset( $wp->query_vars['az_course'] ) ) {
        // فرض معلمات إضافية برمجياً
        $wp->query_vars['post_status'] = 'publish';
    }
}

5. تطبيق عملي: بناء Micro-Router لمعالجة Webhooks بوابات الدفع دون تشغيل The Loop

عندما يقوم طالب بالدفع عبر فودافون كاش أو بطاقة بنكية، ترسل بوابة الدفع إشعاراً في الخلفية (Webhook) إلى مسار معين مثل: /az-api/payment-webhook/. المطور المبتدئ يجعل الطلب يمر بدورة ووردبريس كاملة، فيقوم السيرفر بتحميل القالب وتشغيل استعلامات المقالات وتشغيل مئات الخطافات دون أي داعٍ!

تعال نبني معمارية احترافية باستخدام فلتر do_parse_request تعترض طلب الـ Webhook فوراً، تفحص التوقيع الرقمي، تحدث رصيد الطالب في قاعدة البيانات، وترد بـ HTTP 200 وتنهي التنفيذ في أقل من 5 ميلي ثانية ودون استهلاك 1 ميجابايت من الذاكرة:

/**
 * موجه مسارات دقيق وسريع لمعالجة Webhooks بوابات الدفع
 * اعتراض الطلب عبر do_parse_request لتجاوز The Loop بالكامل
 */
add_filter( 'do_parse_request', 'az_fast_webhook_router', 10, 2 );

function az_fast_webhook_router( bool $continue_parsing, WP $wp ): bool {
    // جلب المسار المطلوب
    $request_uri = $_SERVER['REQUEST_URI'] ?? '';
    $path = trim( parse_url( $request_uri, PHP_URL_PATH ) ?? '', '/' );

    // إذا كان الرابط يطابق مسار الـ Webhook الخاص بنا
    if ( $path === 'az-api/payment-webhook' ) {
        // التأكد من أن نوع الطلب POST حصرياً
        if ( $_SERVER['REQUEST_METHOD'] !== 'POST' ) {
            status_header( 405 );
            wp_send_json_error( [ 'message' => 'Method Not Allowed' ], 405 );
            exit;
        }

        // قراءة البيانات الخام القادمة من البوابة
        $raw_payload = file_get_contents( 'php://input' );
        $signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

        // التحقق من صحة التوقيع الرقمي (HMAC Signature Verification)
        $secret_key = defined( 'AZ_PAYMENT_SECRET' ) ? AZ_PAYMENT_SECRET : 'fallback_secret_key';
        $computed_sig = hash_hmac( 'sha256', $raw_payload, $secret_key );

        if ( ! hash_equals( $computed_sig, $signature ) ) {
            status_header( 403 );
            wp_send_json_error( [ 'message' => 'Invalid Security Signature' ], 403 );
            exit;
        }

        $data = json_decode( $raw_payload, true );

        // تنفيذ التحديث في قاعدة البيانات مباشرة عبر $wpdb
        global $wpdb;
        $order_id = absint( $data['order_id'] ?? 0 );
        $status   = sanitize_text_field( $data['status'] ?? '' );

        if ( $order_id > 0 && $status === 'PAID' ) {
            $wpdb->update(
                "{$wpdb->prefix}az_orders",
                [ 'status' => 'completed', 'paid_at' => current_time( 'mysql' ) ],
                [ 'id' => $order_id ],
                [ '%s', '%s' ],
                [ '%d' ]
            );
        }

        // إرجاع استجابة نجاح سريعة للبوابة وإنهاء التنفيذ فوراً
        status_header( 200 );
        wp_send_json_success( [ 'received' => true, 'order_id' => $order_id ] );
        exit;
    }

    // لجميع الروابط الأخرى، دع ووردبريس يكمل معالجته الطبيعية
    return $continue_parsing;
}

6. الأمان في parse_request: الفرق بين public_query_vars و private_query_vars

من أهم المفاهيم الأمنية في معمارية النواة هو تقسيم المتغيرات إلى نوعين صارمين داخل كلاس WP:

لماذا هذا التقسيم في غاية الأهمية لحماية موقعك؟

لو كان ووردبريس يقبل المتغيرات الخاصة من شريط المتصفح، لكان بإمكان أي زائر كتابة: example.com/?post_type=any&posts_per_page=-1&post_status=draft، وسيقوم ووردبريس بعرض كافة المقالات المسودة والسرية المخفية في قاعدة البيانات للعامة، مع إسقاط السيرفر بنفاد الذاكرة! بفضل نظام الفلترة الصارم في parse_request()، يتم تجريد وحذف أي محاولة لتمرير متغيرات خاصة في الـ URL قبل تسليم الطلب لكائن WP_Query.

7. دراسة حالة واقعية: تخطي The Loop وفر 80% من الذاكرة في نظام تصدير الشهادات

في منصة تدريبية كبرى، تم بناء ميزة تتيح للطلاب تحميل شهادات التخرج بصيغة PDF عبر مسار مثل: /download-certificate/9874/. كان المطور السابق يعتمد على قالب صفحة ووردبريس عادي (Page Template). في كل مرة يطلب فيها طالب تحميل شهادته، كان النظام يقوم بالخطوات التالية:

• تشغيل النواة بالكامل.
• تشغيل كائن WP_Query والبحث في قاعدة البيانات وعمل Joins لجداول الميتا.
• تحميل ملفات القالب وهيدر وفوتر الصفحة الثابتة.
• استدعاء مكتبة توليد الـ PDF وطباعة الملف، مع استهلاك أكثر من 45 ميجابايت من الذاكرة RAM لكل طلب!

عندما تخرج دفعة تضم 2,000 طالب في نفس الساعة وبدأ الجميع في تنزيل شهاداتهم، سقط خادم PHP بالكامل تحت وطأة خطأ Fatal error: Allowed memory size exhausted.

التدخل المعماري عبر do_parse_request:

1. اعترضنا الطلب فوراً داخل فلتر do_parse_request بمجرد مطابقة مسار download-certificate.
2. أوقفنا معالجة parse_request وWP_Query بإرجاع false.
3. تحققنا من جلسة تسجيل دخول الطالب وصلاحياته بـ is_user_logged_in().
4. جلبنا بيانات الشهادة باستعلام $wpdb->get_row() مباشر ومفهرس لا يتجاوز 1 ميلي ثانية.
5. قمنا ببث ملف الـ PDF مباشرة للمتصفح مع ترويسة application/pdf وأنهينا السكربت بـ exit.

النتيجة بالأرقام: انخفض استهلاك الذاكرة من 45 ميجابايت إلى 6 ميجابايت فقط لكل طلب (توفير 86%)، وهبط زمن توليد الشهادة من 2.8 ثانية إلى 180 ميلي ثانية، واستطاع السيرفر خدمة كافة الطلاب المتخرجين في نفس اللحظة دون أدنى تأخير أو اختناق!

8. الوصايا العشر لمهندسي ووردبريس عند التعامل مع parse_request

عشان كودك المعماري يكون على أعلى مستوى من الكفاءة والأمان، التزم بالقواعد العشر التالية:

1. سجل متغيراتك في public_query_vars: لا تتوقع أن يقرأ ووردبريس متغيراً مخصصاً في الرابط إلا بعد تسجيله صراحة عبر فلتر query_vars.
2. استخدم do_parse_request للمسارات غير المرئية (Headless / Webhooks): وفر موارد السيرفر وتجاوز The Loop بالكامل للطلبات التي لا تتطلب عرض صفحات HTML.
3. لا تعتمد على متغيرات السيرفر الخام مباشرة: تجنب القراءة المباشرة من $_GET داخل القوالب؛ اعتمد دائماً على get_query_var() بعد تنقيتها بواسطة parse_request.
4. نظف معلمات الـ Query String من الرموز الخبيثة: استخدم دوال التعقيم مثل sanitize_key() وabsint() عند استلام المتغيرات في خطاف parse_request.
5. استخدم exit دائماً عند الرد المباشر في do_parse_request: لمنع ووردبريس من مواصلة تنفيذ باقي خطوات الإقلاع وتحميل القوالب بعد إرسال الرد.
6. احرص على أمان بوابات الـ Webhooks: تحقق دائماً من التوقيع الرقمي (Signature) وعناوين IP المصرح بها قبل معالجة أي طلب مالي في الـ Router.
7. لا تعدل مصفوفة query_vars عشوائياً: أي تغيير في المتغيرات داخل خطاف parse_request سيؤثر بشكل مباشر على استعلام WP_Query الذي يليه.
8. راقب مصفوفة $wp->matched_rule في بيئة التطوير: لمعرفة أي تعبير نمطي تم استخدامه بالضبط لتحليل الرابط الحالي وكشف أسباب أخطاء التوجيه.
9. افصل معالجة الطلبات الثقيلة عن مسار الزوار الرئيسي: استخدم مسارات مخصصة لتصدير ملفات Excel و PDF والتقارير لتفادي حجز خيوط معالجة واجهة الموقع.
10. التزم بإرسال ترويسات الاستجابة الدقيقة (HTTP Status Headers): استخدم status_header() لتعيين الرموز الصحيحة (200, 403, 404, 405) لمساعدة المتصفحات وبوابات الدفع على فهم نتيجة المعالجة بدقة.

9. التعامل مع Cloudflare و Reverse Proxies وحل حلقات التحويل اللانهائية

في البنية التحتية السحابية الحديثة، نادراً ما يتصل متصفح الزائر بالسيرفر مباشرة؛ في الغالب يمر الطلب عبر شبكة توزيع محتوى مثل Cloudflare أو موزع أحمال (Load Balancer مثل AWS ALB / Nginx Reverse Proxy). هنا يقع الكثير من المطورين في مشكلة مرعبة أثناء مرحلة parse_request: حلقة تحويل لانهائية (Infinite Redirect Loop: ERR_TOO_MANY_REDIRECTS)!

لماذا تحدث هذه الكارثة المعمارية؟

الزائر يطلب الموقع عبر https:// من Cloudflare، ولكن Cloudflare يتصل بسيرفرك الداخلي عبر http:// (Flexible SSL). عندما يصل الطلب إلى parse_request، يفحص ووردبريس متغير $_SERVER['HTTPS'] فيجده غير مفعل! فيعتقد ووردبريس أن الزائر دخل عبر بروتوكول غير آمن، فيقوم بإرسال تحويل 301 إلى https://! والمتصفح يطلب https مرة أخرى، وتتكرر الدورة إلى ما لا نهاية!

الحل الهندسي في ملف wp-config.php أو قبل parse_request:

// إعلام ووردبريس بوجود وسيط عكسي موثوق وتصحيح ترويسات الـ SSL:
if ( isset( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https' ) {
    $_SERVER['HTTPS'] = 'on';
}

if ( isset( $_SERVER['HTTP_CF_VISITOR'] ) && str_contains( $_SERVER['HTTP_CF_VISITOR'], 'https' ) ) {
    $_SERVER['HTTPS'] = 'on';
}

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

الأسئلة الشائعة حول parse_request وكلاس WP (FAQ)

المصادر والمراجع الرسمية المعتمدة

أكمل المسار

• فهرس المستويات والمقالات
• السابق: شرح WP_Rewrite: توليد القواعد وتشخيص التعارض
• التالي: متغيرات الاستعلام في ووردبريس: تسجيل Query Vars والتحقق من القيم
• مسار تعلم ووردبريس وGutenberg