Whoops Error Handler در وردپرس چطور کار می‌کند؟

Whoops Error Handler در وردپرس (مدیریت‌کننده خطای Whoops) چطور کار می‌کند؟ این پرسشی است که در مرز میان دیباگ حرفه‌ای و تجربه توسعه‌دهنده قرار می‌گیرد. Whoops یک کتابخانه PHP است که رابط کاربری زیبا و خوانا برای نمایش خطاها و استثناها فراهم می‌کند و جایگزین صفحات خطای خشک و مبهم PHP می‌شود. این کتابخانه که توسط Filipe Dobreira توسعه یافته و در مخزن Composer با نام filp/whoops منتشر شده، در فریم‌ورک‌هایی مانند Laravel و Slim به‌طور پیش‌فرض استفاده می‌شود. در بستر وردپرس، Whoops می‌تواند به‌عنوان یک ابزار دیباگ در محیط توسعه استفاده شود و تجربه عیب‌یابی را متحول کند. برخلاف حالت پیش‌فرض وردپرس که خطاها را در فایل debug.log ذخیره می‌کند یا با wp_die() نمایش می‌دهد، Whoops یک صفحه تعاملی با stack trace خوانا، context متغیرها، و امکان جست‌وجو در کد فراهم می‌کند. پیاده‌سازی Whoops در وردپرس نیازمند نصب با Composer، ثبت handler اختصاصی، و توجه به تفاوت محیط توسعه و تولید است. در محیط تولید، استفاده از Whoops می‌تواند اطلاعات حساس را افشا کند و بنابراین باید غیرفعال یا محدود شود. در این نوشتار، از معرفی Whoops و مقایسه آن با ابزارهای دیگر، تا نصب، پیکربندی، و سناریوهای عملی در وردپرس را بررسی می‌کنیم.

نخستین‌باری که Whoops را در یک پروژه وردپرسی راه‌اندازی کردم، تفاوت تجربه دیباگ شگفت‌انگیز بود. به‌جای جست‌وجو در debug.log و حدس زدن اینکه خطا از کجا آمده، یک صفحه تعاملی با stack trace کامل و context متغیرها دیدم. از آن زمان، Whoops به یکی از ابزارهای اصلی من در محیط توسعه تبدیل شده است. در این نوشتار، آن تجربه را با شما به اشتراک می‌گذارم.

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

Whoops یک کتابخانه PHP است که برای نمایش خطاها و استثناها به‌صورت خوانا و تعاملی طراحی شده است. این کتابخانه توسط Filipe Dobreira توسعه یافته و در مخزن Composer با نام filp/whoops منتشر می‌شود. Whoops در فریم‌ورک‌هایی مانند Laravel، Slim، CakePHP و Yii به‌طور پیش‌فرض یا اختیاری استفاده می‌شود و در جوامع PHP جایگاه شناخته‌شده‌ای دارد.

مسئله اصلی که Whoops حل می‌کند، تجربه دیباگ خشک و مبهم PHP است. در حالت پیش‌فرض، وقتی خطایی رخ می‌دهد، PHP یک پیام کوتاه با شماره خط نمایش می‌دهد که برای عیب‌یابی کافی نیست. Whoops با نمایش stack trace کامل، context متغیرها در هر فریم، و امکان جست‌وجو در کد، عیب‌یابی را از چند ساعت به چند دقیقه کاهش می‌دهد.

سه ویژگی کلیدی Whoops:

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

این ویژگی‌ها، Whoops را به یکی از محبوب‌ترین ابزارهای دیباگ در اکوسیستم PHP تبدیل کرده است. برای درک عمیق‌تر مکانیزم خطا در PHP، خطای Fatal error در PHP را ببینید.

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

چرا Whoops برای وردپرس مفید است؟

وردپرس به‌طور پیش‌فرض ابزارهای دیباگ محدودی دارد. WP_DEBUG فقط خطاها را در debug.log ذخیره می‌کند و wp_die() یک صفحه ساده نمایش می‌دهد. برای توسعه‌دهندگانی که با پروژه‌های پیچیده کار می‌کنند، این ابزارها کافی نیستند. Whoops چهار مزیت اصلی برای وردپرس فراهم می‌کند:

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

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

تفاوت Whoops و حالت پیش‌فرض وردپرس

ویژگی	حالت پیش‌فرض وردپرس	Whoops
Stack Trace	محدود	کامل
Context متغیرها	خیر	بله
رابط کاربری	ساده	تعاملی
جست‌وجو در کد	خیر	بله
Handler سفارشی	محدود	گسترده
سازگاری با AJAX	پاسخ JSON را می‌شکند	قابل تنظیم

جمع‌بندی این مقایسه ساده است: برای دیباگ ساده، WP_DEBUG کافی است؛ برای دیباگ پیچیده در پروژه‌های بزرگ، Whoops تفاوت چشمگیری ایجاد می‌کند. برای درک عمیق‌تر ابزارهای دیباگ، دیباگ کردن کدهای سفارشی وردپرس را ببینید.

نصب Whoops با Composer

Whoops از طریق Composer نصب می‌شود. در فایل composer.json پروژه:

composer require --dev filp/whoops

نکته مهم: Whoops به‌عنوان وابستگی توسعه (--dev) نصب می‌شود، زیرا در محیط تولید نباید فعال باشد. برای درک عمیق‌تر مدیریت وابستگی‌ها، آموزش Composer در PHP را ببینید.

پس از نصب، پوشه vendor/filp/whoops در پروژه ایجاد می‌شود. اگر پروژه شما از vendor استفاده می‌کند (که با Composer این‌طور است)، به‌طور خودکار در دسترس است.

راه‌اندازی پایه در وردپرس

برای راه‌اندازی Whoops در وردپرس، یک mu-plugin یا افزونه اختصاصی بسازید که فقط در محیط توسعه فعال باشد. یک نمونه ساده:

<?php
// wp-content/mu-plugins/whoops-debug.php

if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
    return;
}

if ( ! file_exists( __DIR__ . '/../vendor/autoload.php' ) ) {
    return;
}

require_once __DIR__ . '/../vendor/autoload.php';

$whoops = new \Whoops\Run();
$whoops->pushHandler( new \Whoops\Handler\PrettyPageHandler() );
$whoops->register();

این کد، Whoops را در محیط توسعه فعال می‌کند و خطاها را در یک صفحه زیبا نمایش می‌دهد. اگر سایت شما خطایی تولید کند، به‌جای صفحه سفید یا پیام کوتاه PHP، یک صفحه تعاملی با stack trace کامل خواهید دید.

ادغام با WP_DEBUG

ترکیب Whoops با WP_DEBUG:

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

// سپس در mu-plugin:
$whoops = new \Whoops\Run();
$whoops->pushHandler( new \Whoops\Handler\PrettyPageHandler() );
$logger = new \Whoops\Handler\CallbackHandler( function( $exception ) {
    error_log( $exception->getMessage() );
} );
$whoops->pushHandler( $logger );
$whoops->register();

این الگو، خطاها را هم در صفحه نمایش می‌دهد و هم در debug.log ذخیره می‌کند. برای درک عمیق‌تر خطاهای PHP، خطای Warning در PHP را ببینید.

مدیریت Whoops در محیط تولید

یکی از مسائل مهم در استفاده از Whoops، مدیریت آن در محیط تولید است. اگر Whoops در محیط تولید فعال باشد، هر خطا اطلاعات حساسی مانند مسیر فایل‌ها، نسخه PHP، و context متغیرها را نمایش می‌دهد که می‌تواند به مهاجم کمک کند.

راه‌حل‌های امن:

فعال نکردن Whoops در تولید: ساده‌ترین راه.
استفاده از CallbackHandler در تولید: به‌جای PrettyPageHandler، از CallbackHandler استفاده کنید که خطاها را به لاگ ارسال می‌کند.
محدود کردن بر اساس IP: Whoops را فقط برای IPهای مشخص فعال کنید.
محدود کردن بر اساس نقش کاربر: Whoops را فقط برای مدیران فعال کنید.

$is_development = ( defined( 'WP_ENVIRONMENT_TYPE' ) && WP_ENVIRONMENT_TYPE === 'development' );
$is_admin = current_user_can( 'manage_options' );

if ( $is_development && $is_admin ) {
    $whoops = new \Whoops\Run();
    $whoops->pushHandler( new \Whoops\Handler\PrettyPageHandler() );
    $whoops->register();
}

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

Handlerهای سفارشی و ادغام با debug.log

Whoops چندین handler پیش‌فرض دارد:

Handler	کاربرد
`PrettyPageHandler`	نمایش صفحه HTML تعاملی
`PlainTextHandler`	نمایش متن ساده (برای CLI)
`JsonResponseHandler`	پاسخ JSON (برای API)
`CallbackHandler`	ارسال خطا به تابع سفارشی

ترکیب چند handler برای سناریوهای مختلف:

$whoops = new \Whoops\Run();

if ( defined( 'DOING_AJAX' ) && DOING_AJAX ) {
    $whoops->pushHandler( new \Whoops\Handler\JsonResponseHandler() );
} else {
    $whoops->pushHandler( new \Whoops\Handler\PrettyPageHandler() );
}

$whoops->pushHandler( new \Whoops\Handler\CallbackHandler( function( $exception ) {
    error_log( sprintf(
        '[Whoops] %s in %s:%d',
        $exception->getMessage(),
        $exception->getFile(),
        $exception->getLine()
    ) );
} ) );

$whoops->register();

این الگو، خطاها را بر اساس زمینه (AJAX یا غیر AJAX) نمایش می‌دهد و همه را در debug.log ثبت می‌کند. برای درک عمیق‌تر AJAX، AJAX Debugging در وردپرس را ببینید.

Whoops در AJAX و REST API

یکی از چالش‌های دیباگ در وردپرس، خطاهای AJAX و REST API است. اگر Whoops با PrettyPageHandler فعال باشد، پاسخ JSON را با HTML می‌شکند و JavaScript نمی‌تواند آن را پردازش کند. راه‌حل، استفاده از JsonResponseHandler در این زمینه‌ها است:

if ( wp_doing_ajax() ) {
    $whoops->pushHandler( new \Whoops\Handler\JsonResponseHandler() );
} else {
    $whoops->pushHandler( new \Whoops\Handler\PrettyPageHandler() );
}

در REST API:

if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
    $whoops->pushHandler( new \Whoops\Handler\JsonResponseHandler() );
}

این الگو، خطاها را در قالب JSON برمی‌گرداند که JavaScript می‌تواند آن را در Console نمایش دهد. برای درک عمیق‌تر REST API، استفاده از REST API در وردپرس را ببینید.

Whoops در CLI و WP-CLI

Whoops در محیط CLI مفید است، اما باید از PlainTextHandler استفاده کرد، زیرا HTML در ترمینال قابل خواندن نیست:

if ( defined( 'WP_CLI' ) && WP_CLI ) {
    $whoops->pushHandler( new \Whoops\Handler\PlainTextHandler() );
} elseif ( wp_doing_ajax() ) {
    $whoops->pushHandler( new \Whoops\Handler\JsonResponseHandler() );
} else {
    $whoops->pushHandler( new \Whoops\Handler\PrettyPageHandler() );
}

این الگو، تجربه دیباگ را در همه زمینه‌ها بهبود می‌بخشد. برای درک عمیق‌تر WP-CLI، دستورات ضروری CLI را ببینید.

سناریوهای واقعی در پروژه‌های وردپرسی

در پروژه‌های واقعی، Whoops در چند سناریو بیشترین ارزش را ایجاد می‌کند:

سناریو ۱: خطای Fatal در hook

وقتی یک افزونه در hook init خطای Fatal می‌دهد، تشخیص آن با debug.log دشوار است. Whoops با نمایش stack trace کامل، به‌سرعت نشان می‌دهد کدام hook، کدام تابع، و کدام پارامتر عامل خطا بوده است.

سناریو ۲: خطای AJAX در محیط تولید

در محیط تولید، خطاهای AJAX معمولاً فقط پاسخ 0 یا 500 برمی‌گردانند و ریشه مشخص نیست. با Whoops و JsonResponseHandler، خطا در Console مرورگر به‌طور کامل نمایش داده می‌شود.

سناریو ۳: خطای REST API در اپلیکیشن موبایل

در توسعه اپلیکیشن‌هایی که از REST API وردپرس استفاده می‌کنند، خطاهای سرور در اپلیکیشن مبهم هستند. Whoops با JsonResponseHandler، خطا را با context کامل به اپلیکیشن می‌فرستد.

سناریو ۴: دیباگ در محیط staging

در محیط staging، Whoops می‌تواند برای همه کاربران فعال باشد و به کشف خطاها کمک کند، بدون اینکه اطلاعات حساس محیط تولید افشا شود.

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

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

فعال کردن Whoops در محیط تولید: این کار اطلاعات حساس را افشا می‌کند.
استفاده از PrettyPageHandler در AJAX: پاسخ JSON را می‌شکند.
عدم استفاده از CallbackHandler: بدون آن، خطاها در debug.log ثبت نمی‌شوند.
نصب Whoops به‌عنوان وابستگی اصلی: باید --dev باشد.
فراموش کردن register(): بدون آن، Whoops فعال نمی‌شود.
عدم بررسی وجود vendor/autoload.php: در محیط‌های مختلف، مسیر متفاوت است.
فعال بودن WP_DEBUG_DISPLAY: می‌تواند با Whoops تداخل کند.
عدم محدودسازی بر اساس نقش: در سایت‌های چندکاربره، همه کاربران صفحات خطا را می‌بینند.
نادیده گرفتن WP-CLI: باید handler مناسب برای CLI استفاده شود.
عدم تست در محیط staging: قبل از فعال‌سازی در تولید، در staging تست کنید.

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

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

Whoops چیست و چه کاربردی دارد؟ یک کتابخانه PHP برای نمایش خطاها و استثناها با رابط تعاملی، stack trace کامل، و context متغیرها.

آیا Whoops جایگزین WP_DEBUG است؟ نه، مکمل آن است. WP_DEBUG خطاها را در لاگ ذخیره می‌کند و Whoops آن‌ها را به‌صورت خوانا نمایش می‌دهد.

چطور Whoops را در وردپرس نصب کنم؟ با Composer: composer require --dev filp/whoops. سپس در یک mu-plugin، handler را ثبت کنید. برای مراحل کامل، راه‌اندازی PHPUnit در وردپرس را ببینید.

آیا Whoops در محیط تولید امن است؟ به‌طور پیش‌فرض نه، زیرا اطلاعات حساس را افشا می‌کند. باید محدود به IP یا نقش کاربر باشد یا از CallbackHandler استفاده شود.

چطور از Whoops در AJAX استفاده کنم؟ با JsonResponseHandler. برای مرور، AJAX Debugging در وردپرس را ببینید.

آیا Whoops با PHPUnit کار می‌کند؟ بله، Whoops می‌تواند در تست‌های PHPUnit برای نمایش خطاهای غیرمنتظره استفاده شود. برای مرور، راه‌اندازی PHPUnit در وردپرس را ببینید.

آیا Whoops روی عملکرد سایت تأثیر دارد؟ در حالت عادی (بدون خطا) تأثیر آن حداقلی است. فقط هنگام بروز خطا، پردازش اضافی انجام می‌دهد.

چطور Whoops را در محیط staging فعال کنم؟ با تعریف WP_ENVIRONMENT_TYPE = 'staging' و فعال‌سازی Whoops فقط در این محیط.

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

خط پایان

Whoops Error Handler یکی از آن ابزارهایی است که پس از استفاده، دیگر نمی‌توان بدون آن کار کرد. این کتابخانه، تجربه دیباگ در وردپرس را از یک فرآیند خسته‌کننده و مبهم، به یک جریان کار سریع و شفاف تبدیل می‌کند. با stack trace کامل، context متغیرها، و رابط تعاملی، عیب‌یابی خطاهای پیچیده از چند ساعت به چند دقیقه کاهش می‌یابد. اما استفاده از آن نیازمند رعایت نکات امنیتی است: در محیط تولید نباید فعال باشد، و در AJAX و REST API باید handler مناسب استفاده شود. اگر پروژه وردپرسی پیچیده‌ای دارید، Whoops یکی از مؤثرترین سرمایه‌گذاری‌هایی است که می‌توانید در ابزارهای توسعه انجام دهید.

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