چرا خطای ناسازگاری قالب با افزونه‌ها رخ می‌دهد و چگونه آن را اصولی برطرف کنیم؟

ناسازگاری قالب و افزونه دقیقاً چیست؟

وقتی می‌گوییم قالب و افزونه با هم ناسازگارند، یعنی در چرخه اجرای یک درخواست HTTP، دو بخش از کد به‌شکلی با هم تعارض دارند که نتیجه‌اش یک رفتار ناخواسته است. این تعارض می‌تواند در چهار لایه مختلف رخ دهد: لایه هوک‌ها (Hook Priority)، لایه توابع و کلاس‌ها (Namespace Collision)، لایه فایل‌های مشترک (Asset Collision)، و لایه نسخه‌ها (Version Incompatibility).

یک سوءبرداشت رایج این است که تصور کنیم تعارض فقط وقتی رخ می‌دهد که «قالب یا افزونه اشکال داشته باشد». این‌طور نیست. بسیاری از تعارض‌های واقعی که دیده‌ام، بین دو کد کاملاً سالم رخ داده‌اند که هر کدام در تنهایی بی‌نقص کار می‌کنند. مسئله در «هم‌زیستی» آن‌هاست، نه در کیفیت تک‌تک‌شان. این دقیقاً همان نکته‌ای است که در مقاله افزونه وردپرس چیست و چگونه افزونه مناسب انتخاب کنیم توضیح داده‌ام: افزونه، از طریق هوک‌ها به هسته وصل می‌شود و هر هوک، یک نقطه تماس مشترک است که می‌تواند منبع تعارض باشد.

از منظر معماری وردپرس، این تعارض‌ها به سه دسته کلی تقسیم می‌شوند:

• تعارض مستقیم: دو بخش کد یک تابع همنام، کلاس همنام یا ثابت همنام تعریف می‌کنند. این حالت معمولاً به خطای Fatal error: Cannot redeclare function منجر می‌شود.
• تعارض غیرمستقیم: دو بخش کد، تابعی را در یک نقطه از هوک ثبت می‌کنند و ترتیب اجرایشان نتیجه را تغییر می‌دهد. این حالت معمولاً خطا نمی‌دهد، اما رفتار سایت را تغییر می‌دهد.
• تعارض منابع: دو بخش کد، فایل‌های CSS یا JS با handle یکسان ثبت می‌کنند یا از نسخه‌های متفاوت یک کتابخانه مشترک استفاده می‌کنند. این حالت منبع شایع‌ترین باگ‌های ظاهری است.

برای درک دقیق‌تر مفهوم پایه این تعارض، می‌توانید در ویکی‌پدیا مطلب WordPress را بخوانید که تاریخ توسعه این CMS و معماری اکوسیستمی‌اش را مرور می‌کند.

تعارض قالب و افزونه، همیشه دعوای دو کد خراب نیست؛ گاهی دعوای دو کد سالم است که در یک نقطه مشترک، با هم نمی‌سازند.

هشت ریشه اصلی این تعارض

در تجربه‌ام، تعارض قالب و افزونه تقریباً همیشه یکی از هشت ریشه زیر را دارد. هر کدام امضای مشخص خودش را در لاگ یا رفتار سایت دارد:

۱. تعارض نام توابع و کلاس‌ها

شایع‌ترین علت. تابعی در functions.php قالب تعریف شده که با تابعی در یک افزونه هم‌نام است. به‌محض فعال‌سازی افزونه، خطای Fatal error: Cannot redeclare function_name() ظاهر می‌شود و سایت از کار می‌افتد. این حالت در قالب‌های قدیمی که از پیشوند اختصاصی استفاده نمی‌کنند، بسیار رایج است. راه‌حل اصولی، استفاده از پیشوندهای یونیک یا تعریف توابع درون کلاس است — همان اصلی که در ساختار فایل‌های یک قالب استاندارد وردپرس به آن اشاره کرده‌ام.

۲. تعارض در اولویت هوک‌ها (Hook Priority)

دو تابع که به یک هوک واحد وصل شده‌اند، اما اولویت‌های متفاوتی دارند. اگر ترتیب اجرا مهم باشد، نتیجه غیرمنتظره می‌شود. مثال کلاسیک: یک افزونه در اولویت ۱۰ محتوای پست را تغییر می‌دهد، و قالب در اولویت ۵ همان محتوا را فیلتر می‌کند. نتیجه این است که فیلتر قالب بعد از تغییر افزونه اجرا می‌شود، نه قبلش. روش درست مدیریت اولویت‌ها را در اولویت در هوک‌های وردپرس چیست تفصیل داده‌ام.

۳. تعارض کتابخانه‌های JavaScript

یکی از پرتکرارترین تعارض‌های پنهان. قالب از یک نسخه jQuery استفاده می‌کند و افزونه از نسخه دیگری. یا هر دو، پلاگینی مثل Slick یا Swiper را با نسخه‌های متفاوت بارگذاری می‌کنند. نتیجه: رفتارهای عجیب در اسلایدر، لایت‌باکس یا انیمیشن‌ها. این حالت به‌خصوص در فروشگاه‌های ووکامرسی که از چند افزونه همزمان استفاده می‌کنند، شایع است. برای مطالعه بیشتر در این زمینه، مقاله چگونه خطاهای جاوااسکریپت را در کنسول مرورگر پیدا کنیم را توصیه می‌کنم.

۴. تعارض در بارگذاری CSS

قالب یک selector عمومی مثل .button را استایل می‌دهد و افزونه هم روی همان selector استایل متفاوتی می‌گذارد. بسته به ترتیب بارگذاری فایل‌ها، یکی دیگری را بازنویسی می‌کند. نتیجه، ظاهر به‌هم‌ریخته در بعضی از صفحات است. این نوع تعارض اغلب با نگاه دقیق به تب Styles در DevTools قابل تشخیص است.

۵. ناسازگاری با نسخه PHP

یک افزونه قدیمی روی PHP ۷.۴ کار می‌کند اما روی PHP ۸.۱ با خطای deprecation یا fatal مواجه می‌شود. اگر قالب هم به‌طور ضمنی روی نسخه جدید PHP تنظیم شده باشد، تعارض چند لایه می‌شود. تشخیص این حالت نیازمند مراجعه به لاگ خطای PHP است — همان روشی که در رفع خطای Fatal error در PHP توضیح داده‌ام.

۶. تعارض در فایل‌های template ووکامرس

قالب شما فایل‌های template ووکامرس را بازنویسی کرده، اما افزونه‌ای هم همان فایل‌ها را تغییر می‌دهد. نتیجه، نمایش نادرست محصولات، سبد خرید یا تسویه‌حساب است. راه‌حل اصولی این حالت، درک سلسله‌مراتب override در ووکامرس است که در سفارشی‌سازی صفحه محصول در ووکامرس با جزئیات شرح داده‌ام.

۷. تعارض در Custom Post Type و تاکسونومی

افزونه‌ای یک نوع پست سفارشی با نام portfolio ثبت می‌کند و قالب هم یک نوع پست سفارشی با همان نام. وردپرس اجازه نمی‌دهد دو نوع پست با نام یکسان ثبت شوند و این باعث می‌شود یکی از آن‌ها بی‌اثر شود. تشخیص این حالت نیازمند بررسی آرایه $wp_post_types در init است.

۸. تعارض در بارگذاری asset با handle یکسان

دو بخش کد، یک فایل CSS یا JS را با یک handle مشترک مثل jquery-ui یا main-script ثبت می‌کنند. وردپرس در این حالت، فقط یکی از آن‌ها را بارگذاری می‌کند و دیگری بی‌اثر می‌شود. این حالت در پروژه‌های تیمی که دو توسعه‌دهنده بدون هماهنگی handleها را انتخاب می‌کنند، شایع است.

تعارضی که در ظاهر خطا نمی‌دهد، خطرناک‌تر از تعارضی است که سایت را سفید می‌کند؛ چون اولی ماه‌ها پنهان می‌ماند.

نشانه‌ها و علائم تشخیص

تعارض قالب و افزونه در همه موارد به‌شکل یک خطای صریح ظاهر نمی‌شود. در تجربه‌ام، این نشانه‌ها ظاهر می‌شوند و اگر به آن‌ها توجه کنید، می‌توانید به‌موقع اقدام کنید:

• صفحه سفید یا خطای ۵۰۰: شایع‌ترین نشانه که در بحث رفع خطای سفید شدن صفحه وردپرس به آن پرداخته‌ام.
• رفتارهای عجیب در بخش خاصی از سایت: مثلاً صفحه محصولات کند است اما بقیه سایت سریع؛ یا فرم تماس در موبایل کار نمی‌کند اما در دسکتاپ سالم است.
• ظاهر به‌هم‌ریخته بعد از فعال‌سازی افزونه جدید: اگر بعد از نصب یک افزونه، چیدمان سایت تغییر کرد، تعارض CSS قطعی است.
• خطاهای جاوااسکریپت در Console: پیام‌های Uncaught TypeError یا ReferenceError که با نصب افزونه جدید ظاهر می‌شوند.
• کندی ناگهانی سایت: اگر سایت بعد از نصب افزونه کند شد، احتمالاً یک تعارض در لایه بارگذاری assetها رخ داده است — همان موضوعی که در افزونه‌های وردپرس چگونه روی سرعت سایت اثر می‌گذارند تحلیلی دقیقش را آورده‌ام.
• عدم اجرای یک قابلیت مشخص: مثلاً حالت تیره قالب کار می‌کند اما وقتی افزونه پاپ‌آپ فعال است، دیگر کار نمی‌کند.
• ناپدید شدن منو یا ویجت: اگر بخشی از قالب بعد از نصب افزونه ناپدید شد، احتمالاً تعارض در لایه هوک یا فایل‌های قالب است.

نکته مهم: هر نشانه‌ای که به‌طور ناگهانی و بعد از نصب یا آپدیت یک افزونه یا قالب ظاهر شود، تقریباً همیشه نشانه تعارض است، نه باگ مستقل. تشخیص این الگوی زمانی، اولین قدم در حل مسئله است.

پروتکل تشخیص گام‌به‌گام

برای رسیدن به ریشه تعارض، این پروتکل را در تجربه‌ام مفید یافته‌ام. مرحله‌به‌مرحله پیش بروید و در هر مرحله، بعد از یک تغییر، سایت را دوباره تست کنید:

گام اول: بکاپ و محیط استجینگ

قبل از هر تغییری، بکاپ کامل بگیرید و اگر امکانش هست، یک نسخه از سایت را روی محیط استجینگ بالا بیاورید. تست تعارض روی سایت زنده، پرخطرترین کار ممکن است، چون ممکن است سایت در میانه تست، برای کاربران نهایی از کار بیفتد.

گام دوم: فعال‌سازی حالت دیباگ وردپرس

در فایل wp-config.php این خطوط را اضافه کنید:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);

با این تنظیمات، خطاها در فایل wp-content/debug.log ثبت می‌شوند و صفحه سایت به‌خاطر نمایش خطا سفید نمی‌شود. برای مطالعه دقیق‌تر، مقاله دیباگ کردن کدهای سفارشی وردپرس را توصیه می‌کنم.

گام سوم: تعویض قالب به قالب پیش‌فرض

به پیشخوان وردپرس بروید، مسیر «نمایش ← پوسته‌ها» را باز کنید و قالب را به یکی از قالب‌های پیش‌فرض وردپرس (مثل Twenty Twenty-Five) تغییر دهید. اگر مشکل حل شد، ریشه در قالب فعلی است. اگر حل نشد، به گام بعدی بروید.

گام چهارم: غیرفعال‌سازی سیستماتیک افزونه‌ها

حالا مهم‌ترین گام: تمام افزونه‌ها را غیرفعال کنید. اگر مشکل حل شد، معلوم می‌شود تعارض بین قالب و یک افزونه خاص است. سپس افزونه‌ها را یکی‌یکی فعال کنید و بعد از هر فعال‌سازی، سایت را تست کنید. اولین افزونه‌ای که مشکل را برگرداند، مقصر است. این روش درست عیب‌یابی است که تفصیلش را در چگونه افزونه مشکل‌ساز وردپرس را پیدا کنیم آورده‌ام.

گام پنجم: استفاده از افزونه Health Check

اگر سایت شما زنده است و امکان تست با کاربر واقعی را ندارید، افزونه Health Check & Troubleshooting گزینه‌ای عالی است. این افزونه یک حالت اختصاصی «Troubleshooting Mode» فعال می‌کند که فقط برای شما تمام افزونه‌ها را غیرفعال می‌کند و بقیه کاربران سایت را بدون تغییر می‌بینند. این بهترین روش برای تست تعارض روی سایت زنده بدون ریسک است.

گام ششم: بررسی لاگ PHP و MySQL

اگر مشکل با خطای صریح همراه است، لاگ خطای PHP و MySQL را بررسی کنید. خطای Fatal error یا Deprecated که در لاگ ظاهر می‌شود، شما را مستقیم به فایل مقصر می‌رساند. برای مطالعه دقیق‌تر درباره لاگ خطاها، مقاله لاگ‌های دیتابیس چگونه بررسی می‌شوند را ببینید.

گام هفتم: بررسی DevTools مرورگر

اگر مشکل ظاهری یا رفتاری است، DevTools مرورگر را باز کنید و به تب Console و Network بروید. خطاهای جاوااسکریپت و درخواست‌های ناموفق، مسیر شما را روشن می‌کنند. برای مطالعه بیشتر درباره ابزارهای مرورگر، مقاله افزونه‌های ضروری مرورگر برای توسعه‌دهندگان را توصیه می‌کنم.

گام هشتم: مستندسازی نتیجه

وقتی مقصر پیدا شد، یادداشتی از ترکیب قالب + افزونه + نسخه PHP بنویسید. این مستندسازی، در آینده به شما کمک می‌کند که در صورت ارتقای یکی از این سه، سریعاً بفهمید که تعارض قبلی چه بود و چه انتظاری دارید.

تفاوت با خطاهای مشابه

تعارض قالب و افزونه اغلب با خطاهای دیگری قاطی می‌شود. این جدول به شما کمک می‌کند تفاوت‌ها را سریع تشخیص دهید:

نکته ظریف: تعارض دو افزونه با تعارض قالب و افزونه، در ظاهر بسیار شبیه‌اند اما روش تشخیصشان متفاوت است. اگر با تعویض قالب به قالب پیش‌فرض، مشکل حل شد، مقصر قالب است. اگر مشکل با قالب پیش‌فرض هم ادامه داشت، مقصر بین افزونه‌هاست. برای مطالعه موردی مشابه، مقاله چگونه خطای قالب وردپرس را عیب‌یابی کنیم را ببینید.

راه‌حل‌های عملی برای هر ریشه

حالا که مقصر را شناسایی کردید، وقت درمان است. راه‌حل‌ها را بر اساس ریشه تعارض دسته‌بندی کرده‌ام:

راه‌حل تعارض توابع و کلاس‌ها

اگر خطای Cannot redeclare function یا Cannot redeclare class می‌گیرید، سه گزینه دارید:

1. تغییر نام تابع در قالب: تابعی که در functions.php تعریف کرده‌اید را با یک پیشوند اختصاصی (مثل mytheme_) بازتعریف کنید.
2. محافظت با function_exists: قبل از تعریف تابع، بررسی کنید که از قبل وجود نداشته باشد:

if ( ! function_exists( 'my_custom_function' ) ) {
    function my_custom_function() {
        // کد شما
    }
}

این الگو، استانداردی است که در قالب‌های حرفه‌ای رعایت می‌شود. برای مطالعه بیشتر درباره استانداردهای کد قالب، مقاله بررسی مهم‌ترین امکانات یک قالب حرفه‌ای را توصیه می‌کنم.

راه‌حل تعارض اولویت هوک‌ها

اگر تعارض در اولویت هوک است، باید اولویت‌ها را تغییر دهید تا ترتیب اجرا اصلاح شود. مثال:

// اجرای قبل از افزونه با اولویت ۹
add_filter( 'the_content', 'my_theme_filter', 9 );

// اجرای بعد از افزونه با اولویت ۲۰
add_filter( 'the_content', 'my_theme_filter_after', 20 );

برای تعیین دقیق اولویت مورد نیاز، باید بدانید که افزونه‌ها در چه اولویت‌هایی روی هوک وصل شده‌اند. برای این کار، می‌توانید از ابزار Debug Bar یا Query Monitor استفاده کنید.

راه‌حل تعارض جاوااسکریپت

سه تکنیک عملی برای حل تعارض JS:

1. غیرفعال‌سازی jQuery همراه قالب: اگر قالب شما نسخه خودش از jQuery را بارگذاری می‌کند، می‌توانید آن را حذف کنید و به jQuery وردپرس اعتماد کنید. وردپرس به‌طور پیش‌فرض jQuery را بارگذاری می‌کند و نیازی به نسخه جداگانه نیست.
2. استفاده از wp_dequeue_script: اگر افزونه‌ای فایل JS منسوخ را بارگذاری می‌کند و با قالب تعارض دارد، می‌توانید آن را با این کد حذف کنید:

add_action( 'wp_enqueue_scripts', function() {
    wp_dequeue_script( 'old-plugin-script' );
    wp_deregister_script( 'old-plugin-script' );
}, 100 );

این الگو در پروژه‌هایی که با افزونه‌های قدیمی کار می‌کنند، بسیار مفید است.

راه‌حل تعارض CSS

در تعارض CSS، بسته به شدت مشکل، سه گزینه دارید:

1. افزایش specificity: در چایلد تم خود، selector را با کلاس والد یا شناسه اضافی تقویت کنید تا اولویت بالاتری داشته باشد.
2. استفاده از !important (با احتیاط): به‌عنوان آخرین راه‌حل، می‌توانید از !important استفاده کنید. اما این کار، نگهداری آینده را سخت می‌کند.
3. حذف استایل افزونه: اگر افزونه‌ای استایل اضافی روی عناصر سراسری اعمال می‌کند، می‌توانید با wp_dequeue_style آن را حذف کنید:

add_action( 'wp_enqueue_scripts', function() {
    wp_dequeue_style( 'problematic-plugin-style' );
}, 100 );

این کار باید در چایلد تم انجام شود، نه در فایل قالب والد. حتی دو خط کد هم در والد، روزی که آپدیت بیاید، سوخته است.

راه‌حل ناسازگاری نسخه PHP

اگر افزونه‌ای با نسخه PHP فعلی سایت سازگار نیست، سه گزینه دارید:

1. به‌روزرسانی افزونه: بررسی کنید که سازنده، نسخه جدیدی منتشر کرده باشد که با PHP 8.x سازگار است.
2. کاهش موقت نسخه PHP: اگر افزونه قدیمی است و به‌روزرسانی ندارد، می‌توانید موقتاً نسخه PHP را به ۷.۴ کاهش دهید. اما این کار امن نیست و توصیه نمی‌شود.
3. جایگزینی افزونه: بهترین راه‌حل، پیدا کردن یک افزونه جایگزین است که با نسخه فعلی PHP سازگار باشد — همان رویکردی که در افزونه‌های ضروری وردپرس به آن اشاره کرده‌ام.

راه‌حل تعارض template ووکامرس

اگر قالب شما فایل‌های template ووکامرس را بازنویسی کرده، همیشه نسخه بازنویسی‌شده را با نسخه اصلی ووکامرس مقایسه کنید تا از سازگاری مطمئن شوید. در هر آپدیت ووکامرس، یک بار این مقایسه را انجام دهید. این موضوع در بحث خطای قالب در ووکامرس تفصیل داده شده است.

راه‌حل تعارض handleها

اگر دو بخش کد، یک handle مشترک را برای asset ثبت می‌کنند، همیشه handle اختصاصی انتخاب کنید. بهترین الگو: استفاده از پیشوند قالب یا افزونه در نام handle. مثلاً به‌جای main-script از mytheme-main-script استفاده کنید.

تعارض‌های asset، نامرئی‌ترین نوع تعارض‌اند؛ چون خطایی نمی‌دهند، فقط رفتار می‌سوزانند.

استراتژی‌های پیشگیری در بلندمدت

پیشگیری از تعارض قالب و افزونه، نیازمند نظم در چرخه توسعه و انتخاب است. در تجربه‌ام، رعایت این نکات بیشترین بازدهی را داشته:

۱. انتخاب افزونه‌های باکیفیت از منبع معتبر

افزونه‌هایی که از مخزن رسمی وردپرس یا سازنده شناخته‌شده می‌آیند، استانداردهای کد بهتری دارند و احتمال تعارض کمتری را ایجاد می‌کنند. فیلترهای دقیق انتخاب را در چگونه یک افزونه وردپرس مطمئن دانلود کنیم آورده‌ام.

۲. انتخاب قالب استاندارد

قالب‌هایی که از APIهای رسمی وردپرس استفاده می‌کنند و ساختار درستی دارند، کمتر با افزونه‌ها تعارض پیدا می‌کنند. اگر می‌خواهید بدانید قالب استاندارد چه نشانه‌هایی دارد، مقاله چگونه یک قالب وردپرس استاندارد را تشخیص دهیم را ببینید.

۳. تست پیش از انتشار

هر افزونه یا قالب جدید را روی محیط استجینگ نصب کنید، سپس با ابزارهایی مثل Theme Check و Query Monitor بررسی کنید که با بقیه افزونه‌ها تعارض نداشته باشد. برای مطالعه درباره روش‌های اصولی تست، مقاله بهترین روش تست قالب وردپرس را توصیه می‌کنم.

۴. مستندسازی ترکیب فعلی

یک فایل ساده در قالب یا مخزن خود داشته باشید که ترکیب فعلی را ثبت کند: نسخه قالب، نسخه افزونه‌های فعال، نسخه PHP، نسخه MySQL. اگر روزی سایت خراب شد، این مستندات به شما کمک می‌کند ریشه را سریع‌تر پیدا کنید.

۵. به‌روزرسانی تدریجی

هرگز همه افزونه‌ها را همزمان آپدیت نکنید. یک به یک، با فاصله چند روز، آپدیت کنید. اگر روزی، آپدیتی سایت را خراب کرد، می‌دانید دقیقاً کدام یک مقصر است.

۶. استفاده از چایلد تم

اگر سفارشی‌سازی در قالب خود انجام می‌دهید، همیشه از چایلد تم استفاده کنید. این کار تضمین می‌کند که با آپدیت والد، تغییرات شما باقی می‌ماند و به‌عنوان یک لایه اضافی، از تعارض با افزونه‌ها هم جلوگیری می‌کند. راهنمای کامل این موضوع در قالب وردپرس چایلد چیست و چه زمانی به آن نیاز داریم آمده است.

۷. اجتناب از قالب‌های سنگین

قالب‌های چندمنظوره که صدها ماژول و کتابخانه جانبی دارند، بیشترین احتمال تعارض با افزونه‌ها را ایجاد می‌کنند. اگر هدف اصلی سایت، سرعت و پایداری است، به‌جای قالب چندمنظوره، به سراغ قالب سبک وردپرس بروید که با سرعت و کمترین بار، بهترین هم‌زیستی را با افزونه‌ها دارد.

۸. پایش مداوم خطاها

از ابزارهایی مثل Query Monitor، New Relic یا Sentry برای پایش خودکار خطاها استفاده کنید. اگر خطای جدیدی ظاهر شد، سریعاً اطلاع پیدا می‌کنید و می‌توانید قبل از اینکه به بحران تبدیل شود، به سراغش بروید.

پرسش‌های پرتکرار درباره تعارض قالب و افزونه

تفاوت تعارض قالب و افزونه با تعارض دو افزونه چیست؟

روش تشخیص تفاوت دارد. اگر با تعویض قالب به قالب پیش‌فرض وردپرس، مشکل حل شد، مقصر قالب است. اما اگر با قالب پیش‌فرض هم مشکل ادامه داشت، مقصر بین دو افزونه است. برای تشخیص نوع اول، همیشه اول قالب را تست کنید.

آیا تعارض قالب و افزونه می‌تواند باعث از دست رفتن داده شود؟

خیر، در بیشتر موارد نه. تعارض معمولاً روی لایه نمایش یا اجرا اثر می‌گذارد، نه روی دیتابیس. اما اگر تعارض باعث خرابی در یک تراکنش شود — مثلاً در ووکامرس — ممکن است بخشی از داده نیمه‌کاره بماند. به همین دلیل، بکاپ منظم حیاتی است.

چطور بفهمم کدام افزونه با قالب من تعارض دارد؟

پروتکل دقیق در بخش «تشخیص گام‌به‌گام» توضیح داده شده. خلاصه‌اش: ابتدا همه افزونه‌ها را غیرفعال کنید، سپس یکی‌یکی فعال کنید تا اولین افزونه‌ای که مشکل را برمی‌گرداند، پیدا شود.

آیا امکان دارد که تعارض فقط در بعضی صفحات رخ دهد؟

بله، و این حالت بسیار رایج است. چون هوک‌ها و assetها ممکن است فقط در صفحات خاصی بارگذاری شوند. مثلاً یک افزونه ممکن است فقط در صفحه محصولات یک اسکریپت را بارگذاری کند که با قالب تعارض دارد.

آیا استفاده از افزونه Health Check امن است؟

بله، این افزونه از مخزن رسمی وردپرس می‌آید و برای همین هدف طراحی شده است. حالت Troubleshooting Mode که ارائه می‌دهد، اجازه می‌دهد روی سایت زنده تست کنید بدون اینکه بقیه کاربران تحت تأثیر قرار بگیرند.

اگر افزونه‌ای با قالب من تعارض داشت، باید آن افزونه را حذف کنم؟

نه لزوماً. سه گزینه دارید: اول، بررسی کنید که نسخه جدید افزونه سازگار است. دوم، اگر ممکن است، در قالب خود کد را به‌شکلی تغییر دهید که تعارض رفع شود. سوم، اگر هیچ‌کدام جواب نداد، به سراغ افزونه جایگزین بروید.

چطور از بروز تعارض در آینده جلوگیری کنم؟

راه‌های پیشگیری در بخش «استراتژی‌های پیشگیری» توضیح داده شده. مهم‌ترین نکته: همیشه آپدیت‌ها را تدریجی انجام دهید و هر تغییر را روی محیط استجینگ تست کنید.

آیا تعارض قالب و افزونه با نسخه PHP رابطه دارد؟

بله. اگر قالب یا افزونه با نسخه PHP سایت شما سازگار نباشد، این می‌تواند خود را به‌شکل تعارض نشان دهد. برای تشخیص، لاگ خطای PHP را بررسی کنید و به خطاهای Deprecated یا Fatal error دقت کنید.

کالبدشکافی فنی: چرخه اجرای هوک‌ها و ترتیب بارگذاری

برای درک عمیق این تعارض‌ها، باید بدانید که وردپرس چطور در یک درخواست HTTP، کدهای مختلف را اجرا می‌کند. هسته وردپرس یک مکانیزم دقیق به نام Hook System دارد که در فایل wp-includes/plugin.php پیاده‌سازی شده است.

وقتی یک درخواست به سایت می‌رسد، این چرخه طی می‌شود:

1. Bootstrap: فایل wp-load.php بارگذاری می‌شود که به‌نوبه خود wp-settings.php را فراخوانی می‌کند.
2. Load Core: فایل‌های هسته وردپرس بارگذاری می‌شوند.
3. Load MU-Plugins: افزونه‌های Must-Use بارگذاری می‌شوند.
4. Load Plugins: تمام افزونه‌های فعال به ترتیب حروف الفبا بارگذاری می‌شوند. هر افزونه، توابع خودش را تعریف می‌کند و در پایان، در صورت نیاز به هوک‌ها وصل می‌شود.
5. Load Theme: قالب فعال بارگذاری می‌شود. فایل functions.php قالب فراخوانی می‌شود و توابع و هوک‌های قالب ثبت می‌شوند.
6. Run Hooks: هسته شروع به اجرای چرخه اصلی می‌کند: init، wp_loaded، template_redirect، و در نهایت رندر قالب.

نکته کلیدی اینجاست: افزونه‌ها زودتر از قالب بارگذاری می‌شوند. بنابراین اگر افزونه‌ای تابعی تعریف کند که در قالب هم تعریف شده، خطای redeclare رخ می‌دهد چون PHP نمی‌تواند دو تابع با نام یکسان داشته باشد.

نکته دوم: ترتیب هوک‌ها بر اساس اولویت است، نه ترتیب ثبت. اگر افزونه‌ای و قالب هر دو روی init تابعی ثبت کرده باشند، آن‌ها بر اساس اولویت اجرا می‌شوند. اولویت پیش‌فرض ۱۰ است. اگر هر دو ۱۰ باشند، ترتیب ثبت تعیین‌کننده است، و چون افزونه‌ها زودتر از قالب بارگذاری می‌شوند، تابع افزونه اول اجرا می‌شود.

نکته سوم و کمتر شناخته‌شده: در چرخه رندر، هوک wp_head در دو مرحله اجرا می‌شود. اول توسط هسته که متادیتا اضافه می‌کند، سپس توسط قالب که wp_head() را در فایل header.php فراخوانی می‌کند. اگر افزونه‌ای هم روی wp_head تابعی ثبت کند و اولویت پایین داشته باشد (مثلاً ۵)، تابعش قبل از هسته اجرا می‌شود و این می‌تواند مشکلات غیرمنتظره ایجاد کند. برای مطالعه بیشتر درباره چرخه اجرا، مقاله ساختار هسته وردپرس چگونه کار می‌کند را توصیه می‌کنم.

از منظر معماری، بهترین الگو برای کاهش احتمال تعارض این است: در قالب، توابع را با پیشوند اختصاصی تعریف کنید، آن‌ها را درون کلاس‌ها یا Namespaceها بگذارید، و روی هوک‌های حساس با اولویت‌های غیرپیش‌فرض کار کنید. این الگو، در قالب‌های حرفه‌ای که در ساخت قالب اختصاصی وردپرس توضیح داده‌ام، استاندارد است.

مطالعه موردی: احیای یک فروشگاه ووکامرسی

یک فروشگاه ووکامرسی با حدود ۵۰۰۰ محصول و روزانه ۲۰۰ سفارش، بعد از آپدیت قالب به نسخه جدید، با مشکل جدی مواجه شد: صفحه تسویه‌حساب در ۳۰٪ مواقع پیام «خطای غیرمنتظره» نشان می‌داد. آمار دقیقاً در ساعات پیک بود و تیم توسعه نمی‌توانست آن را بازتولید کند.

علائم:

• خطا فقط در ساعات پیک
• خطا فقط در صفحه تسویه‌حساب
• در لاگ PHP هیچ خطای صریحی نبود
• در لاگ MySQL، پیام‌های متعدد Lock wait timeout دیده می‌شد

تشخیص:

پس از چند روز بررسی، با فعال کردن Query Monitor روی محیط استجینگ و شبیه‌سازی ترافیک، مشخص شد که یک افزونه قدیمی برای مدیریت تخفیف، در هوک woocommerce_checkout_update_order_meta تابعی ثبت کرده که یک قفل طولانی روی جدول wp_postmeta می‌گیرد. قالب جدید هم در همان لحظه، یک کوئری سنگین روی همان جدول اجرا می‌کرد. ترکیب این دو، باعث قفل‌شدگی و در نتیجه خطای تسویه‌حساب می‌شد.

درمان:

1. ابتدا اولویت هوک افزونه را از ۱۰ به ۵ تغییر دادیم تا تابعش زودتر اجرا شود و قفل زودتر آزاد شود.
2. سپس کوئری قالب را با اضافه کردن ایندکس مناسب روی جدول wp_postmeta بهینه کردیم.
3. در نهایت، به‌جای اجرای کوئری در لحظه تسویه‌حساب، آن را به یک کرون‌جاب منتقل کردیم.

درس‌آموخته:

تعارض قالب و افزونه همیشه در لایه نمایش نیست. گاهی ریشه در لایه دیتابیس است، و در این حالت، اثرش فقط در ساعات پیک ظاهر می‌شود. برای مطالعه بیشتر درباره این دسته از مشکلات، مقاله خطای Lock wait timeout exceeded در MySQL را توصیه می‌کنم.

خط بسته: هم‌زیستی، نه سازش

تعارض قالب و افزونه در نگاه اول یک خطای فنی است، اما در واقع یک پیام معماری است: دو بخش از کد، در یک نقطه مشترک، با هم سازگار نیستند. سؤال درست این نیست «چطور این خطا را رفع کنم»، بلکه این است «چطور ترکیب قالب و افزونه‌های فعلی را به‌شکلی بچینم که هم‌زیستی پایدار داشته باشند».

از تجربه‌ام، شش اصل عملی بیشترین بازدهی را داشته‌اند: اول، همیشه روی محیط استجینگ تست کنید و هرگز روی سایت زنده آزمایش تعارض نکنید. دوم، قالب و افزونه‌های باکیفیت از منبع معتبر انتخاب کنید. سوم، در قالب، توابع را با پیشوند اختصاصی و درون کلاس تعریف کنید. چهارم، از چایلد تم برای هر سفارشی‌سازی استفاده کنید. پنجم، آپدیت‌ها را تدریجی انجام دهید، نه یکجا. ششم، ترکیب فعلی سایت را مستند کنید تا در صورت بروز مشکل، سریع‌تر ریشه را پیدا کنید.

در نهایت، اگر روی یک پروژه پیچیده با چندین افزونه سنگین کار می‌کنید، احتمال تعارض هیچ‌وقت به صفر نمی‌رسد. هدف واقع‌بینانه این است که تعارض را به یک رخداد نادر تبدیل کنید که با پروتکل تشخیص، در کمتر از یک ساعت ریشه‌اش پیدا می‌شود. این هدف در صدها پروژه واقعی جواب داده است.

اگر روی پروژه‌ای با تعارض قالب و افزونه مواجه شده‌اید و روش خاصی برای حلش پیدا کرده‌اید — به‌خصوص اگر با ووکامرس، قالب‌های چندمنظوره، یا افزونه‌های قدیمی سر و کار داشته‌اید — خوشحال می‌شوم تجربه‌تان را بشنوم. بگویید در آن پروژه، تعارض در کدام لایه بود: توابع، هوک‌ها، assetها، یا دیتابیس؟ و اگر در تشخیص آن به نکته‌ای رسیدید که در این مقاله نبود، بگویید تا در نسخه بعدی همان زاویه را عمیق‌تر باز کنم.