functions.php هو ملف PHP خاص بالقالب النشط في WordPress، ويُستخدم لإضافة Theme-specific functionality وربط القالب بـWordPress عبر Hooks وTheme Support وEnqueue وغيرها. لكنه ليس المكان الصحيح لكل وظيفة في الموقع، وأي خطأ Syntax فيه قد يسبب Fatal Error يؤثر على الواجهة ولوحة التحكم.

توضح وثائق WordPress الرسمية أن functions.php يتصرف من حيث التنفيذ بصورة شبيهة بـPlugin، لكن وظائفه مرتبطة بالقالب النشط. إذا كانت الميزة يجب أن تستمر بعد تغيير القالب، فالأفضل وضعها في Plugin مستقل.

المصدر الرسمي: WordPress Theme Handbook – Theme Functions.

أين يوجد functions.php؟

wp-content/themes/your-theme/functions.php

كل Theme يمكن أن يحتوي functions.php خاصًا به، لكن WordPress ينفذ ملف القالب النشط فقط، بالإضافة إلى حالة Child Theme التي لها سلوك خاص.

ماذا يحدث مع Child Theme؟

إذا كان لديك Child Theme، يقوم WordPress بتحميل functions.php الخاص بالـChild أولًا، ثم ملف Parent Theme. ملف Child لا يستبدل ملف الأب كما يحدث مع بعض Template files.

هذه النقطة مهمة لأن تعريف Function بنفس الاسم في الملفين قد يسبب Fatal Error إذا لم يكن Parent Theme مصممًا للسماح بإعادة التعريف.

functions.php أمPlugin؟

نوع الوظيفة	المكان الأنسب
Theme support / menus / assets خاصة بالقالب	functions.php
وظيفة يجب أن تستمر بعد تغيير القالب	Plugin
Custom Post Type يمثل محتوى دائمًا	Plugin غالبًا
تكامل API أوBusiness logic	Plugin
تعديل صغير مؤقت للتجربة	Snippet tool على Staging أوبيئة تطوير

إذا كان هدفك إضافة Snippet بدون تعديل ملفات القالب مباشرة، اقرأ إضافة كود PHP إلى WordPress بدون تعديل المصدر. هذه الصفحة تشرح functions.php نفسه، لا إدارة Snippets.

ولو تفضل إدارة Snippets من لوحة التحكم مع Auto Insert وConditional Logic وSafe Mode، راجع دليل WPCode في 2026. استخدمها للتعديلات المحدودة، وليس كبديل عن Plugin architecture عندما تصبح الوظيفة كبيرة.

لا تعدل Parent Theme مباشرة

إذا عدلت functions.php داخل Parent Theme ثم حدثت القالب، قد تفقد تغييراتك. للحاجات المرتبطة بالTheme استخدم Child Theme أوآلية Extension يوفرها القالب.

ولا تعدل WordPress Core إطلاقًا لهذه الأغراض.

خذ نقطة رجوع قبل أي تعديل

قبل تعديل Production:

خذ Backup أوSnapshot.
استخدم Staging.
تأكد أن لديك File Manager أوSFTP/SSH للوصول إذا تعطلت لوحة WordPress.
اختبر PHP compatibility.
لا تعتمد على Theme File Editor كخطة Recovery.

Hooks: الطريقة الأساسية للتوسعة

WordPress يعتمد نظام Hooks لتجنب تعديل Core. النوعان الأساسيان:

Actions: تنفذ Function عند نقطة معينة.
Filters: تستقبل قيمة وتعيد قيمة معدلة.

Action بسيط

<?php
function mwp_theme_setup() {
    add_theme_support( 'post-thumbnails' );
}
add_action( 'after_setup_theme', 'mwp_theme_setup' );

Filter بسيط

<?php
function mwp_excerpt_length( $length ) {
    return 30;
}
add_filter( 'excerpt_length', 'mwp_excerpt_length' );

استخدم Prefix أوNamespace فريدًا لتقليل احتمال Name Collision مع Core أوPlugins أوTheme parent.

تحميل CSS وJavaScript بالطريقة الصحيحة

لا تكتب <link> أو<script> عشوائيًا في Header. استخدم Enqueue APIs:

<?php
function mwp_enqueue_assets() {
    wp_enqueue_style(
        'mwp-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );

    wp_enqueue_script(
        'mwp-app',
        get_stylesheet_directory_uri() . '/assets/app.js',
        array(),
        wp_get_theme()->get( 'Version' ),
        array( 'in_footer' => true )
    );
}
add_action( 'wp_enqueue_scripts', 'mwp_enqueue_assets' );

في WordPress الحديثة يقبل wp_enqueue_script() Arguments أوسع من مجرد Boolean للـfooter. لكن راجع Compatibility إذا كان القالب يستهدف WordPress قديمة.

Theme Support

من الاستخدامات الصحيحة لـfunctions.php تفعيل قدرات القالب:

<?php
function mwp_setup() {
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
    add_theme_support(
        'html5',
        array( 'search-form', 'comment-form', 'gallery', 'caption', 'style', 'script' )
    );
}
add_action( 'after_setup_theme', 'mwp_setup' );

لا تفعل Feature لمجرد وجود API؛ فعّل فقط ما يدعمه تصميم القالب واختبر مخرجاته.

<?php
function mwp_register_menus() {
    register_nav_menus(
        array(
            'primary' => __( 'Primary Menu', 'mwp-theme' ),
            'footer'  => __( 'Footer Menu', 'mwp-theme' ),
        )
    );
}
add_action( 'after_setup_theme', 'mwp_register_menus' );

لو كنت تستخدم Block Theme كاملًا، قد تختلف بنية Navigation عن Classic Theme؛ لا تنقل كود Classic Theme آليًا بدون فهم نوع القالب.

Sanitize وValidate وEscape

واحدة من أهم الأخطاء في Snippets هي الخلط بين هذه المراحل:

Validation: هل القيمة مسموح بها أصلًا؟
Sanitization: تنظيف المدخل إلى صيغة متوقعة.
Escaping: حماية المخرج عند طباعته في HTML/URL/Attribute.

<?php
$value = sanitize_text_field( wp_unslash( $_POST['example'] ?? '' ) );
echo esc_html( $value );

هذا مثال فقط؛ أي عملية حفظ تحتاج أيضًا Capability checks وNonce حيثما تكون مطلوبة.

Nonces ليست Authorization

Nonce تقلل مخاطر CSRF لكنها لا تثبت أن المستخدم مسموح له بالعملية. في Admin actions اجمع Nonce validation مع current_user_can() وفق الصلاحية المطلوبة.

لا تضع Secrets داخل functions.php

API keys وPasswords وTokens لا يجب Hard-code داخل Theme repository. استخدم Configuration/Environment mechanism مناسبًا للخدمة، وقلل صلاحية المفتاح قدر الإمكان.

متى يصبح functions.php كبيرًا أكثر من اللازم؟

لا يوجد عدد أسطر سحري، لكن إذا تحول الملف إلى مئات الوظائف غير المرتبطة، قسمه إلى ملفات Modules ثم require_once من نقطة واضحة، أوانقل الوظائف الدائمة إلى Plugin.

<?php
require_once get_stylesheet_directory() . '/inc/setup.php';
require_once get_stylesheet_directory() . '/inc/assets.php';

التقسيم لا يحسن الأداء تلقائيًا؛ فائدته الأساسية تنظيم المسؤوليات وقابلية الصيانة.

هل أستخدم function_exists() لكل Function؟

لا. استخدام function_exists() بصورة عشوائية قد يخفي Conflict بدل حل Architecture. استخدم Prefix/Namespace فريدًا. استخدم Pluggable pattern فقط عندما يكون مقصودًا في تصميم Parent Theme.

أخطاء تسبب Fatal Error

نسيان فاصلة أوBracket.
تعريف Function مرتين.
استدعاء Class أوFunction غير موجودة بدون Guard مناسب.
استخدام Syntax تحتاج PHP أحدث من Server.
تشغيل كود يعتمد على Plugin قبل تحميله.
Paste لكود يبدأ بـ<?php داخل ملف مفتوح بالفعل بصورة خاطئة.

ماذا تفعل لو الموقع انهار بعد تعديل functions.php؟

لا تكرر Refresh بلا هدف.
افتح SFTP/SSH/File Manager.
أرجع آخر تعديل أوSnapshot.
راجع PHP error log.
اختبر الملف بـPHP lint إذا لديك CLI.
بعد عودة الموقع، انقل التجربة إلى Staging قبل المحاولة مجددًا.

لا تحذف القالب أوتغير قاعدة البيانات لعلاج Syntax error داخل ملف واضح.

functions.php وPerformance

وجود Functions كثيرة ليس المشكلة بحد ذاته؛ المشكلة هي ما تفعله في Hooks كثيرة التكرار. تجنب:

Queries ثقيلة في init أوwp لكل Request.
Remote API call synchronous في كل Page View.
تحميل Assets على كل الصفحات وهي مطلوبة في صفحة واحدة.
مسح Cache أوRewrite rules في كل Request.

استخدم Hooks المناسبة وCache وCron/queues حسب نوع العمل.

ما الذي لا أنصح به داخل functions.php؟

CPT مهم سيبقى بعد تغيير القالب.
Payment integration.
Authentication system.
Webhook business logic.
SEO data model أساسي.
Database migrations طويلة الأجل.
كود من الإنترنت لا تفهمه.

Checklist قبل Deploy

Snapshot/Backup موجود.
الكود يعمل على Staging.
PHP version متوافقة.
لا يوجد Duplicate function names.
Inputs validated/sanitized.
Outputs escaped.
Capabilities وNonces مضافة حيث تحتاج.
Assets تستخدم Enqueue APIs.
لا توجد Secrets.
Logs خالية من Warning/Fatal جديد.

الخلاصة

functions.php مناسب للوظائف المرتبطة بالقالب، لكنه ليس مخزنًا لكل Snippet. في Child Theme يتم تحميل ملف الطفل قبل الأب ولا يستبدله. استخدم Hooks وEnqueue وTheme APIs، ضع الوظائف الدائمة في Plugin، واختبر أي تعديل على Staging مع نقطة رجوع قبل لمس Production.

functions.php في WordPress 2026: متى تستخدمه وكيف تعدله بأمان