Частая ошибка при настройке отладки PHP:
PHP Warning: Failed loading Zend extension 'xdebug.so' (tried: /usr/lib/php/20230831/xdebug.so ...): cannot open shared object file: No such file or directory
PHP пытается загрузить Xdebug, но файла нет там, где он его ищет. Разберём причины по порядку.
Почему так бывает
- Xdebug не установлен для той версии PHP, которая запускается.
- В системе несколько версий PHP, а расширение поставили только для одной.
- В
php.iniпрописан старый путь, например после обновления PHP поменялся каталог расширений. - Расширение подключено дважды: и в
php.ini, и вconf.d.
Шаг 1. Какая версия PHP работает
php -v php --ini php -i | grep extension_dir
Номер каталога, например 20230831, это версия API, он свой для каждой ветки PHP (8.3 в этом примере). Расширение должно лежать именно там.
Учтите, что у консоли, PHP-FPM и Apache могут быть разные версии и разные файлы php.ini.
Шаг 2. Установка из пакетов
sudo apt update sudo apt install php8.3-xdebug
Подставьте свою версию. Пакет сам кладёт файл в нужный каталог и создаёт /etc/php/8.3/mods-available/xdebug.ini, вручную ничего прописывать не надо.
Если пакета для вашей версии нет в репозитории, можно собрать через PECL:
sudo apt install php8.3-dev php-pear sudo pecl install xdebug
После этого добавьте в php.ini строку zend_extension=xdebug.
Шаг 3. Проверка путей
find /usr/lib/php -name xdebug.so grep -rn xdebug /etc/php/
Если в каком-то файле указан полный путь к несуществующему каталогу, исправьте его или замените на короткое zend_extension=xdebug: тогда PHP сам возьмёт файл из extension_dir. Повторы удалите.
Шаг 4. Настройки Xdebug 3
Если вы переносите старую конфигурацию, помните, что в Xdebug 3 параметры поменялись. Минимальный набор для пошаговой отладки:
zend_extension=xdebug xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003
Порт по умолчанию теперь 9003, а не 9000. Старые параметры вроде xdebug.remote_enable больше не действуют.
Шаг 5. Перезапуск и проверка
sudo systemctl restart php8.3-fpm # или apache2 php -v
В выводе должна появиться строка вида with Xdebug v3.x.x. Для веб-сервера проверьте через phpinfo().
Важно для боевых серверов
Xdebug заметно замедляет PHP, даже когда отладка не идёт. На рабочем сервере его лучше не держать включённым: sudo phpdismod xdebug.