الدوال الشرطية في ووردبريس: التوقيت الصحيح وحدود استخدامها

هذا المقال رقم 17 من 100 في سلسلة معمارية ووردبريس من الأساسيات إلى المشروع النهائي، ضمن المستوى 3: سياق العرض وبيانات المنشور (The Loop & Post Model).

يا أهلاً بك يا هندسة في واحد من أكثر المفاهيم المعمارية التي تبدو شديدة السهولة والبراءة ظاهرياً، ولكنها تتسبب في أعقد الأخطاء البرمجية الخفية في تاريخ مشاريع ووردبريس: الدوال الشرطية (Conditional Tags)! كلنا بنستخدم دوال زي: is_single(), is_page(), is_home(), is_front_page(), is_archive() لتحديد متى يظهر شريط جانبي، أو متى يتم تحميل ملف ستايل معين، أو متى يظهر بانر إعلاني مخصص.

المشكلة الكبرى ليست في “ماذا تفعل هذه الدوال”، بل في: “متى تستيقظ هذه الدوال برمجياً؟”. الكثير من المطورين يكتبون شرطاً مثل: if ( is_single() ) في ملف functions.php مباشرة أو داخل خطاف init، ويتفاجأون بأن الشرط يرجع دائماً false حتى لو كان الزائر فاتح مقال فردي بالفعل! في هذا الدليل المعماري الموسع، هنشرح بالعامية المصرية التقنية المعمارية التحتية للدوال الشرطية؛ هنفهم التوقيت الزمني الدقيق لولادتها في الذاكرة، والفرق بين الدوال العامة ودوال كائن $query، وحل اللغز التاريخي بين is_home و is_front_page، مع تطبيق عملي لبناء محمل أصول مشروط ذكي خفض وزن الصفحات بنسبة 70%، ودراسة حالة حقيقية، وبنك أسئلة شائعة شامل ومصادر موثقة.

1. ما هي الدوال الشرطية (Conditional Tags) في ووردبريس؟

الدوال الشرطية هي مجموعة من الدوال المنطقية الجاهزة (Boolean Helper Functions) المعرفة في ملف wp-includes/query.php. وظيفتها الإجابة بنعم أو لا (true أو false) على سؤال واحد: “ما هو نوع الصفحة أو السياق الذي يتصفحه الزائر حالياً في هذه اللحظة؟”.

خلف الكواليس، هذه الدوال ليست دوال سحرية؛ بل هي مجرد أغلفة رقيقة (Thin Wrappers) تقرأ الخصائص المنطقية المحفوظة داخل كائن الاستعلام الرئيسي العام $GLOBALS['wp_query']. فعندما تستدعي is_single()، ما تفعله النواة حقيقة هو: return $GLOBALS['wp_query']->is_single();!

2. التوقيت البرمجي الحاسم (Timing is Everything): متى تستيقظ الدوال الشرطية؟

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

تعال نتتبع الترتيب الزمني لخطافات إقلاع ووردبريس لنعرف متى تصبح هذه الدوال صالحة للاستخدام:

1. plugins_loaded: ❌ ميتة تماماً (تعيد false دائماً لأن النواة لم تفحص الرابط بعد).
2. setup_theme: ❌ ميتة تماماً.
3. init: ❌ ميتة تماماً (الرابط لم يتم تفكيكه بعد ولم يستعلم ووردبريس عن المقال).
4. wp_loaded: ❌ ميتة تماماً.
5. parse_request: ⚠️ تبدأ في التعرف المبدئي على نوع الطلب ولكن لم يتم جلب المنشورات.
6. pre_get_posts: ⚠️ صالحة فقط عبر كائن الاستعلام الممرر: $query->is_search() (لا تستخدم الدوال العامة هنا!).
7. wp: ✅ ولادة الدوال الشرطية الرسمية! (هنا اكتمل استعلام قاعدة البيانات وأصبحت كل الدوال العامة صالحة للعمل 100%).
8. template_redirect: ✅ صالحة تماماً (الوقت المثالي للتحويلات المشروطة وفحص الصلاحيات).
9. wp_enqueue_scripts: ✅ صالحة تماماً (الوقت المثالي لتحميل ملفات CSS وJS المشروطة).
10. ملفات القالب (Header, Footer, Single): ✅ صالحة وتعمل بكامل طاقتها.

إذا كتبت في ملف functions.php الخاص بقالبك:

// ❌ خطأ معماري فادح يقع فيه الكثيرون:
if ( is_single() ) {
    // هذا الكود لن يتنفذ أبداً في حياته!
    // لأن functions.php يتم تنفيذه في مرحلة مبكرة جداً قبل أن يعرف ووردبريس ما هي الصفحة المطلوبة!
}

// ✅ الطريقة المعمارية الصحيحة بربط الكود بالخطاف المناسب:
add_action( 'wp_enqueue_scripts', function(): void {
    if ( is_singular( 'az_course' ) ) {
        // هنا الكود يعمل بدقة متناهية لأن الاستعلام مكتمل!
        wp_enqueue_style( 'az-course-single', get_stylesheet_directory_uri() . '/css/course.css' );
    }
});

3. الفهرس الشامل لأهم الدوال الشرطية وفك الألغاز التاريخية

تحتفظ النواة بعشرات الدوال الشرطية؛ إليك تصنيفها المعماري الدقيق وفك أشهر الألغاز التي تسبب حيرة المطورين:

اللغز التاريخي الأكبر: ما الفرق بين is_front_page() و is_home()؟

هذا اللغز هو بؤرة اللخبطة رقم 1 في ووردبريس؛ احفظ هذه القاعدة البسيطة:

• is_front_page(): تفحص الصفحة الرئيسية الحقيقية للموقع (أي ما يراه الزائر عند كتابة domain.com)، سواء كانت تعرض أحدث المقالات أو صفحة ثابتة ثابتة اختارها المدير من الإعدادات.
• is_home(): تفحص صفحة أرشيف مقالات المدونة (Blog Posts Index)! لو كان الموقع مضبوطاً على عرض أحدث المقالات في الرئيسية، ستكون is_front_page() و is_home() كلاهما true. ولكن لو حدد المدير صفحة ثابتة للرئيسية (مثل صفحة ترحيبية)، وصفحة أخرى اسمها “المدونة” للمقالات؛ فعند زيارة الصفحة الرئيسية ستكون is_front_page() هي true و is_home() ستكون false! وعند فتح صفحة المدونة ستكون is_home() هي true و is_front_page() ستكون false!

المقارنة المعمارية: is_single() مقابل is_page() مقابل is_singular()

4. الدوال الشرطية العامة مقابل دوال كائن الاستعلام ($query->is_*)

هذه النقطة تمثل علامة فارقة بين مهندس النظم والمطور العادي. عند استخدام خطافات الاستعلام مثل pre_get_posts، لا تستخدم الدوال العامة أبداً! لماذا؟

// ❌ خطأ معماري خفي داخل pre_get_posts:
add_action( 'pre_get_posts', function( $query ) {
    if ( is_search() ) { // خطأ! تفحص الكائن العام القديم!
        // ...
    }
});

// ✅ الطريقة المعمارية الصارمة الدقيقة:
add_action( 'pre_get_posts', function( WP_Query $query ) {
    if ( $query->is_search() ) { // ممتاز! تفحص سياق الكائن الحالي قيد المعالجة!
        $query->set( 'post_type', [ 'post', 'az_course' ] );
    }
});

الدالة العامة تفحص الكائن العام المسجل في $GLOBALS['wp_query']، بينما عند بناء استعلام مخصص أو التدخل في pre_get_posts، يكون الكائن قيد المعالجة لم يتم تعيينه ككائن عام بعد، ولذا فإن استدعاء التابع من كائن الاستعلام الممرر مباشرة $query->is_*() هو الضمان الوحيد لدقة الشرط!

5. تطبيق عملي: بناء محمل أصول مشروط وذكي (Conditional Asset Enqueue Engine)

أكبر سبب لبطء مواقع ووردبريس وسقوطها في اختبارات Google Core Web Vitals هو التحميل العشوائي لملفات الـ CSS والـ JS؛ تجد إضافة الفورم تحمل ملفاتها في كل صفحات الموقع، ومكتبة سلايدر ثقيلة يتم تحميلها في صفحة اتصل بنا التي لا تحتوي على أي سلايدر!

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

/**
 * محمل الأصول المشروط الذكي لأكاديمية أبو زيد
 * تحميل الملفات حصرياً في الصفحات التي تحتاجها لتسريع Core Web Vitals
 */
add_action( 'wp_enqueue_scripts', 'az_smart_conditional_assets_loader', 99 );

function az_smart_conditional_assets_loader(): void {
    $theme_uri = get_stylesheet_directory_uri();
    $ver = '2.5.0';

    // 1. تحميل مكتبة الفيديو والمشغل المتقدم حصرياً في صفحات الدروس الفردية
    if ( is_singular( 'az_lesson' ) ) {
        wp_enqueue_style( 'az-video-player-style', $theme_uri . '/css/player.css', [], $ver );
        wp_enqueue_script( 'az-video-player-script', $theme_uri . '/js/player.js', [ 'jquery' ], $ver, true );
    }

    // 2. تحميل مكتبة الفلاتر وتصفية المنتجات في صفحات الأرشيف والمتجر فقط
    if ( is_post_type_archive( 'az_course' ) || is_tax( [ 'az_course_level', 'az_course_category' ] ) ) {
        wp_enqueue_style( 'az-filter-ui', $theme_uri . '/css/filters.css', [], $ver );
        wp_enqueue_script( 'az-filter-engine', $theme_uri . '/js/filters.js', [], $ver, true );
    }

    // 3. إلغاء تحميل ملفات إضافات النماذج الثقيلة في كافة الصفحات ما عدا صفحة اتصل بنا!
    if ( ! is_page( 'contact-us' ) ) {
        wp_dequeue_style( 'contact-form-7' );
        wp_dequeue_script( 'contact-form-7' );
    }

    // 4. تحميل أكواد بوابة الدفع المشفرة في صفحة إتمام الطلب حصرياً
    if ( function_exists( 'is_checkout' ) && is_checkout() ) {
        wp_enqueue_style( 'az-checkout-secure', $theme_uri . '/css/checkout.css', [], $ver );
    }
}

6. الحالات الشاذة والأفخاخ الخفية في فحص الصفحات الشجرية

في الصفحات الثابتة الشجرية (Hierarchical Pages: Parent and Child Pages)، دالة is_page( 'services' ) ستعيد true لصفحة الخدمات الرئيسية، ولكن ماذا لو كان لديك صفحة فرعية تابعة لها مثل: /services/wordpress-dev/؟

دالة is_page( 'services' ) ستعيد false للصفحة الفرعية! وإذا كنت تريد تطبيق شرط يشمل الصفحة الأب وجميع أبنائها وأحفادها التابعين لها برمجياً، فإليك الدالة المساعدة المعمارية التي تحل هذه المعضلة:

/**
 * دالة شرطية مخصصة للتحقق من الصفحة الحالية أو أي من أبنائها
 */
function az_is_tree( int|string $page_id_or_slug ): bool {
    global $post;

    if ( ! is_page() || ! is_object( $post ) ) {
        return false;
    }

    // تحويل الاسم اللطيف لمعرف رقمي إن لزم الأمر
    $target_id = is_numeric( $page_id_or_slug ) ? (int) $page_id_or_slug : 0;
    if ( ! $target_id ) {
        $page = get_page_by_path( $page_id_or_slug );
        $target_id = $page ? $page->ID : 0;
    }

    // هل هذه هي الصفحة المستهدفة نفسها؟
    if ( $post->ID === $target_id ) {
        return true;
    }

    // هل الصفحة الحالية ابنة مباشرة أو حفيدة للصفحة المستهدفة؟
    $ancestors = get_post_ancestors( $post->ID );
    return in_array( $target_id, $ancestors, true );
}

// الاستخدام العملي: يغطي صفحة services وكل الصفحات المتفرعة منها تلقائياً!
if ( az_is_tree( 'services' ) ) {
    // تطبيق كود الشريط الجانبي الخاص بالخدمات
}

7. دراسة حالة واقعية: كيف حللنا لغز تحميل مكتبة ضخمة في كافة صفحات الموقع؟

في منصة عقارية كبرى تضم أكثر من 80,000 صفحة، كان الموقع يعاني من بطء شديد وهبوط تقييم Google PageSpeed إلى 38/100 على الهواتف المحمولة. وبفحص شبكة التحميل، لاحظنا أن هناك مكتبة خرائط تفاعلية ثلاثية الأبعاد بحجم 3.4 ميجابايت يتم تحميلها في كافة صفحات الموقع بلا استثناء، بما في ذلك المقالات الفردية وسياسة الخصوصية!

التشخيص والتحليل الهندسي:

عند مراجعة كود ملف functions.php، وجدنا المطور السابق قد كتب الكود التالي:

// كود المطور القديم المسبب للكارثة:
add_action( 'init', function() {
    // الكارثة المعمارية هنا:
    // في خطاف init، دالة is_singular('property') ترجع دائماً false!
    // ولذلك قام المطور بحذف الشرط تماماً وتركه يحمل في كل الصفحات ظناً منه أن الدالة لا تعمل!
    wp_enqueue_script( 'heavy-map-3d', get_template_directory_uri() . '/js/map.js' );
});

سبب المشكلة: المطور حاول استخدام الدالة الشرطية في خطاف init المبكر؛ فلم تعمل معه وأعادت false، وبدلاً من أن يفهم توقيت ولادة الدوال الشرطية، استسلم وقام بتحميل المكتبة الضخمة على مستوى الموقع بالكامل!

الإصلاح المعماري: قمنا بنقل الكود فوراً إلى خطاف wp_enqueue_scripts السليم مع تفعيل الفحص الشرطي الدقيق if ( is_singular( 'property' ) ).

النتيجة بالأرقام: تم حذف 3.4 ميجابايت من حجم 98% من صفحات الموقع، وقفز تقييم PageSpeed من 38 إلى 94/100 فوراً، وانخفض استهلاك بيانات السيرفر بأكثر من 450 جيجابايت شهرياً!

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

لضمان استخدام الدوال الشرطية بأعلى دقة معمارية وتجنب الأخطاء الخفية، التزم بالوصايا العشر التالية:

1. لا تستخدم الدوال الشرطية قبل خطاف wp: تجنب استدعاءها في init أو plugins_loaded لأن النواة لم تنتهِ من تحليل الاستعلام بعد.
2. فرق بين is_front_page و is_home: تذكر أن is_front_page تفحص الصفحة الرئيسية للموقع، بينما is_home تفحص صفحة أرشيف مقالات المدونة.
3. استخدم دوال الكائن الممرر داخل pre_get_posts: اعتمد على $query->is_search() بدلاً من الدالة العامة is_search() لضمان فحص سياق الكائن الحالي.
4. وظف الدوال الشرطية لتحميل الأصول (Conditional Enqueue): لا تحمل مكتبات الـ CSS والـ JS إلا في الصفحات التي تستخدمها فعلياً لتسريع Core Web Vitals.
5. مرر المعرفات والأسماء لتقليص نطاق الفحص: استخدم is_page( 'contact' ) أو is_singular( 'az_course' ) بدلاً من الفحص الفضفاض العام.
6. احذر من فحص الصفحات الشجرية: تذكر أن is_page( 'parent' ) لا تشمل الصفحات الفرعية التابعة لها؛ استخدم دالة فحص شجرة الصفحات المخصصة.
7. استفد من wp_doing_ajax() و wp_is_json_request(): لتفادي تنفيذ أكواد الواجهة الرسومية أثناء معالجة طلبات الأجاكس وواجهات البرمجة.
8. افحص وجود دالة إضافات الطرف الثالث قبل استدعائها: مثل استخدام if ( function_exists('is_woocommerce') && is_woocommerce() ) لتفادي انهيار الموقع في حال تعطيل الإضافة.
9. راقب الدوال الشرطية في بيئة التطوير عبر Query Monitor: حيث تعرض لك الأداة جدولاً بكافة الدوال الشرطية التي تنطبق على الصفحة الحالية (True Conditionals).
10. لا تعتمد على الدوال الشرطية داخل ملفات REST API Controller: لأن سياق الطلب في واجهات التطبيقات لا يمر بدورة قوالب ووردبريس التقليدية.

9. معمارية بناء دوال شرطية مخصصة فائقة الأداء (Custom Conditional Tags)

في المشاريع الضخمة، الدوال الشرطية الافتراضية للنواة لا تغطي كافة متطلبات منطق العمل (Business Logic). قد تحتاج دوال متخصصة مثل: az_is_course_lesson()، أو az_is_vip_student()، أو az_is_exam_in_progress().

المطور غير المحترف يكتب الدالة الشرطية بحيث تنفذ استعلام SQL مع كل استدعاء! فإذا استدعيت الدالة في الهيدر، وفي السايدبار، وفي الفوتر، سيقوم السيرفر بضرب قاعدة البيانات 3 مرات بنفس الاستعلام! المعمارية الهندسية النظيفة تعتمد على التخزين الساكن في الذاكرة (Static Runtime Caching):

/**
 * معمارية بناء دالة شرطية مخصصة مع كاش داخلي في الذاكرة
 */
function az_is_active_diploma_student(): bool {
    // مصفوفة ساكنة في الذاكرة RAM للطلب الحالي فقط
    static $is_active = null;

    // إذا تم حساب الشرط مسبقاً في هذا الطلب، أعد النتيجة فوراً دون استعلام!
    if ( null !== $is_active ) {
        return $is_active;
    }

    if ( ! is_user_logged_in() ) {
        $is_active = false;
        return false;
    }

    global $wpdb;
    $user_id = get_current_user_id();

    // فحص الاشتراك في قاعدة البيانات لمرة واحدة فقط
    $has_enrollment = (bool) $wpdb->get_var(
        $wpdb->prepare(
            "SELECT id FROM {$wpdb->prefix}az_enrollments WHERE user_id = %d AND status = 'active' LIMIT 1",
            $user_id
        )
    );

    $is_active = $has_enrollment;
    return $is_active;
}

10. فخ التخزين المؤقت الكامل (Full Page Cache) والدوال الشرطية

عند استخدام حلول التخزين المؤقت للصفحات الكاملة على مستوى السيرفر (مثل Nginx FastCGI Cache, LiteSpeed, أو Cloudflare Edge Caching)، يجب الانتباه الشديد إلى أن خادم الكاش يقوم بتقديم نسخة HTML ثابتة ومسبقة التوليد للزوار دون تشغيل كود PHP على الإطلاق!

ما هي الدوال الشرطية التي تنهار وتفشل مع Full Page Cache؟

• is_user_logged_in(): إذا كش السيرفر صفحة تحتوي على شرط للمستخدم المسجل، قد يرى الزائر العادي اسم وبيانات مستخدم آخر مسجل!
• wp_is_mobile(): إذا قام أول زائر بفتح الصفحة من هاتف وتم تخزينها في كاش السيرفر، سيشاهد زوار الحواسيب اللاحقون تصميم الهاتف المشوه!

الحل المعماري: استخدم ترويسة Vary: User-Agent في خادم Nginx لفصل كاش الهواتف عن كاش الحواسيب، واعتمد على الجافاسكريبت والـ REST API في واجهة المتصفح لعرض البيانات المتغيرة الخاصة بكل مستخدم بدلاً من شروط PHP الثابتة على الصفحات المخبأة.

الأسئلة الشائعة حول الدوال الشرطية في ووردبريس (FAQ)

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

أكمل المسار

• فهرس المستويات والمقالات
• السابق: شرح The Loop: سياق المقال والحلقات الثانوية
• التالي: شرح WP_Post: كائن المحتوى والكاش والتحديث عبر API
• مسار تعلم ووردبريس وGutenberg