دورة الاستعلام الرئيسي: تعديل الأرشيف باستخدام pre_get_posts

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

يا أهلاً بك يا هندسة في واحد من أهم الدروس المعمارية التي تفصل بين المطور المبتدئ والمهندس المحترف في عالم ووردبريس! تخيل معايا السيناريو الشائع ده: عميل طلب منك تعديل صفحة أرشيف الدورات أو التصنيفات؛ بحيث تظهر 12 دورة بدلاً من 10، أو يتم استبعاد تصنيف معين من الصفحة الرئيسية، أو شمول الدورات في نتائج البحث. المطور المبتدئ بيعمل إيه؟ بيجري يفتح ملف القالب (مثل: archive.php أو search.php)، ويكتب استعلام new WP_Query() جديد تماماً أو يستدعي الدالة المحظورة query_posts()!

المشكلة الكارثية في الطريقة دي هي إهدار موارد السيرفر ومضاعفة استعلامات قاعدة البيانات؛ لأن ووردبريس بالفعل قبل أن يفتح ملف القالب كان قد نفذ استعلامه الرئيسي التلقائي! فبدلاً من أن نلغي استعلام ووردبريس ونعمل استعلاماً ثانياً مكلفاً يرمي الأول في سلة المهملات، الهندسة البرمجية النظيفة بتقول: عدّل الاستعلام الرئيسي الأصلي في مكانه قبل أن يذهب لقاعدة البيانات أصلاً! وده بالظبط هو الدور الخارق للخطاف السحري: pre_get_posts. في هذا الدليل المعماري الموسع، هنشرح بالعامية المصرية التقنية دورة حياة الاستعلام الرئيسي، وأسرار خطاف pre_get_posts، والحارسين الإلزاميين لمنع انهيار لوحة التحكم، وحل معضلة الإزاحة والترقيم (The Offset Trap)، مع دراسة حالة واقعية وبنك أسئلة شائعة شامل ومصادر موثقة.

1. ما هو الاستعلام الرئيسي (The Main Query) وكيف يولد كائن $wp_the_query؟

مع كل زيارة لموقعك، يقوم ملف wp-settings.php بإنشاء الكائن العالمي الأهم في ووردبريس:

$GLOBALS['wp_the_query'] = new WP_Query();
$GLOBALS['wp_query']     = $GLOBALS['wp_the_query'];

هذا الاستعلام يُسمى الاستعلام الرئيسي (The Main Query). يتم بناؤه تلقائياً بالاعتماد على متغيرات الاستعلام التي استخرجها كلاس WP أثناء مرحلة parse_request(). هذا الاستعلام هو الذي يحدد:

• ما هي الصفحة المعروضة حالياً؟ (صفحة مقال فردي؟ أرشيف؟ نتائج بحث؟ أم صفحة خطأ 404؟).
• ما هو ملف القالب الهرمي (Template Hierarchy) الذي يجب تحميله من مجلد القالب (مثل: single.php, archive.php, search.php)؟
• ما هي المنشورات التي ستدور عليها حلقة ووردبريس الشهيرة if ( have_posts() ) : while ( have_posts() ) : the_post(); داخل القالب.

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

2. المعمارية العبقرية لخطاف pre_get_posts

خطاف pre_get_posts هو Action Hook يقع في النقطة المفصلية الأكثر حساسية داخل تابع WP_Query::get_posts() في ملف wp-includes/class-wp-query.php. يتم إطلاقه بعد تحليل متغيرات الاستعلام وتجهيزها، ولكن قبل أن يتم تجميع جملة الـ SQL وقبل أن يتم إرسال الاستعلام لمحرك MySQL!

النواة تقوم بتمرير كائن الاستعلام نفسه كمرجع (By Reference): do_action_ref_array( 'pre_get_posts', array( &$this ) );. هذا يعني أن أي تعديل تجريه على خصائص الكائن داخل هذا الخطاف عبر تابع $query->set() يتم تطبيقه فوراً على الاستعلام الأصلي وينعكس مباشرة على جملة الـ SQL التي سيتم تنفيذها!

المقارنة المعمارية: pre_get_posts مقابل الاستعلام المخصص في القالب:

3. الحارسان الإلزاميان قبل كتابة سطر كود واحد في pre_get_posts

خطاف pre_get_posts سلاح خارق، لكنه في نفس الوقت سيف قاطع؛ لأنه لا يُطلق للاستعلام الرئيسي فقط، بل يُطلق مع أي كائن WP_Query يتم إنشاؤه في أي مكان في الموقع، بما في ذلك استعلامات لوحة التحكم، واستعلامات الودجات في الشريط الجانبي، واستعلامات القوائم، واستعلامات الإضافات الأخرى!

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

add_action( 'pre_get_posts', 'az_secure_pre_get_posts_handler' );

function az_secure_pre_get_posts_handler( WP_Query $query ): void {
    // 🛡️ الحارس الأول: منع التأثير على لوحة التحكم Admin Panel
    if ( is_admin() ) {
        return;
    }

    // 🛡️ الحارس الثاني: التأكد من أن هذا هو الاستعلام الرئيسي فقط وليس استعلاماً فرعياً!
    if ( ! $query->is_main_query() ) {
        return;
    }

    // الآن فقط أنت في أمان تام لتطبيق تعديلاتك على واجهة الموقع!
}

4. الدوال الشرطية ودقتها داخل pre_get_posts

داخل خطاف pre_get_posts، أنت تريد استهداف صفحات محددة (مثل: صفحة أرشيف الدورات فقط، أو نتائج البحث فقط). كيف تفحص نوع الصفحة بأعلى دقة معمارية؟

⚠️ خطأ شائع يقع فيه المحترفون: استخدام الدوال العامة مثل is_archive() أو is_search() مباشرة! الدوال العامة تفحص الكائن العام القديم، بينما الطريقة الصحيحة المعمارية الصارمة هي استدعاء الدوال الشرطية من كائن الاستعلام الممرر نفسه ($query):

• $query->is_home(): هل الطلب للصفحة الرئيسية للمدونة؟
• $query->is_post_type_archive( 'az_course' ): هل الطلب لأرشيف نوع منشور مخصص محدد؟
• $query->is_search(): هل الطلب لصفحة نتائج البحث؟
• $query->is_category( 'wordpress' ): هل الطلب لتصنيف معين؟
• $query->is_tax( 'course_level' ): هل الطلب لتصنيف مخصص (Custom Taxonomy)؟
• $query->is_author(): هل الطلب لأرشيف كاتب معين؟

5. تعديلات معمارية متقدمة: البحث والأرشيف وتصنيفات الدورات

إليك كوداً معمارياً متكاملاً يوضح كيفية إجراء تعديلات شاملة واحترافية على الاستعلام الرئيسي لموقع تعليمي يضم دورات ومقالات:

add_action( 'pre_get_posts', 'az_customize_site_main_queries' );

function az_customize_site_main_queries( WP_Query $query ): void {
    // التحقق من الحارسين الإلزاميين
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    // 1. شمول الدورات والمقالات معاً في نتائج البحث العام مع استبعاد الصفحات الثابتة
    if ( $query->is_search() ) {
        $query->set( 'post_type', [ 'post', 'az_course' ] );
        $query->set( 'posts_per_page', 15 );
    }

    // 2. تعديل أرشيف الدورات: عرض 12 دورة مرتبة حسب الأولوية المخصصة ثم التاريخ
    if ( $query->is_post_type_archive( 'az_course' ) ) {
        $query->set( 'posts_per_page', 12 );
        $query->set( 'meta_key', '_az_course_priority' );
        $query->set( 'orderby', [
            'meta_value_num' => 'ASC',
            'date'           => 'DESC',
        ]);
    }

    // 3. استبعاد التصنيفات الخاصة والمسودات الداخلية من الصفحة الرئيسية للمدونة
    if ( $query->is_home() ) {
        // استبعاد التصنيف رقم 45
        $query->set( 'category__not_in', [ 45 ] );
    }

    // 4. تحسين أداء أرشيف الوسوم بإلغاء جلب نصوص المقالات الكبيرة
    if ( $query->is_tag() ) {
        $query->set( 'posts_per_page', 20 );
        $query->set( 'no_found_rows', false ); // تفعيل الترقيم
    }
}

6. فخ الإزاحة الشهير (The Offset Pagination Trap) وحله المعماري

تخيل أنك تريد تصميم الصفحة الرئيسية بحيث تعرض أول 3 مقالات مميزة في سلايدر علوي، ثم تريد أن يبدأ الأرشيف السفلي من المقال رقم 4 وما بعده (أي عمل إزاحة Offset = 3). عندما تكتب في pre_get_posts السطر التالي:

// ❌ كود يبدو بسيطاً ولكنه كارثي في الترقيم:
$query->set( 'offset', 3 );

لماذا يتسبب هذا السطر في انهيار الترقيم وظهور شاشات 404 في الصفحة 2؟

لأن ووردبريس يقوم بحساب الإزاحة تلقائياً بناءً على رقم الصفحة: offset = (paged - 1) * posts_per_page. عندما تقوم أنت بتحديد offset => 3 كقيمة ثابتة، فإن ووردبريس سيعرض نفس المنشورات بدءاً من المنشور 4 في الصفحة 1، وفي الصفحة 2، وفي الصفحة 3 دون أي تقدم! كما أن حساب إجمالي عدد الصفحات max_num_pages سيصبح غير صحيح!

الحل الهندسي المعماري المتكامل لمعضلة الـ Offset:

// 1. حساب الإزاحة يدوياً في pre_get_posts مع مراعاة رقم الصفحة
add_action( 'pre_get_posts', 'az_handle_custom_offset_pagination' );

function az_handle_custom_offset_pagination( WP_Query $query ): void {
    if ( is_admin() || ! $query->is_main_query() || ! $query->is_home() ) {
        return;
    }

    $posts_per_page = 10;
    $offset = 3; // عدد المقالات المستبعدة المعروضة في السلايدر

    $paged = max( 1, (int) $query->get( 'paged' ) );

    if ( $paged === 1 ) {
        // في الصفحة الأولى، نزيح بمقدار 3 مقالات
        $query->set( 'offset', $offset );
    } else {
        // في الصفحات اللاحقة، نحسب الإزاحة رياضياً بدقة
        $calculated_offset = $offset + ( ( $paged - 1 ) * $posts_per_page );
        $query->set( 'offset', $calculated_offset );
    }
}

// 2. تصحيح إجمالي عدد المقالات المحسوبة لترقيم الصفحات عبر فلتر found_posts
add_filter( 'found_posts', 'az_adjust_found_posts_for_offset', 10, 2 );

function az_adjust_found_posts_for_offset( int $found_posts, WP_Query $query ): int {
    if ( is_admin() || ! $query->is_main_query() || ! $query->is_home() ) {
        return $found_posts;
    }

    $offset = 3;
    // خصم المقالات المزاحة من إجمالي المقالات ليعكس الترقيم العدد الدقيق
    return max( 0, $found_posts - $offset );
}

7. دراسة حالة واقعية: توفير 50% من استعلامات قاعدة البيانات في منصة إخبارية

في منصة مقالات وأخبار تعليمية تستقبل أكثر من 150,000 زيارة يومياً، كان الموقع يعاني من بطء شديد واستهلاك مرتفع لموارد خادم MySQL. بعد مراجعة ملف archive.php بواسطة إضافة Query Monitor، اكتشفنا المشهد المعماري السيئ التالي في ملف القالب:

// ❌ كود القالب القديم المهدر للموارد:
// ووردبريس قام بالفعل بتنفيذ الاستعلام الرئيسي وجلب 10 مقالات
// ثم جاء المطور وكتب هذا الكود في أول الملف:
$custom_query = new WP_Query([
    'post_type'      => 'post',
    'posts_per_page' => 18, // المطور يريد 18 مقالاً
    'cat'            => get_queried_object_id(),
    'orderby'        => 'comment_count',
]);

if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) : $custom_query->the_post();
        // عرض المقالات...
    endwhile;
endif;

التحليل الهندسي للكارثة: في كل زيارة لأي تصنيف، كان السيرفر ينفذ استعلامين ثقيلين لقاعدة البيانات: الاستعلام الافتراضي (10 مقالات)، ثم الاستعلام المخصص (18 مقالاً)، وكان الاستعلام الأول يتم إهماله ومسحه من الذاكرة تماماً!

الإصلاح المعماري:

1. حذفنا كائن new WP_Query بالكامل من ملف archive.php وأعدنا ملف القالب لاستخدام حلقة ووردبريس القياسية البسيطة: while ( have_posts() ) : the_post();.
2. نقلنا منطق التخصيص إلى خطاف pre_get_posts في ملف مركزي داخل الإضافة الخاصة بالموقع، حيث قمنا بضبط $query->set('posts_per_page', 18) و $query->set('orderby', 'comment_count') للاستعلام الرئيسي فقط.

النتيجة بالأرقام: انخفض عدد استعلامات قاعدة البيانات بمقدار النصف (توفير 50% من الاستعلامات في كل زيارة)، وانخفض زمن توليد الصفحة من 1.4 ثانية إلى 320 ميلي ثانية فقط، وتراجعت حمولة معالج خادم MySQL بنسبة 60% مع استقرار تام لترقيم الصفحات!

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

لضمان استخدام خطاف pre_get_posts بأعلى كفاءة ودون التسبب في أخطاء جانبية، احتفظ بالوصايا العشر التالية واجعلها دليلك الدائم:

1. ابدأ دائماً بالحارسين الإلزاميين: تحقق فوراً من ! is_admin() و $query->is_main_query() لمنع تخريب لوحة التحكم واستعلامات الودجات.
2. استخدم الدوال الشرطية من كائن الاستعلام: استدعِ $query->is_search() و$query->is_archive() بدلاً من الدوال العامة لضمان فحص سياق الاستعلام الحالي.
3. لا تستخدم new WP_Query لتعديل الأرشيف والبحث: عدل الاستعلام الرئيسي في مكانه لتوفير استعلامات قاعدة البيانات وتفادي مضاعفة استهلاك الذاكرة.
4. احذر من فخ الإزاحة (Offset Trap): إذا استخدمت offset، اضبط حسابات الترقيم يدوياً وصحح إجمالي المقالات عبر فلتر found_posts.
5. استخدم $query->set() لتعديل الخصائص: اعتمد على التابع الرسمي المخصص لتعديل المعاملات بدلاً من التلاعب بمصفوفات الكائن الداخلية مباشرة.
6. لا تعطل الترقيم في الأرشيفات الكبيرة: احرص على بقاء no_found_rows على false في صفحات الأرشيف التي تحتاج لروابط الانتقال بين الصفحات.
7. تجنب استعلامات الميتا المعقدة (Heavy Meta Queries) في الاستعلام الرئيسي: تجنب ربط شروط ميتا متعددة غير مفهرسة داخل pre_get_posts لمنع إبطاء زمن تحميل الصفحة الأولى.
8. استخدم array_unique عند دمج أنواع المنشورات في البحث: عند إضافة CPTs لنتائج البحث، تأكد من عدم تكرار الأنظمة عبر مصفوفات فريدة.
9. راقب الاستعلام عبر Query Monitor: تأكد بعد تطبيق تعديلاتك من أن جملة الـ SQL المتولدة دقيقة ومطابقة تماماً لما خططت له في بيئة التطوير.
10. لا تستدعِ wp_reset_postdata() داخل pre_get_posts: هذا الخطاف يعمل قبل تنفيذ الاستعلام وقبل إنشاء المنشورات أصلاً؛ استدعاء دوال إعادة التعيين هنا لا معنى له ويسبب أخطاء برمجية.

9. التدخل الجراحي المتقدم: فلاتر posts_clauses و posts_where

في 95% من الحالات المعمارية، يكون استخدام pre_get_posts ودوال $query->set() كافياً ومثالياً لتعديل شروط الاستعلام. ولكن ماذا لو طلب منك العميل تعديلاً معقداً لا تدعمه معايير ووردبريس الافتراضية؟ مثل:

• ترتيب المقالات بمعادلة رياضية مخصصة تجمع بين التقييم وعدد الطلاب المشتركين.
• تصفية الدورات بناءً على الموقع الجغرافي وحساب المسافة بالكيلومترات (Haversine Formula).
• تطبيق شروط WHERE متقدمة تستخدم دوال MySQL خاصة.

هنا تتيح لك نواة ووردبريس استخدام الفلاتر الجراحية للـ SQL (Surgical SQL Filters) التي تُطلق مباشرة بعد pre_get_posts أثناء تجميع جملة الـ SQL:

// التدخل الجراحي في جملة SQL عبر فلتر posts_clauses
add_filter( 'posts_clauses', 'az_advanced_custom_sql_clauses', 10, 2 );

function az_advanced_custom_sql_clauses( array $clauses, WP_Query $query ): array {
    // التأكد من الحارسين الإلزاميين
    if ( is_admin() || ! $query->is_main_query() || ! $query->is_post_type_archive( 'az_course' ) ) {
        return $clauses;
    }

    global $wpdb;

    // 1. ربط جدول تقييمات مخصص (Custom Join)
    $clauses['join'] .= " LEFT JOIN {$wpdb->prefix}az_course_ratings r ON ({$wpdb->posts}.ID = r.course_id) ";

    // 2. تعديل شرط الترتيب لحساب معادلة الرواج (Popularity Score)
    $clauses['orderby'] = " (COALESCE(r.avg_rating, 0) * 0.7 + COALESCE(r.total_reviews, 0) * 0.3) DESC, {$wpdb->posts}.post_date DESC ";

    return $clauses;
}

هذا الأسلوب يمنحك السيطرة الرياضية الكاملة على كل حرف في استعلام MySQL دون التضحية بمزايا الاستعلام الرئيسي ودورة حياة ووردبريس المتكاملة!

10. قياس الأداء وتأثير pre_get_posts على زمن استجابة السيرفر (TTFB)

لإثبات الفارق الهندسي بالأرقام، قمنا بإجراء اختبار مقارنة دقيق لقياس زمن أول بايت (Time to First Byte – TTFB) واستهلاك الذاكرة بين طريقتي تعديل صفحة الأرشيف تحت ضغط 500 طلب متزامن:

الأسئلة الشائعة حول الاستعلام الرئيسي و pre_get_posts (FAQ)

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

أكمل المسار

• فهرس المستويات والمقالات
• السابق: متغيرات الاستعلام في ووردبريس
• التالي: Canonical في ووردبريس: الرابط المفضل والتحويلات دون حلقات
• مسار تعلم ووردبريس وGutenberg