خطای MySQLi extension missing در PHP چیست و چگونه آن را در وردپرس رفع کنیم؟

خطای MySQLi extension missing در PHP، یکی از آن خطاهایی است که در نگاه اول ساده به نظر می‌رسد ولی می‌تواند کل سایت وردپرسی را با یک صفحه سفید از کار بیندازد. اولین باری که این خطا را در یک پروژه واقعی دیدم، روی یک هاست اشتراکی بود که مدیرش، سرور را از PHP ۷.۴ به PHP ۸.۰ ارتقا داده بود بدون توجه به این‌که افزونه mysqli در نسخه جدید فعال نیست. نتیجه این تغییر، پیام کوتاه ولی کشنده‌ای بود که در آن لحظه حتی نام دقیق افزونه مفقود را نشان نمی‌داد. فهمیدن اینکه ریشه مشکل در سطح PHP است نه در سطح وردپرس، برای صاحب سایت سخت بود چون از نظر او، همه چیز در دیروز کار می‌کرد.

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

خطای MySQLi extension missing دقیقاً چه می‌گوید؟

این خطا در PHP یعنی: کد شما یا وردپرس تلاش کرده از توابع نسخه بهبودیافته MySQL یعنی MySQLi استفاده کند، ولی این افزونه روی سرور شما فعال نیست. mysqli یک افزونه PHP است که برای برقراری ارتباط با دیتابیس MySQL طراحی شده و اگر فعال نباشد، هیچ تابعی از این خانواده در دسترس کد PHP نخواهد بود. پیام دقیق این خطا معمولاً به شکل زیر است:

Fatal error: Uncaught Error: Call to undefined function mysqli_connect()
in /path/to/wordpress/wp-includes/wp-db.php:1720
Stack trace:
#0 /path/to/wordpress/wp-includes/load.php(573): wpdb->__construct()
#1 /path/to/wordpress/wp-settings.php(137): require_wp_db()
#2 /path/to/wordpress/wp-config.php(92): require_once( '/path/to/wordpress/wp-settings.php' )
...

سه چیز در این پیام مهم است. اول، نام تابع یا کلاس مفقود: در مثال بالا mysqli_connect(). این نام، دقیقاً به شما می‌گوید که کدام افزونه PHP فعال نیست. دوم، مسیر فایلی که در آن تلاش برای استفاده از این تابع انجام شده — در بیشتر موارد، این فایل در هسته وردپرس است چون وردپرس از mysqli استفاده می‌کند. سوم، stack trace که ترتیب اجرا را نشان می‌دهد.

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

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

Your PHP installation appears to be missing the MySQL extension which is required by WordPress.

این پیام، نسخه ساده‌تر و کاربرپسندتر همان خطا است که وردپرس مستقیماً نمایش می‌دهد. در این حالت، وردپرس در همان مراحل اولیه راه‌اندازی تشخیص می‌دهد که افزونه mysqli در دسترس نیست و با یک پیام مشخص متوقف می‌شود. این رویکرد، به‌دلیل طراحی وردپرس است که از چند سال پیش به‌جای استفاده از توابع قدیمی mysql، از mysqli یا pdo_mysql استفاده می‌کند.

خطای MySQLi extension missing، پیامی واضح دارد: افزونه mysqli در PHP فعال نیست. رفع ریشه‌ای، فعال‌سازی این افزونه است نه تلاش برای حذف خطا.

mysqli و pdo_mysql: تفاوت و نقش در وردپرس

برای درک دقیق این خطا، باید تفاوت بین دو افزونه اصلی PHP برای اتصال به MySQL را بشناسید: mysqli و pdo_mysql. هر دو، در نهایت با دیتابیس MySQL کار می‌کنند ولی از نظر معماری، رویکرد و کاربرد متفاوتند. درک این تفاوت، در انتخاب راه‌حل رفع خطا نقش کلیدی دارد.

MySQLi: افزونه اختصاصی MySQL

MySQLi (که مخفف MySQL Improved است و در مرجع فنی وب با نام MySQLi شناخته می‌شود) یک افزونه PHP اختصاصی برای MySQL است. این افزونه، توابعی مثل mysqli_connect()، mysqli_query() و mysqli_fetch_assoc() فراهم می‌کند. مزیت اصلی‌اش، پشتیبانی کامل از ویژگی‌های اختصاصی MySQL و سرعت بالاتر نسبت به pdo_mysql در بعضی سناریوها است. عیب اصلی‌اش، وابستگی کامل به MySQL است و در صورت مهاجرت به دیتابیس دیگر، همه کد باید بازنویسی شود.

PDO: لایه انتزاعی دیتابیس

PDO که مخفف PHP Data Objects است و در مرجع فنی با عنوان PHP Data Objects شناخته می‌شود، یک لایه انتزاعی است که امکان اتصال به چند نوع دیتابیس (MySQL، PostgreSQL، SQLite و…) را با یک API یکسان فراهم می‌کند. افزونه pdo_mysql بخش مخصوص MySQL در این لایه است. مزیت اصلی PDO، انعطاف‌پذیری و پرتاب استثنا (Exception) در خطاها است. عیب اصلی، سرعت کمی پایین‌تر در سناریوهای ساده.

وردپرس و انتخاب بین این دو

وردپرس کلاس wpdb را دارد که لایه انتزاعی خودش را می‌سازد. این کلاس، از PHP 5.5 به بعد، به‌طور خودکار در زمان بارگذاری، بررسی می‌کند که آیا mysqli فعال است یا نه. اگر باشد، از mysqli استفاده می‌کند؛ اگر نباشد، از pdo_mysql بهره می‌برد؛ و اگر هیچ‌کدام فعال نباشد، خطای مورد بحث را برمی‌گرداند. این مکانیزم را می‌توان در فایل wp-includes/wp-db.php مشاهده کرد.

ویژگی	mysqli	pdo_mysql
توابع اختصاصی	`mysqli_*`	متدهای `PDO`
پشتیبانی از چند دیتابیس	خیر	بله
پرتاب Exception	اختیاری	پیش‌فرض
سرعت در سناریوی ساده	کمی بالاتر	کمی پایین‌تر
توصیه رسمی PHP	برای MySQL	برای چند دیتابیس

در پروژه‌های واقعی، وردپرس معمولاً از mysqli استفاده می‌کند چون این افزونه در اکثر هاست‌های اشتراکی به‌طور پیش‌فرض فعال است. اگر این افزونه فعال نباشد، وردپرس سراغ pdo_mysql می‌رود. اگر هر دو مفقود باشند، خطای مورد بحث رخ می‌دهد. جزئیات فنی این مکانیزم در اتصال PHP به MySQL و آموزش PDO در PHP آمده است.

چرا این خطا در پروژه‌های وردپرسی رخ می‌دهد؟

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

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

شایع‌ترین سناریو. وقتی هاست، نسخه PHP را از ۷.۴ به ۸.۰ یا از ۸.۰ به ۸.۱ ارتقا می‌دهد، گاهی پیکربندی افزونه‌های PHP در نسخه جدید، از نسخه قبلی کپی نمی‌شود. نتیجه این است که سایت روی نسخه جدید PHP بالا نمی‌آید چون افزونه mysqli در آن فعال نیست. تجربه میدانی من این است که این سناریو در هاست‌های ایرانی، بیشتر از هاست‌های بین‌المللی رخ می‌دهد چون پیکربندی نسخه‌های PHP در پنل‌ها کمتر یکپارچه است.

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

سناریوی دوم: مهاجرت به هاست جدید

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

سناریوی سوم: نصب وردپرس روی سرور بدون پیکربندی MySQL

در نصب‌های دستی روی VPS یا سرور اختصاصی، اگر مدیر سرور، پکیج PHP را نصب کند ولی افزونه php-mysql یا php-mysqli را نصب نکند، این خطا رخ می‌دهد. این سناریو در سرورهای لینوکسی که با پکیج مدیر نصب می‌شوند، بیشتر دیده می‌شود چون به‌طور پیش‌فرض همه افزونه‌ها نصب نمی‌شوند.

سناریوی چهارم: Docker و محیط‌های کانتینری

در محیط‌های Docker، اگر ایمیج PHP از نوع php:fpm-alpine یا مشابه باشد، ممکن است افزونه mysqli در آن نصب نباشد. راه‌حل، اضافه کردن دستور نصب افزونه در Dockerfile است:

RUN docker-php-ext-install mysqli pdo pdo_mysql

این الگو در پروژه‌هایی که وردپرس را روی Kubernetes یا Docker اجرا می‌کنند، بسیار رایج است.

سناریوی پنجم: محیط لوکال بدون پیکربندی کامل

در محیط‌های لوکال مثل XAMPP، WAMP یا MAMP، اگر افزونه mysqli در php.ini غیرفعال باشد، این خطا رخ می‌دهد. در این محیط‌ها معمولاً افزونه به‌طور پیش‌فرض فعال است ولی اگر کسی پیکربندی را تغییر داده باشد، ممکن است مفقود شود. اصول راه‌اندازی محیط لوکال در توسعه وردپرس با محیط لوکال چگونه انجام می‌شود آمده است.

پنج سناریو، یک ریشه مشترک دارند: پیکربندی PHP روی سرور، افزونه mysqli را در دسترس قرار نمی‌دهد. رفع ریشه‌ای، فعال‌سازی افزونه است نه تلاش برای دور زدن آن.

تأثیر نسخه PHP بر دسترسی به mysqli

نسخه PHP، تأثیر مستقیمی بر دسترسی به افزونه mysqli دارد. در نسخه‌های قدیمی‌تر PHP، توابع mysql (بدون i) استفاده می‌شد که از PHP 7.0 به‌طور کامل حذف شدند. این تغییر، در پروژه‌هایی که از کدهای قدیمی استفاده می‌کردند، منبع خطاهای متعددی شد. جدول زیر خلاصه وضعیت افزونه‌های MySQL در نسخه‌های مختلف PHP را نشان می‌دهد:

نسخه PHP	افزونه mysql	افزونه mysqli	افزونه pdo_mysql
PHP 5.x	فعال	فعال	فعال
PHP 7.0 تا 7.3	حذف شده	فعال	فعال
PHP 7.4	حذف شده	فعال	فعال
PHP 8.0 به بالا	حذف شده	فعال	فعال

نکته مهم در این جدول: از PHP 7.0 به بعد، افزونه mysql (بدون i) به‌طور کامل حذف شده و وردپرس هم از نسخه ۵.۳، این تغییر را پذیرفته و از mysqli یا pdo_mysql استفاده می‌کند. اگر سایت شما روی نسخه‌های جدید PHP با خطای mysqli extension missing مواجه می‌شود، یعنی نه mysqli و نه pdo_mysql در دسترس نیستند.

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

تفاوت رفتار در هاست اشتراکی، VPS و سرور اختصاصی

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

هاست اشتراکی

در هاست اشتراکی، دسترسی به php.ini مستقیماً وجود ندارد ولی پنل‌هایی مثل cPanel، DirectAdmin یا پنل‌های اختصاصی هاست‌های ایرانی، امکان فعال‌سازی افزونه‌های PHP را فراهم می‌کنند. در cPanel، این تنظیمات در بخش Select PHP Version یا PHP Extensions قابل دسترسی است. اصول کار با cPanel در cPanel چیست و چه کاربردی دارد؟ آمده است.

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

VPS و سرور اختصاصی

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

برای سیستم‌های Debian و Ubuntu:

sudo apt update
sudo apt install php-mysql php-mysqli
sudo systemctl restart php8.1-fpm
sudo systemctl restart apache2

برای سیستم‌های CentOS، RHEL و AlmaLinux:

sudo dnf install php-mysqlnd
sudo systemctl restart php-fpm
sudo systemctl restart httpd

نکته مهم: در دستورات بالا، نسخه PHP باید با نسخه نصب‌شده روی سرور مطابقت داشته باشد. اگر نسخه PHP 8.1 است، باید php8.1-mysql نصب شود نه php-mysql. این جزئیات، در پروژه‌های واقعی زیاد نادیده گرفته می‌شود و باعث نصب افزونه روی نسخه اشتباه می‌شود.

محیط‌های Docker و Kubernetes

در محیط‌های کانتینری، راه‌حل در سطح Dockerfile یا ایمیج است. اگر از ایمیج رسمی PHP استفاده می‌کنید، باید در Dockerfile این خط را اضافه کنید:

FROM php:8.1-fpm

RUN docker-php-ext-install mysqli pdo pdo_mysql

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

مرحله تشخیص: از phpinfo تا لاگ سرور

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

ابزار اول: تابع phpinfo

سریع‌ترین راه برای بررسی وضعیت افزونه‌های PHP، استفاده از تابع phpinfo() است. یک فایل ساده با محتوای زیر بسازید و در ریشه سایت آپلود کنید:

<?php
phpinfo();
?>

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

ابزار دوم: بررسی در پنل هاست

در cPanel، بخش Select PHP Version وضعیت همه افزونه‌های PHP را نشان می‌دهد. اگر کنار mysqli تیک خورده باشد، افزونه فعال است. اگر تیک نخورده باشد، می‌توانید فعالش کنید. مشابه این بخش در پنل DirectAdmin در قسمت PHP Settings وجود دارد.

ابزار سوم: بررسی در سطح خط فرمان

در VPS و سرور اختصاصی، دستور زیر فهرست افزونه‌های فعال PHP را نشان می‌دهد:

php -m | grep -i mysqli
php -m | grep -i pdo

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

ابزار چهارم: بررسی لاگ سرور

در بعضی سناریوها، لاگ‌های سرور وردپرس دقیق‌تر از پیام خطای عمومی عمل می‌کنند. فعال‌سازی حالت دیباگ وردپرس در wp-config.php این امکان را فراهم می‌کند:

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

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

نکته امنیتی در تشخیص

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

رفع خطا در cPanel و هاست اشتراکی

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

گام اول: ورود به بخش PHP Version

در cPanel، بخش Select PHP Version یا MultiPHP Manager را پیدا کنید. در بعضی پنل‌های ایرانی، این بخش با نام «مدیریت نسخه PHP» یا مشابه نمایش داده می‌شود. اگر با cPanel آشنایی کمتری دارید، cPanel چیست و چه کاربردی دارد؟ راهنمای جامعی است.

گام دوم: انتخاب نسخه PHP و مشاهده افزونه‌ها

در این بخش، فهرست نسخه‌های PHP نمایش داده می‌شود و کنار هر نسخه، وضعیت افزونه‌های آن نشان داده می‌شود. روی نسخه‌ای که سایت شما استفاده می‌کند کلیک کنید تا فهرست کامل افزونه‌ها نمایش داده شود. این فهرست، دو حالت نمایشی دارد: بخش Extensions که فهرست افزونه‌ها است و بخش Options که گزینه‌های پیکربندی PHP را نشان می‌دهد.

گام سوم: فعال‌سازی mysqli و pdo_mysql

در فهرست افزونه‌ها، دو گزینه mysqli و pdo_mysql را پیدا کنید و هر دو را تیک بزنید. علاوه بر این دو، توصیه می‌کنم mysqlnd (که مخفف MySQL Native Driver است) را هم فعال کنید، چون وردپرس روی آن بهتر عمل می‌کند. اگر افزونه دیگری مثل mysql (بدون i) در فهرست دیده می‌شود، آن را نادیده بگیرید چون از PHP 7.0 به بعد حذف شده و اگر فعال باشد، حتی ممکن است مشکلاتی ایجاد کند.

گام چهارم: ذخیره تغییرات

بعد از تیک زدن افزونه‌ها، روی دکمه Save یا Apply کلیک کنید. بعضی پنل‌ها این تغییرات را به‌طور خودکار اعمال می‌کنند و بعضی دیگر، نیازمند ذخیره دستی هستند. در هاست‌های ایرانی، تجربه‌ام این است که تغییرات به‌طور خودکار اعمال می‌شود.

گام پنجم: تست سایت

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

گام ششم: در صورت رد شدن درخواست، تیکت بزنید

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

سلام،

در سایت وردپرسی من خطای زیر رخ می‌دهد:
"Your PHP installation appears to be missing the MySQL extension which is required by WordPress."

لطفاً افزونه‌های mysqli و pdo_mysql را روی نسخه PHP [نسخه] فعال کنید.

با تشکر

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

رفع خطا در VPS و سرور اختصاصی

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

راه‌حل برای Debian و Ubuntu

در سیستم‌های مبتنی بر Debian، افزونه‌های PHP از طریق پکیج مدیر apt نصب می‌شوند. گام‌به‌گام:

# بروزرسانی فهرست پکیج‌ها
sudo apt update

# نصب افزونه‌های MySQL
sudo apt install php-mysql php-mysqli php-pdo-mysql php-mysqlnd

# ری‌استارت سرویس PHP
sudo systemctl restart php8.1-fpm

# ری‌استارت وب‌سرور
sudo systemctl restart apache2
# یا اگر Nginx دارید:
sudo systemctl restart nginx

نکته مهم: در دستور اول، نسخه PHP باید با نسخه نصب‌شده روی سرور مطابقت داشته باشد. اگر نسخه PHP شما 8.1 نیست، عدد را به نسخه صحیح تغییر دهید. برای مشاهده نسخه‌های نصب‌شده:

ls /etc/php/
dpkg -l | grep php

راه‌حل برای CentOS، RHEL و AlmaLinux

در سیستم‌های مبتنی بر RHEL، افزونه‌های PHP از طریق pکیج مدیر dnf یا yum نصب می‌شوند:

# نصب افزونه‌های MySQL
sudo dnf install php-mysqlnd

# ری‌استارت سرویس‌ها
sudo systemctl restart php-fpm
sudo systemctl restart httpd

در سیستم‌های جدیدتر، پکیج php-mysqlnd شامل همه افزونه‌های MySQL مورد نیاز است. اگر از نسخه‌های قدیمی‌تر استفاده می‌کنید، ممکن است نیاز به نصب php-mysqli جداگانه داشته باشید:

sudo dnf install php-mysqli php-pdo

راه‌حل در سرورهایی که از Plesk استفاده می‌کنند

در سرورهایی که Plesk دارند، مراحل فعال‌سازی از طریق پنل انجام می‌شود:

ورود به پنل Plesk.
بخش Tools & Settings و سپس PHP Settings.
انتخاب نسخه PHP و کلیک روی Manage Extensions.
تیک زدن mysqli و pdo_mysql.
ذخیره تغییرات.

مراحل مشابه در پنل DirectAdmin در بخش PHP Settings وجود دارد. اصول کار با سرورهای مدیریت‌شده در VPS مدیریت شده یا مدیریت نشده؟ آمده است.

بررسی پیکربندی PHP بعد از نصب

بعد از نصب یا فعال‌سازی، بررسی کنید که افزونه درست بارگذاری شده است:

php -m | grep -i mysqli
php -m | grep -i pdo_mysql

# بررسی از طریق وب
curl -s https://yoursite.com/phpinfo.php | grep -i mysqli

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

راه‌حل جایگزین: انتقال به pdo_mysql

اگر به هر دلیلی نمی‌توانید افزونه mysqli را فعال کنید، راه‌حل جایگزین استفاده از pdo_mysql است. وردپرس به‌طور خودکار اگر mysqli فعال نباشد، سراغ pdo_mysql می‌رود. برای فعال‌سازی صریح pdo_mysql، در فایل wp-config.php این ثابت را اضافه کنید:

define( 'DB_DRIVER', 'pdo_mysql' );

توجه کنید که این ثابت، در وردپرس به‌طور رسمی پشتیبانی نمی‌شود و مکانیزم تشخیص خودکار وردپرس، اولویت را به mysqli می‌دهد. برای استفاده صریح از pdo_mysql، باید کلاس wpdb را با کلاس اختصاصی جایگزین کنید یا از یک db.php در پوشه wp-content استفاده کنید. این رویکرد در پروژه‌های پیشرفته رایج است ولی برای اکثر پروژه‌ها، فعال‌سازی mysqli ساده‌تر است.

اصول کار با PDO در آموزش PDO در PHP آمده و اتصال به دیتابیس در اتصال PHP به MySQL توضیح داده شده است.

مزایا و معایب استفاده از pdo_mysql به‌جای mysqli

سه مزیت اصلی pdo_mysql نسبت به mysqli وجود دارد. اول، انعطاف‌پذیری در برابر تغییر دیتابیس — اگر در آینده به PostgreSQL یا SQLite مهاجرت کنید، کد شما بدون تغییر کار می‌کند. دوم، پشتیبانی پیش‌فرض از Prepared Statements که در برابر حمله SQL Injection مقاوم‌تر است. سوم، پرتاب Exception به‌طور پیش‌فرض که مدیریت خطا را ساده‌تر می‌کند.

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

انتخاب بین mysqli و pdo_mysql، یک تصمیم معماری است نه سلیقه‌ای؛ در اکثر پروژه‌های وردپرسی، فعال‌سازی هر دو افزونه بهترین رویکرد است.

پرسش‌های پرتکرار درباره خطای MySQLi missing

خطای MySQLi extension missing چه معنایی دارد؟ این خطا در PHP یعنی افزونه mysqli که برای اتصال به دیتابیس MySQL طراحی شده، روی سرور شما فعال نیست. وردپرس برای ارتباط با دیتابیس به این افزونه نیاز دارد. راه‌حل، فعال‌سازی افزونه در پنل هاست یا نصب آن در سطح سرور است.

تفاوت mysqli و pdo_mysql چیست؟ mysqli یک افزونه اختصاصی MySQL است که توابع مثل mysqli_connect() را فراهم می‌کند. pdo_mysql بخشی از لایه انتزاعی PDO است که امکان اتصال به چند دیتابیس مختلف را با API یکسان فراهم می‌کند. هر دو در وردپرس قابل استفاده‌اند و وردپرس به‌طور خودکار تشخیص می‌دهد کدام فعال است.

چرا این خطا در PHP 8 بیشتر از PHP 7.4 دیده می‌شود؟ این خطا به نسخه PHP مربوط نیست، ولی در مهاجرت از PHP 7.4 به PHP 8، اگر پیکربندی افزونه‌های PHP از نسخه قبلی کپی نشود، این خطا رخ می‌دهد. این سناریو در هاست‌های اشتراکی که نسخه PHP را خودکار ارتقا می‌دهند، شایع است.

آیا راه‌حل سریع وجود دارد؟ بله، در اکثر هاست‌های اشتراکی، از پنل cPanel در بخش Select PHP Version می‌توانید در چند دقیقه افزونه mysqli را فعال کنید. اگر پنل هاست این امکان را ندارد، از پشتیبانی بخواهید. در VPS و سرور اختصاصی، از طریق خط فرمان و با دستور نصب پکیج، انجام می‌شود.

چطور بفهمم افزونه mysqli فعال است یا نه؟ سه روش اصلی وجود دارد. اول، از طریق تابع phpinfo() که وضعیت همه افزونه‌ها را نشان می‌دهد. دوم، از پنل هاست در بخش مدیریت نسخه PHP. سوم، از خط فرمان با دستور php -m | grep mysqli. اگر خروجی این دستور نام افزونه را نشان دهد، فعال است.

آیا این خطا روی سرعت سایت اثر دارد؟ این خطا در حالت Fatal Error، اجرای اسکریپت را کاملاً متوقف می‌کند و سایت با خطا بالا نمی‌آید. این یعنی افت کامل سایت نه فقط کندی. اگر با گلوگاه‌های سرعت سایت آشنا نیستید، تاثیر هاست بر سرعت سایت چقدر است تحلیل دقیقی دارد.

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

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

چطور در Docker این خطا را رفع کنم؟ در Dockerfile، قبل از کپی کردن کد وردپرس، دستور زیر را اضافه کنید:

RUN docker-php-ext-install mysqli pdo pdo_mysql

سپس ایمیج را دوباره بسازید و کانتینر را ری‌استارت کنید.

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

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

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

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

چرا این خطا در زمان نصب وردپرس رخ می‌دهد؟ وردپرس در همان مراحل اولیه نصب، نیاز به اتصال به دیتابیس دارد و اگر افزونه mysqli فعال نباشد، در همان مراحل اولیه متوقف می‌شود و پیام «Your PHP installation appears to be missing the MySQL extension which is required by WordPress» را نمایش می‌دهد. راه‌حل، فعال‌سازی افزونه قبل از شروع نصب است.

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

تفاوت این خطا با خطای Connection refused به MySQL چیست؟ این دو خطا متفاوتند. خطای MySQLi missing یعنی افزونه PHP فعال نیست، ولی خطای Connection refused یعنی افزونه فعال است ولی اتصال به سرور MySQL برقرار نمی‌شود. اگر با خطای دوم مواجه هستید، رفع خطای اتصال به دیتابیس در وردپرس راهنمای مکملی است.

آیا استفاده از PDO به‌جای mysqli در وردپرس رسمی است؟ وردپرس به‌طور رسمی از mysqli استفاده می‌کند ولی مکانیزم تشخیص خودکار آن، در صورت نبود mysqli، از pdo_mysql بهره می‌برد. استفاده صریح از pdo_mysql نیازمند تغییرات در کلاس wpdb است که توصیه نمی‌شود مگر در سناریوهای خاص.

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

از رفع موضعی به معماری مقاوم

در پایان این مسیر، یک حقیقت را باید پذیرفت: خطای MySQLi extension missing، یک خطای سطحی نیست؛ نشانه‌ای از یک شکاف در پیکربندی سرور است. اگر این خطا را فقط با فعال‌سازی موقت افزونه حل کنید ولی به پیکربندی کلی PHP توجه نکنید، در آینده با مهاجرت به هاست جدید یا با ارتقای PHP، دوباره با همان خطا مواجه می‌شوید. راه‌حل بلندمدت، مستندسازی پیکربندی سرور و بررسی دوره‌ای آن است.

سه اصل که در همه پروژه‌های خودم رعایت می‌کنم. اصل اول: قبل از هر مهاجرت یا ارتقای PHP، پیکربندی افزونه‌های موجود را مستند کنید تا در محیط جدید قابل بازسازی باشد. اصل دوم: در انتخاب هاست، بخش پیکربندی PHP را جزء معیارهای اصلی قرار دهید نه یک ویژگی جانبی. اصل سوم: در محیط staging، همیشه سناریوهای مختلف PHP را تست کنید تا از غافلگیری در production جلوگیری شود. اصول انتخاب هاست در بهترین هاست برای وردپرس آمده است.

یک نکته عملی که در پروژه‌های واقعی زیاد به کارم آمده: پیش از هر ارتقای PHP، فهرست افزونه‌های فعال فعلی را با ابزاری مثل php -m ذخیره کنید. این فهرست، در محیط جدید به شما می‌گوید چه افزونه‌هایی باید فعال شوند. تجربه‌ام این است که این یک عادت کوچک، جلوی چند ساعت عیب‌یابی در روز مهاجرت را می‌گیرد.

اگر در ابتدای مسیر یادگیری هستید، سه تمرین را پیشنهاد می‌کنم. اول، روی یک نصب تستی وردپرس، عمداً افزونه mysqli را غیرفعال کنید و ببینید این خطا چطور رخ می‌دهد و چطور رفع می‌شود. دوم، در محیط staging، فهرست افزونه‌های PHP را با php -m ذخیره کنید و قبل و بعد از هر تغییر مقایسه کنید. سوم، روی یک VPS تستی، افزونه را از خط فرمان نصب کنید و تفاوت رفتار سرور قبل و بعد را ببینید. این سه تجربه، درک عمیقی از اهمیت پیکربندی PHP به شما می‌دهد که هیچ مقاله‌ای جایگزینش نمی‌شود. 🛠️