خطاهای رایج PHP و راه رفع آن‌ها در وردپرس: راهنمای عیب‌یابی

سایت وردپرسی‌تان ناگهان صفحه سفید نشان می‌دهد یا بالای صفحه یک خط قرمز مثل «Fatal error: Allowed memory size exhausted» چاپ شده است. بیشتر خطاهای رایج PHP چند علت مشخص دارند و پیدا کردنشان به حدس زدن نیاز ندارد، چون خود PHP نوع خطا، نام فایل و شماره خط را می‌گوید. در این مقاله ۹ خطای پرتکرار را با علت و راه رفع هر کدام می‌بینید. قبل از آن هم یاد می‌گیرید خطا را از کجا بخوانید، چون بدون دیدن پیام اصلی هر تعمیری شانسی است.

فهرست مطالب

• اول پیام خطا را ببینید
• انواع خطا در PHP
• ۱. Parse error: syntax error
• ۲. Allowed memory size exhausted
• ۳. Maximum execution time exceeded
• ۴. Call to undefined function و Class not found
• ۵. Uncaught TypeError
• ۶. Undefined variable و Undefined array key
• ۷. Headers already sent
• ۸. Creation of dynamic property is deprecated
• ۹. Passing null to parameter is deprecated
• نسخه PHP و خطاهای بعد از ارتقا
• سؤالات متداول

اول پیام خطا را ببینید

وقتی سایت صفحه سفید یا خطای ۵۰۰ می‌دهد، PHP معمولاً پیام دقیق را پنهان کرده است. برای دیدنش در وردپرس سه ثابت در فایل wp-config.php کافی است. طبق مستندات رسمی وردپرس، WP_DEBUG کلید اصلی است، WP_DEBUG_LOG خطاها را در فایل wp-content/debug.log می‌نویسد و WP_DEBUG_DISPLAY تعیین می‌کند خطا روی صفحه چاپ شود یا نه.

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

این ترکیب روی سایت زنده بهترین گزینه است، چون خطا در فایل ثبت می‌شود و بازدیدکننده‌ها چیزی نمی‌بینند. این سه خط را باید بالاتر از خط «That’s all, stop editing» بگذارید. بعد صفحه خراب را یک بار باز کنید و آخرین خط‌های debug.log را بخوانید. هر خطا سه چیز دارد: نوع، پیام و مسیر فایل با شماره خط. مسیر فایل به شما می‌گوید مشکل از قالب، یک افزونه یا هسته وردپرس است. وقتی کارتان تمام شد، WP_DEBUG را به false برگردانید و فایل لاگ را پاک کنید، چون ممکن است مسیرهای داخلی سرور در آن باشد.

اگر وردپرس اصلاً بالا نمی‌آید و به wp-config.php هم دسترسی ندارید، لاگ خطای خود PHP را از پنل هاست بخوانید. در بیشتر پنل‌ها فایلی به نام error_log کنار فایل‌های سایت ساخته می‌شود. اگر نمی‌دانید کجاست، از پشتیبانی هاستتان بپرسید.

انواع خطا در PHP

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

نوع	معنی	اثر روی سایت
Parse error	کد از نظر نگارشی غلط است	اجرا متوقف می‌شود
Fatal error	خطای غیرقابل ادامه، مثل نبود تابع یا پر شدن حافظه	اجرا متوقف می‌شود
Uncaught Error / TypeError	استثنایی که کسی آن را مدیریت نکرده	اجرا متوقف می‌شود
Warning	مشکلی هست ولی کد ادامه می‌دهد	معمولاً سایت کار می‌کند، اما رفتار ممکن است غلط باشد
Deprecated	این کد در نسخه‌های بعدی کار نخواهد کرد	فعلاً بی‌اثر، ولی در ارتقا خراب می‌شود

اگر لاگ پر از Deprecated و Warning است ولی سایت کار می‌کند، اول سراغ Fatal و Parse بروید و بقیه را بعداً مرتب کنید.

۱. Parse error: syntax error

علت: یک اشتباه نگارشی در فایل PHP، مثل نقطه‌ویرگول فراموش‌شده، پرانتز یا آکولاد بسته‌نشده یا گیومه‌ای که باز مانده است. این خطا تقریباً همیشه بعد از ویرایش دستی functions.php یا چسباندن یک تکه کد از اینترنت پیش می‌آید.

PHP Parse error: syntax error, unexpected token "}" in
/wp-content/themes/my-theme/functions.php on line 42

راه رفع:

1. مسیر فایل و شماره خط را از پیام بخوانید.
2. خط گفته‌شده و چند خط قبل از آن را نگاه کنید. PHP خطا را آنجا گزارش می‌کند که دیگر نمی‌تواند ادامه دهد، و ریشه مشکل معمولاً کمی بالاتر است.
3. اگر تازه کدی اضافه کرده‌اید، همان را حذف یا کامنت کنید.
4. فایل را با FTP یا مدیریت فایل هاست باز کنید، چون پیشخوان وردپرس در این وضعیت بالا نمی‌آید.

در نسخه‌های PHP 8 پیام‌ها دقیق‌تر شده‌اند و مثلاً می‌گویند کدام توکن غیرمنتظره بوده است. اگر سایتتان تازه به PHP 8 رفته و این خطا را می‌بینید، افزونه یا قالب قدیمی که کدش با نسخه جدید سازگار نیست محتمل‌ترین مقصر است.

۲. Allowed memory size exhausted

Fatal error: Allowed memory size of 67108864 bytes exhausted
(tried to allocate 20480 bytes) in /wp-includes/...

علت: اجرای یک صفحه بیشتر از سقف رم مجاز PHP مصرف کرده است. عددی که در پیام می‌بینید به بایت است. ۶۷۱۰۸۸۶۴ بایت یعنی ۶۴ مگابایت. معمولاً یکی از این سه اتفاق افتاده است: افزونه سنگین، پردازش حجم زیادی داده (مثلاً ایمپورت محصول یا ساخت بکاپ) یا حلقه‌ای که تمام نمی‌شود.

راه رفع:

• در wp-config.php مقدار حافظه وردپرس را بالا ببرید:

define( 'WP_MEMORY_LIMIT', '256M' );

• اگر تغییر اثری نداشت، سقف اصلی را هاست تعیین می‌کند. مقدار memory_limit را از بخش تنظیمات PHP پنل هاست بالا ببرید یا از پشتیبانی بخواهید.
• بعد از رفع موقت، دنبال علت بگردید. افزونه‌ها را یکی‌یکی غیرفعال کنید و ببینید خطا با کدام برطرف می‌شود. بالا بردن حافظه برای افزونه‌ای که اشتباه نوشته شده فقط مشکل را عقب می‌اندازد.

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

۳. Maximum execution time exceeded

Fatal error: Maximum execution time of 30 seconds exceeded

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

راه رفع: اگر کار واقعاً سنگین است (مثلاً ایمپورت)، مقدار را موقت بالا ببرید. از پنل هاست یا با این خط در فایل .htaccess در سرورهای آپاچی یا لایت‌اسپید:

php_value max_execution_time 120

روی بعضی هاست‌ها این دستور خطای ۵۰۰ می‌دهد، چون PHP به‌صورت FastCGI اجرا می‌شود و مقدارها را باید از پنل تغییر داد. اگر بعد از افزودن آن سایت بالا نیامد، همان خط را پاک کنید. وقتی خطا بدون کار سنگین و بی‌دلیل می‌آید، اتصال به یک API بیرونی که پاسخ نمی‌دهد یا یک کوئری کند دیتابیس را بررسی کنید.

۴. Call to undefined function و Class not found

Fatal error: Uncaught Error: Call to undefined function mb_strlen()
Fatal error: Uncaught Error: Class "WooCommerce" not found

علت: کد تابع یا کلاسی را صدا زده که در آن لحظه وجود ندارد. سه سناریوی رایج:

1. افزونه جانبی بدون افزونه اصلی: مثلاً افزونه‌ای که به ووکامرس وابسته است و ووکامرس غیرفعال یا حذف شده است.
2. افزونه PHP روی سرور نصب نیست: مثل mbstring، curl یا intl. نمونه اول بالا همین حالت است.
3. فایل ناقص آپلود شده: بعد از به‌روزرسانی یا انتقال سایت، بخشی از فایل‌ها نیامده است.

راه رفع: نام تابع یا کلاس را در پیام ببینید و بفهمید به کدام افزونه تعلق دارد. اگر وابستگی است، آن افزونه را فعال یا نصب کنید. اگر افزونه PHP نیست، از بخش «Select PHP Version» یا «PHP Extensions» پنل هاست آن را فعال کنید. اگر بعد از انتقال سایت رخ داده، فایل‌های افزونه را دوباره آپلود کنید. برای مهاجرت بدون این دردسرها می‌توانید از خدمات انتقال سایت وردپرس استفاده کنید.

۵. Uncaught TypeError

Fatal error: Uncaught TypeError: strlen(): Argument #1 ($string)
must be of type string, array given

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

راه رفع:

• ردیابی خطا (stack trace) را در لاگ ببینید. خط اول معمولاً فایل مقصر را نشان می‌دهد.
• اگر فایل متعلق به افزونه یا قالب است، آن را به آخرین نسخه به‌روز کنید. اگر نسخه جدید ندارد، نسخه PHP را موقت یک پله پایین بیاورید تا جایگزین پیدا کنید.
• اگر کد خودتان است، نوع داده را قبل از ارسال بررسی کنید، مثلاً با is_string( $value ).

۶. Undefined variable و Undefined array key

Warning: Undefined variable $total in ... on line 18
Warning: Undefined array key "page" in ... on line 25

علت: به متغیری که تعریف نشده یا به کلیدی که در آرایه وجود ندارد دسترسی داده‌اید. در PHP 8 این دو مورد با همین سطح Warning گزارش می‌شوند. مثلاً کد $page = $_GET['page']; وقتی در آدرس پارامتر page نباشد همین هشدار را می‌دهد.

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

$page  = $_GET['page'] ?? 'home';
$total = 0; // قبل از حلقه‌ای که روی آن جمع می‌زند

این‌ها هشدارند و سایت را از کار نمی‌اندازند، اما در لاگ شما را غرق می‌کنند و ممکن است رفتار غلط بسازند (مثلاً جمع اشتباه). اگر مقصر یک افزونه است، به‌روزرسانی یا گزارش به سازنده کافی است.

۷. Headers already sent

Warning: Cannot modify header information - headers already sent by
(output started at /wp-content/themes/my-theme/functions.php:3)

علت: PHP قبل از ارسال هدر (مثل ریدایرکت یا کوکی ورود) چیزی را به مرورگر فرستاده است. حتی یک فاصله یا خط خالی کافی است. دو منبع رایج دارد: فضای خالی بعد از تگ بستن ?> در انتهای فایل، یا نشانه BOM که بعضی ویرایشگرها اول فایل اضافه می‌کنند.

بخش داخل پرانتز مهم‌ترین قسمت پیام است: «output started at» دقیقاً فایل و خطی را می‌گوید که اولین خروجی از آنجا آمده است.

راه رفع:

1. فایل گفته‌شده را باز کنید.
2. همه فضای خالی و خط‌های خالی بعد از ?> را پاک کنید. در فایل‌هایی که فقط PHP دارند، اصلاً تگ بستن لازم نیست و حذفش امن‌ترین کار است.
3. فایل را با کدگذاری UTF-8 بدون BOM ذخیره کنید.

۸. Creation of dynamic property is deprecated

Deprecated: Creation of dynamic property MyClass::$title is deprecated

علت: از PHP 8.2 به بعد، تعریف یک ویژگی (property) که در کلاس اعلام نشده منسوخ شده است. طبق RFC رسمی PHP، در نسخه 8.2 فقط هشدار Deprecated می‌دهد و خصوصیت همچنان ساخته می‌شود، ولی در PHP 9.0 قرار است به Error تبدیل شود. یعنی افزونه‌ای که امروز فقط هشدار می‌دهد، در ارتقای بزرگ بعدی از کار می‌افتد.

راه رفع (برای کد خودتان): ویژگی را در کلاس تعریف کنید:

class MyClass {
    public $title; // این خط خطا را برطرف می‌کند
}

اگر استفاده از ویژگی پویا عمدی است، می‌توانید بالای کلاس #[AllowDynamicProperties] بگذارید. برای افزونه‌های دیگران کاری از شما ساخته نیست جز به‌روزرسانی یا گزارش به سازنده.

۹. Passing null to parameter is deprecated

Deprecated: strlen(): Passing null to parameter #1 ($string)
of type string is deprecated

علت: از PHP 8.1، دادن null به پارامتری از توابع داخلی که null را نمی‌پذیرد، هشدار Deprecated تولید می‌کند. مثلاً strlen( $title ) وقتی $title خالی است. این یکی از رایج‌ترین پیام‌های لاگ بعد از ارتقا به PHP 8.1 است.

راه رفع: مقدار پیش‌فرض بدهید:

$length = strlen( $title ?? '' );

نسخه PHP و خطاهای بعد از ارتقا

بخش بزرگی از خطاهای بالا (TypeError، Undefined array key، dynamic property، Passing null) به نسخه PHP مربوط است. نسخه‌های جدید سخت‌گیرترند و کد قدیمی را رد می‌کنند. ولی ماندن روی نسخه قدیمی هم راه‌حل نیست، چون نسخه‌ای که پشتیبانی امنیتی ندارد، حفره‌های کشف‌شده را دیگر وصله نمی‌کند. بر اساس صفحه رسمی نسخه‌های پشتیبانی‌شده PHP و جمع‌بندی منابع مرجع، وضعیت نسخه‌ها از پایان ۲۰۲۶ این است (تاریخ‌ها را قبل از تصمیم در صفحه رسمی php.net دوباره ببینید، چون ممکن است تغییر کنند):

نسخه	پایان پشتیبانی امنیتی
PHP 8.1	پایان یافته (۳۱ دسامبر ۲۰۲۵)
PHP 8.2	۳۱ دسامبر ۲۰۲۶
PHP 8.3	۳۱ دسامبر ۲۰۲۷
PHP 8.4	۳۱ دسامبر ۲۰۲۸
PHP 8.5	۳۱ دسامبر ۲۰۲۹

برای ارتقای امن این ترتیب را رعایت کنید:

1. بکاپ کامل از فایل‌ها و دیتابیس بگیرید.
2. همه افزونه‌ها، قالب و هسته وردپرس را به‌روز کنید. جزئیات را در مقاله بروزرسانی سایت وردپرسی ببینید.
3. اگر امکان دارد، ابتدا روی یک نسخه آزمایشی (staging) نسخه جدید PHP را امتحان کنید.
4. در پنل هاست یک پله بالا بروید (مثلاً از 8.1 به 8.2)، نه چند پله با هم. بعد WP_DEBUG_LOG را روشن کنید و صفحه‌های اصلی، فرم‌ها و پرداخت را بگردید.
5. اگر خطای بحرانی دیدید، نسخه را به حالت قبل برگردانید و افزونه مقصر را از مسیر فایل در لاگ پیدا کنید.

ارتقا با مسائل امنیتی هم ارتباط دارد. نمونه‌اش آسیب‌پذیری‌ای است که در مقاله PHP2Shell بررسی کرده‌ایم.

سؤالات متداول

لاگ خطای PHP در وردپرس کجاست؟

اگر WP_DEBUG_LOG را فعال کرده باشید، در مسیر wp-content/debug.log است. لاگ خود PHP معمولاً فایلی به نام error_log در پوشه سایت یا در بخش «Errors» پنل هاست است.

خطای Allowed memory size exhausted را چطور رفع کنم؟

مقدار WP_MEMORY_LIMIT را در wp-config.php بالا ببرید و اگر اثری نداشت، memory_limit را از پنل هاست افزایش دهید. بعد افزونه‌ای را که بیشترین مصرف را دارد پیدا و بررسی کنید.

فرق Warning و Fatal error چیست؟

Warning یعنی مشکلی هست ولی اجرا ادامه پیدا می‌کند. Fatal error یعنی اجرا همان‌جا قطع می‌شود و معمولاً صفحه سفید یا خطای ۵۰۰ می‌بینید.

بعد از ارتقای PHP سایتم خراب شد. چه کنم؟

نسخه PHP را در پنل هاست به نسخه قبلی برگردانید تا سایت بالا بیاید. بعد با لاگ خطا افزونه یا قالب مقصر را پیدا و به‌روز کنید و دوباره یک پله ارتقا دهید.

آیا نمایش خطا روی سایت زنده خطرناک است؟

بله. پیام‌های خطا مسیر فایل‌ها و گاهی جزئیات سرور را نشان می‌دهند. روی سایت زنده نمایش را خاموش کنید (WP_DEBUG_DISPLAY برابر false) و خطا را فقط در فایل لاگ ثبت کنید.

PHP 8.1 هنوز امن است؟

بر اساس تاریخ‌های منتشرشده، پشتیبانی امنیتی PHP 8.1 در پایان سال ۲۰۲۵ تمام شده است. اگر هاستتان هنوز همان را ارائه می‌دهد، نسخه جدیدتر را از پنل انتخاب یا از پشتیبانی درخواست کنید.

از کجا شروع کنید؟

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

منابع: مستندات رسمی وردپرس: Debugging in WordPress · PHP: Supported Versions · PHP RFC: Deprecate dynamic properties