محرك Rewrite في ووردبريس: تحويل الروابط إلى متغيرات طلب

هذا المقال رقم 6 من 100 في سلسلة معمارية ووردبريس من الأساسيات إلى المشروع النهائي، ضمن المستوى 1: أساسيات نواة ووردبريس.

يا مرحب يا هندسة! لو سألت أي مستخدم عادي أو حتى مطور مبتدئ في ووردبريس: “هو لما إنت بتدخل على رابط زي abozaid.local/courses/wordpress-diploma/، إيه اللي بيحصل؟”، هيقولك: “أكيد في مجلد على السيرفر اسمه courses وجواه مجلد اسمه wordpress-diploma وجواه ملف HTML!”. الحقيقة الصادمة للجميع إن السيرفر معندوش أي مجلدات بالأسماء دي أصلاً، وكل الروابط دي مجرد خدعة بصرية ومعمارية عبقرية بيديرها محرك أسطوري في نواة ووردبريس اسمه: محرك إعادة كتابة الروابط (WordPress Rewrite Engine).

محرك الـ Rewrite هو البوابة الأولى وحلقة الوصل اللي بتاخد الروابط الأنيقة الصديقة للمستخدم ومحركات البحث (Pretty Permalinks) وتحولها وتترجمها للروابط المعقدة اللي بتفهمها النواة وقاعدة البيانات (Query Variables زي: index.php?post_type=az_course&name=wordpress-diploma). في الدليل العملي الموسع ده، هنشرح بالعامية المصرية التقنية كل أسرار كلاس WP_Rewrite؛ هنفهم إزاي خادم الويب (Nginx/Apache) بيسلم الطلب لووردبريس، وكيفية إضافة قواعد مخصصة بـ add_rewrite_rule()، وسر خيار top مقابل bottom، وكارثة إفراغ القواعد flush_rewrite_rules()، وبناء نقاط النهاية المخصصة (Rewrite Endpoints)، مع دراسة حالة واقعية لصفحات الشهادات الافتراضية، وبنك أسئلة شائعة شامل ومصادر موثقة.

1. الفكرة المعمارية لمحرك Rewrite: من الروابط الأنيقة إلى متغيرات النواة

في الأيام الأولى للويب وووردبريس القديم، كانت كل الروابط بتظهر بالشكل القبيح ده: example.com/?p=123 أو example.com/?cat=4. الروابط دي كان فيها مشكلتين كبار جداً:

1. سيئة جداً لتجربة المستخدم (User Experience): الزائر مش فاهم الرقم ده بيعبر عن إيه وصعب يحفظ الرابط أو يشاركه.
2. سيئة لمحركات البحث (SEO): محركات البحث زي جوجل بتفضل وجود الكلمات الدلالية المستهدفة في مسار الرابط (URL Slug) لتفهم موضوع المقال.

عشان يحلوا المشكلة دي، فريق نواة ووردبريس بنى محرك الـ Rewrite؛ وهو عبارة عن مترجم تعابير نمطية (Regex Translation Machine). وظيفته ياخد أي مسار زائر يطلبه، ويقارنه بقائمة من القواعد المخزنة في قاعدة البيانات؛ أول ما يلاقي قاعدة مطابقة، يستخرج المتغيرات من الرابط ويحولها لمصفوفة من متغيرات الاستعلام الرسمية (Query Vars) لتسليمها لكائن WP_Query ليبدأ البحث في جداول MySQL.

2. من يلتقط الطلب أولاً؟ خادم الويب (Nginx/Apache) أم ووردبريس؟

قبل ما ووردبريس يشوف الرابط أصلاً، خادم الويب هو اللي بيستلم الطلب من شبكة الإنترنت. لازم نفهم دور خادم الويب عشان نحدد مكان أي عطل:

• في سيرفرات Apache: ملف .htaccess بيحتوي على توجيهات mod_rewrite الشهيرة:
  RewriteCond %{REQUEST_FILENAME} !-f (إذا لم يكن الرابط يشير لملف حقيقي على القرص زي صورة أو ملف CSS)
  RewriteCond %{REQUEST_FILENAME} !-d (وإذا لم يكن الرابط يشير لمجلد حقيقي)
  RewriteRule . /index.php [L] (قم بتمرير الرابط بالكامل فوراً لملف index.php ليبدأ ووردبريس في معالجته!).
• في سيرفرات Nginx: نفس المهمة بتتم من خلال كتلة التوجيه في ملف الإعدادات:
  try_files $uri $uri/ /index.php?$args;.

بمجرد وصول الطلب إلى index.php، خادم الويب بينهي مهمته تماماً، ويبدأ محرك ووردبريس الداخلي WP_Rewrite في فحص المسار.

3. تشريح كلاس WP_Rewrite ومصفوفة القواعد العظمى (rewrite_rules)

في النواة، كائن $wp_rewrite هو كائن عام من كلاس WP_Rewrite المعرف في wp-includes/class-wp-rewrite.php. الكائن ده بيحتفظ بمصفوفة ضخمة جداً مخزنة في جدول الخيارات wp_options تحت المفتاح rewrite_rules.

المصفوفة دي بيكون شكلها كالتالي:

// عينة من مصفوفة rewrite_rules المخزنة في قاعدة البيانات:
[
    '^courses/([^/]+)/?$'                  => 'index.php?az_course=$matches[1]',
    '^category/(.+?)/page/?([0-9]{1,})/?$' => 'index.php?category_name=$matches[1]&paged=$matches[2]',
    '^category/(.+?)/?$'                   => 'index.php?category_name=$matches[1]',
    '(.+?)/trackback/?$'                   => 'index.php?name=$matches[1]&tb=1',
    '(.+?)/feed/(feed|rdf|rss|rss2|atom)/?$' => 'index.php?name=$matches[1]&feed=$matches[2]',
    '(.+?)/?$'                             => 'index.php?name=$matches[1]'
]

لاحظ الترتيب الدقيق! ووردبريس بيلف على المصفوفة دي بالترتيب من أعلى لأسفل، ويختبر المسار المطلوب بالدالة preg_match(). أول قاعدة تنجح في المطابقة (Match)، بيتم اعتمادها فوراً وتجاهل باقي القواعد التي تليها في المصفوفة.

4. التشريح العميق لدالة add_rewrite_rule وسر خيار top و bottom

لو عايز تضيف رابط مخصص وجديد تماماً لموقعك، بنستخدم الدالة الرسمية add_rewrite_rule(). الدالة دي بتاخد 3 معاملات في غاية الأهمية:

add_rewrite_rule( string $regex, string|array $query, string $after = 'bottom' );

1. المعامل الأول ($regex): تعبير نمطي (Regular Expression) بيوصف شكل الرابط. لازم يبدأ بـ ^ (بداية المسار بعد اسم الدومين) وينتهي بـ /?$ (نهاية المسار مع جعل السلاش الأخيرة اختيارية). ونستخدم الأقواس ([^/]+) لالتقاط المتغيرات الممررة.
2. المعامل الثاني ($query): الرابط الداخلي المستهدف الذي تفهمه النواة. ويتم استدعاء القيم الملتقطة بالرمز $matches[1] للقوس الأول، و$matches[2] للقوس الثاني.
3. المعامل الثالث ($after): وده السر المعماري الحاسم! القيمة الافتراضية هي 'bottom' (أي إضافة القاعدة في آخر القائمة). ولكن في 90% من الحالات، لازم تغيرها وتخليها 'top'!

ليه خيار ‘top’ في غاية الأهمية؟

لأن ووردبريس عنده قاعدة عامة وشاملة في أسفل المصفوفة: '(.+?)/?$' => 'index.php?name=$matches[1]' (وهي القاعدة المخصصة للمقالات والصفحات الفردية). لو إنت ضفت قاعدتك الجديدة بـ 'bottom'، القاعدة العامة هتلتقط الرابط بتاعك الأول وتعتقد إنه مقال عادي وتطلع للزائر خطأ 404 Not Found! لكن لو ضفت قاعدتك بـ 'top'، ووردبريس هيفحص قاعدتك إنت الأول قبل القواعد العامة ويعالج الرابط بنجاح!

5. تسجيل المتغيرات المخصصة عبر فلتر query_vars

كتير من المطورين يكتبوا add_rewrite_rule() صحيحة جداً، مثلاً:

add_rewrite_rule( '^student-portal/([0-9]+)/?$', 'index.php?student_id=$matches[1]', 'top' );

وبعدين يفتح القالب ويكتب $student_id = get_query_var( 'student_id' );، ويتفاجأ إن النتيجة فاضية empty تماماً! ليه حصل كده؟

لأن ووردبريس مطبق نظام حماية أمني صارم جداً اسمه القائمة البيضاء للمتغيرات (Query Vars Whitelist). ووردبريس بيتجاهل أي متغير في الرابط إلا لو كان مسجلاً في قائمته الرسمية المعتمدة. عشان متغيرك يتقرأ، لازم تسجله بالفلتر ده في ملف functions.php أو في إضافتك:

// تسجيل المتغير المخصص في القائمة البيضاء للنواة
add_filter( 'query_vars', 'az_register_custom_query_vars' );

function az_register_custom_query_vars( array $vars ): array {
    $vars[] = 'student_id';
    $vars[] = 'certificate_code';
    return $vars;
}

6. الخطر الأكبر والكارثة الشائعة: دالة flush_rewrite_rules()

لما بنضيف قاعدة روابط جديدة، ووردبريس مش بيشوفها فوراً؛ لأن القواعد بتكون متكشة في جدول wp_options. عشان نحدث القواعد في قاعدة البيانات، بنحتاج نستدعي دالة flush_rewrite_rules().

وهنا بيقع أكبر خطأ برمجي كارثي بنشوفه في كود المبتدئين:

// ❌ كود كارثي وانتحار برمجي صريح:
add_action( 'init', function() {
    add_rewrite_rule( ... );
    flush_rewrite_rules(); // كارثة!
});

ليه كتابة flush_rewrite_rules في خطاف init جريمة لا تغتفر؟

دالة flush_rewrite_rules() عملية ثقيلة جداً ومكلفة للغاية؛ بتقوم بمسح جدول الخيارات بالكامل، وإعادة توليد مئات التعابير النمطية، وكتابة صف جديد ضخم في قاعدة البيانات، وإعادة توليد ملف .htaccess على القرص الصلب! لما تحطها في init، إنت بتجبر السيرفر ينفذ العملية المرهقة دي مع كل زيارة ومع كل نقرة ومع كل صورة بيطلبها أي زائر في الموقع! السيرفر هيقع فوراً ويوصل استهلاك المعالج إلى 100% تحت أدنى ترافيك!

الممارسة الهندسية الصحيحة لإفراغ القواعد:

1. أثناء تطوير الإضافة: الدخول إلى لوحة التحكم > الإعدادات (Settings) > الروابط الدائمة (Permalinks) والنقر على زر حفظ التغييرات. مجرد فتح الصفحة والنقر على حفظ بيعمل إفراغ آمن للقواعد لمرة واحدة فقط.
2. برمجياً داخل الإضافات: استدعاء الدالة فقط داخل خطاف تفعيل الإضافة register_activation_hook وخطاف إلغاء التفعيل register_deactivation_hook:

// التسجيل النظيف لقواعد الروابط في الإضافات الاحترافية:
function az_diploma_setup_rewrites(): void {
    add_rewrite_rule(
        '^diploma-verify/([A-Z0-9-]+)/?$',
        'index.php?az_verify_code=$matches[1]',
        'top'
    );
}
add_action( 'init', 'az_diploma_setup_rewrites' );

// إفراغ القواعد حصرياً عند تفعيل الإضافة لمرة واحدة:
function az_diploma_activate(): void {
    az_diploma_setup_rewrites();
    // المعامل false يعني عدم إعادة كتابة ملف .htaccess إلا لو تطلب الأمر لتسريع العملية
    flush_rewrite_rules( false );
}
register_activation_hook( __FILE__, 'az_diploma_activate' );

// تنظيف القواعد عند إلغاء التفعيل:
function az_diploma_deactivate(): void {
    flush_rewrite_rules( false );
}
register_deactivation_hook( __FILE__, 'az_diploma_deactivate' );

7. المسارات الفرعية ونقاط النهاية (Custom Rewrite Endpoints)

لو عندك منشورات أو صفحات حقيقية موجودة بالفعل، وعايز تضيف ليها رابط فرعي في نهايتها (مثل: صفحة حساب الطالب /my-account/ وتريد إضافة تبويب الشهادات /my-account/certificates/، أو مقال وتريد إضافة مسار الطباعة /my-post/print/)، مش محتاج تكتب Regex معقد؛ ووردبريس بيوفر دالة هندسية متخصصة اسمها add_rewrite_endpoint():

add_action( 'init', 'az_add_certificate_endpoint' );

function az_add_certificate_endpoint(): void {
    // إضافة نقطة نهاية للشهادات على كل الصفحات EP_PAGES
    add_rewrite_endpoint( 'certificates', EP_PAGES );
}

بمجرد إضافة السطر ده، ووردبريس هيتعرف تلقائياً على أي مسار ينتهي بـ /certificates/ أو /certificates/123/ ويسجل متغير certificates تلقائياً دون الحاجة لتسجيله في query_vars!

8. توجيه وعرض القالب المخصص بواسطة template_include

بعد ما الرابط اتحلل ومتغير الاستعلام اتسجل في WP_Query، إزاي نحدد الملف اللي هيعرض الصفحة دي للزائر؟

بنستخدم فلتر template_include في ووردبريس لفحص المتغير وتحميل قالب PHP مخصص من داخل إضافتك أو قالبك:

add_filter( 'template_include', 'az_load_custom_verify_template' );

function az_load_custom_verify_template( string $template ): string {
    $verify_code = get_query_var( 'az_verify_code' );

    // لو الطلب الحالي يحتوي على كود التحقق الخاص بنا:
    if ( ! empty( $verify_code ) ) {
        // نبحث عن القالب المخصص في مسار الإضافة
        $custom_template = plugin_dir_path( __FILE__ ) . 'templates/verify-certificate.php';
        
        if ( file_exists( $custom_template ) ) {
            return $custom_template; // استبدال القالب وعرض صفحة التحقق
        }
    }

    return $template; // في باقي الحالات، اترك ووردبريس يختار القالب الطبيعي
}

9. دراسة حالة واقعية: بناء نظام التحقق من شهادات الطلاب دون إنشاء صفحات وهمية

في منصة تعليمية تضم أكثر من 20,000 طالب متخرج، كانت المنصة تحتاج لتوفير رابط تحقق رسمي لكل طالب بصيغة: platform.com/verify/AZ-99882/. المطور السابق كان يقوم بإنشاء منشور ووردبريس مخصص (Custom Post Type) في قاعدة البيانات لكل شهادة يتم إصدارها!

المشاكل المعمارية الناتجة عن الحل القديم:

• جدول wp_posts امتلأ بأكثر من 20,000 سجل وهمي كل وظيفته فقط فحص صحة الكود!
• تعطيل محركات البحث وامتلاء خرائط الـ Sitemap بروابط شهادات لا تحتوي على محتوى نصي ذي قيمة.
• بطء في استعلامات الموقع وتضخم مساحة التخزين.

الحل الهندسي الأنيق بـ Virtual Dynamic Endpoints:

1. حذفنا المنشورات الوهمية بالكامل من جدول wp_posts.
2. أضفنا قاعدة إعادة كتابة واحدة فقط عبر add_rewrite_rule( '^verify/([A-Z0-9-]+)/?$', 'index.php?az_cert=$matches[1]', 'top' ).
3. سجلنا المتغير az_cert في query_vars.
4. في فلتر template_include، إذا وُجد المتغير az_cert، نقوم بفحص الكود مباشرة في جدول شهادات مخصص بـ $wpdb->get_row()؛ إن كان الكود صحيحاً نعرض صفحة الشهادة التفاعلية مع الباركود، وإن لم يكن نعرض رسالة شهادة غير صالحة، كل ذلك في صفحة ديناميكية افتراضية دون وجود أي منشور فعلي في قاعدة البيانات!

النتيجة بالأرقام: تم تخفيض أكثر من 20,000 منشور من قاعدة البيانات، وأصبح إصدار رابط التحقق فورياً ومشفراً ويعمل بسرعة استجابة تقل عن 15 ميلي ثانية!

10. الوصايا العشر لمهندسي ووردبريس عند إدارة محرك الروابط

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

1. لا تستدعِ flush_rewrite_rules في خطاف init إطلاقاً: هذه أخطر ممارسة تدمر أداء الخادم؛ استدعها حصرياً عند تفعيل أو إلغاء تفعيل الإضافة.
2. استخدم دائماً ‘top’ في قواعدك المخصصة: لتضمن أن تكون لقاعدتك الأولوية قبل أن تبتلعها قواعد ووردبريس العامة للصفحات والمقالات.
3. سجل متغيراتك في القائمة البيضاء query_vars: أي متغير تمرره في الرابط الداخلي لـ index.php لن تستطيع قراءته بـ get_query_var إلا بعد تسجيله في الفلتر.
4. اكتب تعابير نمطية محكمة ودقيقة: حدد قيود المحارف بدقة (مثلاً: [0-9]+ للأرقام فقط) ولا تستخدم .* بشكل فضفاض لمنع التداخل والتعارض مع روابط النواة.
5. اجعل السلاش الأخيرة اختيارية: ضع دائماً /?$ في نهاية التعبير النمطي ليعمل الرابط بنجاح سواء كتب الزائر السلاش في النهاية أم لا.
6. استفد من add_rewrite_endpoint للمسارات الفرعية: استخدم نقاط النهاية عند إضافة تبويبات للحسابات أو مسارات الطباعة لتجنب كتابة تعابير نمطية يدوية.
7. استخدم Rewrite Rules Inspector في بيئة التطوير: راقب وفحص مصفوفة الروابط كاملة وتأكد من ترتيب قاعدتك ومطابقتها للمسار المطلوب.
8. عالج حالات عدم العثور برمز 404 صريح: في القوالب الافتراضية، إذا لم يطابق المتغير سجلاً صالحاً، اضبط الحالة إلى 404 عبر $wp_query->set_404(); status_header(404); لإرشاد محركات البحث.
9. تأكد من إعدادات خادم الويب (Nginx / Apache): تأكد دائماً من أن ملف .htaccess قابل للكتابة في Apache، أو أن كتلة try_files مضبوطة بشكل صحيح في Nginx لتمرير الروابط لووردبريس.
10. نظف القواعد عند إلغاء التثبيت: احرص دائماً على إفراغ القواعد عند إلغاء تفعيل إضافتك لمنع بقاء قواعد يتيمة تعرقل عمل الإضافات الأخرى.

11. تشخيص تعارضات التعابير النمطية (Regex Conflicts & Rule Precedence)

واحدة من أكثر المشاكل المربكة التي تواجه كبار المطورين في ووردبريس هي ظاهرة ابتلاع القواعد (Rule Swallowing). تخيل معي أنك قمت بتسجيل القاعدتين التاليتين في نفس الإضافة:

// القاعدة الأولى: مخصصة لترقيم صفحات الدورات
add_rewrite_rule(
    '^courses/page/([0-9]+)/?$',
    'index.php?post_type=az_course&paged=$matches[1]',
    'top'
);

// القاعدة الثانية: مخصصة لعرض صفحة الدورة الفردية بواسطة الـ slug
add_rewrite_rule(
    '^courses/([^/]+)/?$',
    'index.php?az_course=$matches[1]',
    'top'
);

ما الكارثة التي ستحدث هنا لو عكست ترتيب التسجيل؟

لو قمت بتسجيل قاعدة الدورة الفردية ^courses/([^/]+)/?$ في البداية بأولوية أعلى، فعندما يطلب الزائر صفحة الترقيم /courses/page/2/، سيقوم التعبير النمطي العام ([^/]+) بمطابقة كلمة page واعتبارها اسماً لدورة تدريبية غير موجودة! وبالتالي سيعرض ووردبريس خطأ 404 بدلاً من فتح صفحة الدورات رقم 2!

القاعدة الهندسية الذهبية: رتّب دائماً القواعد من الأكثر تخصيصاً وتضييقاً (Most Specific) إلى الأكثر عمومية واتساعاً (Most Generic). ضع مسارات الأرقام والكلمات المفتاحية الثابتة في القمة، ومسارات النصوص المفتوحة في الأسفل.

12. الأمان في محرك الروابط: الوقاية من ثغرات Open Redirect و SSRF

عند بناء مسارات التحويل وتوجيه الروابط المخصصة في ووردبريس، يقع الكثير من المطورين في ثغرات أمنية خطيرة تتعلق بالتحويل غير الآمن (Unvalidated Open Redirect):

• كارثة استخدام wp_redirect مع مدخلات الزوار: إذا كان مسارك يستقبل رابط العودة (Return URL) بعد تسجيل الدخول أو إتمام خطوة معينة، واستخدمت wp_redirect( $_GET['redirect_to'] )، يستطيع المهاجم تمرير رابط خارجي لموقع تصيد احتيالي (Phishing Site) مثل evil-phishing.com، ليقوم موقعك بتحويل الزائر تلقائياً لموقع المخترق!
• الحل الأمني الصارم: دالة wp_safe_redirect(): توفر نواة ووردبريس دالة أمنية متقدمة اسمها wp_safe_redirect( $location, $status ). هذه الدالة تفحص اسم الدومين الممرر في الرابط؛ فإن كان ينتمي لنفس موقعك أو لقائمة المواقع الموثوقة المسجلة في فلتر allowed_redirect_hosts، يتم التحويل بأمان، وإن كان رابطاً خارجياً مجهولاً، يتم تحويل الزائر تلقائياً إلى الصفحة الرئيسية لموقعك وإحباط الهجوم بالكامل!
• تطهير المتغيرات المستخرجة من الـ Regex: تذكر دائماً أن ما يتم التقاطه بواسطة $matches[1] هو نص خام لم يخضع لأي تعقيم؛ إذا أردت استخدامه في استعلامات أو عمليات شرطية، مرره فوراً عبر sanitize_title() أو absint() أو sanitize_text_field() قبل البدء في معالجته برمجياً.

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

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

أكمل المسار

• فهرس المستويات والمقالات
• السابق: شرح wpdb في ووردبريس
• التالي: روابط ووردبريس على Apache وNginx
• مسار تعلم ووردبريس وGutenberg