Debugging وردپرس با Xdebug 3 چرا این‌قدر قدرتمند است؟ Xdebug 3 یک extension PHP است که امکانات دیباگ گام‌به‌گام، پروفایلینگ، و تحلیل پوشش کد را در محیط توسعه فراهم می‌کند و نسبت به نسخه‌های قبلی، سرعت بالاتر، پیکربندی ساده‌تر، و مصرف حافظه کمتری دارد. در بستر وردپرس، این ابزار به‌ویژه برای دنبال کردن جریان اجرای کد، مشاهده مقدار متغیرها در هر گام، و شناسایی دقیق محل خطا بی‌نظیر است. برخلاف var_dump() و error_log که تصویری لحظه‌ای می‌دهند، Xdebug امکان توقف اجرا، بازرسی کامل وضعیت، و حرکت گام‌به‌گام در کد را فراهم می‌کند. نسخه ۳ نسبت به نسخه ۲ چند تغییر بنیادین دارد: بازنویسی کامل معماری، پیکربندی با xdebug.mode به‌جای فلگ‌های متعدد، و بهبود چشمگیر عملکرد. چالش‌های اصلی شامل پیچیدگی راه‌اندازی اولیه، تداخل با برخی افزونه‌ها، و نیاز به درک عمیق مفاهیم دیباگ است. در این نوشتار، از معرفی Xdebug 3 و تغییرات آن نسبت به نسخه قبلی، تا راه‌اندازی گام‌به‌گام در وردپرس، پیکربندی VS Code و PhpStorm، و سناریوهای عملی دیباگ را بررسی می‌کنیم.

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

Xdebug چیست و چه مسئله‌ای را حل می‌کند؟

Xdebug یک extension PHP است که برای دیباگ، پروفایلینگ، و تحلیل پوشش کد طراحی شده و توسط Derick Rethans توسعه یافته است. این extension با PHP ادغام می‌شود و امکان دیباگ گام‌به‌گام را در IDEهایی مانند VS Code، PhpStorm، و Eclipse فراهم می‌کند. برخلاف روش‌های سنتی دیباگ مانند var_dump() یا error_log، Xdebug امکان توقف اجرا، بازرسی وضعیت، و حرکت گام‌به‌گام را می‌دهد.

مسئله اصلی که Xdebug حل می‌کند، پیچیدگی دیباگ در کدهای تودرتو و طولانی است. در وردپرس، یک درخواست HTTP از ده‌ها فایل، صدها تابع، و چندین hook عبور می‌کند. دنبال کردن دستی این جریان با var_dump() عملاً غیرممکن است. Xdebug این جریان را قابل مشاهده و قابل کنترل می‌کند. برای درک عمیق‌تر ساختار اجرای وردپرس، ساختار هسته وردپرس را ببینید.

سه قابلیت اصلی Xdebug عبارتند از:

  • Step Debugging: حرکت گام‌به‌گام در کد با توقف در نقاط مشخص.
  • Profiling: تحلیل عملکرد و شناسایی گلوگاه‌ها.
  • Code Coverage: تحلیل پوشش کد در تست‌ها.

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

Xdebug یک «میکروسکوپ» برای کد است: به‌جای حدس زدن درباره رفتار برنامه، آن را گام‌به‌گام مشاهده می‌کنید. همین ویژگی، تفاوت بین دیباگ مؤثر و اتلاف وقت را می‌سازد.

تغییرات Xdebug 3 نسبت به نسخه ۲

Xdebug 3 در نوامبر ۲۰۲۰ منتشر شد و چند تغییر بنیادین نسبت به نسخه ۲ داشت که آن را به یک ابزار مدرن تبدیل کرد:

ویژگیXdebug 2Xdebug 3
پیکربندیفلگ‌های متعدد (remote_enable، auto_trace، ...)یک پارامتر mode
سرعتسربار بالاتربهبود قابل توجه
حالت پیش‌فرضفعالغیرفعال
پورت پیش‌فرض دیباگ۹۰۰۰۹۰۰۳
نصبمستقلبا پکیج‌های توزیع

مهم‌ترین تغییر، جایگزینی فلگ‌های متعدد با پارامتر xdebug.mode است. در Xdebug 2، باید چند فلگ مانند remote_enable، auto_trace، و profiler_enable را به‌طور جداگانه تنظیم می‌کردید. در Xdebug 3، فقط مقدار mode را تعیین می‌کنید. این سادگی، پیکربندی را بسیار سرراست‌تر کرده است.

تغییر دیگر، پورت پیش‌فرض دیباگ است که از ۹۰۰۰ به ۹۰۰۳ تغییر یافت. این تغییر برای جلوگیری از تداخل با سایر سرویس‌ها بود، زیرا پورت ۹۰۰۰ معمولاً توسط PHP-FPM یا سایر ابزارها استفاده می‌شود. برای درک عمیق‌تر پیکربندی سرور، مشخصات سرور وردپرس را ببینید.

حالت‌های Xdebug 3 و کاربرد هرکدام

Xdebug 3 چند حالت اصلی دارد که با کاما از هم جدا می‌شوند:

حالتکاربرد
developنمایش خوانای متغیرها با var_dump
debugدیباگ گام‌به‌گام با IDE
profileپروفایلینگ عملکرد
traceثبت جریان اجرا در فایل
coverageتحلیل پوشش کد
gcstatsآمار جمع‌آوری زباله
offغیرفعال

در محیط توسعه، معمولاً حالت develop,debug را فعال می‌کنید. حالت develop خروجی var_dump() را خوانا می‌کند و حالت debug امکان اتصال IDE را فراهم می‌سازد. برای پروفایلینگ موقت، حالت profile را اضافه کنید. برای درک عمیق‌تر ابزارهای دیباگ، دیباگ کردن کدهای سفارشی وردپرس را ببینید.

نصب Xdebug 3 روی سرور

نصب Xdebug 3 بستگی به سیستم‌عامل و نسخه PHP دارد. یک نمونه برای Ubuntu با PHP 8.2:

sudo apt install php8.2-xdebug

پس از نصب، فایل پیکربندی در مسیر /etc/php/8.2/mods-available/xdebug.ini ایجاد می‌شود. برای macOS با Homebrew:

brew install php@8.2
pecl install xdebug

پس از نصب، با اجرای دستور زیر از نصب صحیح مطمئن شوید:

php -m | grep xdebug

اگر خروجی xdebug بود، نصب موفق بوده است. برای درک عمیق‌تر مدیریت سرور، مدیریت سرور Linux را ببینید.

پیکربندی فایل xdebug.ini

یک پیکربندی پایه برای محیط توسعه:

zend_extension=xdebug.so
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.var_display_max_depth=10
xdebug.var_display_max_children=256
xdebug.var_display_max_data=1024

توضیح پارامترهای کلیدی:

  • start_with_request=yes: هر درخواست را با دیباگ شروع می‌کند (برای محیط توسعه).
  • client_host: آدرس IDE (معمولاً localhost).
  • client_port: پورت دیباگ (پیش‌فرض ۹۰۰۳).
  • var_display_max_depth: عمق نمایش آرایه‌ها در var_dump.

پس از تغییر، سرویس PHP را ری‌استارت کنید:

sudo systemctl restart php8.2-fpm

برای درک عمیق‌تر تنظیمات وردپرس، تنظیمات عمومی وردپرس را ببینید.

راه‌اندازی دیباگ در VS Code

VS Code یکی از محبوب‌ترین IDEها برای دیباگ وردپرس است. برای راه‌اندازی، ابتدا extension PHP Debug (توسط Felix Becker) را نصب کنید. سپس در فایل .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

پس از راه‌اندازی، در VS Code کلید F5 را بزنید و سپس سایت وردپرس را در مرورگر باز کنید. اگر همه چیز درست باشد، VS Code در اولین نقطه توقف (breakpoint) متوقف می‌شود. برای مرور سایر ابزارهای توسعه، ابزارهای ضروری فرانت‌اند را ببینید.

راه‌اندازی دیباگ در PhpStorm

PhpStorm یکی دیگر از IDEهای محبوب است که پشتیبانی داخلی از Xdebug دارد. مراحل راه‌اندازی:

  1. در Settings > Languages & Frameworks > PHP > Debug پورت را روی ۹۰۰۳ تنظیم کنید.
  2. در Settings > PHP > Servers یک سرور جدید بسازید و مسیر پروژه را مپ کنید.
  3. در نوار ابزار، روی آیکون «Start Listening for PHP Debug Connections» کلیک کنید.
  4. سایت را در مرورگر باز کنید.

در PhpStorm، می‌توانید نقاط توقف شرطی (conditional breakpoint) تعریف کنید که فقط در شرایط مشخص متوقف می‌شوند. این قابلیت، دیباگ را بسیار دقیق‌تر می‌کند. برای درک عمیق‌تر ساختار پروژه، ساختاردهی پروژه توسعه وردپرس را ببینید.

نکات اختصاصی دیباگ وردپرس

دیباگ وردپرس با Xdebug چند نکته اختصاصی دارد:

توقف در هوک‌ها

برای دیباگ یک hook خاص، در فایل wp-includes/plugin.php یا در کد افزونه خود، در تابع do_action یا apply_filters نقطه توقف بگذارید. اما بهتر است نقاط توقف را در کد خودتان بگذارید، نه در هسته وردپرس. برای درک عمیق‌تر هوک‌ها، هوک‌های وردپرس را ببینید.

توقف در کوئری‌های دیتابیس

برای دیباگ کوئری‌ها، در فایل wp-includes/wp-db.php در متد query() نقطه توقف بگذارید. اما این کار می‌تواند سایت را کند کند، زیرا هر درخواست شامل ده‌ها کوئری است. به‌جای آن، از افزونه Query Monitor استفاده کنید یا نقاط توقف شرطی تعریف کنید. برای درک عمیق‌تر کوئری‌ها، بهینه‌سازی کوئری‌های MySQL را ببینید.

دیباگ template loading

یکی از رایج‌ترین کاربردهای Xdebug در وردپرس، شناسایی این است که کدام فایل قالب برای نمایش یک صفحه استفاده می‌شود. برای این کار، در فایل wp-includes/template-loader.php نقطه توقف بگذارید یا از تابع get_template_part() استفاده کنید. برای درک عمیق‌تر، فایل‌های ضروری قالب وردپرس را ببینید.

دیباگ AJAX و REST API با Xdebug

دیباگ AJAX در وردپرس چند چالش دارد: درخواست‌ها از JavaScript ارسال می‌شوند، پاسخ‌ها JSON هستند، و Xdebug ممکن است پاسخ را بشکند. برای دیباگ AJAX:

  1. پارامتر XDEBUG_SESSION_START را در درخواست AJAX قرار دهید.
  2. یا از VS Code با start_with_request=yes استفاده کنید.
  3. در کوئری AJAX، نقطه توقف در handler خود بگذارید.

یک نمونه با jQuery:

jQuery.post( ajaxurl + '?XDEBUG_SESSION_START=vscode', {
    action: 'myplugin_get_data',
    nonce: myData.nonce,
} );

در سمت سرور، نقطه توقف در handler بگذارید و Xdebug متوقف می‌شود. برای درک عمیق‌تر دیباگ AJAX، AJAX Debugging در وردپرس را ببینید.

پروفایلینگ با Xdebug 3

Xdebug 3 حالت پروفایلینگ دارد که با فعال‌سازی mode=profile اجرا می‌شود. خروجی آن در فایل CacheGrind ذخیره می‌شود و با ابزارهایی مانند KCacheGrind، QCacheGrind، یا Webgrind قابل مشاهده است.

xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug
xdebug.profiler_output_name=cachegrind.out.%p

پس از اجرا، فایل cachegrind.out.* در مسیر مشخص‌شده ساخته می‌شود. با Webgrind می‌توانید آن را در مرورگر باز کنید و گلوگاه‌ها را ببینید. برای درک عمیق‌تر پروفایلینگ، Tideways برای وردپرس را ببینید.

نکته مهم: پروفایلینگ با Xdebug سربار بالایی دارد (حدود ۲۰۰ درصد). بنابراین فقط در محیط توسعه و برای بازه‌های کوتاه استفاده کنید.

چرا Xdebug در محیط تولید فعال نباشد؟

فعال بودن Xdebug در محیط تولید چند مشکل ایجاد می‌کند:

  • سربار بالا: حالت debug می‌تواند سربار ۱۰۰ تا ۲۰۰ درصد ایجاد کند.
  • افشای اطلاعات: خروجی var_dump و stack trace می‌تواند اطلاعات حساس را نمایش دهد.
  • تداخل با کش: Xdebug با کش صفحات و کش PHP می‌تواند تداخل کند.
  • ارسال مداوم سیگنال: اگر IDE متصل نباشد، Xdebug زمان‌بر می‌شود.
  • افشای مسیرها: مسیر فایل‌ها در خطاها نمایش داده می‌شود.

در محیط تولید، Xdebug باید با mode=off یا غیرفعال باشد. برای پایش عملکرد در تولید، از ابزارهایی مانند Tideways یا New Relic استفاده کنید. برای درک عمیق‌تر امنیت، اصول امنیت وب را ببینید.

اشتباهات رایج در استفاده از Xdebug 3

  • فعال بودن start_with_request=yes در تولید: سایت را به‌شدت کند می‌کند.
  • استفاده از پورت اشتباه: Xdebug 3 روی ۹۰۰۳ است، نه ۹۰۰۰.
  • عدم تنظیم pathMappings: نقاط توقف در Docker یا VM کار نمی‌کنند.
  • فراموش کردن ری‌استارت PHP: تغییرات اعمال نمی‌شوند.
  • فعال بودن develop در تولید: خروجی متغیرها افشا می‌شود.
  • نصب extension بدون تطابق نسخه PHP: خطای بارگذاری.
  • عدم استفاده از نقاط توقف شرطی: دیباگ در حلقه‌های طولانی زمان‌بر می‌شود.
  • توقف در هسته وردپرس: می‌تواند با به‌روزرسانی هسته از بین برود.
  • فراموش کردن حذف نقاط توقف قبل از انتشار: خطای احتمالی در تولید.
  • عدم استفاده از log: وقتی اتصال IDE برقرار نمی‌شود، xdebug.log کمک می‌کند.

برای مرور خطاهای مشابه، اشتباهات رایج در کدنویسی وردپرس را ببینید.

پرسش‌های پرتکرار درباره Xdebug 3

Xdebug 3 چیست و چه کاربردی دارد؟ یک extension PHP برای دیباگ گام‌به‌گام، پروفایلینگ، و تحلیل پوشش کد.

تفاوت Xdebug 2 و 3 چیست؟ Xdebug 3 پیکربندی ساده‌تر (با mode)، سرعت بالاتر، و پورت پیش‌فرض ۹۰۰۳ دارد.

آیا Xdebug در محیط تولید امن است؟ نه، به‌طور پیش‌فرض نه. باید با mode=off غیرفعال باشد.

چطور Xdebug را در Docker راه‌اندازی کنم؟ با تنظیم client_host=host.docker.internal و pathMappings در IDE. برای مراحل کامل، توسعه وردپرس با محیط لوکال را ببینید.

چرا Xdebug نقاط توقف را نمی‌بیند؟ دلایل رایج: پورت اشتباه، pathMappings نادرست، فایروال، یا start_with_request=no بدون پارامتر شروع.

آیا Xdebug روی سرعت اجرای کد تأثیر دارد؟ بله، حتی در حالت develop سربار دارد. در محیط توسعه قابل قبول است اما در تولید نه.

چطور پروفایل Xdebug را تحلیل کنم؟ با Webgrind، QCacheGrind، یا KCacheGrind. برای درک عمیق‌تر، Tideways برای وردپرس را ببینید.

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

خط پایان

Debugging وردپرس با Xdebug 3 یکی از آن مهارت‌هایی است که پس از یادگیری، بهره‌وری توسعه‌دهنده را چند برابر می‌کند. حرکت گام‌به‌گام در کد، بازرسی متغیرها، و مشاهده دقیق جریان اجرا، تجربه دیباگ را از یک فرآیند خسته‌کننده به یک جریان کار سریع تبدیل می‌کند. تغییرات Xdebug 3 نسبت به نسخه ۲ — پیکربندی ساده‌تر، سرعت بالاتر، و پورت جدید — این ابزار را به یک انتخاب مدرن تبدیل کرده است. اما استفاده از آن نیازمند رعایت نکات امنیتی است: در محیط تولید نباید فعال باشد، و پیکربندی باید دقیق باشد. اگر پروژه وردپرسی پیچیده‌ای دارید، Xdebug 3 یکی از مؤثرترین سرمایه‌گذاری‌هایی است که می‌توانید در ابزارهای توسعه انجام دهید.

اگر در پروژه‌ای Xdebug 3 را راه‌اندازی کرده‌اید یا با چالش‌هایی روبه‌رو شده‌اید، تجربه خود را در دیدگاه‌ها بنویسید؛ به‌خصوص اگر پیکربندی خاصی برای Docker یا VM داشته‌اید، این اطلاعات برای خواننده بعدی بسیار ارزشمند است.