کد سفارشی که کار می‌کند، تنها نیمی از کار است؛ نیم دیگر، کدی است که وقتی خطا داد، بتوانید سریع علتش را پیدا کنید. در سال‌ها کار با پروژه‌های وردپرسی، دیده‌ام توسعه‌دهندگانی که در نوشتن کد مهارت دارند ولی در دیباگ، ساعت‌ها وقت تلف می‌کنند. تفاوت این دو گروه، معمولاً در ابزار و روش است، نه در هوش. این مقاله، دیباگ کدهای سفارشی وردپرس را از پایه تا الگوهای حرفه‌ای مرور می‌کند: از تنظیمات WP_DEBUG تا Xdebug، Query Monitor، تحلیل لاگ، و خطاهای رایج. برای درک پیش‌نیازها، افزونه وردپرس چیست، افزودن کد سفارشی به وردپرس، و تست و دیباگ پروژه‌های وردپرس را پیش از ادامه ببینید.

رویکرد سیستمی به دیباگ

دیباگ، یک فرآیند کشف تدریجی است، نه یک لحظهٔ شهود. پنج گام مشخص دارد که در پروژه‌های واقعی به کار می‌برم: یک — توصیف دقیق مشکل: چه چیزی اتفاق می‌افتد که نباید؟ چه چیزی نمی‌افتد که باید؟ دو — بازتولید: می‌توانید مطمئن شوید که این مشکل در هر شرایطی رخ می‌دهد؟ در یک URL خاص؟ با یک کاربر خاص؟ سه — محدودسازی: مشکل در کدام بخش کد است؟ کدام افزونه؟ کدام قالب؟ کدام درخواست؟ چهار — تحلیل علت: چرا این بخش خطا می‌دهد؟ پنج — رفع و تأیید: تغییر، رفع شد؟ خطای دیگری اضافه نشد؟ تجربه‌های میدانی من در این مورد: بیش از ۷۰٪ زمان دیباگ، صرف گام‌های یک تا سه می‌شود. اگر این گام‌ها را دقیق انجام دهید، گام چهارم تقریباً خودش را نشان می‌دهد. راهنمای کلی در تست و دیباگ پروژه‌های وردپرس و اشتباهات رایج توسعه. یک قاعده: هرگز بدون بازتولید، سراغ تغییر کد نروید. تغییرات کور، معمولاً یک مشکل را حل می‌کنند و سه مشکل جدید می‌سازند.

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

فعال‌سازی WP_DEBUG

اولین ابزار دیباگ در وردپرس، خودِ WP_DEBUG است. سه تنظیم در wp-config.php:

// فعال‌سازی حالت دیباگ
define( 'WP_DEBUG', true );

// نوشتن خطاها در فایل
define( 'WP_DEBUG_LOG', true );

// عدم نمایش خطاها در صفحه
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// نمایش اسکریپت‌ها در نسخهٔ غیرفشرده
define( 'SCRIPT_DEBUG', true );

// ذخیرهٔ کوئری‌ها (فقط در محیط توسعه)
define( 'SAVEQUERIES', true );

توضیح هرکدام: یک — WP_DEBUG: فعال‌کنندهٔ حالت دیباگ. دو — WP_DEBUG_LOG: خطاها در wp-content/debug.log ذخیره می‌شوند، نه در صفحه. سه — WP_DEBUG_DISPLAY: اگر true باشد، خطاها در صفحه نمایش داده می‌شوند. در محیط توسعه می‌توانید فعال کنید، در Production باید false باشد تا خطاها به کاربر نمایش داده نشوند. چهار — SCRIPT_DEBUG: وردپرس نسخه‌های غیرفشردهٔ CSS/JS را لود می‌کند. برای دیباگ front-end مفید است. پنج — SAVEQUERIES: تمام کوئری‌ها در متغیر $wpdb->queries ذخیره می‌شوند. در Production غیرفعال باشد چون بار اضافه دارد. راهنمای هوک‌های دیباگ در هوک‌های وردپرس. یک نکتهٔ امنیتی مهم: هیچ‌یک از این تنظیمات را روی Production فعال نگذارید، مگر WP_DEBUG با WP_DEBUG_LOG و WP_DEBUG_DISPLAY = false که برای لاگ‌گیری دوره‌ای مفید است. راهنما در امنیت وردپرس برای مبتدیان.

خواندن و تفسیر error_log

پس از فعال‌سازی WP_DEBUG_LOG، فایل wp-content/debug.log پر می‌شود. الگوی هر خط:

[15-Sep-2026 14:23:11 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function my_function() in /path/to/file.php:45
Stack trace:
#0 /path/to/another.php(28): my_other_function()
#1 {main}
  thrown in /path/to/file.php on line 45

سه بخش کلیدی هر خط: یک — نوع خطا: Fatal error، Warning، Notice، Deprecated. دو — پیام: توضیح خطا. سه — مسیر و شمارهٔ خط: محل دقیق خطا. نکته: در Stack trace، مسیر تماس‌ها را دنبال کنید. خط اول trace، محلی است که خطا رخ داده. خطوط بعدی، مسیر فراخوانی هستند. راهنمای انواع خطا در رفع خطای Fatal error PHP، رفع خطای Warning در PHP، رفع خطای Notice در PHP، و خطای Deprecated در PHP. یک نکته در خواندن لاگ: اگر لاگ شما بزرگ است، آخرین ۱۰۰ خط را با tail -n 100 debug.log در ترمینال ببینید. در cPanel از File Manager و ابزار نمایش لاگ استفاده کنید.

Query Monitor: چشمان دیباگ

Query Monitor، محبوب‌ترین افزونهٔ دیباگ برای وردپرس است. سه قابلیت اصلی: یک — کوئری‌های دیتابیس: تعداد، زمان، منبع، و کوئری خام هر کوئری. دو — هوک‌ها: کدام هوک‌ها در چه ترتیبی اجرا می‌شوند. سه — خطاهای PHP: خطاهایی که در صفحه رخ می‌دهند، با مسیر و خط. نحوهٔ استفاده: پس از نصب، نوار باریکی در پایین صفحهٔ پیشخوان و فرانت‌اند ظاهر می‌شود. با کلیک روی هر بخش، جزئیات کامل نمایش داده می‌شود. تجربه‌های میدانی من در این مورد: در پروژه‌ای که صفحهٔ اصلی در ۴ ثانیه لود می‌شد، Query Monitor نشان داد که یک افزونهٔ کوچک، ۸۰ کوئری اضافه در هر بازدید می‌زند. حذف آن، زمان پاسخ را به ۱.۵ ثانیه رساند. راهنمای تکمیلی در بهینه‌سازی کوئری‌ها و بهینه‌سازی کد وردپرس. نکته: Query Monitor را روی Production فعال نگذارید. روی استیجینگ یا محیط لوکال استفاده کنید. راهنمای محیط لوکال در توسعه با محیط لوکال.

Xdebug و step debugging

Xdebug، ابزار حرفه‌ای دیباگ PHP است. سه قابلیت کلیدی: یک — Step Debugging: کد را خط به خط اجرا کنید و متغیرها را در هر نقطه ببینید. دو — Stack Traces: مسیر فراخوانی در لحظهٔ خطا. سه — Profiling: زمان اجرای هر تابع. پیکربندی در php.ini:

xdebug.mode = debug,develop
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.start_with_request = trigger
xdebug.log_level = 0

پس از پیکربندی، در VS Code یا PHPStorm، افزونهٔ Xdebug Client را نصب کنید و Breakpoint بگذارید. تجربه‌های میدانی من در این مورد: در پروژه‌ای که یک باگ پیچیده داشت (متغیر در شرط خاصی null می‌شد و از مسیرهای مختلفی رد می‌شد)، Xdebug در پنج دقیقه علت را نشان داد؛ روش error_log و var_dump، سه روز طول کشیده بود. راهنمای محیط لوکال در توسعه با محیط لوکال. نکته: Xdebug را روی Production غیرفعال کنید. بار اضافه دارد و سرعت سایت را چند برابر کم می‌کند. یک نکتهٔ تکمیلی: در پروژه‌های تیمی، تعریف Xdebug در یک فایل پیکربندی مشترک، به همهٔ اعضای تیم کمک می‌کند تجربهٔ دیباگ یکسانی داشته باشند. الگو در ساختاربندی پروژهٔ وردپرس.

دیباگ front-end و JS

خطاهای front-end، ابزار دیباگ متفاوتی می‌خواهند: یک — کنسول مرورگر: برای خطاهای JavaScript. در Chrome با F12 یا Ctrl+Shift+J باز می‌شود. خطاها با رنگ قرمز، هشدارها با زرد. با کلیک روی هر خطا، به مسیر فایل و شمارهٔ خط می‌رسید. راهنمای کامل در پیدا کردن خطاهای JS در کنسول. دو — تب Network: برای درخواست‌های شبکه. ترتیب لود، حجم، کد پاسخ (200، 404، 500)، و زمان هر درخواست. سه — تب Performance: برای پروفایلینگ front-end. زمان رندر، زمان اجرای JS، و گلوگاه‌ها. چهار — تب Sources: برای دیباگ JavaScript با Breakpoint. تجربه‌های میدانی من در این مورد: در پروژه‌ای که یک فرم با شکست مواجه می‌شد، کنسول مرورگر نشان داد که یک فایل JS سوم‌شخص، متغیر جهانی $ را از jQuery گرفته و بازتعریف کرده. حذف آن فایل، فرم را نجات داد. راهنمای تکمیلی در ابزارهای تست سرعت سایت و Core Web Vitals.

انواع خطا و ریشه‌یابی

پنج نوع خطای رایج در کد سفارشی، با علت و ریشه‌یابی:

نوع خطاپیام نمونهعلت اصلی
Parse errorsyntax error, unexpected...اشتباه نگارشی در PHP
Fatal errorCall to undefined functionتابع فراخوانی‌شده وجود ندارد
WarningUndefined variableمتغیر قبل از تعریف استفاده شده
NoticeUndefined indexاندیس آرایه وجود ندارد
DeprecatedFunction X is deprecatedاستفاده از تابع منسوخ

روش ریشه‌یابی هر کدام: یک — Parse error: پیام خطا، شمارهٔ خط دقیق می‌دهد. فایل را در آن خط باز کنید. راهنمای کامل در خطای Parse error در PHP و رفع Parse error در functions.php. دو — Fatal error: تابع یا کلاس موردنیاز لود نشده. مسیر در رفع Fatal error PHP و رفع Call to undefined function. سه — Warning: معمولاً متغیر بدون تعریف. راهنما در رفع Warning PHP و رفع Undefined variable. چهار — Notice: اندیس آرایه بدون بررسی. راهنما در رفع Notice در PHP و رفع Undefined index. پنج — Deprecated: تابع در نسخه‌های جدید PHP منسوخ شده. راهنما در خطای Deprecated در PHP. یک نکتهٔ مهم: خطاهای Warning و Notice در محیط Production می‌توانند با WP_DEBUG = false مخفی شوند، ولی این مخفی‌کردن، مشکل را حل نمی‌کند — در محیط توسعه، این خطاها را جدی بگیرید.

خطاهای رایج در کد سفارشی

هشت خطای رایج که در کدهای سفارشی زیاد دیده‌ام: یک — نبود semicolon: Parse error در خط بعد. دو — عدم تطابق آکولاد: Parse error در انتهای فایل. سه — استفاده از تابع قبل از تعریف: Fatal error. چهار — اشتباه در نام تابع: Fatal error. پنج — عدم استفاده از isset قبل از اندیس آرایه: Notice. شش — عدم استفاده از $wpdb->prepare: SQL Injection و خطا در کوئری. هفت — نبود escape در خروجی: XSS، که در لاگ خطا نمی‌آید ولی آسیب امنیتی جدی است. هشت — استفاده از توابع منسوخ: Deprecated. راهنمای هر خطا در Parse error، Fatal error، Warning، Notice، و Deprecated. یک آسیب‌پذیری شایع در این هشت مورد: خطای هفت. هیچ لاگ خطایی، XSS را نشان نمی‌دهد، ولی آسیب آن جدی است. راهنمای امنیت در PHP امن در وردپرس، پاک‌سازی داده‌ها، و اعتبارسنجی داده‌ها.

دیباگ روی Production

دیباگ روی Production، محدودیت‌های خاص خودش را دارد. پنج قاعدهٔ الزامی: یک — WP_DEBUG_DISPLAY = false: خطاها به کاربر نمایش داده نشوند. دو — WP_DEBUG_LOG = true: خطاها در فایل ذخیره شوند. سه — پایش دوره‌ای لاگ: روزانه یا هفتگی، فایل debug.log را بررسی کنید. چهار — ابزار monitoring: از سرویس‌هایی مثل New Relic یا Uptime Robot برای پایش خطاها و زمان پاسخ استفاده کنید. پنج — بکاپ فوری: پیش از هر تغییر روی Production، بکاپ کامل. راهنمای بکاپ در بکاپ سایت و افزونه‌های بکاپ. یک نکتهٔ مهم: برای دیباگ روی Production، از یک زیرساخت لاگ‌گیری مرکزی استفاده کنید. سرویس‌هایی مثل Sentry یا Bugsnag، خطاها را در یک داشبورد جداگانه نمایش می‌دهند و از پر شدن debug.log روی هاست جلوگیری می‌کنند. راهنمای ساختاربندی در ساختاربندی پروژهٔ وردپرس.

ساختار کلاس‌محور و لاگ

در پروژه‌های جدی، لاگ‌گیری در یک کلاس اختصاصی نگه داشته می‌شود:

class My_Plugin_Logger {

    public static function log( $message, $context = array(), $level = 'info' ) {
        if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
            return;
        }

        $entry = sprintf(
            '[%s] [%s] %s %s',
            current_time( 'mysql' ),
            strtoupper( $level ),
            is_string( $message ) ? $message : wp_json_encode( $message ),
            $context ? wp_json_encode( $context ) : ''
        );

        error_log( $entry );
    }

    public static function info( $message, $context = array() ) {
        self::log( $message, $context, 'info' );
    }

    public static function warning( $message, $context = array() ) {
        self::log( $message, $context, 'warning' );
    }

    public static function error( $message, $context = array() ) {
        self::log( $message, $context, 'error' );
    }
}

// استفاده
My_Plugin_Logger::error( 'API request failed', array(
    'url'    => $url,
    'status' => $status,
    'body'   => $body,
) );

مزیت این ساختار: لاگ‌ها با ساختار مشخص، امکان فیلتر، و حذف خودکار در محیط Production. الگوهای مشابه در کدنویسی اختصاصی افزونه، ساختار فایل‌های افزونهٔ استاندارد، و استانداردهای کدنویسی وردپرس. یک نکته در لاگ‌گیری: حتماً سطح لاگ (info, warning, error) را مشخص کنید. در پروژه‌های بزرگ، فیلتر کردن لاگ‌ها بر اساس سطح، در زمان بحران نجات‌دهنده است. یک الگوی تکمیلی: پاک‌سازی خودکار لاگ قدیمی پس از ۳۰ روز، با یک cron job ساده. این کار، از پر شدن فضای هاست جلوگیری می‌کند.

الگوهای پیشرفته

چهار الگوی پیشرفته در دیباگ، برای پروژه‌های حرفه‌ای: یک — تست‌های خودکار به‌عنوان سیستم دیباگ: خطاهایی که با تست‌های خودکار گرفته می‌شوند، هرگز به کاربر نمی‌رسند. راهنمای تست در تست و دیباگ پروژه‌های وردپرس. دو — Distributed Tracing: در پروژه‌های بزرگ، ردیابی یک درخواست از مرورگر تا دیتابیس با ابزارهایی مثل Jaeger. سه — Error Tracking Service: Sentry، Bugsnag یا Rollbar، خطاها را در یک داشبورد جداگانه با جزئیات کامل (Stack trace، کاربر، مرورگر) نمایش می‌دهند. چهار — Feature Flags: در پروژه‌های با انتشار سریع، قابلیت‌های جدید با Feature Flag فعال/غیرفعال می‌شوند تا در صورت مشکل، بدون انتشار نسخهٔ جدید، غیرفعال شوند:

if ( get_option( 'my_plugin_enable_new_feature', false ) ) {
    // کد جدید
} else {
    // کد قدیم
}

راهنمای Options API در کار با Options API. یک نکتهٔ معماری در پروژه‌های سازمانی: ترکیب Error Tracking با CI/CD، یک چرخهٔ بازخورد سریع می‌سازد که خطاهای Production را در همان روز به تیم توسعه می‌رساند. الگو در CI/CD در وردپرس. تجربه‌های میدانی من در این مورد: در پروژه‌ای با Sentry، خطاهای Production که قبلاً ماه‌ها پنهان می‌ماندند، در چند دقیقه پس از رخ دادن، به تیم گزارش می‌شدند و در همان هفته رفع می‌شدند.

اشتباهات رایج

دیباگ کدهای سفارشی وردپرس، مسیر روشنی دارد: فعال‌سازی WP_DEBUG در محیط توسعه، خواندن دقیق debug.log، استفاده از Query Monitor برای کوئری و هوک، Xdebug برای step debugging، ابزارهای مرورگر برای front-end، شناخت انواع خطا و ریشه‌یابی، رعایت پنج قاعدهٔ دیباگ روی Production، لاگ‌گیری ساختاریافته در کد سفارشی، و استفاده از الگوهای پیشرفته مانند Error Tracking. اگر امروز یک کار در این مسیر انجام می‌دهید: در پروژهٔ فعلی خود، یک فایل debug.log باز کنید و آخرین ۲۰ خط آن را بخوانید؛ همان فهرست، نقشهٔ بهبود شماست. اگر تجربه‌ای از یک دیباگ پیچیده دارید که با Xdebug یا Error Tracking سریع‌تر حل شد، در دیدگاه‌ها بنویسید؛ همان گزارش‌های واقعی، این راهنما را دقیق‌تر می‌کند. 🐛